AI agent skills: a practical guide for development teams

Your team has licenses for Claude Code, Cursor or Copilot. Every developer has found their own tricks: prompts that work, instructions that give good results, ways of asking for code reviews that produce useful feedback. The problem is that this knowledge lives in each person's head. When someone leaves, they take their prompts with them. When someone new joins, they start from scratch.

Skills solve exactly this. They are the standard mechanism for packaging instructions, scripts and knowledge into reusable units that any AI agent can discover and execute. It's not a theoretical concept: the Claude Code team at Anthropic has hundreds of Skills in active use, and describes them as the most-used extension point of the tool.

But their flexibility is also their risk. A poorly written Skill burns tokens without adding value, confuses the agent or, worse, produces inconsistent results the developer accepts without reviewing. This guide distills the lessons published by Anthropic, the patterns that work in real teams, and the mistakes we've seen across 12 transformations.

What a Skill is and why it matters

A Skill is a SKILL.md file with instructions that an AI agent loads when they're relevant. The idea is simple: instead of repeating the same instruction every time you need something, you write it once, package it, and let the agent discover it automatically or invoke it on demand with /skill-name.

But a Skill is more than a text file. It's a directory that can contain:

• SKILL.md (required): the main instructions with YAML metadata.
• Reference files: detailed documentation the agent loads only when it needs it.
• Executable scripts: code the agent runs directly, without having to generate it.
• Templates: templates the agent fills in based on the context.
• Examples: input/output pairs that show the expected format.

Open standard: Skills follow the Agent Skills standard, which means they work across multiple AI tools, not just Claude Code. It's a portable format by design.

The typical structure of a Skill with medium complexity:

my-skill/
├── SKILL.md              # Main instructions (required)
├── reference.md          # Detailed documentation (loaded on demand)
├── examples.md           # Usage examples
├── templates/
│   └── template.md       # Template to fill in
└── scripts/
    └── validate.sh       # Script the agent executes

Anatomy of an effective SKILL.md

Every SKILL.md has two parts: a YAML frontmatter with metadata and a Markdown body with instructions.

The frontmatter: metadata that guides the agent

The frontmatter defines when and how the Skill is used. The key fields:

The body: two types of content

According to Anthropic, thinking about what type of content your Skill contains helps you decide how to structure it:

Lessons from the Claude Code team

Thariq Shihipar, from the Anthropic team, published a series of articles on the lessons learned building Claude Code. In "How We Use Skills," he shares what they've discovered managing hundreds of Skills internally. These are the lessons with the most impact:

1. The "Gotchas" section is the highest-value content

The best Skills started as a few lines and a warning about something that could go wrong. That warning — the gotcha — is what makes the difference. It's information the agent can't infer from the code: a subtle edge case, an unexpected API behavior, an undocumented convention.

In practice: Every time an agent makes a mistake using your Skill, add a gotcha. Anthropic's most useful Skills have accumulated gotchas over months. They weren't born perfect. They evolved with use.

2. Don't repeat what the agent already knows

Claude (and other advanced models) knows a lot about programming, frameworks and common patterns. Explaining what a PDF is or how a popular library works is spending tokens without adding value.

Anthropic's rule: if you're publishing a Skill that is mostly knowledge, focus on information that pushes the agent out of its default way of thinking. The exceptions, the edge cases, your team's decisions that differ from the default pattern.

3. Give information, not excessive constraints

The agent will try to follow your instructions to the letter. If you're too specific, you lose the agent's ability to adapt to the real context. If you're too vague, you add no value.

The balance depends on the risk:

4. The file system is progressive disclosure

Not all information should be loaded all the time. Anthropic's Skills use the file system as a progressive disclosure mechanism: the SKILL.md contains the essentials and points to reference files the agent loads only when it needs them.

This isn't a minor optimization. The context window is a shared resource. Your Skill competes with the conversation history, other Skills, the system prompt and the user's current request. Every token counts.

