Claude Agent SDK Skills: Build Reusable Agent Capabilities

The Claude Agent SDK skill system gives agents domain-specific expertise by packaging instructions, scripts, and resources into filesystem-based directories that agents discover and load on demand.

Why Reusable Skills Matter for Production Agents

Every team building production agents runs into the same friction: the agent that writes excellent API endpoints forgets the team's error-handling conventions on its next session. Manually pasting the same instructions into every prompt wastes tokens and breaks down the moment a second engineer joins the project.

The Claude Agent SDK addresses this through skills, which are self-contained directories of instructions and resources that agents discover at startup and load only when relevant. Anthropic's engineering team describes skill authoring as an onboarding guide for agents, and the analogy holds. Skills capture the institutional knowledge senior engineers carry that the model lacks, including company-specific conventions, deployment procedures, and architectural patterns absent from any public training corpus.

This guide covers skill definition, multi-skill composition, team-wide sharing and versioning, and how skills compare to adjacent abstractions like tools and agents. The closing sections walk through how Intent uses these patterns to coordinate skill-equipped agents at scale across agentic development environments.

What Are SDK Skills: Reusable Agent Capabilities

Claude Agent SDK skills are organized folders of instructions, scripts, and resources that agents discover and load dynamically to perform specific tasks. Prompts work as conversation-level instructions for one-off tasks, while skills persist as filesystem artifacts that load on demand and remove the need to repeat the same guidance across multiple conversations.

Skills work across Claude.ai, Claude Code, the Claude Agent SDK, and the Claude Developer Platform Messages API, though deployment modes differ. Claude Code loads skills from the filesystem, while the Messages API accepts skills as request-scoped parameters with their own limits (see the FAQ for details). Anthropic has also published the skill format as an open standard with the stated goal of cross-platform portability.

Three-Level Progressive Disclosure Architecture

The defining mechanism of reusable Claude SDK skills is staged loading. Content enters the agent's context in three tiers to minimize token consumption, scaling from cheap metadata at startup to full resource bundles only when a task actually needs them. The table below summarizes what gets loaded at each level and the cost involved:

The loading sequence works as follows, per Anthropic's agent skills overview: at startup, the system prompt includes short metadata like "PDF Processing - Extract text and tables from PDF files..." When a user request matches, the agent reads the full SKILL.md instructions. Supporting files, including reference docs and utility scripts, load only if the task requires them. When Claude invokes a skill, the system loads the SKILL.md instructions into the conversation context.

This staged architecture is what makes large skill libraries practical. An agent can scan 50 skill descriptions at startup for roughly 5,000 tokens total, then pay full context cost only for the two or three skills relevant to the current task.

Defining a Skill: Interface, Tools, and Context Requirements

A skill definition consists of a SKILL.md file using YAML frontmatter for metadata, followed by Markdown instructions. The canonical directory structure packages everything the skill needs:

pdf-skill/
├── SKILL.md          ← main instructions (required)
├── FORMS.md          ← form-filling guide (loaded on-demand)
├── REFERENCE.md      ← detailed API reference (loaded on-demand)
└── scripts/
    └── fill_form.py  ← utility script (executes without entering context)

Minimal Valid Skill

The simplest functional skill requires only a SKILL.md with frontmatter:

---
name: explain-code
description: Explains code with visual diagrams and analogies. Use when explaining
  how code works, teaching about a codebase, or when the user asks "how does this work?"
---

When explaining code, always include:

1. **Start with an analogy**: Compare the code to something from everyday life
2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
3. **Walk through the code**: Explain step-by-step what happens
4. **Highlight a gotcha**: What's a common mistake or misconception?

This file is stored at ~/.claude/skills/explain-code/SKILL.md for personal scope or .claude/skills/explain-code/SKILL.md for project scope.

Frontmatter Interface Contract

Anthropic's docs describe required skill frontmatter fields such as name and description, with examples and community resources also referencing additional optional fields. The fields below summarize what each one controls and whether it ships in the official documentation:

Skill Scope and Precedence

Skills can be loaded and used together, though Anthropic's public documentation does not substantiate the specific scope hierarchy or name-collision precedence described here. The conventional layout teams use in practice maps three scope levels to filesystem locations:

Note: This precedence ordering reflects community convention rather than a formally documented Anthropic specification. Verify against the Claude Code release in use before relying on collision behavior.

Pattern: Pre-Approved Tool Binding

Tool permissions and invocation behavior depend on the specific Claude interface and configuration:

---
name: commit
description: Stage and commit the current changes
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

Stage and commit the current changes:

1. Run `git status` to see what's changed
2. Stage all changes with `git add -A`
3. Write a descriptive commit message following conventional commits
4. Commit with `git commit -m "<message>"`

The documented Claude skills and tools configuration governs pre-approval behavior, so the undocumented Bash(git add *) pattern shown above is illustrative only. Other tools remain callable under normal permission settings.

Pattern: Shell Preprocessing for Dynamic Context

