Skills and Skill Creation
Applies to: any engineer who pastes the same instructions into an agent more than twice · Time to learn: 40 min reading + 30 min exercise · Lever: context
A skill is a folder with a SKILL.md file that teaches an agent one repeatable procedure. The agent sees only a one-line description until the task matches, then loads the full instructions. That makes skills the cheapest way to give an agent deep, task-specific know-how without bloating every session. Pages 2 to 5 covered always-on context; this page covers context that loads on demand.
- A skill =
SKILL.md(YAML frontmatter + Markdown) plus optionalscripts/,references/,assets/. - Only
nameanddescriptionare always loaded. The body loads when the skill triggers; resources load when needed. - The
descriptionis the trigger. Write what the skill does and when to use it, in the third person. - Put deterministic steps in scripts, judgment in prose. Test with and without the skill before you trust it.
- Skills can run scripts: review third-party skills like code before installing.
Why it matters in the AI age
As an FDE you repeat the same procedures in every client repo: write an ADR, cut release notes, refresh docs after a change, run the same checks. Pasting those instructions into every prompt wastes tokens and drifts. Putting them in AGENTS.md loads them in every session, even when irrelevant (see Context Engineering). A skill loads only when used, so long reference material costs almost nothing until needed (Claude Code skills docs). Anthropic's own guidance: create a skill when you keep pasting the same procedure; keep always-loaded facts in CLAUDE.md (Claude Code docs).
Core concepts
What a skill is
release-notes/
├── SKILL.md # Required: metadata + instructions
├── scripts/ # Optional: executable code (deterministic steps)
├── references/ # Optional: documentation loaded on demand
└── assets/ # Optional: templates, static resources
SKILL.md starts with YAML frontmatter on its first line, followed by Markdown instructions. The open standard requires name and description; Claude Code treats all fields as optional but recommends description (agentskills.io spec, Claude Code docs).
Progressive disclosure: three loading tiers
| Tier | What loads | When | Guidance |
|---|---|---|---|
| 1. Metadata | name, description | Startup, for every installed skill | About 100 tokens per skill |
| 2. Instructions | SKILL.md body | The skill activates | Under 5000 tokens; under 500 lines |
| 3. Resources | scripts/, references/, assets/ | The instructions point to them | Keep references one level deep |
The context stays small because 50 installed skills cost 50 short descriptions, not 50 manuals. A script that runs also costs only its output, not its source. Source: agentskills.io spec, Anthropic best practices.
Open standard and where skills live
Skills follow the open Agent Skills format at agentskills.io, so a well-formed skill is not tied to one vendor. This page uses Claude Code paths; check your harness docs for others (see Agent Harnesses).
| Location | Path | Scope |
|---|---|---|
| Enterprise | managed settings | All users in the organization |
| Personal | ~/.claude/skills/<name>/SKILL.md | All your projects on this machine |
| Project | .claude/skills/<name>/SKILL.md | This repo: commit it so the team shares it |
| Nested | <subdir>/.claude/skills/<name>/SKILL.md | Sessions in or below that subdirectory |
| Plugin | <plugin>/skills/<name>/SKILL.md | Invoked as /plugin-name:skill-name |
On a name collision, enterprise wins over personal, and personal over project (Claude Code docs). For client work, prefer project skills in the client repo only if the client agrees to host them; otherwise keep them personal or in a Lieber plugin.
Automatic versus slash invocation
Claude uses a skill when its description matches the request, or you invoke it directly with /skill-name. Two frontmatter switches control this (Claude Code docs):
| Field | Effect |
|---|---|
disable-model-invocation: true | Only you can invoke it (use for skills with side effects, such as deploys or commits) |
user-invocable: false | Only the agent invokes it (background knowledge) |
Skill, AGENTS.md, rule, MCP server, hook, or subagent?
| Need | Use | Why | Example |
|---|---|---|---|
| Facts the agent needs in every session | AGENTS.md / CLAUDE.md | Always loaded, so keep it short | "Run mise run test; services live in services/" |
| Guidance for certain files only | Path-scoped rule (.claude/rules/) | Loads when matching files are touched | "Terraform files: always run tofu fmt" |
| A multi-step procedure used sometimes | Skill | Loads on demand; can bundle scripts | Write an ADR; cut release notes |
| Access to an external system or live data | MCP server | Gives tools, not instructions | Query GitHub issues; read AWS docs |
| Something that must happen every time | Hook | Enforced by the harness, not by the model's memory | Format after each edit; block edits to .env |
| A separate task with its own context | Subagent | Own context window; returns only a summary | Review a diff with fresh eyes; search the codebase |
Rules of thumb: instructions that can be ignored go in context (AGENTS.md, rules, skills); behavior that cannot be ignored goes in a hook (Hooks, Pre-commit, and Quality Gates). Skills and MCP complement each other: MCP provides the tool, a skill teaches the workflow that uses it (Anthropic: Agent Skills). See AGENTS.md, CLAUDE.md, and Rules and MCP Servers for the others.
Writing the description (the trigger)
The description decides whether the skill ever fires. Anthropic's guidance: write in the third person, say what the skill does and when to use it, and name the user phrases that should trigger it (best practices).
| Weak | Strong |
|---|---|
Helps with documents | Writes an Architecture Decision Record into docs/adr from the current discussion. Use when the user says "record this decision", "write an ADR", or a design choice was just agreed. |
I can help you write ADRs (first person) | Generates ADRs ... (third person) |
Size limits
| Limit | Value | Source |
|---|---|---|
name | 1 to 64 chars; lowercase letters, digits, hyphens; must match the folder name | agentskills.io |
description | 1 to 1024 chars, non-empty | agentskills.io |
| Description in Claude Code's skill listing | description plus when_to_use truncated at 1,536 chars | Claude Code docs |
SKILL.md | Keep under 500 lines; body under 5000 tokens | agentskills.io |
| Reserved words | anthropic and claude not allowed in name (Anthropic API) | best practices |
(as of 2026-10)
How to do it
Create a skill step by step
- Notice a repeated workflow. You pasted the same instructions three times, or corrected the same agent mistake twice. Anthropic recommends building skills from observed gaps rather than guessing (Anthropic: Agent Skills).
- Write
SKILL.md. Add only what the model does not already know: your conventions, paths, output format. Default assumption from Anthropic: the model is already very capable (best practices). - Add scripts for deterministic steps. Anything with one right answer (date stamps, next ADR number, running linters) belongs in a script. Choose the degree of freedom to fit the task: prose for flexible steps, exact scripts for fragile ones.
- Test with and without the skill. Run the same prompt in a fresh session twice. The skill earns its place only if the output is measurably better.
- Iterate. Fix the description if it did not trigger (or triggered wrongly); fix the body if the output drifted.
- Share. Commit to
.claude/skills/or package in a plugin (below).
Use Anthropic's skill-creator
Anthropic publishes a skill-creator skill in anthropics/skills. Install it in Claude Code:
/plugin marketplace add anthropics/skills
/plugin install example-skills@anthropic-agent-skills
Its workflow: capture intent, draft the skill, save test prompts to evals/evals.json, run each prompt with and without the skill (two subagents in the same turn), grade the outputs, review them in an eval viewer, rewrite, and rerun into the next iteration folder. It can also optimize the description using trigger queries (skill-creator SKILL.md).
Evals for skills
Anthropic's guidance is evaluation-driven development: build evals before writing extensive documentation (best practices).
- Write at least three realistic test prompts (the checklist asks for three).
- Record the baseline: run them without the skill.
- Write minimal instructions that close the gap.
- Rerun; compare against the baseline; grade with assertions you can check (file exists, section present, command exited 0).
- Test with each model you plan to use (Haiku, Sonnet, Opus).
The best-practices guide notes there is no built-in way to run these evaluations, which is why skill-creator ships its own runner. Also add trigger evals: prompts that should fire the skill and near-miss prompts that should not.
Example 1: adr
Writes an Architecture Decision Record into docs/adr from the current discussion. The script picks the next number so the agent does not guess.
.claude/skills/adr/
├── SKILL.md
├── scripts/next-adr-number.sh
└── assets/adr-template.md
---
name: adr
description: Writes an Architecture Decision Record into docs/adr from the current discussion. Use when the user says "write an ADR", "record this decision", or a design choice was just agreed and should be documented.
---
# Write an ADR
1. Run `scripts/next-adr-number.sh` to get the next number and file name slug
prefix. Never pick the number yourself.
2. Copy `assets/adr-template.md` to `docs/adr/<number>-<kebab-title>.md`.
3. Fill every section from the current conversation. Do not invent facts:
if the context, options, or consequences are not in the discussion, ask
the user instead of guessing.
4. List at least two considered options with the reason each was accepted or
rejected.
5. Set Status to `Proposed` unless the user says the decision is final.
6. Add a one-line entry to `docs/adr/README.md` if that file exists.
7. Show the user the file path and a three-line summary.
#!/usr/bin/env bash
# Prints the next zero-padded ADR number, e.g. 0007
set -euo pipefail
dir="${1:-docs/adr}"
mkdir -p "$dir"
last=$(ls "$dir" | grep -E '^[0-9]{4}-' | sort | tail -1 | cut -c1-4 || true)
printf '%04d\n' $((10#${last:-0000} + 1))
# <number>. <Title>
- Status: Proposed
- Date: <YYYY-MM-DD>
- Deciders: <names>
## Context
What problem or constraint forced a decision?
## Decision
What we will do, in one or two sentences.
## Options considered
- Option A: why accepted or rejected
- Option B: why accepted or rejected
## Consequences
What gets easier, what gets harder, what we must revisit.
Why this works: the number comes from a script (deterministic), the template keeps the format identical across ADRs, and the "do not invent facts" step keeps the agent honest. See Scratchpads, Memory, and Markdown Knowledge Bases for where ADRs fit in a knowledge base.
Example 2: post-change-update
After a change, this skill runs the formatters and linters, updates the relevant docs, the execution plan's progress log, and the scratchpad. Make it user-invoked (/post-change-update) because it edits several files.
.claude/skills/post-change-update/
├── SKILL.md
└── scripts/run-checks.sh
---
name: post-change-update
description: Closes out a code change. Runs formatters and linters, updates affected docs, appends to the execution plan progress log, and refreshes the scratchpad. Use after finishing a task, before committing, or when the user says "post update" or "wrap up this change".
disable-model-invocation: true
---
# Post-change update
Run these steps in order. Stop and report if a step fails.
1. **Checks.** Run `scripts/run-checks.sh`. If it reports failures, fix them
and rerun until it exits 0. Do not skip or disable a rule to pass.
2. **Scope.** Run `git diff --stat` and `git status --short` to list what
changed in this task.
3. **Docs.** For each changed module, find docs that mention it
(`grep -rn "<module or command>" README.md docs/`). Update statements that
are now wrong. Do not rewrite unaffected text.
4. **Plan.** Open the current execution plan (the file under `plans/` whose
status is in progress). Tick the finished task, append a dated line to
`## Progress`, and add anything unexpected to `## Surprises & Discoveries`
or `## Decision Log`.
5. **Scratchpad.** Update the session scratchpad: what is done, what is
next, open questions. Keep it under 30 lines.
6. **Report.** Print: checks result, files updated, next task from the plan.
Do not commit unless the user asks.
#!/usr/bin/env bash
# Format, then lint, only what this repo uses. Exit non-zero on failure.
set -uo pipefail
rc=0
if [ -f pyproject.toml ] && command -v ruff >/dev/null; then
ruff format . && ruff check --fix . || rc=1
fi
if [ -f biome.json ] && command -v biome >/dev/null; then
biome check --write . || rc=1
fi
if [ -f go.mod ] && command -v golangci-lint >/dev/null; then
golangci-lint fmt && golangci-lint run || rc=1
fi
if ls ./*.tf >/dev/null 2>&1 && command -v tofu >/dev/null; then
tofu fmt -recursive || rc=1
fi
exit $rc
The plan sections (Progress, Surprises & Discoveries, Decision Log) follow the ExecPlan format described in Execution Plans (OpenAI cookbook). Pair this skill with an edit-time hook: the hook formats every edit, the skill does the thorough close-out (Hooks, Pre-commit, and Quality Gates). The tools themselves are explained in The Agent-Ready Toolchain.
Share skills via plugins
A Claude Code plugin bundles skills, agents, hooks, and MCP servers; its manifest is .claude-plugin/plugin.json, and a marketplace lists plugins in .claude-plugin/marketplace.json (plugins docs). Plugin skills are invoked as /plugin-name:skill-name. An enabled plugin adds its skill names and descriptions to every session's context, so install only what you use.
Review third-party skills like code
A skill can include scripts that run with your credentials. Before installing one from a marketplace or a repo, read SKILL.md, every file in scripts/, and any network calls, exactly as you would review a dependency. Anthropic's skills post makes the same recommendation: audit skills from third parties before installing (Anthropic: Agent Skills). Note licensing: many skills in anthropics/skills are Apache 2.0, but the document skills (docx, pdf, pptx, xlsx) are source-available, not open source (anthropics/skills).
Best practices
- Keep
SKILL.mdshort and move detail intoreferences/, one level deep. - One skill, one job. Split a skill that has two unrelated triggers.
- Use consistent terms inside a skill; avoid time-sensitive statements.
- Name skills clearly (
adr,release-notes); avoidhelper,utils,tools. - Use forward slashes in paths.
- Test with every model your team runs.
- Validate the format with the reference validator:
skills-ref validate ./my-skill(agentskills.io). - Mark side-effect skills
disable-model-invocation: true.
Pitfalls to design around
- Write the description before the body, and test that it fires: a perfect skill with a vague description never runs.
- Put exact commands in scripts, not prose, whenever one correct answer exists.
- Keep always-true facts in
AGENTS.md; a skill that must load every session should be context, not a skill. - Pin and review plugins; do not auto-install marketplaces on client machines.
- Keep skills free of secrets and client data, since project skills are committed.
- Delete or update skills when the workflow changes; stale instructions are worse than none.
Try it
Lab (20 min)
- In a real repo, create
.claude/skills/adr/with the files above anddocs/adr/if missing. - In a fresh session, discuss a small design choice with the agent, then ask it to "write an ADR for that". Confirm the skill fires and the number comes from the script.
- Disable the skill (rename the folder) and repeat the same prompt. Compare: format, numbering, invented facts.
- Add
post-change-update, make a one-line code change, run/post-change-update, and check the plan and scratchpad edits. - Write three trigger prompts that should fire
adrand two that should not; check each.
Checklist
- The skill solves a workflow I repeated at least three times.
-
namematches the folder and is at most 64 chars;descriptionis third person, says what and when, under 1024 chars. -
SKILL.mdis under 500 lines; detail lives inreferences/. - Deterministic steps are scripts, and the scripts run on a clean checkout.
- I compared output with and without the skill on at least three prompts.
- Side-effect skills set
disable-model-invocation: true. - Third-party skills and their scripts were read before install.
- The skill is committed or packaged in a plugin, with an owner.
Sources
- Claude Code, Extend Claude with skills: https://code.claude.com/docs/en/skills (locations, precedence, invocation, frontmatter, 1,536-char listing cap; as of 2026-10)
- Agent Skills specification (open standard): https://agentskills.io/specification (fields, limits, three tiers,
skills-ref validate) - Anthropic, Skill authoring best practices: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices (description guidance, evals, reserved words)
- Anthropic Engineering, Equipping agents for the real world with Agent Skills: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
- anthropics/skills repository: https://github.com/anthropics/skills (install commands, licensing)
- skill-creator: https://raw.githubusercontent.com/anthropics/skills/main/skills/skill-creator/SKILL.md
- Claude Code plugins: https://code.claude.com/docs/en/plugins
- OpenAI Cookbook, Using PLANS.md for multi-hour problem solving: https://developers.openai.com/cookbook/articles/codex_exec_plans