Rule of thumb: SKILL.md should be under 500 lines. If you need more, move the detailed content to separate files and reference them from SKILL.md. References should be one level deep only: SKILL.md → reference.md (not SKILL.md → advanced.md → details.md).

5. Develop Skills iteratively with the agent itself

The most effective process Anthropic uses internally follows a two-instance pattern:

• Claude A (the expert): helps you create and refine the Skill.
• Claude B (the user): uses the Skill on real tasks and reveals the gaps.

The cycle: complete a task without the Skill → identify what context you had to provide manually → ask Claude A to package it as a Skill → test with Claude B → observe where it fails → go back to Claude A to refine.

This cycle is exactly what our Spec-Driven Development methodology calls iteration over specifications: knowledge is codified, tested and continuously improved.

5 patterns that work

These patterns appear again and again in the most effective Skills, both internal to Anthropic and in teams we've transformed:

1. Template pattern

You provide a template the agent fills in. Useful when you need a consistent output format: commit messages, reports, technical documentation. The degree of rigidity depends on the case: strict for API formats, flexible for analysis.

2. Examples pattern (input/output)

Example pairs that show the expected format. More effective than describing the format in words. The agent understands the style and level of detail you expect by seeing concrete examples, not by reading abstract rules.

3. Workflow pattern with a checklist

For complex multi-step operations, provide a checklist the agent copies and checks off as it progresses. This prevents it from skipping critical steps, especially in validation processes.

## Deploy workflow
Copy this checklist and mark your progress:

- [ ] Step 1: Run the test suite
- [ ] Step 2: Build the application
- [ ] Step 3: Push to the deploy target
- [ ] Step 4: Verify the deploy succeeded
- [ ] Step 5: Smoke test in production

4. Config pattern

You store configuration in a config.json inside the Skill's directory. If it doesn't exist, the agent asks the user for the data. This lets the same Skill work in different environments without modifying the instructions.

5. Dynamic injection pattern

Skills that run shell commands before sending the content to the agent. The syntax !`command` runs the command and replaces the placeholder with the result. The agent receives real data, not the command.

A practical example: a code review Skill that runs !`git diff` to inject the real changes into the prompt before the agent analyzes them.

Anti-patterns that destroy Skills

These mistakes are as common as they are damaging. We've seen them repeatedly:

Overly verbose Skill

Explaining what a PDF is, how Python decorators work, or what git commit does. The agent knows this. Every unnecessary paragraph is context that displaces useful information. The rule: if you can assume the agent knows it, don't include it.

Too many options

"You can use pypdf, pdfplumber, PyMuPDF or pdf2image..." This doesn't help, it paralyzes. Provide a clear default and one alternative for the exceptional case. Nothing more.

Nested references

SKILL.md points to advanced.md, which points to details.md, which contains the real information. The agent may only partially read files referenced from other referenced files. Keep references one level deep.

Information that expires

"If you're doing this before August 2025, use the v1 API." This turns into misinformation the moment the date passes. Use "legacy pattern" sections with collapsible details if you need historical context.

Inconsistent terminology

Mixing "API endpoint," "URL," "route" and "path" to refer to the same thing. The agent doesn't know they're synonyms in your context. Pick one term, use it consistently.

The real cost: A poorly written Skill isn't harmless. It consumes tokens from the context window, reduces the agent's response quality on other tasks and, if it produces subtly incorrect results, it generates technical debt that goes unnoticed until it's too late.

Skills as a team: from the individual to the organizational

The real power of Skills appears when they stop being individual tools and become shared team knowledge. There are four levels of distribution:

The Anthropic team describes how they've built an internal plugin marketplace where Skills that gain traction organically are promoted to the official marketplace via PR. There's no centralized team deciding which Skills to use: adoption is bottom-up.

This model reflects what we see in the most effective teams: knowledge isn't imposed top-down. It's discovered, validated and scaled.

Skills and Spec-Driven Development: two sides of the same coin

If you've read our insights on context engineering and Spec-Driven Development, you'll see that Skills are the practical implementation of both concepts:

