Composite Skills

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:

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")

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 an additional dependencies field:

---
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.
dependencies:
  skills:
    - name: "@anthropics/variable-scoping"
      version: "^1.0"
    - name: "@anthropics/testing-patterns"
      version: "^1.0"
    - name: "@anthropics/error-handling"
      version: "^1.0"
    - name: "@anthropics/architecture-reasoning"
      version: "^2.0"
metadata:
  version: "1.0.0"
  nous.skill-tier: composite
---

dependencies.skills

A list of constituent skill dependencies. Each entry has:

metadata.nous.skill-tier

Explicit tier declaration: "composite" or "atomic" (default). This makes the distinction machine-readable for tooling and discovery.

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).

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:

The composite skill body acts as a router. It tells the runtime which constituents to load based on the current context. A code review composite might load @anthropics/variable-scoping for a frontend file but @anthropics/architecture-reasoning for an infrastructure change.

Directory structure

Composite skills use the same directory structure as atomic skills:

code-review/
├── SKILL.md          # Frontmatter (with dependencies) + composition instructions
├── 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 dependencies field is not part of the core agentskills.io spec, but the spec is permissive — unknown frontmatter fields are ignored.

This means:

• APM-aware runtimes resolve dependencies, install constituents, and load them progressively.
• 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 orchestration instructions.

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

Example

A complete composite skill for code review:

---
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.
dependencies:
  skills:
    - name: "@anthropics/variable-scoping"
      version: "^1.0"
    - name: "@anthropics/testing-patterns"
      version: "^1.0"
    - name: "@anthropics/error-handling"
      version: "^1.0"
    - name: "@anthropics/architecture-reasoning"
      version: "^2.0"
metadata:
  version: "1.0.0"
  nous.skill-tier: composite
---

## Code Review Composition

When reviewing code, apply the following judgment framework:

### For all code changes

Load and apply:
- **@anthropics/variable-scoping** — check scope hygiene, unused declarations, mutation patterns
- **@anthropics/error-handling** — verify error propagation, user-facing messages, logging

### For backend and infrastructure changes

Additionally load:
- **@anthropics/architecture-reasoning** — evaluate system boundaries, coupling, data flow
- **@anthropics/testing-patterns** — verify test coverage, edge cases, integration points

### For frontend changes

Additionally load:
- **@anthropics/testing-patterns** — focus on component testing, interaction flows, accessibility

### Judgment weighting

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

Next steps

• SKILL.md Specification — atomic skill format and validation rules
• Publishing — get your composite skill into the registry
• CLI Reference — install and manage composite skills