Write, Install, or Generate: A Practical Guide to Agent Skills

A plain-English guide to Agent Skills — what they are, how they differ from MCP, and the three ways to source one: write, install, or generate.

If you use Claude at work, you probably have a running tab of context you paste into every session: your team's naming conventions, the testing library you prefer, that one internal helper Claude keeps forgetting. You copy. You paste. You remind. And you do it all again next week.

Agent Skills are Anthropic's answer to that fatigue. Announced in October 2025 and released as an open standard that December, they're now supported across Claude API, Claude Code, Cursor, VS Code Copilot, Cline, and more than two dozen other coding agents. The idea is simple: teach an agent something once, then reuse that knowledge everywhere — without bloating your prompts or your token bill.

This guide explains what a skill is, how it differs from MCP (the other acronym you'll hear in the same breath), the three ways to get one — write, install, or generate — and two patterns for scaling beyond a single skill once you have a few.

What a skill actually is

A skill is a folder with a markdown file inside. The file — SKILL.md — contains two things: a short description that tells Claude when to use the skill, and a longer body with the actual instructions.

Think of it as a recipe card. When you ask Claude to bake bread, it pulls the card titled "here's how we bake bread in this kitchen." When you ask for something unrelated, the card sits in the drawer untouched. The point is that the card isn't in Claude's working memory until it's needed.

That's the difference between a skill and a big system prompt. A system prompt is the entire cookbook handed to Claude at every meal, even when you only want toast. A skill is one recipe pulled out on demand. Anthropic documents each idle skill as costing roughly 100 tokens of metadata — enough for Claude to know the skill exists without paying for its full content.

That math matters once you have a handful. Twenty skills at ~100 tokens each is 2,000 tokens of fixed overhead no matter how long each skill actually is. The same twenty rules dumped into a system prompt would weigh in at tens of thousands of tokens every turn.

Skills vs. MCP: the recipe vs. the pantry

The other term you'll hear is MCP — the Model Context Protocol. People often treat skills and MCP as competing ideas, but they solve different problems.

• MCP is the live connection between Claude and your data: query a Jira ticket, read a Google Doc, fetch current Stripe API docs. It's the pantry — where the fresh ingredients live.
• A skill is a reusable set of instructions: "when you're writing a React component, follow these rules." It's the recipe — how you combine ingredients, consistently, every time.

Here's a side-by-side view:

They aren't competitors. Most real workflows use both — MCP pulls the live docs; a skill teaches Claude how your team adapts them.

The anatomy of a skill

Every skill uses a layered structure Anthropic calls progressive disclosure:

1. Metadata — always loaded. A short header at the top of SKILL.md that says who the skill is and when to trigger it. About 100 tokens.
2. The body — loaded when triggered. The markdown instructions Claude reads once the description matches your task.
3. Reference files — pulled in only if the body points to them. Supporting docs, checklists, example code.

A minimal skill looks like this:

---
name: acme-pr-style
description: Use when drafting a pull request description. Enforces Acme Corp's PR template and ticket-linking rules.
---

# Acme PR Style

- Start every PR title with a ticket ID like `[ACME-1234]`.
- The body must have three sections: **Summary**, **Changes**, **Test plan**.
- Never merge without at least one linked Linear ticket.
- Use "we" voice, not "I" voice.

That's the whole skill. The block between the --- lines is YAML, and Claude uses the description to decide whether to activate the skill when you type a request. Once active, the body becomes a hard rule for that conversation.

The Anthropic spec requires only two frontmatter fields — name and description — and Claude Code adds a small handful of optional ones (for example, user-invocable: true, the default, controls whether the skill also appears in the / slash-command menu). You don't need anything beyond the two required fields for your first skill.

Build your first skill in five minutes

Let's walk through the PR-style skill end to end.

Step 1. Create the folder.

In your project root, add:

.claude/skills/acme-pr-style/
└── SKILL.md

Step 2. Write SKILL.md.

Copy the example from the previous section — swap acme for your team name and replace the rules with yours.

Step 3. Ask Claude to use it.

Start Claude Code in that directory and ask something that matches the trigger:

"Write the PR description for my current branch."

Claude scans the active skills, notices the description matches "drafting a pull request," and silently loads the body. In Claude Code you'll see a confirmation like:

[Skill loaded: acme-pr-style]

Your PR description now follows the template.

Step 4. Iterate on the description.

If Claude doesn't pick up the skill, the culprit is almost always the description field. It's the only signal Claude has when deciding to activate. Vague descriptions ("coding standards") rarely trigger. Task-shaped descriptions ("Use when drafting a pull request description") do. A useful rule: phrase it like you're writing a job posting — state the trigger condition first, then the outcome.

Step 5. Share it.

Commit .claude/skills/acme-pr-style/ to your repo. Every teammate who checks out the repo automatically gets the skill — no install step, no sync service. That's the quiet win here: the rules live with the code. When you bump your PR template, you bump the skill in the same commit, and Claude stays aligned with your current conventions instead of the ones from six months ago.

You don't have to write every skill from scratch

You just hand-wrote one, and that's the most direct path. Before you do it for everything, though, it helps to know that hand-writing is one of three ways to get a skill — and that the other two are usually faster when they apply.

• Write your own for everything specific to your team — naming conventions, internal libraries, security requirements, release workflows. This is the irreducible kernel: nobody outside your team can produce it.

• Install one somebody else wrote from a community source. These come in three flavors, in order of how curated they are:

  • Curated CLI registry — small but vetted, install via command. skills.sh (Vercel Labs, early 2026) is the canonical example: npx skills find to search, npx skills add <pkg> to install.
  • Curated "awesome" list — a GitHub README organized by category; copy or clone manually. awesome-claude-skills (maintained by Composio) is the largest, grouped by use case: document processing, dev tools, data analysis, app automation, and so on.
  • Search-driven aggregator — auto-indexes hundreds of thousands of skills from GitHub with AI-assisted search and one-click install. SkillsMP lists 900K+ across Claude Code, Codex, and ChatGPT.

• Generate one from live documentation when you're picking up a third-party library and don't know it well enough to write the rules yourself. Context7's wizard (npx ctx7 skills generate) does this — covered in the next section.

Rule of thumb: write for internal rules, install for shared community patterns, generate for third-party library knowledge. Note: curated sources are higher signal but smaller; aggregators have everything but you should read each SKILL.md before installing — skills can ship scripts the agent will execute, which means you should verify the code is safe to run.

Generate skills from docs with the Context7 wizard

Writing a skill for your team's conventions is one thing — you already know the rules. Writing a skill for a third-party library is harder, because you have to know the library well enough to capture its current best practices, the patterns that are deprecated, and the mistakes you want the agent to avoid. Most of us aren't that fluent with the SDK we adopted last week, and the docs keep moving. So skills for external libraries often don't get written, or get written from stale memory and quietly drift.

Context7 ships a CLI workflow specifically for this gap. Run:

npx ctx7 skills generate

and you get an interactive wizard that turns Context7's live documentation index into a scoped skill in five steps:

1. Describe the expertise — Clerk authentication, Drizzle migrations, Tailwind v4 theming. Frame it as the domain you want the agent to be expert in, not the task you want it to do.
2. Pick the sources — the wizard searches Context7's library and shows matching documentation sets. You confirm which ones it should treat as ground truth.
3. Answer the scoping questions — it asks targeted clarifications: which framework you're on (Next.js, Remix, Astro), what stage you're at (initial setup, hardening, migration), which slice of the API you care about (sign-in/sign-up, social SSO, organizations).
4. Review and refine — the wizard queries Context7 for the latest docs, drafts the skill, and shows you exactly which snippets it pulled from. If something's off, you describe what to change and it regenerates while keeping what you liked.
5. Install — pick the targets. The wizard detects Claude Code, Cursor, Codex, OpenCode, Amp, and Antigravity, and writes the skill into the right folder for each — or all of them with --all.

What you end up with isn't a generic library wiki. It's a focused SKILL.md that answers the exact question you scoped — say, "set up sign-in and sign-up in a Next.js App Router app with Clerk." It typically includes where the provider component goes, how the middleware should be wired, the required environment variables, and, usefully, the wrong patterns the official docs explicitly warn against.

The non-obvious win is the scoping. Instead of one omnibus clerk skill that tries to cover everything, you re-run the wizard for each concern: one skill for sign-in/sign-up flows, another for user management and profiles, another for social SSO. Each is narrow enough to have a sharp description, which means each triggers precisely when relevant. The agent loads the auth-flow skill while you're wiring login pages, and the profile skill while you're building the account screen — never both at once, and never the wrong one.

A reasonable heuristic: reach for the wizard when you're adopting a library you don't know intimately, or when you suspect the model's training data is older than the version you're on. Keep writing your own skills for the rules only your team knows — internal libraries, naming conventions, security requirements. The wizard is a great way to get a library skill. It can't write your culture skill.

Compose skills into new skills

Once you have a few skills, the next unlock is treating them as building blocks. A skill can invoke other installed skills as subroutines — running them in sequence, in parallel, or both — and combine the results with its own work to produce something neither could on its own.

A concrete example from my own toolkit is a code-review-report skill that runs two independent review passes against the same diff and consolidates them into a severity-tiered report. The two passes compose differently:

• A convention-based pass the skill runs itself. It reads the project's CLAUDE.md and a per-language checklist, and reviews each file against those rules. For large diffs the skill fans this out across subagents — up to ten files per subagent — so the diff never has to fit in a single context.
• An adversarial pass done by invoking another installed skill: /codex:adversarial-review from the Codex plugin. It runs the same diff through a different model (Codex) playing the skeptic, looking for bugs, security issues, and architectural risks the convention pass might miss.

Both passes run in parallel. When they return, code-review-report consolidates them:

1. Deduplicate. If both reviewers flag the same issue, it becomes a corroborated, higher-confidence item tagged [Both]. Disagreements are surfaced rather than hidden.
2. Classify and format. Group findings into a severity-tiered report (Critical / High / Medium / Low / Nits), annotate each with its source ([Claude], [Codex], or [Both]), and append lint output.

The result is a single report backed by two independent perspectives — something meaningfully different from either pass alone.

The compounding payoff is the point. Claude and Codex have different training and different blind spots, so running both against the same diff catches issues either model alone would miss. The [Both] tag turns agreement into signal — when two independent reviewers flag the same issue, the team can triage with much higher confidence than they could from either alone. Disagreements stay visible too, which is itself useful: a finding only one reviewer raised tells you something about the issue's character (model-specific blind spot, ambiguous case, judgment call worth a human discussion).

The pattern generalizes. Any time you catch yourself running two or three skills by hand in the same order — research, then draft, then critique; lint, then test, then summarize — that sequence is itself a skill. Write a new SKILL.md whose body tells Claude "run skill X, then run skill Y, then consolidate the outputs like this." You get reuse, a shareable workflow, and the same ~100 tokens of idle overhead as any other skill.

Fan out to subagents inside one skill

Composition isn't the only way to scale a skill. A skill can also dispatch its own subagents — short-lived workers, each with a fresh context, all running in parallel — and consolidate the results when they return. This is the move when one skill needs to do work that's too big for a single context window or has natural parallelism inside it.

code-review-report does this for its convention-based pass. Reviewing every file in a large diff against CLAUDE.md and a per-language checklist would either overflow context or grind serially. Instead, the skill splits the changed file list into batches of up to ten files and dispatches one subagent per batch. Each subagent loads the same instructions but only its own slice of the diff, runs the mechanical and semantic checks, and returns structured findings. The parent skill collects all batches and merges them into the consolidation step.

Three things make subagent fan-out earn its complexity:

• Context economics. Each subagent has its own fresh context. The parent skill never has to hold the whole diff at once — only the consolidated findings, which are typically orders of magnitude smaller than the raw input.
• Real parallelism. Subagents run concurrently on the wall clock, not just logically. Reviewing thirty files across three subagents of ten finishes roughly three times faster than one subagent grinding through all thirty.
• Isolation. A subagent can't contaminate another with framing from an earlier file or half-formed conclusions. Each one sees its slice cleanly.

The fan-out can take two shapes, and both are worth knowing:

• Partition by data (what code-review-report does) — same work, different slice of input. Each subagent runs the same instructions on a different chunk of the diff. Best for naturally divisible inputs: file batches, record windows, time ranges, regions of a document.
• Partition by concern — different work, same input. One subagent specializes in security, another in performance, another in test coverage; they all see the full input but each looks for something different. Best when concerns are independent and benefit from a dedicated reviewer rather than being squeezed into one pass.

The trade-off is real: subagents cost tokens (each one re-loads its instructions and partial context) and add orchestration overhead. Fan out only when the work is divisible and large enough that the alternatives — overflowing context, running serially — are worse. For a five-file diff, the parent context is fine. For a fifty-file diff, fan out.

Takeaways

• Skills are recipe cards. Markdown files Claude reads only when they match your task, at ~100 tokens of idle overhead each.
• Skills are not MCP. Skills are reusable procedures; MCP is live data access. You'll likely use both.
• Skills live in your repo. When the rules change, commit the change. Claude reads the latest version automatically, across every teammate.
• Generate library skills, write team skills. Use npx ctx7 skills generate to spin up scoped skills for third-party libraries from current docs. Write your own for the rules only your team knows.
• Two ways to scale beyond one skill. Compose other skills as building blocks, or fan out to subagents inside a single skill. Use the first when the pieces are already separate skills; use the second when the work inside one skill is too big for one context.

If you've caught yourself pasting the same block of context into Claude twice this week, that block is already your first skill. The rest is copying it into a SKILL.md file.

Appendix — A developer's deeper look

For readers who write code, here's what a skill looks like once it grows up.

Recommended directory layout

.claude/skills/acme-typescript/
├── SKILL.md                 # Metadata + core rules
├── references/
│   ├── naming-conventions.md
│   └── standard-patterns.ts # "Good" vs "Bad" code examples
└── templates/
    └── api-route.ts.template

The references/ folder is Level 3 of progressive disclosure. The body of SKILL.md mentions these files by path, and Claude opens them only when it actually needs the example — keeping the active context small until the moment you need the detail.

A realistic SKILL.md

---
name: acme-typescript
description: Enforces Acme Corp's strict TypeScript 5.x standards, including Zod validation at boundaries and the internal Result<T, E> error pattern. Use when writing or reviewing any .ts file.
user-invocable: true
---

# Acme TypeScript Standards

## Type safety
- No `any`. Use `unknown` with a type guard.
- Boundary data (API, file, env) must be validated with Zod.
- Derive the TypeScript type from the schema: `type X = z.infer<typeof XSchema>`.

## Error handling
- Use `Result<T, E>` from `./references/standard-patterns.ts`.
- Never throw for expected business errors; return `err(...)` instead.

## Reference
- See `./references/standard-patterns.ts` for the canonical implementation.

ultrathink

This is the culture side of the divide from earlier — it codifies Acme's internal Result<T, E> pattern, which no wizard could know about. The library counterparts you'd pair it with — say zod-runtime-validation or typescript-strict-mode — are exactly the kind of skill npx ctx7 skills generate would draft for you from the official docs in a couple of minutes.

That last word — ultrathink — is a real Claude Code trigger. When it appears anywhere inside a skill, Claude allocates its extended-thinking budget (roughly 32,000 tokens) whenever the skill is active. Use it for skills that enforce expensive or subtle constraints where quiet mistakes are costly.

A reference file

references/standard-patterns.ts:

export type Result<T, E = Error> =
  | { ok: true; value: T }
  | { ok: false; error: E };

export const ok = <T>(value: T): Result<T, never> => ({ ok: true, value });
export const err = <E>(error: E): Result<never, E> => ({ ok: false, error });

When Claude is asked to edit a service file, it reads the skill, sees "use the pattern at ./references/standard-patterns.ts," opens that file once, and applies the pattern consistently across every change in the session. That's what progressive disclosure buys you: one source of truth, loaded only when relevant.

References

• Anthropic — Equipping agents for the real world with Agent Skills
• Agent Skills overview (Claude platform docs)
• Claude Code — Skills reference
• Context7 CLI documentation
• skills.sh — the open agent skills ecosystem
• Context7 + Skill Wizard = Instant Claude Code Skills (YouTube)
• Awesome Claude Skills
• Agent Skills Marketplace