modular-skill-framework

name	modular-skill-framework
description	This skill should be used when the user asks about "modular skills", "composable skills", "skill composition", "split a skill", "skill boundaries", "skill interfaces", "token-efficient skills", "single responsibility for skills", or needs design patterns and implementation guidelines for reusable skill components in Claude Code plugins.

Modular Skills Framework

Design patterns and implementation guidelines for reusable skill components that compose cleanly, stay focused, and minimize context overhead.

Core Principles

• Single Responsibility — One focused purpose per skill; one primary workflow or decision domain.
• Composable Design — Skills combine via explicit handoffs, shared references, and sibling skills rather than monolithic instructions.
• Clear Interfaces — Well-defined contracts for triggers, inputs, outputs, and bundled resources so agents know what to load and when.
• Token Efficiency — Minimal always-on context; bulk detail in references/, determinism in scripts/, output files in assets/.

When to Use This Skill vs skill-development

Question	Use
How to write SKILL.md, frontmatter, triggers	skill-development
Whether to split/merge skills, compose a plugin skill set	modular-skill-framework
Quality audit of one skill	skill-development + /meta:audit-skill
Plugin directory layout, plugin.json	plugin-structure

Apply both when scaffolding a new skill ecosystem: use this skill for boundaries and composition, then skill-development for file-level authoring and the quality checklist.

Skill Boundaries (Single Responsibility)

Before adding content to an existing skill, ask:

1. Trigger test — Would a different user phrase activate a different workflow? If yes, consider a sibling skill with its own description triggers.
2. Audience test — Does the content serve a different role (author vs auditor vs operator)? Split by role when workflows diverge.
3. Depth test — Is the material reference documentation (>~300 words, schemas, checklists)? Move to references/; if the reference set has its own lifecycle, consider a dedicated skill.
4. Overlap test — Do trigger phrases collide with a sibling in the same plugin? Narrow descriptions or merge skills.

Prefer:

• One primary outcome per skill (e.g. "create commit" not "all of git")
• Commands for one-shot audits; skills for reusable authoring patterns
• Shared references/ only when two skills truly share stable docs

Avoid:

• Kitchen-sink skills that list every related task in one description
• Duplicating the same checklist in multiple skills (link once, load on demand)
• Nested skill directories or multiple SKILL.md files per skill name

Composable Design

Skills compose at three layers:

Plugin skill set
├── Sibling skills     # Parallel specialists (git-commit, git-push, git-pr)
├── Commands           # Orchestrated one-shots (/meta:audit-skill)
└── Bundled resources  # Shared references/scripts where justified

Composition patterns:

1. Pipeline — Skill A ends with "then apply skill-b" when the user needs the next phase. Name the sibling explicitly; do not paste skill-b's body.
2. Facade + specialists — A thin overview skill (rare) points to focused siblings; prefer plugin README and discovery via distinct triggers instead.
3. Command orchestration — Multi-step evaluation (e.g. batch skill audit) lives in commands/, loading each target skill's checklist reference on demand.
4. Reference library — One canonical reference file; other skills link to it with a one-line "when to load" cue instead of copying content.

When designing a new plugin skill set, sketch triggers in a table (phrase → skill) before writing bodies. Eliminate ambiguous rows before implementation.

Clear Interfaces

Every skill exposes interfaces agents and commands rely on:

Interface	Contract
Discovery	description lists specific third-person trigger phrases
Activation	SKILL.md body = essential procedure only
References	Linked with when-to-load guidance; paths relative to skill root
Scripts	Documented invocation; use ${CLAUDE_PLUGIN_ROOT} in plugins
Handoff	Name sibling skill or command; state required inputs ($ARGUMENTS, paths)
Output	Stable headings or templates when consumers (commands, users) depend on format

Commands that invoke skills should say which reference to apply (e.g. references/quality-checklist.md) rather than inlining checklist text.

See references/interfaces.md for handoff templates and anti-patterns.

Token Efficiency

Load context in layers (see skill-development progressive disclosure):

1. Metadata — always available
2. SKILL.md — on trigger
3. references/, scripts/, assets/ — only when needed

Rules of thumb:

• Target a lean SKILL.md (~1,500 words or less in the body)
• Move schemas, long examples, and checklists to references/
• Use scripts for repeated deterministic checks instead of re-deriving steps
• Do not load assets/ into context unless transforming them

See references/token-efficiency.md for sizing and splitting guidance.

Implementation Workflow

1. Define the skill graph — List skills, triggers, and handoffs for the plugin.
2. Assign responsibilities — One primary outcome per skill; merge or split until the trigger table has no ambiguous rows.
3. Design interfaces — Frontmatter triggers, reference links, command entry points.
4. Scaffold directories — Create only references/, scripts/, assets/ in use.
5. Author with skill-development — Write SKILL.md, run quality checklist.
6. Validate composition — Check sibling overlap, handoff clarity, and README component list.

Additional Resources

• references/design-patterns.md — Split/merge heuristics, composition patterns, examples
• references/interfaces.md — Contracts, handoffs, command–skill integration
• references/token-efficiency.md — Context budgeting and reference sizing