Introduction to Agent Skills

Agent Skills are folders holding a SKILL.md file (a name, a description, and instructions) that Claude Code, Codex, and Cursor load on demand. The agent lists every skill’s name and description in each session and reads the body only when a task matches. A skill arrives as a portable copy from npx skills add or inside a plugin.

On Monday you explained the release checklist to the agent. On Tuesday a fresh session merged without the changelog step, and your teammate on Codex never had it. This page is for developers and tech leads who want that knowledge written once and pinned for every agent.

What is a skill, and how is it different from MCP and plugins?

A skill is instructions, not a live connection: it holds no credentials or server of its own. Anything it fetches goes through bundled scripts or commands the agent runs with its own permissions. The format is an open standard (since 2025-12-18): a skill-name/SKILL.md folder whose frontmatter name is at most 64 characters and whose description is at most 1,024. The specification’s showcase listed 46 compatible clients on 2026-09-26.

---
name: release-checklist
description: Use when preparing a release or merging to main. Runs the changelog, version bump and smoke-test steps in order.
---
1. Update CHANGELOG.md from merged PR titles since the last tag.
2. Bump the version with `npm version minor --no-git-tag-version`.
3. Run `npm run smoke` and paste the last 20 lines of output before you say "done".

The description decides when the skill fires, so write it as a trigger condition; until then the skill costs a few dozen tokens.

Layer	What it gives the agent	Choose it when
Skill	A procedure or convention	The agent should follow a practice: TDD, a release checklist
MCP server	Live tools and data	The agent must read or change external state: PRs, tickets, a database
Plugin	A bundle of skills, commands, subagents, hooks, and MCP servers	You want a vendor’s skills and tools wired together, or a hook that starts a method

For the decision guide across all six layers, see how skills, MCP, plugins, and frameworks fit together.

Where does each agent read skills, and how do you call one?

The agents read different directories, so the skills CLI writes one canonical copy in .agents/skills/ and symlinks it into .claude/skills/ for Claude Code.

	Claude Code	Codex	Cursor
Project skills	.claude/skills/<name>/, also in parent directories	.agents/skills/<name>/, from the working directory up to the repo root	.agents/skills/, .cursor/skills/, .claude/skills/, and .codex/skills/
Personal skills	~/.claude/skills/	~/.agents/skills/ per OpenAI’s docs; npx skills add -g writes ~/.codex/skills/	~/.cursor/skills/, ~/.agents/skills/ (plus the .claude/.codex compatibility paths)
Invoke by name	/<name>; plugin skills are /<plugin>:<skill>	$<name>; /skills lists them	Name it in the prompt
Built in	/code-review, /simplify, /verify, /run, /batch, /loop (turn off with disableBundledSkills)	skill-creator, skill-installer, plugin-creator	/loop

Checked on 2026-09-26 against the Claude Code 2.1.283 docs and the codex-cli 0.157.1 binary. The Codex personal directory and every Cursor path come from vendor documentation (secondary, not re-checked on 2026-09-26).

Install one skill both ways: plugin or portable copy?

Anthropic’s frontend-design ships both as a plugin in claude-plugins-official and as a folder in anthropics/skills. On 2026-09-26 the plugin showed 1,134,112 installs on the Claude Marketplace directory (claude.com/plugins), and the portable copy 923,303 on skills.sh (secondary: LinklyAI/best-skills snapshot, 2026-09-26).

Claude Code

Plugin route (terminal):

claude plugin install frontend-design@claude-plugins-official --scope project
claude plugin details frontend-design     # component list and always-on token cost

Invoke it as /frontend-design:frontend-design; --scope project records it in .claude/settings.json for the team. claude plugin details frontend-design reported about 78 always-on tokens on 2026-09-26.

Portable route (terminal):

npx skills add anthropics/skills --skill frontend-design -a claude-code

Invoke it as /frontend-design. Pick one route, or you get two copies.

Codex

Portable route (terminal):

npx skills add anthropics/skills --skill frontend-design -a codex

The files land in .agents/skills/frontend-design/. Invoke with $frontend-design, or type /skills to confirm Codex sees it. For Codex plugins (codex plugin add, not install, in 0.157.1), see plugins and marketplaces.

Cursor

Portable route (terminal):

npx skills add anthropics/skills --skill frontend-design -a cursor

