Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Skill

Pattern

A reusable solution you can apply to your work.

Understand This First

Context

At the agentic level, a skill is a reusable packaged workflow or expertise unit that an agent can invoke to handle a specific type of task. Where a tool is a single callable capability (read a file, run a command), a skill is a higher-level package: it bundles instructions, conventions, examples, and sometimes tool configurations into a coherent unit that teaches the agent how to perform a particular kind of work.

Skills bridge the gap between a general-purpose agent and one with domain-specific expertise. An agent with a “write a pattern entry” skill knows the template, the conventions, the cross-reference format, and the quality checklist, without the human needing to explain all of that every time.

Problem

How do you capture repeatable expertise so that an agent can perform a specific type of task consistently, without re-explaining the process each time?

Agentic workflows often involve recurring task types: writing documentation to a template, creating test files following project conventions, generating migration scripts, or reviewing code against a checklist. Each time the human explains the conventions from scratch, they risk omitting details, introducing inconsistencies, and wasting time and context window space on instructions that should be standardized.

Forces

  • Repetition of task-type instructions wastes context window space and human attention.
  • Consistency suffers when instructions are restated slightly differently each time.
  • Expertise capture: the knowledge of how to do something well should be written down once and reused.
  • Flexibility: skills must be adaptable to specific situations, not rigid scripts.

Solution

Package repeatable expertise into a skill file, a document that contains the instructions, template, conventions, examples, and quality criteria for a specific type of task. The harness loads the skill when the task type is invoked, injecting the expertise into the agent’s context.

A good skill includes:

A clear description of when the skill applies and what it produces.

Step-by-step guidance, not rigid scripts, but structured instructions that allow the agent to exercise judgment within defined guardrails.

Templates and examples that show the expected output format.

Quality criteria that define what “done well” looks like: a checklist the agent can verify against before declaring the task complete.

Skills are distinct from instruction files in scope. An instruction file provides project-wide conventions that apply to every task. A skill provides task-specific expertise that applies only when that type of work is being done.

How Skills Grow

Skills rarely start as polished documents. They evolve through a predictable lifecycle:

Ad-hoc instructions. You explain the process in a prompt: “Write a migration file with a timestamp prefix, up and down functions, and make sure it’s reversible.” This works once but doesn’t persist.

Saved snippet. After explaining the same thing three times, you paste the instructions into a text file or a project wiki. The agent can now reference it, but the instructions are informal and tied to one specific case.

Generalized skill file. You rewrite the snippet as a proper skill: structured steps, a template, quality criteria, and notes on when the skill applies. The harness loads it on demand. Other team members start using it.

Evolved skill. Over weeks of use, the skill accumulates refinements. Edge cases get documented. The quality checklist grows tighter. Steps that confused the agent get rewritten. The skill becomes more reliable than any single team member’s memory of the process.

The progression from ad-hoc to evolved mirrors how teams formalize any process. The difference in agentic workflows is that the formalization is directly executable: a better skill file produces better agent output on the next invocation, with no retraining or onboarding required.

Tip

When you find yourself explaining the same process to an agent more than twice, write a skill. Thirty minutes spent writing a clear skill file saves hours of repeated explanation and produces more consistent results.

How It Plays Out

A team maintains a pattern book with a specific article format: title, context, problem, forces, solution, examples, consequences, related patterns. They write a skill file that captures this template, the writing guidelines, the cross-reference conventions, and the quality checklist. When they ask the agent to write a new article, they invoke the skill. The agent produces a well-structured entry on the first try, matching the book’s conventions without the human restating them.

A developer creates a skill for generating database migration files. The skill includes the naming convention (timestamp prefix), the template (up and down functions), the project’s migration tool syntax, and validation rules (must be reversible, must not drop data without a backup step). Every migration the agent generates follows these conventions automatically.

A small team starts with ad-hoc code review instructions pasted into each conversation. After a month, one developer notices the instructions have drifted across team members: two people check for error handling, one doesn’t; nobody consistently checks for test coverage. She consolidates the best version into a review-pr skill file with five checklist items, a severity rubric, and a template for the review comment. Over the next few weeks, the team adds two more checklist items that kept getting missed. Three months later, the skill catches issues more reliably than any individual reviewer did before it existed.

Example Prompt

“Use the new-article skill to write a pattern entry for Context Engineering. Follow the article template and cross-reference conventions described in the skill file.”

Consequences

Skills make agentic workflows more consistent and efficient. They capture expertise in a reusable form that benefits every future invocation, reducing the burden on the human to remember and restate conventions. Agent output quality improves because the skill provides rich, focused context for the specific task type rather than generic instructions.

The cost is the effort of writing and maintaining skill files. Skills that are too rigid become obstacles when the task doesn’t quite fit the template. Skills that are too vague provide little benefit. The best skills are opinionated enough to enforce important conventions but flexible enough to accommodate reasonable variation.

  • Depends on: Agent — skills are invoked by agents.
  • Depends on: Harness (Agentic) — the harness loads and manages skills.
  • Contrasts with: Tool — a tool is a single capability; a skill is a packaged workflow.
  • Contrasts with: Instruction File — instruction files are project-wide; skills are task-specific.
  • Uses: Context Engineering — skills are a form of context that is loaded on demand.

Sources

  • Anthropic formalized the skill concept for coding agents in Claude Code (October 2025) and published the Agent Skills specification as an open standard in December 2025, with Barry Zhang, Keith Lazuka, and Mahesh Murag describing the design in “Equipping Agents for the Real World with Agent Skills.” The specification defines skills as filesystem-based packages of instructions, scripts, and resources that agents discover and load dynamically.
  • The idea of packaging reusable behaviors as composable “skills” has deep roots in robotics and autonomous agent research, where skill abstractions have organized robot capabilities into hierarchical, reusable units since at least the 1990s.
  • Progressive disclosure — the architectural principle of loading context only when needed rather than cramming everything into a monolithic prompt — is the core design insight behind skill loading. Anthropic’s Agent Skills documentation identifies this as the key pattern that makes skills scalable.