skills-composition

Skills Composition - Patterns

How to build workflows that span more than one Cursor / Agent Skill cleanly. Covers chaining, scope resolution, graceful degradation, and the discipline of "one skill, one capability".

Companion rules:

• 015-context-engineering.mdc - prompt packing, retrieval, compaction
• 100-core.mdc - SOLID / DRY / KISS / YAGNI

When to invoke

Use when designing:

• A slash command that needs to call more than one skill in sequence
• A skill that calls helpers in another skill (vs duplicating the logic)
• A workflow where a downstream skill is optional (graceful degradation)
• A new skill where the right answer might be "extend an existing skill instead"

Do not use for:

• Single-skill workflows - just call the skill directly
• One-off scripts - skills are for repeatable workflows

The Five Golden Rules

1. One skill, one capability. A skill answers one question well. Multiple capabilities = multiple skills.
2. Compose via commands, not by importing. Skills do not "import" each other; a slash command (or another skill's workflow) orchestrates them.
3. Project scope wins over personal scope. A project-scope skill (.cursor/skills/) wins over a personal-scope copy (~/.cursor/skills/) of the same name.
4. Auto-detect siblings; degrade gracefully. When skill A optionally extends skill B, A checks for B at known paths and skips silently if absent.
5. HITL gates between phases for irreversible steps. Even within a single command, prompt before destructive or expensive steps.

Skill scope resolution

Cursor (and Claude Code) discover skills at multiple paths. The resolution order:

flowchart LR
    invoke[Skill / command invocation]
    invoke --> proj{".cursor/skills/<name>/SKILL.md exists?"}
    proj -->|"Yes"| use1["Use project-scope skill"]
    proj -->|"No"| user{"~/.cursor/skills/<name>/SKILL.md exists?"}
    user -->|"Yes"| use2["Use personal-scope skill"]
    user -->|"No"| compat{".claude/skills or .codex/skills exists?"}
    compat -->|"Yes"| use3["Use compatibility-scope skill"]
    compat -->|"No"| missing[Skill not found]