Skills rarely exist in isolation. Complex tasks require combining multiple skills, and understanding composition patterns helps you design skills that work well together. This skill covers how to decompose complex topics into composable skill units, define interfaces between skills, and architect skill packs that are greater than the sum of their parts.

## Key Points

1. Inline reference (within a section):
2. Prerequisites block (at the top):
- Familiarity with REST API concepts
- Node.js project with Express installed
3. Next steps (at the bottom):
- Add authorization rules
- Set up monitoring
4. Comparison reference:
- Planning a new skill pack with multiple related skills
- Deciding how to split a large topic across skill files
- Reviewing a skill pack for structural coherence
- Adding a new skill to an existing pack

Skill Composition Patterns

Purpose

Skills rarely exist in isolation. Complex tasks require combining multiple skills, and understanding composition patterns helps you design skills that work well together. This skill covers how to decompose complex topics into composable skill units, define interfaces between skills, and architect skill packs that are greater than the sum of their parts.

Composition Fundamentals

Why Compose Skills?

Problems with monolithic skills:
├── Too long to load into context efficiently
├── Cover too many topics to be discoverable
├── Hard to update (changing one section risks breaking others)
├── Can't be mixed and matched for different tasks
└── Duplicate content across similar skills

Problems with overly granular skills:
├── Too many files to manage
├── Lost context — each skill is too narrow to be useful alone
├── Excessive cross-referencing needed
├── Agent must load many skills for simple tasks
└── No coherent narrative or learning path

The sweet spot:
Each skill covers one coherent task or concept area,
but references related skills for extended capabilities.

Composition vs. Dependency

Composition: Skill A and Skill B are independently useful,
but together they enable a more powerful workflow.

Dependency: Skill B requires Skill A to function.
Skill B alone doesn't make sense.

├── Composition example:
│   ├── "PostgreSQL Query Optimization" + "Database Monitoring"
│   │   = Both useful alone, together enable performance management
│   └── Either skill can be used without the other
│
├── Dependency example:
│   ├── "Kubernetes Pod Debugging" depends on "Kubernetes Fundamentals"
│   │   = Debugging skill assumes knowledge from fundamentals
│   └── Should reference, but remain usable with basic K8s knowledge
│
└── Goal: Prefer composition over dependency
    └── Each skill should include enough context to be standalone
    └── Reference other skills for depth, not for basic understanding

Composition Patterns

Pattern 1: Layer Cake

Skills organized by abstraction level, each building on the previous:

Layer Cake Pattern:
┌──────────────────────────────────┐
│ Advanced Patterns & Optimization │  ← Layer 3
├──────────────────────────────────┤
│ Core Implementation              │  ← Layer 2
├──────────────────────────────────┤
│ Fundamentals & Setup             │  ← Layer 1
└──────────────────────────────────┘

Example: React skills
├── Layer 1: react-fundamentals.md
│   └── Components, JSX, state, props, hooks basics
├── Layer 2: react-state-management.md
│   └── useState, useReducer, context, patterns
├── Layer 3: react-performance-optimization.md
│   └── Memoization, virtualization, code splitting

Rules for Layer Cake:
├── Each layer is independently useful
├── Higher layers mention but don't repeat lower layer content
├── User can enter at any layer based on experience
├── Reference format: "See [Skill Name] for foundation on X"
└── Each layer has its own "When to Apply" criteria

Pattern 2: Hub and Spoke

One central skill connects to specialized satellite skills:

Hub and Spoke Pattern:
                ┌────────────┐
                │ API Auth   │
                └─────┬──────┘
                      │
┌────────────┐  ┌─────┴──────┐  ┌────────────┐
│ API Error  │──│ REST API   │──│ API Rate   │
│ Handling   │  │ Design     │  │ Limiting   │
└────────────┘  │ (Hub)      │  └────────────┘
                └─────┬──────┘
                      │
                ┌─────┴──────┐
                │ API        │
                │ Versioning │
                └────────────┘

Hub skill: Broad overview with clear pointers to spokes
Spoke skills: Deep dive into specific aspects

Hub content:
├── Overview of the full domain
├── Decision framework (which spoke do I need?)
├── Common patterns that connect spokes
└── Brief coverage of each spoke topic + reference

Spoke content:
├── Deep, focused coverage of one aspect
├── Standalone (includes enough hub context to function)
├── References hub for broader context
└── May reference sibling spokes for related topics

Pattern 3: Pipeline

Skills that represent stages of a workflow:

Pipeline Pattern:
┌────────┐   ┌────────┐   ┌────────┐   ┌────────┐
│ Design │──→│ Build  │──→│ Test   │──→│ Deploy │
│        │   │        │   │        │   │        │
└────────┘   └────────┘   └────────┘   └────────┘

Each stage:
├── Can be used independently (enter pipeline at any stage)
├── Defines clear inputs (what do I need to start this stage?)
├── Defines clear outputs (what does this stage produce?)
├── References previous stage for context
└── References next stage for "what's next"

Example: Machine Learning Pipeline
├── ml-data-preparation.md
│   ├── Input: Raw data sources
│   └── Output: Cleaned, feature-engineered dataset
├── ml-model-training.md
│   ├── Input: Prepared dataset
│   └── Output: Trained model + evaluation metrics
├── ml-model-evaluation.md
│   ├── Input: Trained model + test data
│   └── Output: Performance report + go/no-go decision
└── ml-model-deployment.md
    ├── Input: Validated model
    └── Output: Production-ready model serving endpoint

