Skills — The Modular Capability Layer

2.1 What Are Skills?

Skills are the modular capability layer of Claude Code and compatible AI agent systems. They extend what an agent can do by providing specialized instructions, workflows, and domain knowledge packaged as Markdown files. Unlike tools, which give agents new actions (read a file, call an API), skills give agents new knowledge — the procedural understanding of how to approach complex, multi-step tasks.

The core insight behind skills is progressive disclosure. An agent with 100 skills does not load all 100 into its context window at startup. Instead, only the skill name and a short description (~50 tokens each) are present initially. When a user invokes a skill or the agent determines one is relevant, the full instructions are loaded. This keeps context lean while making extensive specialized knowledge available on demand.

Users interact with skills through slash commands. Typing /commit in Claude Code invokes the commit skill. Typing /deploy staging invokes a deploy skill with "staging" as an argument. But skills also activate autonomously: if an agent's description says "Use when writing tests," the agent loads it automatically when it encounters a testing task.

The Merger: Commands and Skills

Claude Code supports two overlapping mechanisms that create slash commands: commands (files in .claude/commands/) and skills (files in .claude/skills/). Both produce entries in the / menu. The distinction is that skills add optional features beyond what commands provide:

• Commands are simple: a Markdown file in .claude/commands/ becomes a slash command. The filename (minus .md) becomes the command name. No frontmatter required. Content is injected into the conversation when invoked.
• Skills are richer: a SKILL.md file in a skill directory can include frontmatter fields for auto-activation, model overrides, tool permissions, subagent execution, argument hints, and more. Skills can also contain supporting files referenced by the main SKILL.md.

In practice, the terms are often used interchangeably. If you need a quick custom command, drop a Markdown file in .claude/commands/. If you need auto-activation, description-based discovery, subagent isolation, or any of the advanced features, use a skill directory with SKILL.md.

The Open Standard and Industry Adoption

Agent Skills were first announced by Anthropic on October 16, 2025, as a feature of Claude Code. On December 18, 2025, the specification was published as an open standard at agentskills.io/specification, establishing a vendor-neutral format for packaging agent capabilities. The decision to open-source the specification was deliberate: skills are more valuable when they are portable across agent platforms.

The adoption curve has been rapid. Within weeks of the open standard release, OpenAI adopted the Agent Skills format for Codex CLI and ChatGPT. Microsoft integrated skills support into VS Code and GitHub Copilot. Cursor, Goose, Amp, and OpenCode added native support. By April 2026, the community had published over 71,000 skills on the agentskills.io registry, and the GitHub repository for community-contributed skills had surpassed 20,000 stars.

The cross-platform compatibility means a skill written for Claude Code works in Cursor, OpenCode, Goose, and any other agent that implements the agentskills.io specification. This portability is a significant advantage over platform-specific plugin systems. A team can invest in building high-quality skills knowing they are not locked into a single AI agent platform.

Skills vs Commands vs Plugins vs Tools

2.2 Skill Storage and Discovery

Skills are discovered from four scope levels, each with a distinct purpose and priority. When skill names collide across scopes, higher-priority scopes win. This hierarchy enables enterprises to enforce standards, individuals to customize their workflow, and projects to define domain-specific behavior.

The Four Scope Levels

Automatic Discovery Mechanics

Claude Code scans skill directories recursively, supporting nested subdirectories for organizational purposes. A monorepo with packages/auth/.claude/skills/ and packages/billing/.claude/skills/ discovers skills from both locations. Each skill directory must contain a SKILL.md file — this is the only required file. The directory name is irrelevant to discovery; what matters is the name field in frontmatter (or the filename if no name is specified).

Skills are also discovered from directories added via the --add-dir flag. This enables sharing skills across related projects without duplicating files. If you maintain a shared skills repository, you can add it to any project session:

# Add shared skills from another directory
claude --add-dir ~/shared-skills

# Skills in ~/shared-skills/.claude/skills/ are now discoverable
# They merge with the project's own skills

Directory Structure

A skill directory has one required file and any number of supporting files:

.claude/skills/
  deploy/
    SKILL.md              # Required: frontmatter + instructions
    templates/
      nginx.conf.template # Supporting file referenced by SKILL.md
      docker-compose.yml  # Supporting file referenced by SKILL.md
    examples/
      staging-deploy.md   # Example referenced by SKILL.md
  code-review/
    SKILL.md              # Another skill
    checklists/
      security.md         # Loaded on demand when SKILL.md references it
      performance.md

