Composite Skills

Compose atomic skills into coherent domain expertise with dependency resolution, progressive loading, and graceful degradation

The problem

Atomic skills work well for single concerns — variable scoping best practices, a code review checklist, error handling guidelines. But real-world domains require composing many judgment units into coherent expertise.

A senior engineer doing a code review doesn't apply one heuristic. They draw on variable scoping, testing patterns, error handling, and architecture reasoning simultaneously, weighting each based on context. An atomic skill can't express this. A composite skill can.

Two skill tiers

APM supports two tiers of skills:

Tier	Dependencies	Portability	Role
Atomic	None	Universal — works in any agentskills.io-compatible agent	A single, self-contained unit of domain expertise
Composite	Declares dependencies on other skills	Full support in APM-aware runtimes, graceful degradation elsewhere	Orchestrates how constituent skills are composed and applied

Atomic skills remain fully compliant with the agentskills.io specification. They are portable across all 34+ supporting agent products.

Composite skills extend the spec with a dependencies field and composition semantics. They are structurally valid SKILL.md files — any agent can consume them as standalone documents. APM-aware runtimes get the full benefit of dependency resolution and progressive loading.

The three-layer model

Composite skills fit into a three-layer architecture:

Workflow graph node (e.g., "code review step")
  → loads composite skill (e.g., "@anthropics/code-review")
    → loads atomic skills (e.g., "@anthropics/variable-scoping", "@anthropics/testing-patterns")

Layer	Role	Example
Workflow node	Orchestrates execution — what to do, in what order, with what gates	"Run code review on this PR"
Composite skill	Orchestrates judgment — what expertise to apply and how to compose it	"Evaluate against variable scoping, testing patterns, and error handling. Weight testing highest for backend code."
Atomic skill	Provides judgment — a single, self-contained unit of domain expertise	"Variables should be declared in the narrowest possible scope..."

The workflow says what to do. The composite skill says what judgment to apply. The atomic skills are the judgment.

Manifest format

A composite skill uses standard SKILL.md frontmatter with additional kind and dependencies fields:

---
name: code-review
description: >
  Comprehensive code review judgment composing variable scoping, testing
  patterns, error handling, and architecture reasoning. Use when reviewing
  code changes, pull requests, or conducting quality assessments.
kind: composite
dependencies:
  - "@anthropics/variable-scoping"
  - "@anthropics/testing-patterns"
  - "@anthropics/error-handling"
  - "@anthropics/architecture-reasoning"
---

`kind`

Explicit skill type: "composite" or "skill" (default). This is the same field used across the registry database, lockfile, and API responses.

`dependencies`

A flat list of scoped package names that this skill depends on. APM resolves and installs these when the composite skill is installed.

Rule of thumb: if a skill has a dependencies field, it's composite. If it doesn't, it's atomic.

Dependency resolution

Composite skill dependencies use the same resolution engine as all APM packages — the npm/pnpm model:

Recursive resolution. Installing a composite skill installs all constituent skills, including transitive dependencies.
DAG enforcement. The dependency graph must be a directed acyclic graph. Circular dependencies are rejected at install time.
Deduplication. If two composite skills both depend on @anthropics/testing-patterns, it is installed once in .skills/.
Version conflict handling. If two composites require incompatible versions of the same atomic skill, install fails with a clear error (pnpm-style strict resolution).
Partial failure. If a dependency fails to install, the parent composite skill is still installed and a warning is logged. The missing dependency can be retried with apm install.

apm install @anthropics/code-review
# Resolves and installs:
#   .skills/anthropics/code-review/SKILL.md              (composite)
#   .skills/anthropics/variable-scoping/SKILL.md          (atomic)
#   .skills/anthropics/testing-patterns/SKILL.md          (atomic)
#   .skills/anthropics/error-handling/SKILL.md             (atomic)
#   .skills/anthropics/architecture-reasoning/SKILL.md     (atomic)

Progressive disclosure

Loading all constituent skills at once would be wasteful. A composite skill with 12 dependencies shouldn't load 60,000 tokens into context simultaneously. Instead, composite skills use three-tier progressive disclosure:

Tier	When	Token budget	What loads
Discovery	Agent scans available skills	~100 tokens	`name` + `description` from frontmatter
Activation	Skill is relevant to current task	< 5,000 tokens	Composite SKILL.md body — the routing table
Constituent loading	Routing table condition matches	On demand	Individual atomic skill bodies

The composite skill body acts as a router. It contains a routing table that tells the agent which constituents to load based on the current context. The agent never loads all dependencies — only the ones the routing table directs it to.