• Context engineering defines the discipline of designing and managing AI context. Skills are its packaging and distribution mechanism.
• SDD establishes that work with AI should start from structured specifications. A Skill is a specification: it defines what the agent must do, with which tools, following which pattern, and which errors to avoid.

In our methodology, Skills are part of the project constitution: the set of rules and knowledge the AI must respect. Together with the specification templates, the prompt playbooks and the code review checklists, Skills complete the system that makes the AI produce consistent results aligned with the team's standards.

The practical difference: A team without Skills repeats instructions in every conversation. A team with Skills writes the instruction once and the system distributes it. At scale, this translates into a 75% reduction in time per feature and a 40% increase in code consistency.

How to start: a checklist for your first Skill

You don't need to build a complete system from day one. Start with one Skill, measure the impact and scale. This is the path:

1. Identify a repetitive task. Something your team explains to the AI more than three times a week. Commit messages, code reviews, component migrations, test configuration.
2. Complete the task with the agent, without a Skill. Observe what context you have to provide manually. Note the corrections you make.
3. Create the minimal Skill. Just the SKILL.md with basic frontmatter and the essential instructions. No extra files. No scripts.
4. Test with a real case. Not a made-up example. Observe where the agent fails or succeeds.
5. Add gotchas. Every agent mistake is a potential gotcha. Add it to the Skill.
6. Commit to the repository. Put it in .claude/skills/ so the whole team inherits it.
7. Iterate. The Skill will improve with every real use. Don't try to make it perfect at the start.

---
name: code-review
description: Reviews code following the project's
  conventions. Use when the user asks for a review or before
  committing changes.
---

When reviewing code, follow these steps:

1. Verify it meets the conventions in CONVENTIONS.md
2. Look for possible bugs or uncovered edge cases
3. Suggest readability improvements only if significant
4. Flag as a "gotcha" any pattern that could be confusing

## Gotchas for this project
- React hooks must follow the useXxxQuery pattern
  (not useGetXxx)
- Never use any in API response types
- Integration tests require the --run-db flag

The future: Skills as a competitive advantage

We're at an inflection point. Generative AI is no longer differentiated by the model: every team has access to the same LLMs. The differentiation lies in how you configure and steer that AI.

Teams that treat Skills as an engineering asset — versioned, tested, distributed, continuously improved — will have a compounding advantage. Every Skill that works reduces friction for the whole team. Every gotcha added prevents an error that would have cost hours of debugging. Every shared pattern eliminates variability in the quality of the output.

The question isn't whether your team needs Skills. It's how long you can afford to keep going without them.

Frequently asked questions

What is a Skill for an AI agent?

A Skill is a directory containing a SKILL.md file with instructions the agent loads when they are relevant. Beyond the main file it can include reference documentation, executable scripts, templates and input/output examples. It follows the open Agent Skills standard.

How is a Skill different from a saved prompt?

A prompt is repeated every time you need it; a Skill is written once, packaged, and the agent discovers it automatically or invokes it on demand. Unlike a prompt, it can carry scripts, templates and documentation the agent loads only when required.

What should a SKILL.md contain?

YAML metadata in the frontmatter, telling the agent when to load it, and a body with the instructions. The most valuable part is usually the gotchas section: what goes wrong and is not obvious to someone who has not hit it before.

Why do Skills fail?

Four common anti-patterns: being too verbose — explaining what the agent already knows displaces useful context — offering too many options instead of one clear default, chaining nested references more than one level deep, and including information with an expiry date.

How does a team start building its own Skills?

Iteratively, and with the agent itself: write a minimal version, test it on real tasks and fix what breaks. The goal is to get the knowledge out of individual heads and into a place the whole team can use.

Written by

Jordi García

Tech Lead at onext

Jordi García is Tech Lead at onext. He works on bringing AI into governed production across development and product teams —with Spec-Driven Development, context engineering and human verification at every step— and authors onext's technical insights on the method, quality and cost of applied AI.

LinkedIn →