Monorepo Patterns

Monorepos present a unique challenge for skill discovery because different packages within the same repository may need different skills. Claude Code handles this through nested discovery: skill directories at any depth within the project are scanned and merged. Consider a typical monorepo structure:

monorepo/
  .claude/skills/              # Root-level skills (shared across all packages)
    commit-conventions/
      SKILL.md
    ci-pipeline/
      SKILL.md
  packages/
    auth/
      .claude/skills/          # Auth-specific skills
        oauth-flow/
          SKILL.md
    billing/
      .claude/skills/          # Billing-specific skills
        stripe-integration/
          SKILL.md
    frontend/
      .claude/skills/          # Frontend-specific skills
        component-patterns/
          SKILL.md

In this layout, every developer in the monorepo gets the root-level commit-conventions and ci-pipeline skills. Developers working in packages/auth/ additionally get the oauth-flow skill. The agent automatically discovers skills from the working directory upward to the repository root, loading package-specific skills alongside shared ones. If a package skill collides with a root skill by name, the package-level skill wins (closer to the working directory takes priority within the same scope level).

For organizations with shared skill libraries maintained separately from application code, the --add-dir approach provides a clean separation. The shared skills repository can be versioned, tested, and published independently, and individual projects consume them by reference rather than by copy. This pattern is particularly effective when combined with enterprise-managed settings that ensure certain critical skills are always present.

2.3 SKILL.md Format and Frontmatter Reference

Every skill begins with a SKILL.md file. The file has two parts: YAML frontmatter (metadata between --- delimiters) and a Markdown body (the actual instructions). The frontmatter controls how the skill is discovered, when it activates, and how it executes. The body contains the instructions the agent follows.

---
name: deploy-staging
description: >
  Deploy the application to the staging environment. Use when the user asks
  to deploy, push to staging, or test in a staging environment.
argument-hint: [branch-name]
allowed-tools:
  - Bash
  - Read
  - Grep
disable-model-invocation: true
---

# Deploy to Staging

## Prerequisites
1. Ensure you are on the correct branch
2. Run the test suite: `npm test`
3. Check for uncommitted changes

## Steps
1. Build the application: `npm run build`
2. Run database migrations: `npm run migrate:staging`
3. Deploy via rsync: `rsync -avz dist/ staging.example.com:/app/`
4. Verify deployment: `curl -s https://staging.example.com/health`

## Rollback
If the health check fails, redeploy the previous version:
```
git checkout HEAD~1
npm run build
rsync -avz dist/ staging.example.com:/app/
```

Complete Frontmatter Reference

The following table documents every frontmatter field available in the Agent Skills specification as of April 2026. Fields marked "Recommended" significantly improve skill behavior but are not strictly required for the file to be valid.

2.4 Types of Skill Content

Skill content falls into two broad categories based on how the agent uses it. Understanding this distinction helps you design skills that activate correctly and deliver the right kind of value.

Many production skills blend both categories. A deployment skill might start with reference content (environment configuration, naming conventions) and then transition to task content (step-by-step deployment commands). The important thing is that the frontmatter flags match the skill's intent: if it performs destructive operations, set disable-model-invocation: true regardless of how much reference content it contains.

---
name: api-conventions
description: >
  REST API conventions for this project. Use when creating endpoints,
  reviewing API code, or discussing API design.
user-invocable: false
---

# API Conventions

## Naming
- Resources are plural nouns: `/users`, `/orders`
- Actions use sub-resources: `/users/123/activate`
- Query parameters use camelCase: `?pageSize=20`

## Response Format
All responses use the envelope pattern:
```json
{
  "data": { ... },
  "meta": { "page": 1, "total": 42 }
}
```

## Error Handling
Errors return appropriate HTTP status codes with a body:
```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is required",
    "field": "email"
  }
}
```

---
name: db-migrate
description: >
  Run database migrations against the specified environment. Creates backup
  first. Use when user asks to migrate, update schema, or run migrations.
argument-hint: [environment]
disable-model-invocation: true
allowed-tools:
  - Bash
  - Read
---

# Database Migration

## Arguments
- `$1` = target environment (staging, production)

## Steps
1. Verify environment: `echo "Migrating: $1"`
2. Create backup: `pg_dump $DB_URL > backup-$(date +%s).sql`
3. Run migrations: `npx prisma migrate deploy`
4. Verify schema: `npx prisma db pull --print`
5. Report results to user

