workflowContext Engineering5 min read

Writing Your Own Skills

Our take

This hub is full of skills other people wrote. The compounding win is writing your own. A skill is how you encode your team's process once and have every agent follow it the same way.

A skill is a folder with a SKILL.md file that teaches an agent one repeatable procedure. Only its name and description load up front, so the body costs nothing until the task actually matches. Agent Skills is an open standard, so the same folder works across Claude Code, Cursor, Codex, Copilot, Gemini CLI and 40+ other agents.

On this page11 parts

01The Problem
02Anatomy
03Write the Description for Discovery
04Match Freedom to Fragility
05Progressive Disclosure
06Build the Evaluation First
07Where Skills Live
08Why This Matters for Senior Teams
09Where It Fits in the Stack
10When Not to Use It
11Source

The Problem

AGENTS.md tells your agent what the project is. It does not tell the agent how your team does a thing. So the "how" ends up in three bad places: pasted into chat every time, buried inside a context file that keeps growing, or in one engineer's head.

The symptom is easy to spot. If you keep pasting the same checklist, or a section of your CLAUDE.md has quietly turned from a fact into a procedure, that content wants to be a skill.

The distinction is also a budget decision. AGENTS.md and CLAUDE.md load on every single session. A skill pre-loads only its name and description, and pulls the body in only when the task matches. Long reference material is effectively free until you need it.

Anatomy

A skill is a directory. SKILL.md is the entrypoint. Everything else is optional and loads on demand:

text

1frontend-release/
2├── SKILL.md              # loaded when the skill triggers
3├── checklist.md          # loaded only if SKILL.md points to it
4├── reference/
5│   └── design-tokens.md
6└── scripts/
7    └── verify_build.sh   # executed, never loaded into context

The frontmatter is two required fields. That is the whole spec:

markdown

1---
2name: reviewing-prs
3description: Runs the team's review checklist across React and TypeScript changes. Use when reviewing a pull request, a diff, or staged changes.
4---
5
6# Reviewing PRs
7
8...

name is lowercase letters, numbers and hyphens, 64 characters max. description is 1,024 characters max, and it is the single most important line in the file.

Write the Description for Discovery

Until the skill fires, the agent sees nothing but name and description. Write a vague description and the skill never loads, and you conclude that skills do not work.

Two rules:

Say what it does and when to use it, using the trigger words a person would actually type.
Write in third person. The description is injected into the system prompt, and first or second person ("I can help you...") measurably hurts selection.

Good: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

Bad: Helps with documents.

Match Freedom to Fragility

Anthropic's framing is an agent walking a path.

Open field.Many routes work and context decides which. Give direction, not steps. Code review, naming, refactor suggestions.
Narrow bridge with cliffs.One safe route. Give the exact command and say explicitly not to improvise. Migrations, release scripts, anything destructive.

Most bad skills are open-field prose written for a narrow-bridge task, or a rigid script imposed on something that needed judgement. Pick the one that matches how badly the task breaks.

Progressive Disclosure

Keep the SKILL.md body under 500 lines. Past that, split it:

Link reference files directly from SKILL.md, one level deep. Nested references get partially read and the agent walks away with half the information.
Tell the agent when to open each file. "Read reference/api-errors.md when the API returns a non-200" beats "see reference/ for details."
Give any reference file over 100 lines a table of contents at the top, so a partial read still reveals the full scope.
Prefer a committed script over asking the agent to generate one. Scripts are more reliable, consistent across runs, and cost zero context until they execute. Make it obvious whether the agent should run the file or read it.

Build the Evaluation First

The failure mode is a long, plausible skill that solves a problem you imagined.

Run your agent on three real tasks with no skill loaded. Write down exactly where it failed or what you had to explain. Those failures are your test cases. Now write the shortest skill that fixes them, rerun the same three tasks, and compare against the baseline. Anything in the file that does not move one of those three cases is context tax.

Then use the loop that actually works. One session helps you write and refine the skill. A separate, fresh session uses it on real work. Watch the second session, bring what broke back to the first, repeat. You supply the domain knowledge, the fresh session exposes the gaps.

Where Skills Live

In Claude Code:

~/.claude/skills/<name>/SKILL.md for personal skills, available in every project you work on
.claude/skills/<name>/SKILL.md for project skills, committed to the repo and shared with the team
<plugin>/skills/<name>/SKILL.md for skills distributed inside a plugin

The project path is the one that matters for a team. It goes through code review like any other file, it lands with the branch that needed it, and every engineer and every agent on the repo picks it up. Claude Code watches these directories and reloads edits without a restart.

If you plan to share a skill outside Claude Code, stick to the portable frontmatter fields: name, description, license, compatibility, metadata and allowed-tools. Claude Code accepts extra fields, but packaging for the open standard fails hard on anything the spec does not allow.

Why This Matters for Senior Teams

Process becomes reviewable."How we cut a release" stops being tribal knowledge and becomes a file in a PR, with an author, a diff, and a rollback path.
It scales past the person who wrote it.A skill is the only artifact in this stack that makes a junior engineer's agent behave like your best engineer's agent.
Context stays cheap.Moving procedures out of CLAUDE.md and into skills shrinks what every session pays for, and keeps your always-on context down to facts.
It survives tool churn.The same folder is read by 40+ agents. When half the team moves to a different IDE next quarter, the process moves with them.

Where It Fits in the Stack

Directly after AGENTS.md.AGENTS.md holds facts, skills hold procedures. If a section of your AGENTS.md has grown ordered steps, that section is a skill trying to get out.
Underneath Agent Teams.Reusable teammate roles are only as good as the procedures they load. Define security-reviewer once as a skill, reuse it as a subagent and as a teammate.
Around Spec Kit.Spec Kit structures one feature. A skill structures the parts you do identically on every feature.
Install before you author.Start from the ecosystem in the Skills tab and npx skills add. Write your own only for what is genuinely specific to your codebase.
Distribute with a plugin.Once two or more people need the same skill, wrap it in a plugin and a private marketplace so it installs and versions like any other dependency.

When Not to Use It

If the instruction is one sentence and always true, it belongs in AGENTS.md, not a skill. If you will run it once, just prompt. Skills earn their keep on procedures you repeat, that have a correct order, and that are expensive to get wrong. Everything else is overhead with a YAML header on top.