# What Are Agent Skills? A Practical Guide to SKILL.md Files Most people using AI coding agents are still doing the same thing over and over. They explain the repo. The workflow. The coding standards. The same gotchas they explained last week. Then the agent forgets all of it next session. That is what **Skills** are trying to fix. A Skill packages repeatable instructions, workflows, and reference material into a folder an AI agent can find and load when needed. If prompts are what you say right now, Skills are what you teach the agent once so you stop repeating yourself. ## What Is a Skill? A Skill is a folder that usually looks something like this: ```text writing-blog-posts/ ├── SKILL.md ├── references/ │ ├── writing-style.md │ └── repo-format.md └── scripts/ └── validate-post.sh ``` The required file is `SKILL.md`. That file tells the agent: - What the skill does - When to use it - What workflow to follow - Which reference files matter - Which scripts or checks can help - What mistakes to avoid Anthropic describes Skills as folders of instructions, scripts, and resources that agents can load dynamically. That is accurate, but the simpler version is: **A Skill is an onboarding guide for an AI agent.** Not for a human. For the agent. ## What SKILL.md Actually Does `SKILL.md` is the entry point. At the top, YAML frontmatter: ```md --- name: writing-blog-posts description: Creates blog posts in the site's house style. Use when the user asks to write, draft, edit, or publish a blog post. --- ``` Then Markdown instructions: ```md # Writing Blog Posts ## Workflow 1. Read the writing style guide. 2. Review 2-3 nearby posts. 3. Draft the post in the correct folder. 4. Run formatting and build checks. 5. Open a pull request for review. ## References - For style, read `references/writing-style.md`. - For frontmatter, read `references/repo-format.md`. ``` The frontmatter helps the agent decide whether the skill applies. The body tells it how to do the work. The extra files give it more detail only when the task needs them. ## Skills Are Not Just Long Prompts A Skill is not a giant prompt dumped into the context window. If you treat it that way, you will write bad Skills. The better mental model: **a Skill is a loader specification.** You are deciding what information gets loaded, when, and how much context it costs. Anthropic calls this **progressive disclosure**. Three levels: 1. **Metadata**: The `name` and `description` in the YAML frontmatter. Always visible so the agent can decide when to trigger the Skill. 2. **SKILL.md body**: The main instructions. Loads only when the agent decides the Skill applies. 3. **References, scripts, and assets**: Extra files that load or run only when needed. This matters. If you put everything into one giant `SKILL.md`, the agent loads all of it every time. If you keep `SKILL.md` lean and move details into references, the agent loads only what the task needs. ## The Kitchen Analogy Think of the agent as a chef. The model is smart, but it does not know your kitchen. It does not know where the ingredients are, which recipes your team likes, what customers complain about, which ovens run hot, or which dish always needs extra prep. A Skill gives it that operating knowledge. - The **frontmatter** is the menu title: "Use this for pasta night." - The **SKILL.md body** is the recipe card. - The **references** are the binder with detailed notes. - The **scripts** are appliances the chef can run instead of doing everything by hand. The chef does not need the entire binder in front of them for every meal. They need the right recipe at the right time. ## What Skills Are Good For Skills work when you have a repeatable pattern you want the agent to follow consistently. Good use cases: - Writing blog posts in a consistent style - Creating pull requests in a specific repo format - Turning product ideas into PRDs - Breaking PRDs into implementation issues - Running a TDD workflow - Reviewing code against team standards - Creating reports from a known data source - Using an MCP server correctly - Generating documents with a consistent structure - Remembering project-specific gotchas If you find yourself saying the same thing to the agent three times, it probably belongs in a Skill. ## What Skills Are Not Skills are useful, but not magic. They are not: - A replacement for good prompts - A replacement for tests - A replacement for MCP servers - A replacement for project documentation - A way to make a bad workflow good - A guarantee the agent will always behave perfectly - A place to dump everything you know about a project That last one matters. A bloated Skill can make the agent worse. The context window is not free real estate. Every token you load competes with the user's request, conversation history, file contents, tool output, and error messages. A good Skill is not the longest instruction file you can write. It is the smallest amount of reusable guidance that reliably improves the agent's work. ## Skills vs Prompts vs AGENTS.md vs MCP These terms get mashed together, so here is the practical distinction. A **prompt** is for this conversation. ```text Write this post in a practical developer-to-developer style. ``` A **Skill** is for repeatable workflows. ```text Whenever writing posts for this site, follow this repo structure, style guide, validation process, and PR workflow. ``` An **AGENTS.md** or similar project instruction file is broad project context. ```text This repo uses pnpm, tests live in __tests__, never edit generated files, and PRs require a build. ``` An **MCP server** gives the agent access to tools or data. ```text Read Linear issues, create GitHub tickets, query Postgres, fetch Sentry errors. ``` A Skill can teach the agent how to use those tools well. MCP gives the agent the kitchen. Skills give it the recipes. ## A Tiny Example Skill Here is a simple Skill for clarifying plans before writing code: ```md --- name: grilling-ideas description: Interviews the user to clarify plans before implementation. Use when the user asks to plan a feature, validate an idea, or says "grill me". --- # Grilling Ideas Interview the user about the plan until there is a shared understanding. Focus on: - The goal - The user experience - Edge cases - Dependencies - Trade-offs - Failure modes - What can be verified by checking the codebase For each question, include your recommended answer when there is an obvious one. Stop when the implementation path is clear enough to write a short plan. ``` No giant manifesto. No 40-step process. No explanation of what planning is. Just a clear, reusable behavior. And it can be short — one thing people who use Skills heavily learn quickly is that a focused, short Skill often outperforms a long one. ## How to Create Your First Skill Start small. Pick one annoying repeated workflow. Something like: - "Write release notes from merged PRs" - "Create a blog post in my site format" - "Review a PR for security issues" - "Turn a vague feature idea into implementation issues" - "Debug a bug by reproducing first, then instrumenting" Create a folder: ```bash mkdir -p writing-release-notes/references writing-release-notes/scripts cd writing-release-notes touch SKILL.md ``` Your first `SKILL.md` can be this simple: ````md --- name: writing-release-notes description: Writes concise release notes from git history, merged PRs, or changelog entries. Use when the user asks for release notes, changelog summaries, or version announcements. --- # Writing Release Notes ## Workflow 1. Identify the release range or version. 2. Gather merged PRs, commits, or changelog entries. 3. Group changes into Features, Fixes, Breaking Changes, and Internal. 4. Write for users first, developers second. 5. Mention migration steps if there are breaking changes. ## Output Format ```md ## Highlights - ... ## What's Changed ### Features - ... ### Fixes - ... ### Internal - ... ## Upgrade Notes - ... ``` ## Verification Before finalizing, check that every major change maps back to a PR, commit, or changelog entry. ```` Then use it. Watch where the agent still gets confused. Add only the missing guidance. ## The Frontmatter Is More Important Than You Think The `description` field is how the agent decides whether to load the Skill. Bad: ```yaml description: Helps with writing. ``` Better: ```yaml description: Writes release notes from git history, merged PRs, or changelog entries. Use when the user asks for release notes, changelog summaries, changelogs, or version announcements. ``` A good description says what the Skill does, when to use it, and what trigger phrases the user might say. This is one of the highest-leverage parts of the file. A vague description means the agent may never load the Skill. One that is too broad means it loads when it should not. ## Keep SKILL.md Lean Anthropic recommends keeping the main `SKILL.md` short and moving details into linked files as the Skill grows. ```text blog-writing/ ├── SKILL.md ├── references/ │ ├── writing-style.md │ ├── frontmatter.md │ └── pr-workflow.md └── scripts/ └── validate-post.sh ``` `SKILL.md` becomes the map: ```md ## References - For voice and tone, read `references/writing-style.md`. - For frontmatter rules, read `references/frontmatter.md`. - For PR steps, read `references/pr-workflow.md`. ``` The agent opens those files only when the task needs them, not on every run. ## Use Scripts for Deterministic Work A Skill can include scripts, and this is worth doing more than most people realize. If something needs to be exact, do not ask the model to wing it. Use code. Examples: - Validate frontmatter - Count words - Check links - Parse CSVs - Generate reports - Extract PDF fields - Run a formatting command - Compare output against a schema Scripts have two advantages: they are deterministic, and the agent usually only needs the output, not the script contents loaded into context. That makes them both more reliable and often cheaper to run. Use natural language where judgment matters. Use code where precision matters. ## Add Gotchas This is where Skills become genuinely useful. The model has general knowledge. Your project has weird specifics. Put the weird specifics in the Skill. ```md ## Gotchas - Run the build from the repo root, not inside `apps/web`. - Do not edit generated files under `src/generated`. - Blog posts must use single quotes in frontmatter. - Always check `git diff` before committing. - If the test runner hangs, run the focused test file instead of the full suite. ``` These are things the agent will not reliably infer. A good gotchas section saves you from correcting the same mistakes over and over. ## Test the Skill Like Software Skills are part of your agentic system, so treat them like it. You do not need a sophisticated evaluation setup. Three types of tests will tell you most of what you need to know. ### 1. Trigger Tests Make sure the Skill loads when it should. Should trigger: ```text Write release notes for v2.4.0. Summarize the changelog for this release. Turn these merged PRs into a version announcement. ``` Should not trigger: ```text Write a birthday card. Explain semantic versioning. Create a spreadsheet. ``` If it under-triggers, improve the description with better keywords. If it over-triggers, make the description more specific. ### 2. Functional Tests Run real tasks and check whether the output follows the workflow. For a release notes Skill, ask: - Did it group changes correctly? - Did it miss any major PRs? - Did it invent changes? - Did it include upgrade notes when needed? - Did it cite the source PRs or commits? This is where you learn what instructions are missing. ### 3. Baseline Comparison Run the same task with and without the Skill. - Is the output better? - Did it take fewer clarifying messages? - Did it use fewer tool calls? - Did it avoid known mistakes? - Did it produce a more consistent structure? A Skill is only worth keeping if it improves the agent's work compared to not having it. ## Common Mistakes **Making one giant Skill.** Do not create a 1,500-line `SKILL.md`. Keep the main file short. Move details into references. Use scripts for exact operations. **Vague descriptions.** The description is routing logic, not a tagline. Be specific. Tell the agent when to use the Skill and what trigger phrases to watch for. **Hardcoding your local machine.** If you want to share the Skill, avoid paths like `/Users/travis/projects/my-app`. Prefer discovery instead: ```md Find the repo root by locating `package.json` and `.git`. ``` Skills break when they assume too much about one environment. **Teaching the agent what it already knows.** You do not need to explain what Markdown is. You do not need a history of Git. Assume the model is smart. Spend tokens on your process, constraints, examples, and gotchas. **Never updating the Skill.** When the agent makes the same mistake twice, update the Skill. When your process changes, update the Skill. When a new model interprets it differently, test and tune it. These files need maintenance. ## A Practical SKILL.md Template Here is a starter template I would actually use: ````md --- name: your-skill-name description: Does [specific job]. Use when the user asks to [trigger phrase], [trigger phrase], or [related task]. --- # Your Skill Name ## Goal State the outcome this Skill should produce. ## Workflow 1. Do the first important thing. 2. Gather the needed context. 3. Execute the core task. 4. Verify the result. 5. Report the outcome clearly. ## Rules - Keep the diff small. - Do not modify unrelated files. - Ask before destructive actions. - Prefer focused checks before full-suite checks. ## References - Read `references/style.md` for writing style. - Read `references/repo.md` for repo-specific conventions. ## Scripts Use these when relevant: ```bash scripts/validate.sh ``` ## Gotchas - Add project-specific traps here. ## Done Criteria The task is complete when: - The output exists in the expected location. - Validation passes. - Any assumptions are documented. ```` ## Are Skills Useful for You? Probably, if you use agents regularly. Especially if you catch yourself saying things like: - "Remember to follow our style guide." - "No, run the build from the root." - "Use our PR template." - "Don't touch that generated folder." - "Ask me questions before writing code." - "Break this into issues first." - "Use TDD for this." - "Check the docs before assuming." Those are Skills waiting to happen. If you only use AI for occasional one-off questions, you probably do not need any yet. Skills are most useful when the work repeats. ## My Recommendation Do not start with ten Skills. Start with one. Pick the workflow that annoys you most. For a developer, I would probably start with one of these: 1. **Planning Skill**: Forces the agent to ask clarifying questions before coding. 2. **TDD Skill**: Makes the agent write one failing test, pass it, then refactor. 3. **PR Skill**: Teaches the agent how your repo expects changes to be validated and submitted. 4. **Writing Skill**: Captures your blog/newsletter/docs style. 5. **Debugging Skill**: Requires reproduction, hypotheses, instrumentation, and verification before changing code. Build it. Use it five times. Each run will show you what's missing. Fix those gaps, and it gets better. ## Final Thoughts A folder. A `SKILL.md` file. Some references. Maybe a script or two. It does not look like much. But over time, you are encoding how your work actually gets done — not in documentation nobody reads, but in instructions an agent can actually follow. They help agents stop acting like brilliant interns with amnesia and start acting more like teammates who have read the onboarding docs. Not magic. Not a replacement for good engineering. But if you are serious about using AI agents for real work, they are worth learning. ## Sources Worth Reading - [Anthropic: Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) - [Anthropic: Agent Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) - [Anthropic: Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) - [Anthropic: The Complete Guide to Building Skills for Claude](https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf) - [Lax Meiyappan: What you're actually writing when you write a SKILL.md](https://internals.laxmena.com/p/what-youre-actually-writing-when) - [Matt Pocock / AI Hero: 5 Agent Skills I Use Every Day](https://www.aihero.dev/5-agent-skills-i-use-every-day) - [Matt Pocock / AI Hero: My Grill Me Skill Went Viral](https://www.aihero.dev/my-grill-me-skill-has-gone-viral)