2.5 Invocation Control — Who Can Trigger What

Two frontmatter fields control who can invoke a skill and when its content loads into context. Understanding their interaction is critical for designing skills that activate correctly.

The 2x2 Matrix

Choosing the Right Configuration

2.6 String Substitutions and Dynamic Context

Skills support string substitutions and shell injection for dynamic content. These mechanisms allow skills to adapt their instructions based on arguments, session state, and live system data rather than containing only static text.

Argument Substitutions

Environment Variables

Shell Injection

Skills can embed live system data by executing shell commands during preprocessing. This runs before the skill content reaches Claude, so the agent sees the command's output, not the command itself.

---
name: review-pr
description: Review the current PR with full diff context.
argument-hint: [pr-number]
---

# PR Review

## PR Summary
!`gh pr view $1 --json title,body,author --jq '.title + "\n" + .body'`

## Full Diff
```!
gh pr diff $1
```

## Review Checklist
- [ ] Are there breaking changes?
- [ ] Are new dependencies justified?
- [ ] Do tests cover the changes?
- [ ] Is the commit history clean?

Review this PR and provide feedback on each checklist item.

Two shell injection syntaxes are available:

• Inline: !`command` — The command output replaces the backtick expression inline. Use for short outputs (a PR title, a version number, a branch name).
• Block: ```! followed by commands and ``` — The entire block is replaced with the command's output. Use for longer outputs (diffs, logs, file contents).

---
name: session-status
description: Show current project state and recent activity.
---

# Session Status

## Current Branch
!`git branch --show-current`

## Recent Commits
```!
git log --oneline -10
```

## Modified Files
```!
git status --short
```

## Node Version
!`node --version`

Based on this context, summarize the current project state
and suggest what to work on next.

2.7 Supporting Files

While SKILL.md is the only required file, production skills often include supporting files that provide templates, examples, scripts, and reference material. The key principle is that SKILL.md should be a focused entrypoint (under 500 lines recommended), and it should reference supporting files so Claude knows they exist and when to load them.

Recommended Structure

.claude/skills/publish-pipeline/
  SKILL.md                    # Entrypoint: ~200 lines of core instructions
  templates/
    pandoc-html.template      # HTML template for document conversion
    pandoc-pdf.template       # PDF template with XeLaTeX styling
  scripts/
    ftp-sync.sh               # FTP deployment script
    validate-output.sh        # Post-build validation
  examples/
    basic-publish.md          # Minimal example for simple documents
    multi-format.md           # Example with HTML + PDF output

Referencing Supporting Files

Claude does not automatically read every file in a skill directory. The SKILL.md must tell Claude about supporting files and when to use them. There are two patterns:

---
name: publish-pipeline
description: Build and deploy documents as HTML/PDF with FTP sync.
---

# Publish Pipeline

## Templates
When building HTML output, read and use the template at:
`${CLAUDE_SKILL_DIR}/templates/pandoc-html.template`

When building PDF output, read and use the template at:
`${CLAUDE_SKILL_DIR}/templates/pandoc-pdf.template`

## Deployment
After building, run the FTP sync script:
`bash ${CLAUDE_SKILL_DIR}/scripts/ftp-sync.sh`

## Examples
For reference on usage patterns, see:
- `${CLAUDE_SKILL_DIR}/examples/basic-publish.md`
- `${CLAUDE_SKILL_DIR}/examples/multi-format.md`

The Python Script Pattern

A common pattern for skills that generate visual output (charts, diagrams, formatted reports) is to include a Python script that the skill instructs Claude to run:

---
name: coverage-report
description: Generate visual test coverage report with charts.
allowed-tools:
  - Bash
  - Read
  - Write
---

# Coverage Report Generator

1. Run the test suite with coverage: `npm test -- --coverage --json`
2. Parse the JSON coverage output
3. Run the visualization script:
   `python3 ${CLAUDE_SKILL_DIR}/scripts/generate-charts.py coverage.json`
4. The script outputs an HTML report to `coverage-report.html`
5. Open and summarize the key findings for the user

2.8 Running Skills in Subagents

By default, a skill's content is injected into the main conversation context. For expensive or long-running skills, this is wasteful — the skill instructions and intermediate work consume context that the main conversation needs. The context: fork setting solves this by running the skill in an isolated subagent.

How Forked Skills Work