The ! prefix syntax (community convention, not formally specified in Anthropic's official documentation) is used by some Claude Code workflows to execute commands before the skill content reaches the agent, injecting live data:

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Your task
Summarize this pull request for a code review.

Each !command`` executes before the skill content is sent to the agent. Output replaces the placeholder, so the agent receives a fully rendered prompt with actual PR data. Teams relying on this pattern should test it against their current Claude Code version, since behavior may change without notice.

Enabling Skills in the Agent SDK

To activate skill discovery programmatically, include "Skill" in allowed_tools and set setting_sources:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Review this PR using our code review checklist",
        options=ClaudeAgentOptions(
            setting_sources=["user", "project"],
            allowed_tools=["Skill", "Read", "Grep", "Glob"],
        ),
    ):
        if isinstance(message, ResultMessage) and message.subtype == "success":
            print(message.result)

asyncio.run(main())

The setting_sources parameter governs where settings files are discovered, including the locations from which skills are loaded. By default, the SDK does not look for settings files, CLAUDE.md, or skills.

Composing Skills: Stacking Capabilities Across Agents

Composition in the Claude Agent SDK is declarative: skills live in folders that Claude can load when needed based on their descriptions. As Anthropic describes the model, skills are composable resources that extend Claude's capabilities. The way teams stack those resources determines whether multiple skills coexist in one context window or get distributed across specialist agents.

Deterministic Composition via Subagents

For workflows requiring specific skill combinations, the skills: array in subagent definitions preloads the full skill content into the subagent's context at startup, removing the need to discover and load those skills during execution:

# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Reviews code changes for quality, security, and compliance
skills:
  - style-guide
  - security-patterns
  - performance-heuristics
memory: user
---
Review code changes. Apply all preloaded skills systematically.
Report findings in structured format: [category] severity: description.

Subagents do not inherit skills from the parent conversation, so engineers must list them explicitly. Whether skills with disable-model-invocation: true can be preloaded via this mechanism is not clearly documented; the field is specified as preventing auto-invocation, but its interaction with explicit subagent preloading is unconfirmed in Anthropic's official docs and should be verified before relying on either behavior.

Orchestrator Pattern: Skill-Specialized Subagents

Anthropic's multi-agent pattern uses an orchestrator-worker design where a lead agent coordinates the process and delegates tasks to specialized subagents that operate in parallel. The same coordinator-implementor-verifier shape shows up in Intent's three-agent architecture, where each specialist holds its own skill set scoped to a step in the spec.

.claude/
├── agents/
│   ├── orchestrator.md
│   ├── code-reviewer.md      # skills: [style-guide, security-patterns, performance-heuristics]
│   ├── api-developer.md      # skills: [api-conventions, error-handling-patterns]
│   └── test-engineer.md      # skills: [test-coverage, qa-workflows]
├── skills/
│   ├── api-conventions/SKILL.md
│   ├── error-handling-patterns/SKILL.md
│   ├── security-patterns/SKILL.md
│   ├── style-guide/SKILL.md
│   ├── performance-heuristics/SKILL.md
│   ├── test-coverage/SKILL.md
│   └── qa-workflows/SKILL.md
└── CLAUDE.md

Each subagent operates with an isolated context window. Subagents in the Claude Agent SDK have isolated contexts, but the SDK documentation does not clearly guarantee that skills loaded in one subagent stay invisible to another such as code-reviewer and api-developer. Only the subagent's return value crosses back to the orchestrator. Multiple subagents can run in parallel, which is the same property open-source agent orchestrators lean on for git-worktree-based isolation.

Context Sharing Boundaries

Composition strategy dictates whether skills coexist in shared context or live in separate sandboxes. The four mechanisms below cover the common patterns and the workflows each one fits best:

When teams use an orchestrator pattern, isolating skills per subagent reduces cross-contamination between tasks while preserving a clean return channel back to the coordinator. Intent applies this same isolation by giving each specialist agent its own git worktree, keeping per-agent skill stacks scoped without polluting the coordinator's view of the spec.

Managing Skill Conflicts

Principled frameworks for multi-skill conflict resolution remain an open research problem. Current mitigations include writing non-overlapping trigger conditions in skill descriptions, using subagent isolation as a structural conflict resolver, and including explicit precedence statements within SKILL.md files. For example: "If both X and Y conventions apply, follow X for authentication endpoints and Y for data endpoints."

Sharing and Versioning Skills Across Teams

Skill libraries only deliver value when teams ship them like the rest of the codebase: in version control, with semantic versioning, and behind real test gates. The four practices below cover the lifecycle from authoring through production rollout.

Package Skills as Self-Describing Directories

Each skill should be a self-contained, independently deployable directory stored in version control. The SKILL.md manifest contains both human-readable documentation and the runtime instructions the agent loads when the skill is invoked. Supporting .py or script files handle tool-level logic, keeping the manifest focused on behavioral guidance.

Apply Semantic Versioning with Environment Promotion

Version skills by change type:

• Patch (x.x.N): Bug fixes to instructions, clarifications that do not change behavior
• Minor (x.N.x): New capabilities added, backward-compatible
• Major (N.x.x): Breaking changes such as renamed fields, removed workflows, or changed trigger conditions

Pair semantic versioning with staging and production environment tags to promote skill versions through environments without requiring code changes, decoupling promotion from deployment.

Treat Skill Testing as a CI/CD Gate

Skills require the same testing rigor as production code. The Promptfoo provider docs support the Claude Agent SDK directly:

providers:
  - id: anthropic:claude-agent-sdk
    config:
      setting_sources: ['project', 'local']

The Anthropic skills repository includes a skill-creator skill with at least one specialized subagent for quality evaluation: agents/grader.md for assertion evaluation.

Scale Governance Patterns

Team skill libraries typically need governance rules as they grow. Common patterns include naming conventions to prevent collisions, required YAML frontmatter, and standardized workflow structure within each skill directory. Intent's living specifications complement this by anchoring skill changes to the actual implementation state, so version bumps reflect real behavioral shifts and stay in sync with what shipped.

Skills vs Tools vs Agents: When to Use Each Abstraction

The three abstractions in the agent skills SDK serve distinct roles. Choosing the wrong one for a given problem produces predictable failure modes.

Tools are atomic, callable functions with a fixed interface and no internal decision-making. A tool executes a single operation and returns a result, analogous to system calls.

Skills sit higher in the stack than tools. Where a tool defines what an agent can execute, a skill shapes how the agent approaches a class of problems by encoding domain-specific knowledge, procedural conventions, and multi-step behavioral patterns. A skill may invoke tools but extends them with applicability logic, multi-step sequencing, and termination criteria.

Agents are autonomous decision-making entities where LLMs direct their own processes, dynamically selecting tools while maintaining control over how they accomplish tasks.

The matrix below maps each abstraction to its operational properties, which is what most engineers use to decide which one fits a given problem:

The diagnostic rule: if the abstraction executes an action, it is a tool. If it shapes how the agent reasons about a domain, it is a skill. If it must dynamically decide which tools to use and in what order, it is an agent.

Anthropic's guidance on building effective agents applies here. For many applications, a lightweight approach using strong prompting, retrieval, and in-context examples is sufficient without a full agentic workflow. Teams should reach for agents only when workflows genuinely require dynamic, unpredictable decision-making.

How Intent Coordinates Skill-Equipped Agents at Scale

Intent is a desktop workspace for spec-driven development that uses a three-agent architecture (coordinator, implementors/specialists, and verifier) aligned with the skill composition patterns described above. The sections below break down how Intent layers BYOA flexibility, per-task model routing, and skill-driven specialists into a single coordinated workspace.

Three-Layer Modularity Architecture

Intent separates agent identity, model selection, and skill loading into independent layers, so teams can swap any one of them without rewriting the others. The result is a workspace where existing Claude Code or Codex subscriptions plug into the same orchestration layer that runs Auggie.

Because Intent supports Auggie, Claude Code, Codex, and OpenCode through its BYOA model, teams with existing Claude Code subscriptions can use their agent directly in Intent's orchestration layer.

Living Specifications as Coordination

Intent's living specifications address a limitation that static requirements and skill libraries cannot fully capture: coordination that must stay synchronized as work evolves during execution. Static AGENTS.md or CLAUDE.md files load at startup and do not change during execution. Living specs update as agents discover new requirements and complete work, keeping every agent aligned with the actual implementation state as it evolves past the initial plan.

Isolation Without Fragmentation

Each Intent task runs in an isolated git worktree, providing filesystem-level isolation that prevents agents from conflicting during parallel execution. The three-role agent model (Coordinator, Implementor, Verifier) maps cleanly to the orchestrator pattern from the Claude Agent SDK: specialist agents execute with their own skill sets in isolated contexts, while the Coordinator synthesizes results against the living specification.

For teams that want skill-equipped agents running across the full SDLC instead of inside a single workspace, Augment Cosmos (currently in research preview) extends this orchestration model into a shared agent runtime with tenant memory and event-driven triggers from tools like Linear, Slack, and GitHub.

Start With One Reusable Skill Your Team Uses Weekly

The core tension in agent skill management is between flexibility and consistency: teams need skills that are reusable across agents and projects while remaining specific enough to encode genuine institutional knowledge. The starting point is packaging one workflow the team repeats weekly into a SKILL.md with clear trigger conditions, testing it with Promptfoo, and committing it alongside the codebase it serves.

Once that first skill earns its keep, the next question is how to coordinate skill-equipped agents working in parallel without losing track of the spec they share.

FAQ

Related

• 6 Best Spec-Driven Development Tools for AI Coding in 2026
• 9 Open-Source Agent Orchestrators for AI Coding (2026)
• 9 Best AI Coding Agent Desktop Apps in 2026
• 5 Best Agentic Development Environments for Enterprise Teams in 2026
• 6 Best Devin Alternatives for AI Agent Orchestration in 2026