The files land in .agents/skills/frontend-design/. Cursor installs plugins from Agent chat with /add-plugin <name>, per Cursor’s plugin repository (not run in a Cursor binary).

Choose the plugin when the method depends on a hook, command, or MCP server: the portable Superpowers copy has no session-start hook, so its workflow does not start on its own. Choose the portable copy when the team uses more than one agent; it pins to a commit in skills-lock.json.

Copy-paste prompt: confirm which copy loaded

List every skill you can see in this session, with the directory or plugin each one comes from. If any skill appears twice, name both sources and tell me which one you would use. Then, for frontend-design only: quote its description, say whether you would load it for "restyle the pricing table in src/components/Pricing.tsx", and name the first two instructions you would apply. Do not edit any file.

From “I need X” to a pinned team install

1. Search for candidates and prefer the canonical owner, because copycat repos reuse popular names: npx skills find changelog.

2. Read before installing the SKILL.md and every bundled script, because skills run with the agent’s full permissions.

   npx skills add anthropics/skills --list
   npx skills use anthropics/skills@frontend-design    # prints the prompt, installs nothing

3. Pin to a commit by installing at the hash that git ls-remote prints, for all three agents at once.

   git ls-remote https://github.com/anthropics/skills HEAD
   npx skills add anthropics/skills#COMMIT_SHA --skill frontend-design -a claude-code -a codex -a cursor -y

4. Commit and review .agents/skills/, .claude/skills/, and skills-lock.json in one pull request, with a code owner on the skills directories.

5. Prove it works with an acceptance prompt in each agent, and move the pin only by rerunning step 3 (npx skills update keeps the recorded ref).

Copy-paste prompt: vet a skill before the team adopts it

I need a skill that writes CHANGELOG.md entries from merged pull requests in Keep a Changelog format. Run `npx skills find changelog` and pick the three strongest candidates. For each one, give the owner/repo, the skill name from its SKILL.md frontmatter, and every script or shell command the skill would run. Flag any network call, any write outside the repository, and any hook. Recommend one and write the pinned install command for claude-code, codex and cursor. Do not install anything.

How do you know a skill is doing its job without reading every diff?

• It loads. /skills in Codex, /context in Claude Code, or the first prompt above shows it.
• It fires on the right task. Ask the agent to run it and mark each numbered instruction done, skipped, or not applicable, beside the diff and test output.
• It has not drifted. The skill folders and skills-lock.json change only in a reviewed pull request; a CI step that runs npx -y skills@1.7.0 experimental_install and then git diff --exit-code -- .agents/skills skills-lock.json fails when someone hand-edits a committed skill, or when an unpinned or branch-pinned source has moved upstream.
• Plugins can carry evals. claude plugin eval runs a plugin’s eval suite against a no-plugin baseline.

To write your own skill with evals, see building and publishing your own skills.

When skills do not load, do not fire, or fire twice

Traps checked on 2026-09-26 (skills CLI 1.7.0)

• --skill=grill-me is silently ignored, so with -y the CLI installs every skill in the repository. Use --skill grill-me or -s.
• --skill matches the frontmatter name, not the folder: vercel-react-best-practices works, react-best-practices fails.
• Some skills delegate: Matt Pocock’s grill-me calls grilling, so install both.
• Several unrelated repositories publish “superpowers”; the canonical one is obra/superpowers.

The skill never fires. Rewrite the description as “Use when…” with the words people actually type, then check it with the first prompt.

The skill appears twice. Keep one route: claude plugin uninstall <plugin> or npx skills remove <skill>.

/code-review runs the wrong thing. Claude Code’s built-in skill owns the bare name; Anthropic’s plugin runs as /code-review:code-review.

Two skills contradict each other. Use Dr. Skill to find colliding descriptions, then remove one.

For global installs, lockfile restores, and updates, see installing, sharing, and pinning skills.

Where to go next with Agent Skills

Installing, sharing, and pinning skills Every skills CLI command, scopes, updates, and removal.

Skill supply-chain security What a malicious skill can do and how to review one.

The 25 most-installed practice skills Planning, TDD, debugging, and review skills.

Plugins and marketplaces What a plugin bundles and how to pin one.

Official skills from technology makers Vendor-maintained skills for the platforms you deploy to.

Superpowers A design-to-PR method: skills plus a session-start hook.