1. User invokes /skill-name or Claude auto-activates the skill
2. Instead of injecting the skill content into the main context, the runtime spawns a subagent — a new Claude instance with its own, clean context window
3. The skill's Markdown body becomes the subagent's task prompt
4. The subagent executes independently, using tools, reading files, and producing output
5. When the subagent completes, its output is summarized back to the parent context
6. The parent sees the result without having consumed context on the intermediate steps

---
name: deep-review
description: >
  Comprehensive code review with security, performance, and architecture
  analysis. Runs in isolated context to avoid consuming main session budget.
context: fork
agent: code-reviewer
allowed-tools:
  - Read
  - Grep
  - Glob
---

# Deep Code Review

Perform a comprehensive review of the codebase changes:

1. Run `git diff HEAD~1` to see recent changes
2. For each changed file:
   - Check for security vulnerabilities (injection, auth bypass, secrets)
   - Check for performance issues (N+1 queries, unbounded loops, large allocations)
   - Check for architectural violations (layer crossing, circular dependencies)
3. Compile findings into a structured report with severity levels
4. Suggest specific fixes for each finding

The Agent Field

The agent field selects which subagent type runs the forked skill. This can be a built-in agent type or a custom agent defined in .claude/agents/:

The Inverse Relationship

There is a dual relationship between skills and subagents. A skill can specify context: fork to run in a subagent, and conversely, a subagent can specify skills in its definition to load specific skills into its context. This creates two patterns:

Effort and Model Overrides in Forked Skills

When a skill runs in a forked context, the model and effort frontmatter fields become particularly powerful. A computationally expensive analysis skill can specify model: claude-opus-4-6-20250401 with effort: max for deep reasoning, while the parent conversation continues on a faster model. Conversely, a simple formatting or validation skill can use model: claude-sonnet-4-20250514 with effort: low to complete quickly and cheaply.

This creates an economic model for skill execution. Each forked skill can independently optimize its cost-performance tradeoff without affecting the rest of the session. In our production system, we use this pattern for the simplify skill: three parallel subagents each analyze different quality dimensions, and since they are forked, their combined intermediate reasoning does not consume the parent's context window. The parent receives only the consolidated findings.

Hooks Scoped to Skills

The hooks frontmatter field enables skill-specific automation that only fires while the skill is active. This is a more surgical alternative to global hooks defined in settings.json. A deployment skill can define a PreToolUse hook that validates every Bash command against a safety checklist before execution, without imposing that overhead on normal development work:

---
name: deploy-production
description: Production deployment with safety hooks.
disable-model-invocation: true
hooks:
  PreToolUse:
    - matcher: Bash
      command: "python3 ${CLAUDE_SKILL_DIR}/validate-command.py"
---

# Production Deployment
...

Skill-scoped hooks are particularly useful for security-sensitive operations. A database migration skill might define a hook that prevents DROP TABLE commands. A file management skill might hook into Write operations to prevent modifications outside a specific directory. These constraints apply only while the skill is active and disappear when it completes, providing targeted safety rails without global overhead.

2.9 Bundled Skills

Claude Code ships with five built-in skills that demonstrate best practices and provide immediately useful capabilities. These skills are available in every session without any configuration.

Bundled Skills as Design Templates

The five bundled skills collectively demonstrate most of the key skill design patterns discussed in this section. /batch demonstrates context: fork with parallel execution and worktree isolation. /claude-api demonstrates reference content that loads on demand without any task execution. /debug demonstrates diagnostic tooling that introspects the agent runtime itself. /loop demonstrates temporal execution patterns with interval-based repetition. /simplify demonstrates the multi-agent review pattern where several forked agents analyze the same codebase independently and aggregate findings.

When building custom skills, these bundled implementations serve as proven templates. The /batch pattern, in particular, is frequently adapted for domain-specific parallel workflows — batch documentation updates, batch test generation, batch migration scripts. The key insight from /batch is that worktree isolation (each subagent gets its own git worktree) eliminates the coordination problem that plagues most parallel file modification approaches. Instead of trying to merge concurrent edits to the same working directory, each agent works in isolation and results are merged at the git level where conflict detection is well-understood.

The /simplify pattern is equally instructive: by splitting a single review task into three independent analyses (reuse, quality, efficiency), the skill achieves more thorough coverage than a single-pass review. Each subagent can focus deeply on its dimension without context competition. This multi-perspective pattern generalizes to any task where different evaluation criteria benefit from independent attention.

2.10 Restricting Skill Access

Claude Code provides several mechanisms to control which skills can run, who can invoke them, and how much context budget they consume. These controls are essential for enterprise environments, shared teams, and security-sensitive projects.

