AI Agent Skills: A Practical Engineering Guide

A skill is the playbook your agent reaches for the moment a task matches its job description.

If you have built anything with autonomous AI agents, you have probably hit the same wall: the model knows how to call tools, but it does not reliably know when to apply your team's specific procedure, in your specific order, with your specific verification step. Agent Skills are the answer to that gap. This guide explains what they are, how the loading model keeps your context window lean, and the engineering practices that separate a skill that quietly works from one that bloats every prompt.

A one-sentence definition: An Agent Skill is a reusable, versioned directory that packages procedural knowledge — a workflow — so an agent can discover it, load it on demand, and follow it step by step.

The conventions described here were cross-verified across three independent AI families — Claude (Anthropic), the OpenAI GPT family, and Google's Gemini family — which agreed on the core structure, the progressive-disclosure loading model, and the boundary between skills and tools. Where they differ is mostly vocabulary, not mechanics.

The Core Concept: SKILL.md and Progressive Disclosure

Every skill is a folder. At its root sits a single entry file, SKILL.md, with two parts:

1. YAML frontmatter — at minimum a name and a description. The description is not decoration. It is the activation trigger: the string the agent matches a user request against to decide whether this skill is relevant.
2. A markdown body — the actual playbook: principles, a step-by-step process, and a verification section that tells the agent how to confirm the work succeeded.

A typical layout:

my-skill/
├── SKILL.md            # frontmatter + body (kept small)
├── references/         # large docs loaded only when needed
│   └── api-details.md
└── scripts/            # executable helpers, relative paths
    └── validate.sh

A minimal SKILL.md frontmatter looks like this:

---
name: pdf-form-filler
description: >
  Fill, flatten, and validate PDF AcroForm fields from a JSON
  data map. Use when the user wants to populate a fillable PDF
  template or batch-generate filled PDFs from structured data.
---

Why the loading model matters

The reason skills scale is progressive disclosure — a three-stage loading strategy that keeps the context window small:

Stage	What the agent loads	Cost	When
Idle	Only each skill's name + description	Very low	Always available
Matched	The full SKILL.md body	Moderate	Request matches a description
Executing	Files in references/ and scripts/	On demand	The step actually needs them

At idle, an agent with fifty skills installed is carrying only fifty short descriptions — a few hundred tokens, not fifty full procedures. When a request matches a description, the agent reads that one skill's body. Only when a step explicitly needs a 400-line API reference or a helper script does that file enter context. This is the entire reason you can install many skills without drowning the model in irrelevant instructions.

This also reframes how you think about context budgets. If you are optimizing token usage across an agent system, skills are a structural lever, not just a prompt-trimming exercise — a theme we go deeper on in our companion LLM token cost optimization guide.

A note on accuracy while we are here: when you measure how much context a skill actually consumes, use the provider's own tooling. For Claude that means the count_tokens API, not tiktoken (which is OpenAI's tokenizer and gives inaccurate counts for Claude). And if your skill body instructs the model to "think harder" on a step, express that through adaptive thinking with effort levels (low through max) rather than a fixed token budget — the old fixed budget_tokens style of reasoning control is deprecated on current flagship models such as Claude Opus 4.8, GPT-5.5, and Gemini 3.5 Flash.

Best Practices Checklist

The difference between a skill the agent reliably picks up and one it ignores or misuses comes down to a handful of disciplines.

• Write a specific, exclusive description. This is the auto-routing key. "Helps with documents" is useless; "Extract tables from scanned invoices into CSV; use when the user has an invoice image and wants structured line items" routes correctly. Name the trigger conditions explicitly.
• One skill, one responsibility. A skill that does PDF filling and email sending and report formatting will match too broadly and confuse routing. Split it.
• Separate personal from project skills. Personal skills live in a user-level directory (e.g. ~/.claude/skills); project skills live in the repo (e.g. .claude/skills) and are version-controlled so the whole team — and CI — gets the same playbook.
• Keep large docs in references/. Never paste hundreds of lines of API documentation into the SKILL.md body. Link to a reference file; the agent loads it only when a step needs it. A bloated body defeats progressive disclosure.
• Make scripts self-contained with relative paths. A helper in scripts/ should run from the skill directory without hard-coded absolute paths, so the skill is portable across machines and environments.
• Include an explicit verification step. The body should tell the agent how to confirm success — run the test, check the exit code, diff the output. Procedural knowledge without a check is half a procedure.
• Version and review skills like code. Because project skills are committed, treat changes to them as you would any pull request: review the description change especially, since it alters routing behavior for everyone.
• Use a skill-creator meta-skill. A small "skill that writes skills" enforces your frontmatter conventions, directory layout, and description style so new skills are consistent from day one.

A practical authoring loop for a project skill:

mkdir -p .claude/skills/release-notes/{references,scripts}
# author SKILL.md with a tight description + numbered steps
git add .claude/skills/release-notes
git commit -m "feat: add release-notes skill"

Common Misconceptions

Three misunderstandings show up repeatedly, and all three were flagged independently in the cross-AI review.

1. "A skill replaces my tools or MCP servers." It does not. Tools and MCP (the Model Context Protocol) are the channels through which an agent acts on the world — calling an API, querying a database, reading a file. A skill is the higher-level procedural playbook that tells the agent when and how to use those channels and in what order. They operate at different layers and complement each other. A skill that says "use the database tool to fetch open orders, then the email tool to notify each customer, verifying delivery after each send" orchestrates tools; it is not a tool itself. If you find yourself reimplementing an API client inside a skill, you have crossed the boundary in the wrong direction.

2. "More detail in SKILL.md is always better." The opposite is usually true. Stuffing full API references, exhaustive edge cases, and copy-pasted documentation into the body inflates every invocation and buries the actual procedure. Keep the body to principles and steps; push the heavy material into references/. The body is a map, not the territory.

3. "If a skill exists, the agent will use it." Only if the description earns the match. A vague or overlapping description means the agent either skips the skill or fires the wrong one. Description quality is routing quality. When two skills compete for the same requests, tighten both descriptions until each owns a distinct slice of the problem space.

Rule of thumb: if you cannot read a skill's description and predict exactly which user requests should trigger it — and which should not — neither can the agent.

How skills fit into the larger agent loop (planning, tool selection, memory, verification) is its own discipline; our agent harness engineering guide covers the surrounding scaffolding that makes skills dependable in production. Together with the token-optimization guide linked earlier, these three pieces form a connected series on building cost-aware, reliable agents.

Wrapping Up

Agent Skills give you a clean, scalable way to encode "the way we do this here" so an autonomous agent can discover and follow it without you bloating its context. The mechanics are simple once the model clicks: a versioned directory, a SKILL.md whose description is the trigger and whose body is the playbook, with heavy material deferred to references/ and scripts/. Progressive disclosure — name and description at idle, body on match, auxiliary files at execution — is what lets you install many skills cheaply. The best practices reduce to discipline: tight descriptions, single responsibility, lean bodies, explicit verification, and version control. And the misconceptions all stem from confusing layers: skills orchestrate tools, they do not replace them; brevity beats bulk; and a skill is only as discoverable as its description is precise.

These conventions held up consistently across three independent AI families, which is a useful signal that you are building on a stable, portable pattern rather than one vendor's quirk.

Your next step: pick one repetitive workflow your agent currently fumbles, write a single-responsibility skill with a razor-sharp description, and watch the routing improve. Then come back and read the two sibling guides in this series to make that skill cheap to run and reliable under load. Build one skill today — your future agent runs will thank you.