universal-agent-skills

Framework-agnostic agent skill loader for any AI agent runtime. Drop-in adapters for Claude Agent SDK, OpenAI Assistants, LangChain, CrewAI, AutoGen, and any system that takes a system prompt.

Each skill is a markdown file with frontmatter and a careful, prompt-engineered body — load it, hand it to your agent as a system prompt or role, done.

Install

npm install universal-agent-skills

Quick start

import { forClaude, forOpenAI, forLangChain, listSkills } from "universal-agent-skills";

// See what's available
console.log(listSkills());
// [
//   { name: "ux-expert-rakibulism", description: "...", tags: ["design","ux","review",...] },
// ]

// Use with Claude Agent SDK / Anthropic Messages API
import Anthropic from "@anthropic-ai/sdk";
const anthropic = new Anthropic();
const { system } = forClaude("ux-expert-rakibulism");
const msg = await anthropic.messages.create({
  model: "claude-opus-4-7",
  max_tokens: 4096,
  system,
  messages: [{ role: "user", content: "Review this dashboard screen:\n\n" + designDescription }],
});

// Use with OpenAI Assistants
import OpenAI from "openai";
const openai = new OpenAI();
const assistant = await openai.beta.assistants.create({
  model: "gpt-4o",
  ...forOpenAI("ux-expert-rakibulism"),
});

// Use with LangChain
import { PromptTemplate } from "@langchain/core/prompts";
const skill = forLangChain("ux-expert-rakibulism");
const prompt = PromptTemplate.fromTemplate(skill.template);
const formatted = await prompt.format({
  design: "...",
  format: "pinned comments",
});

Skills

Design

| Skill | What it does | |---|---| | ux-expert-rakibulism | Reviews UI screens in "rakibulism" voice — direct, client-facing, promise-list-style feedback |

Every skill follows the same authoring principles: lead with the spine, prioritize findings, prefer concrete output formats, name what to avoid. Larger skills also bundle a references/ directory of deeper material the body points to.

API

// Load
loadAllSkills(): Skill[]
getSkill(name: string): Skill
listSkills(): SkillSummary[]
getRelatedSkills(name: string): RelatedSkillSummary[]
asSystemPrompt(name: string): string

// Framework adapters
forClaude(name):       { system, metadata }              // metadata includes related_skills: string[]
forOpenAI(name):       { name, description, instructions }
forLangChain(name):    { template, inputVariables }
forCrewAI(name):       { role, goal, backstory }
forAutoGen(name):      { name, system_message }
forCursor(name):       { filename, content }             // Cursor .cursor/rules/*.mdc file
forAgentsMd(name):     { filename, content }             // AGENTS.md section (Codex, OpenCode, Antigravity, Cursor, Windsurf, Copilot...)
forStitchPrompt(name): { content }                       // plain paste-ready prompt, no file convention
forGeneric(name):      { name, description, version, tags, inputs, related, author, author_url, instructions }

Author attribution

Skill.author / Skill.author_url are populated from a skill's own frontmatter (author: rakibulism, author_url: https://x.com/rakibulism) and are null when a skill doesn't declare them. Only add these fields to a skill you actually wrote; never overwrite another skill's existing attribution.

Related skills — so an agent doesn't need every name typed up front

A skill can declare related: [other-skill-name, ...] in its frontmatter to point at complements it's commonly loaded alongside. getRelatedSkills(name) resolves those into full summaries (dropping any name that no longer resolves, rather than throwing), so a consuming agent can decide to pull in a companion skill automatically instead of requiring the user to already know and type its name:

import { getSkill, getRelatedSkills } from "universal-agent-skills";

const skill = getSkill("ux-expert-rakibulism");
const related = getRelatedSkills("ux-expert-rakibulism");
// -> [] unless a future skill declares `related: [ux-expert-rakibulism]` or vice versa

// e.g. in an agent loop: if the request looks like it needs a related skill too,
// load it without waiting for the user to name it explicitly.

This is opt-in per skill — only add related where two skills are genuinely complementary, not as a blanket cross-link between every skill in a domain.