Routing table

The routing table is the core of a composite skill's body. It maps trigger conditions to dependencies using a structured table:

Column	Required	Description
When	Yes	The condition under which this track activates. Natural language the agent matches against.
Load	Yes	What to load — a `@skill:` reference or relative file path.
Ignore	No	What to explicitly exclude from context. Prevents cross-contamination between tracks.

The When column is free-text. The agent matches it semantically against the current task.

The Load column is a @skill:scope/name reference (for cross-package dependencies) or a relative file path (for internal sub-entries within the skill directory).

The Ignore column is optional but recommended. It prevents agents from loading unrelated tracks into context. For composites with more than a few dependencies, always include it.

Two-column table (default)

Use when tracks are independent and don't need isolation:

| When | Load |
|------|------|
| Find, discover, or browse skills | `@skill:apm/search` |
| Install, add, or set up a skill | `@skill:apm/install` |

Three-column table (with isolation)

Use when tracks should not read each other's content:

| When | Load | Ignore |
|------|------|--------|
| You are the Orchestrator | orchestrator/ENTRY.md | implementation-agent/, review-agent/ |
| You are the Implementation Agent | implementation-agent/ENTRY.md | orchestrator/, review-agent/ |
| You are the Gate Review Agent | review-agent/ENTRY.md | orchestrator/, implementation-agent/ |

Directory structure

Composite skills use the same directory structure as atomic skills:

code-review/
├── SKILL.md          # Frontmatter (with dependencies) + routing table
├── references/       # Optional: composition guidance, domain context
├── scripts/          # Optional: executable code
└── assets/           # Optional: static resources

Composite skills do not contain their constituent skills. They reference them by scoped name. Constituents are independently installed packages in .skills/ — peers, not children.

Graceful degradation

Composite skills are structurally valid SKILL.md files. The kind, dependencies, and routing table are not part of the core agentskills.io spec, but the spec is permissive — unknown frontmatter fields are ignored, and the routing table is standard markdown.

This means:

APM-aware runtimes resolve dependencies, install constituents, and load them via the routing table.
Other agents see a valid SKILL.md and use the composite's body as standalone guidance. They don't get constituent loading, but they still get the routing instructions as readable text.

No agent breaks. APM-aware agents get the full experience.

Examples

Minimal: APM spec

A composite with two independent atomic dependencies:

---
name: spec
description: APM skill resolution. Defines how @skill references resolve to installed SKILL.md files.
kind: composite
dependencies:
  - "@apm/search"
  - "@apm/install"
---

## Skill resolution

`@skill:<scope>/<name>` resolves to `.skills/<scope>/<name>/SKILL.md`.
Read and follow the skill's instructions when relevant to the current task.
If the file does not exist, continue without it.

## Skills

| When | Load |
|------|------|
| Find, discover, or browse skills | `@skill:apm/search` |
| Install, add, or set up a skill | `@skill:apm/install` |

~60 tokens. Two tracks, no isolation needed.

Full: Code review

A composite with four dependencies and context-dependent routing:

---
name: code-review
description: >
  Comprehensive code review composing variable scoping, testing patterns,
  error handling, and architecture reasoning. Use when reviewing code
  changes, pull requests, or conducting quality assessments.
kind: composite
dependencies:
  - "@anthropics/variable-scoping"
  - "@anthropics/testing-patterns"
  - "@anthropics/error-handling"
  - "@anthropics/architecture-reasoning"
---

## Code Review

Apply the relevant judgment skills based on what is being reviewed.

| When | Load | Ignore |
|------|------|--------|
| All code changes | `@skill:anthropics/variable-scoping` | |
| All code changes | `@skill:anthropics/error-handling` | |
| Backend or infrastructure changes | `@skill:anthropics/architecture-reasoning` | |
| Backend or infrastructure changes | `@skill:anthropics/testing-patterns` | |
| Frontend changes | `@skill:anthropics/testing-patterns` | `@skill:anthropics/architecture-reasoning` |

## Judgment weighting

When concerns conflict, weight by impact:
1. Correctness (always wins)
2. Security (never compromise)
3. Readability (maintainability over cleverness)
4. Performance (only when measured)

The routing table replaces prose headers. The agent scans the When column, matches against the current context, and loads only the relevant skills. Frontend reviews load variable-scoping, error-handling, and testing-patterns — but explicitly ignore architecture-reasoning.

Next steps

SKILL.md Specification — atomic skill format and validation rules
@skill: Specification — reference syntax and resolution rules
Publishing — get your composite skill into the registry
CLI Reference — install and manage composite skills

On this page