Pattern 4: Matrix

Skills organized along two dimensions (technology x concern):

Matrix Pattern:
              │ Setup      │ Usage       │ Debugging
──────────────┼────────────┼─────────────┼───────────
PostgreSQL    │ pg-setup   │ pg-queries  │ pg-debug
              │            │             │
Redis         │ redis-setup│ redis-usage │ redis-debug
              │            │             │
MongoDB       │ mongo-setup│ mongo-usage │ mongo-debug

Benefits:
├── Users can navigate by technology OR by concern
├── Consistent structure across a dimension
├── Easy to identify gaps (empty cells = missing skill)
└── Templating possible along one dimension

Each cell skill:
├── Stands alone for its specific intersection
├── Cross-references same row (other concerns for same tech)
├── Cross-references same column (same concern, different tech)
└── Shares structure with other skills in same column

Pattern 5: Specialization

A general skill and multiple specialized variants:

Specialization Pattern:
        ┌────────────────────┐
        │ Authentication     │
        │ (General Concepts) │
        └────┬───────┬───────┘
             │       │
    ┌────────┴─┐  ┌──┴────────┐  ┌──────────────┐
    │ OAuth2   │  │ JWT Auth  │  │ Session Auth │
    │ (spec)   │  │ (spec)    │  │ (spec)       │
    └──────────┘  └───────────┘  └──────────────┘

General skill:
├── Covers concepts common to all specializations
├── Comparison table to help choose specialization
├── Doesn't duplicate specialized content
└── "Choose X when..." decision framework

Specialized skills:
├── Inherit context from general skill (brief recap)
├── Deep implementation detail for specific approach
├── Include migration path from other specializations
└── Standalone usable (includes enough general context)

Designing Skill Interfaces

Input and Output Contracts

Every skill should implicitly or explicitly define:

Inputs (prerequisites):
├── What knowledge is assumed?
├── What tools/environment must exist?
├── What state must the system be in?
└── What data/artifacts are needed?

Outputs (results):
├── What will be true after applying this skill?
├── What artifacts are produced?
├── What state does the system end in?
└── What can the user do next?

Example:
Skill: "Docker Multi-Stage Build Optimization"

Inputs:
├── Working Dockerfile (single-stage, functioning)
├── Docker installed and running
├── Application that builds and runs correctly
└── Basic Docker knowledge (images, containers, layers)

Outputs:
├── Multi-stage Dockerfile (smaller image size)
├── Separate build and runtime stages
├── Understanding of layer caching for CI/CD
└── Ready for: deployment, CI pipeline integration

Cross-Referencing Between Skills

Cross-Reference Patterns:

1. Inline reference (within a section):
   "For database connection pooling configuration,
   see the 'PostgreSQL Connection Management' skill."

2. Prerequisites block (at the top):
   "Prerequisites:
   - Familiarity with REST API concepts
     (see 'REST API Design Fundamentals')
   - Node.js project with Express installed
     (see 'Express.js Project Setup')"

3. Next steps (at the bottom):
   "After implementing authentication:
   - Add authorization rules
     (see 'Role-Based Access Control')
   - Set up monitoring
     (see 'API Security Monitoring')"

4. Comparison reference:
   "This skill covers the React approach.
   For Vue.js, see 'Vue Composition API Patterns'.
   For Angular, see 'Angular Signal Patterns'."

Rules:
├── Reference by title (not file path — titles are stable)
├── Brief context for why the reference is relevant
├── Never require the referenced skill (standalone principle)
└── Reference both upstream (prerequisites) and downstream (next steps)

Skill Pack Organization

Directory Structure

Recommended pack structure:
skills/
├── react-skills/
│   ├── react-fundamentals.md
│   ├── react-hooks-patterns.md
│   ├── react-state-management.md
│   ├── react-performance.md
│   ├── react-testing.md
│   └── react-server-components.md
├── devops-skills/
│   ├── docker-fundamentals.md
│   ├── docker-compose-patterns.md
│   ├── kubernetes-fundamentals.md
│   ├── ci-cd-pipelines.md
│   └── infrastructure-as-code.md
└── database-skills/
    ├── sql-fundamentals.md
    ├── postgresql-optimization.md
    ├── database-migrations.md
    └── database-monitoring.md

Naming Conventions:
├── Directory: kebab-case, plural, descriptive category
├── Files: kebab-case, specific topic
├── No numbered prefixes (001-xxx) — use metadata for ordering
├── No "part-1", "part-2" — give each a descriptive name
└── Match category in frontmatter to directory name

Pack Cohesion

Signs of good pack cohesion:
├── All skills share a common domain
├── Skills reference each other naturally
├── A user interested in one skill likely needs others in the pack
├── The pack tells a complete story for its domain
└── No skill feels "orphaned" or unrelated

Signs of poor pack cohesion:
├── Skills on unrelated topics grouped together
├── No cross-references between skills in the pack
├── Wide variance in depth/quality between skills
├── Pack is too broad ("programming-skills" with 50 topics)
└── Some skills belong in a different pack

When to Apply This Skill

Use this skill when:

• Planning a new skill pack with multiple related skills
• Deciding how to split a large topic across skill files
• Reviewing a skill pack for structural coherence
• Adding a new skill to an existing pack
• Refactoring skills that overlap or duplicate content
• Designing skill navigation for a specific workflow