# Introduction to Agent Skills

URL: https://developertoolkit.ai/en/ecosystem/skills/
Description: Agent Skills are SKILL.md folders that Claude Code, Codex, and Cursor load on demand: plugin or portable copy, where each agent reads them, and pinning.

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.

```markdown
---
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](/en/ecosystem/).

## 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`) | `imagegen`, `openai-docs`, `review-agent`, `skill-creator`, `skill-installer` (0.162.1; `plugin-creator` was removed from the bundle in 0.159.0) | `/loop`, `/review`, `/create-skill`, `/migrate-to-skills` and others |

Checked on 2026-09-26 against the Claude Code 2.1.283 docs and the codex-cli 0.157.1 binary. The Codex rows were checked again on 2026-10-13 in OpenAI's skills guide (project and personal directories, `$` invocation and `/skills`) and in the `rust-v0.162.1` source (bundled sample skills). The Cursor project and personal paths and the built-in skills were checked against Cursor's skills docs on 2026-10-12.

## 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):

```bash
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):

```bash
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):

```bash
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](/en/ecosystem/plugins/).

**Cursor**

Portable route (terminal):

```bash
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**

```text
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.

    ```bash
    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.

    ```bash
    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**

```text
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](/en/ecosystem/skills/building-custom-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](/en/ecosystem/skills/drskill/) to find colliding descriptions, then remove one.

For global installs, lockfile restores, and updates, see [installing, sharing, and pinning skills](/en/ecosystem/skills/installing-managing/).

## Where to go next with Agent Skills

- [Installing, sharing, and pinning skills](/en/ecosystem/skills/installing-managing/) — Every skills CLI command, scopes, updates, and removal.
- [Skill supply-chain security](/en/ecosystem/skills/skill-security/) — What a malicious skill can do and how to review one.
- [The 25 most-installed practice skills](/en/ecosystem/skills/top-practice-skills/) — Planning, TDD, debugging, and review skills.
- [Plugins and marketplaces](/en/ecosystem/plugins/) — What a plugin bundles and how to pin one.
- [Official skills from technology makers](/en/ecosystem/skills/top-skills-official/) — Vendor-maintained skills for the platforms you deploy to.
- [Superpowers](/en/ecosystem/frameworks/superpowers/) — A design-to-PR method: skills plus a session-start hook.