Claude Code Agent Skills

The most common misconception is that a skill is "a markdown file with instructions." It isn't. A skill is a directory — a package of guides, scripts, templates, and data that Claude discovers gradually instead of cramming into the prompt.

#It's a directory, not a file

The old way dumps every instruction into the prompt — wasting tokens and inviting the model to forget. The skills approach loads a tiny bit of metadata up front and reads the full content only when the task actually needs it.

my-skill/
├── SKILL.md        # frontmatter (name + description) + the guide
├── references/     # docs read only when needed
├── scripts/        # runnable code — output enters context, not the code
├── assets/         # templates, images
└── examples/

#Progressive disclosure

Information loads in three levels, so the context window only ever holds what the current step requires:

#Why it matters

The context window is a shared resource — every token you embed competes with conversation history and the model's reasoning space. LLMs suffer "context rot": quality degrades as length grows, because attention has to weigh every pair of tokens.

#Nine categories

Anthropic groups its internal skills into nine kinds (guidance, not rules): library/API reference, product verification, data fetching & analysis, business process, code scaffolding, code quality & review, CI/CD & deployment, runbooks, and infrastructure ops.

#Writing a good skill

• The description is a trigger, not a summary. Say when to activate. Tuned descriptions lift activation rates dramatically (roughly 20% → 50%, and up to ~90% with examples).
• The Gotchas section is the most valuable part. List the failure points that push the model off its defaults, and keep updating them.
• Treat the file system as context engineering. Split references into separate files the model reads only when needed.
• Package scripts ahead of time. Claude composes existing scripts rather than writing them from scratch, and the code never enters context — only its output.
• Don't railroad. A skill is reused many times; give enough information but leave room to adapt.

# description: trigger vs summary
Poor:  "I help with Excel."
Good:  "Handle Excel files and create reports. Activate when the
        user asks about spreadsheet data, CSV analysis, or tabular output."

#A skill in action

Take a standup-post skill. Progressive disclosure plays out in three steps:

1. Claude scans metadata and recognizes the skill (~100 tokens).
2. You ask for a standup; it reads the SKILL.md body — procedure, format, gotchas (~2,000 tokens).
3. It runs scripts/fetch_activity.py to pull GitHub PRs and Jira tickets and compares against a log — only the output enters context.

One /standup-post command synthesizes multi-source activity into a consistent, formatted update.

#Ecosystem & a quality warning

There are 60K+ skills on GitHub, and quality varies wildly. One evaluator tested 47 popular skills and found 40 produced worse output than vanilla Claude Code — mostly shallow prompt wrappers that add latency without value.

#Start in five minutes

Create a directory, write a SKILL.md with frontmatter, and invoke it:

mkdir -p .claude/skills/my-first-skill

---
name: my-first-skill
description: "Describe WHEN TO TRIGGER, not a summary.
  e.g. Use when the user asks to do X, Y, or Z."
---
 
# Main guidance (keep under ~5,000 tokens)
 
Procedure:
1. ...
2. ...
 
## Gotchas
- Common pitfall #1
- Common pitfall #2
 
## References
See references/api-docs.md for details.

Or skip the boilerplate: run /skill-creator, the meta-skill that drafts a skill, optimizes the description, and evaluates its trigger rate for you.