---

name: skill-composition-patterns description: Use when a task is too large or too multi-domain for a single skill, you are noticing overlap between existing skills, or you want to build a skill system that routes between skills cleanly. Covers the entry-router, reference-file, and skill-chain patterns plus split vs merge decisions and safe cross-linking.

Skill Composition Patterns

A single skill handles one repeatable job. But real workflows cross several jobs. This skill covers how to connect skills together without turning them into a tangled monolith.

This guide is grounded in the real skill structure of this repo. The existing skill system at .agents/skills/ and .claude/skills/ provides working examples of all three patterns.

When to trigger

A task crosses multiple sub-domains, you are seeing duplicate content across skills, a skill is getting too long to have one clear job, or you want to build a skill that dispatches to more specialized ones.

The three composition patterns

Pattern 1: Entry router

One skill acts as the dispatcher. It reads the request, maps it to the right specialized skill, and says "go there." It holds the map, not the procedures.

Real example in this repo: The skills-mcp-platform skill under .agents/skills/skills-mcp-platform/SKILL.md routes skill library work. The handoff skill routes content CI work.

Use this when:

• A domain has multiple sub-tasks an agent cannot reliably distinguish from a single description.
• You want a stable entry point that grows without changing the specialized skills.

The entry router holds no procedure of its own. If it starts accumulating steps, those steps belong in a specialized skill.

Pattern 2: Reference files

A skill has a main SKILL.md that covers the workflow and one or more reference files that cover supporting detail. Reference files are loaded on demand - the agent only fetches them when it decides it needs the depth.

Real example in this repo: agent-fleet-coordination in the public library has reference/roles.md, reference/file-ownership.md, and reference/harvest-loop.md. Each reference file covers one thing. The main SKILL.md describes the workflow and tells the agent when to load each reference.

For repo skills: use a flat SKILL.md with a ## Reference section at the end that lists what else the agent should read and when.

For flagship library skills: use the multi-file format. Source files go in skills-source/<slug>/reference/. The generator at scripts/build-flagship-skills.mjs compiles them into lib/library/flagship-skills.ts. Each reference file gets a purpose field in the META object that tells the agent when to fetch it.

skills-source/
  my-skill/
    SKILL.md              <- main workflow
    reference/
      advanced-config.md  <- loaded on demand
      pitfall-catalog.md  <- loaded on demand

Pattern 3: Skill chain

Skills reference each other through the relatedPaths field and inline "after this, see" notes. Each skill is complete on its own; the chain is navigational, for an agent that needs the next step.

Real example in this repo: The neon-drizzle-migrations skill links to neon-serverless-patterns via relatedPaths. The skill-writing-guide skill links to skill-testing-checklist and skill-composition-patterns - this file.

Use this when two skills are naturally sequential (write the skill, then test it) or one skill has a well-known follow-up outside its scope. The chain is navigational, not procedural.

Split vs merge for this repo

Split when:

• The skill has two distinct trigger conditions that would not both fire for the same task.
• The skill covers both a public/marketing surface AND a dashboard/member surface - those are different design contracts.
• The skill is accumulating rules that already exist in AGENTS.md (those belong there, not in the skill).
• The skill is longer than one screen and you cannot identify the one job it is for.

Merge when:

• Two tiny skills are always triggered together and one is meaningless without the other.
• Splitting creates duplication: the same command in both files.

The right answer is almost always to split. Merging is usually laziness.

Safe cross-linking

Reference another skill by slug or path. Never reproduce its content inline.

• OK: "Before running these steps, load the ship-pipeline skill."
• OK: "For billing, see credit-metered-ai-endpoints in the library."
• Not OK: paste the other skill's procedure inline.

Rules that apply everywhere (no em dashes, no gradients, square corners, work on branches) belong in AGENTS.md > CRITICAL RULES - not in a skill. Point there.

Versioning contract

Full workflow: AGENTS.md > Repo Skills > Flagship skill authoring.

Pitfalls

• An entry router that starts accumulating procedure steps becomes the skill agents load for everything in the domain. Keep entry routers mapping-only. When it gets steps, extract them into a specialized skill.
• Flagship reference files that grow larger than their parent SKILL.md suggest the reference is the real skill. Promote it.
• Hand-editing lib/library/flagship-skills.ts creates drift from the source files. If you change a flagship skill, always edit the source in skills-source/ and re-run the generator.
• Two skills with overlapping triggers will both load for some requests. If they give contradictory instructions, one wins arbitrarily. Audit trigger overlap when adding a new skill that touches an existing domain.
• Not syncing .agents/skills/ and .claude/skills/ means Codex agents and Claude Code agents have different skill sets. Always write to both.
• Putting global rules (no em dashes, square corners) inside a skill creates a second source of truth that drifts from AGENTS.md. Keep global rules in AGENTS.md; keep workflow-specific knowledge in skills.