Permission-Level Controls

{
  // Deny the Skill tool entirely - disables ALL skills
  "permissions": {
    "deny": ["Skill"]
  }
}

{
  // Allow only specific skills
  "permissions": {
    "deny": ["Skill"],
    "allow": [
      "Skill(commit)",
      "Skill(deploy-staging)"
    ]
  }
}

{
  // Allow a skill and all its sub-skills
  "permissions": {
    "allow": ["Skill(gsd *)"]
  }
}

{
  // Deny specific skills while allowing others
  "permissions": {
    "deny": [
      "Skill(deploy-production)",
      "Skill(db-migrate)"
    ]
  }
}

Frontmatter-Level Controls

Beyond permissions, the frontmatter provides two skill-level controls:

• disable-model-invocation: true — Blocks Claude from auto-activating the skill entirely. The skill only runs when a user explicitly types the slash command. This is the strongest per-skill control: it removes the skill from the description budget, prevents false activations, and ensures human intent.
• paths globs — Limits auto-activation to specific file patterns. A skill with paths: ["*.rs", "Cargo.toml"] only auto-activates when the user is working with Rust files. This prevents a Rust-specific skill from triggering during JavaScript work.

Description Budget Control

The environment variable SLASH_COMMAND_TOOL_CHAR_BUDGET controls the total character budget for skill descriptions in the system prompt. When the combined descriptions exceed this budget, skills are truncated or dropped to fit. This is a blunt instrument but useful when you have many skills and need to control context overhead:

# Reduce the description budget to 5000 characters
export SLASH_COMMAND_TOOL_CHAR_BUDGET=5000

# Start Claude Code with the reduced budget
claude

2.11 Production Skill Patterns — From Our 34+ Skills

Over 10 months of production use, we have built and refined 34+ skills that power an autonomous development workflow. These skills organize into five functional categories: orchestration, communication, pipeline, workflow, and state management. Each category addresses a distinct challenge in multi-agent systems.

The following patterns are drawn from real production skills running daily in our codebase (gsd-skill-creator). Code examples are simplified for clarity but reflect actual implementations.

Orchestration Skills

Orchestration skills coordinate multiple agents, dispatch work, and track progress. They are the "management layer" that decides who does what and monitors completion.

---
name: fleet-mission
description: >
  Parallel agent fleet dispatch with progress tracking and result
  aggregation. Launch N agents, monitor completion, merge results.
context: fork
allowed-tools:
  - Task
  - Read
  - Write
  - Bash
---

# Fleet Mission Protocol

1. Parse mission manifest from $ARGUMENTS
2. For each work unit, launch a subagent via Task tool
3. Monitor agent completion via status files
4. Aggregate results into unified report
5. Handle failures: retry once, then report partial results

Communication Skills

Communication skills solve the inter-agent messaging problem. In a multi-agent system, agents need to signal each other, pass data, and coordinate timing. These skills implement different communication patterns for different durability and timing requirements.

{
  "id": "msg-2026-04-07-001",
  "from": "executor-3",
  "to": "mayor",
  "subject": "Phase 12 complete",
  "body": "All 4 plans executed. 0 failures. Ready for verify.",
  "timestamp": "2026-04-07T14:32:00Z",
  "read": false
}

Pipeline Skills

Pipeline skills implement multi-stage processing flows with defined inputs, transformations, and outputs. Each stage has explicit success and failure handling.

Workflow Skills

Workflow skills manage the lifecycle of development work — from planning through execution to verification. They encode institutional knowledge about how work moves through the system.

State Management Skills

State management skills handle persistence, recovery, and runtime abstraction. They ensure the system survives crashes, restarts, and context resets.

{
  "version": 3,
  "timestamp": "2026-04-07T14:30:00Z",
  "agents": {
    "executor-1": { "status": "active", "task": "phase-12-plan-3" },
    "executor-2": { "status": "idle", "task": null }
  },
  "work_queue": ["phase-12-plan-4", "phase-12-plan-5"],
  "completed": ["phase-12-plan-1", "phase-12-plan-2"]
}

How Skills Compose: A Worked Example

To understand how these patterns work together in practice, consider what happens when a developer types /gsd-execute-phase 12 in our production system. This single command triggers a cascade of skill compositions:

1. gsd-workflow (workflow) receives the request and determines that phase 12 needs execution. It reads the ROADMAP.md and PLAN files to understand the phase structure and dependencies.
2. sling-dispatch (orchestration) takes the phase's plan files and enters its 7-stage pipeline: it fetches plan files, allocates agents to each plan, prepares context for each agent, runs pre-execution hooks, then dispatches execution.
3. fleet-mission (orchestration) launches parallel subagents — one per plan in the phase. Plans in Wave 1 run simultaneously; Wave 2 waits for Wave 1 to complete.
4. beads-state (state) tracks each agent's status, writing crash-recoverable state files after every significant operation. If the system fails during execution, the state file shows exactly which plans completed and which did not.
5. nudge-sync (communication) provides real-time progress updates. Each executor agent writes a nudge file with its current status, which the fleet-mission coordinator polls to track overall progress.
6. Each executor loads beautiful-commits (workflow) to create properly formatted commits for its completed work.
7. When all executors complete, done-retirement (pipeline) validates the results, creates a summary commit, pushes to the remote, and archives the working files.
8. Finally, session-awareness (workflow) updates the project state files so the next session knows phase 12 is complete and phase 13 is ready.

This entire sequence is driven by skills. No hardcoded logic exists in the agent's base behavior — the skills provide all the procedural knowledge. This means the workflow can be modified by editing SKILL.md files, without changing any code. The composition is emergent: each skill focuses on one responsibility, and the orchestration skills wire them together through convention (well-known file paths, state file formats, nudge protocols).

2.12 Skill Design Guidelines

Effective skills are the result of deliberate design decisions about description quality, content structure, invocation patterns, and testing. The following guidelines are distilled from building and maintaining 34+ production skills over 10 months.

Description Writing

The description is the most important field in a skill's frontmatter. It serves three purposes simultaneously: it tells Claude when to auto-activate the skill, it tells users what the skill does in the / menu, and it contributes to the persistent context budget. Every word must earn its place.

Content Structure

• Keep SKILL.md under 500 lines. Extract reference material, templates, and examples into supporting files. The SKILL.md should contain decision logic and step sequencing.
• Use clear headings. Claude parses Markdown structure to understand the skill's organization. H2 for major sections, H3 for subsections.
• Number your steps. Ordered lists produce more reliable execution than prose paragraphs. Claude follows numbered steps sequentially.
• Include error handling. Tell Claude what to do when a step fails. "If the build fails, check the error log at build.log and fix the issue before proceeding."
• Reference supporting files with ${CLAUDE_SKILL_DIR}. This ensures portability across different machines and directory structures.

Testing Skills

Test both activation modes for every skill:

1. Manual invocation: Type the slash command and verify it executes correctly. Test with different arguments, no arguments, and malformed arguments.
2. Auto-activation: Describe the problem the skill solves in natural language and verify Claude loads the skill. Test with variations of the trigger phrases. Verify the skill does not activate for unrelated requests.
3. Edge cases: Test with large inputs, missing prerequisites (files not found, tools not available), and concurrent invocations (if the skill is used in multi-agent contexts).

Troubleshooting

Skill Lifecycle Best Practices

Skill Architecture at Scale

Our production system demonstrates that skills scale to complex autonomous workflows. The 34+ skills organize into a layered architecture where each layer builds on the one below:

Each layer depends only on layers below it. Primitive skills have no skill dependencies. Protocol skills use primitive skills. Pipelines compose protocols. Orchestration skills dispatch pipelines. Workflow skills tie everything together into a coherent developer experience. This layered approach enables individual skills to be tested, replaced, and evolved independently.

The analogy to software architecture is intentional and precise. Just as a well-designed software system separates concerns into layers (data access, business logic, presentation), a well-designed skill system separates agent capabilities into composable layers. The primitive layer handles I/O and persistence. The protocol layer handles coordination semantics. The pipeline layer handles multi-step process flows. The orchestration layer handles agent topology. The workflow layer handles human interaction. Each layer has its own testing surface and failure modes, and problems at one layer can be diagnosed and fixed without affecting the others.

This architecture was not designed upfront. It emerged over 10 months of iterative development, driven by real problems encountered in production. The earliest skills were monolithic — a single 800-line SKILL.md that tried to handle orchestration, state management, and workflow logic. As the system grew to 20+ skills, the monolithic approach became unmaintainable: changes to state persistence broke orchestration, changes to orchestration broke workflow routing. The refactoring into layered, single-responsibility skills was driven by the same forces that drive the evolution of any production software system — the need for independent changeability and testability.