Skills

A skill is a reusable, task-specific instruction bundle that an agent activates when the current task matches the skill’s description. Skills are structured natural language — not compiled code, not deterministic scripts. They hand the agent a playbook (context, constraints, steps, scoped tools) while leaving execution to the model.

Instruction files define project-wide behavior. Skills decompose specialized workflows — migrations, deployments, releases, code review — into self-contained units that load only when relevant. Without that split, every specialized procedure has to live in the root instruction file, bloating context and drowning signal.

Universal Structure

graph TD
    S["SKILL.md<br/><i>Instructions + YAML frontmatter</i><br/><b>Always loaded on activation</b>"]
    SC["scripts/<br/><i>Executable automation</i>"]
    RF["references/<br/><i>Docs loaded on demand</i><br/>NOT in main context"]
    AS["assets/<br/><i>Templates, boilerplate</i>"]

    S --> SC
    S --> RF
    S --> AS

    T["Task matches description"] -->|"auto-activate"| S
    U["/skill-name"] -->|"manual invoke"| S

    style S fill:#eef2ff,stroke:#c7d2fe
    style RF fill:#fefce8,stroke:#fde68a

SKILL.md is the only required file. scripts/ holds deterministic operations the agent should run rather than improvise. references/ holds detailed docs pulled in only when needed. assets/ stores templates the skill points at as starting points.

Cross-Platform Mapping

The agentskills.io SKILL.md spec is shared by Anthropic, OpenAI, and Google ADK — the same skill directory is portable across all three.

Key Properties

• Auto-activation. Skills declare a natural-language description; the agent matches semantically. Description quality is the dominant factor in activation accuracy — vague descriptions cause false positives, narrow ones cause false negatives.
• Manual override. Force activation with /skill-name. Set disable-model-invocation: true to require explicit invocation — critical for dangerous workflows like production deployments.
• On-demand loading. Only SKILL.md loads on activation. references/ files load conditionally when deeper context is needed.
• Isolation. context: fork runs the skill in a sub-agent with its own context window, preventing long executions from polluting the main conversation.
• Scoped tools. The allowed-tools field restricts which tools the agent may call. Caveat: enforced by the Claude Code CLI but ignored when skills are loaded through the Agent SDK — do not rely on it as a security boundary in SDK-driven runtimes.
• Path-specific activation. The paths field (glob patterns) gates auto-load to matching files — essential in monorepos where directories have different tooling.

SKILL.md Anatomy

YAML frontmatter defines metadata and behavior; the markdown body defines the workflow.

---
name: db-migration
description: >
  Generate and validate database migration files for PostgreSQL schema changes.
  Handles column additions, table creation, index management, and enum
  modifications. Always generates both up and down migrations.
allowed-tools:
  - Read
  - Edit
  - Write
  - Bash(alembic *)
  - Bash(psql *)
  - Bash(make db-*)
context: fork
paths:
  - "services/api/models/**/*.py"
  - "services/api/migrations/**/*.py"
disable-model-invocation: false
---

The body is plain markdown: numbered pre-flight checks, generation steps with embedded shell calls (!alembic heads), @references/schema-conventions.md pulls for conditional context, and a final report-back step. Keep it short; push depth into references/.

Best Practices

• Write specific, matchable descriptions. Name task types handled, technologies involved, and scope boundaries. Natural phrasing beats keyword stuffing.
• Keep SKILL.md lean. Treat it as an executive briefing. Long checklists and conventions belong in references/ and load conditionally. A 60-line SKILL.md pointing at detailed docs outperforms a 300-line monolith.
• Use allowed-tools for least privilege — but know its limits. Declare the minimum tool set required. Remember the CLI-only caveat: in SDK runtimes, enforce restrictions at the harness layer, not in frontmatter.
• Compose skills via cross-invocation. A release skill can invoke /run-tests, then /changelog, then /deploy-staging — building complex workflows from simple, tested units.

A Note on Slash Commands

.claude/commands/<name>.md (project) and ~/.claude/commands/<name>.md (user) markdown files still work — body becomes the prompt, $ARGUMENTS placeholder supported. Custom slash commands are increasingly being subsumed into Skills; new work should prefer Skills, treating the commands directory as legacy-adjacent.