Using a skill in Cursor, Codex, OpenCode, Antigravity, or other IDE/agent tools

Claude Agent SDK and Claude Code read SKILL.md natively — no export needed. Other tools have their own file conventions, so three more adapters generate ready-to-drop content for them:

| Tool | Format | Adapter | |---|---|---| | Cursor | .cursor/rules/<name>.mdc (YAML frontmatter + body) | forCursor(name) | | OpenAI Codex, OpenCode, Google Antigravity, Windsurf, GitHub Copilot | AGENTS.md — the open, tool-agnostic standard all of these read | forAgentsMd(name) | | Stitch (or any prompt-only design tool with no rule-file concept) | plain-text prompt, paste directly | forStitchPrompt(name) |

import { forCursor, forAgentsMd, forStitchPrompt } from "universal-agent-skills";

const cursor = forCursor("ux-expert-rakibulism");
// -> { filename: "ux-expert-rakibulism.mdc", content: "---\ndescription: ...\nalwaysApply: false\n---\n\n..." }
// Write this to .cursor/rules/ in your project.

const agentsMd = forAgentsMd("ux-expert-rakibulism");
// -> { filename: "ux-expert-rakibulism.agents.md", content: "## ux-expert-rakibulism ...\n\n..." }
// AGENTS.md conventionally holds every convention for a whole project, not just one skill —
// append this section onto your project's existing AGENTS.md rather than replacing it wholesale.

const stitch = forStitchPrompt("ux-expert-rakibulism");
// -> { content: "..." } — copy-paste directly into Stitch's prompt box.

Or generate all three at once for a skill (or every skill) with the bundled script, which writes into skills/<name>/exports/:

node scripts/export-skill.js ux-expert-rakibulism
node scripts/export-skill.js --all

A skill with a references/ folder loses those links when exported as a single file. A skill's body commonly links to references/*.md for deep-dive material (see "Authoring your own skills" below) — those relative links only resolve if the references/ folder is copied alongside the exported file at the same relative path. If you're dropping a Cursor .mdc or AGENTS.md section into a different project, copy the skill's references/ folder too (or inline the reference content you need) rather than shipping just the single exported file.

Use with Python frameworks (CrewAI, AutoGen)

The package is ESM JS, but the markdown skills are framework-neutral. To consume from Python:

# After npm install, the markdown files are at:
node_modules/universal-agent-skills/skills/<name>/SKILL.md

Read the file directly, strip frontmatter (---...---), use the body as your agent's backstory (CrewAI) or system_message (AutoGen).

Or generate a JSON catalog from Node and hand it to Python:

node -e "import('universal-agent-skills').then(m => console.log(JSON.stringify(m.loadAllSkills(), null, 2)))" > skills.json

Authoring your own skills

A skill is a directory containing SKILL.md, optionally with a references/ directory of supporting docs:

skills/
  my-skill/
    SKILL.md
    references/        # optional deep-dive docs the SKILL.md body points to
      topic-a.md
      topic-b.md

loadAllSkills() reads SKILL.md as the system prompt; references/ files are progressive-disclosure material the agent (or a human) opens as needed.

SKILL.md frontmatter:

---
name: my-skill
description: One sentence describing when to use this skill and what it produces.
version: 0.1.0
tags: [domain, capability]
inputs:
  - name: input_name
    description: What this input is.
    required: true
related: [other-skill-name]  # optional — see "Related skills" above
author: your-name            # optional — only if you wrote this skill yourself
author_url: https://...      # optional — link to your profile/site
---

# Body

The system-prompt content. Be specific about process, output format, and what to avoid.

Drop the directory into skills/ and loadAllSkills() picks it up.

Design principles

These skills were written to follow a few rules:

• Lead with intent. The first paragraph tells the model when to apply the skill.
• Process before output. How to think, not just what to emit.
• Specify output shape. Models drift without a target format.
• Name failure modes. "What to avoid" sections prevent common errors.
• Concrete over abstract. Concrete examples beat abstract advice.

License

MIT