majiayu000 Specification Decomposer
Transform large unified specifications into agent skills with multi-level progressive disclosure.
When to Use
- Source specification exceeds 50KB (too large for single context load)
- Content has natural semantic groupings (domains, topics, categories)
- Granular access needed (load only relevant parts per query)
- Source has atomic units (patterns, sections, articles) that can stand alone
Core Workflow
- Analyze source spec structure and size
- Identify semantic domains (not structural divisions)
- Map atomic units to domains
- Design navigation architecture:
- SKILL.md as AI decision hub
- Domain indexes with manual navigation + auto-generated tables
- Pattern preservation strategy for updates
- Generate 4-level hierarchy:
- Level 1: SKILL.md frontmatter (always loaded)
- Level 2: SKILL.md body (on skill trigger)
- Level 3: Domain index files (on domain access)
- Level 4: Individual unit files (on specific need)
- Implement generation script with navigation preservation
- Validate file sizes (<50KB each)
Key Principles
Semantic over Structural
Group by meaning/use-case, NOT by source document structure.
Bad: Part A, Part B, Part C (mirrors source structure) Good: foundations, workflows, trust-assessment (mirrors usage)
Individual over Clustered
Keep atomic units separate with TOC navigation.
Bad: Cluster related items into single files Good: Individual files + domain index with "Load when..." guidance
Why: Clustering forces loading unnecessary context. Individual files + TOC = load exactly what's needed.
Levels Encoded by Convention
domain/
├── index.md # Level 3 (always named index.md)
├── unit_1.md # Level 4
└── unit_2.md # Level 4
No separate level folders - the level is implicit in the file role.
File Size Limits
| Level | Max Size | Content |
|---|---|---|
| L2 SKILL.md body | 50KB / ~500 lines | Core workflow + domain navigation |
| L3 domain/index.md | 20KB / ~200 lines | Domain overview + unit TOC |
| L4 individual files | 50KB | Single atomic unit |
If a unit exceeds 50KB, split into sub-units with their own index.
Optional Directories
According to the Agent Skills specification, three optional directories can enhance your skill:
references/prompts/
For complex skills, add operational prompts in references/prompts/:
| File | Purpose |
|---|---|
workflow.md |
Step-by-step process for using the skill |
principles.md |
Quick reference for key concepts |
keywords.md |
Navigation hints, search terms |
Prompts help the agent know HOW to use the decomposed content effectively. See references/operational-prompts.md for details.
assets/
Store static resources that support the skill:
- Templates (document templates, configuration templates)
- Images (diagrams, examples)
- Data files (lookup tables, schemas)
scripts/
Automation scripts for maintaining the skill structure (generation, validation, etc.)
Frontmatter Extensions
The official Agent Skills specification defines a minimal set of required fields (name, description) and optional fields (license, compatibility, metadata, allowed-tools).
Specific clients (e.g., Cursor) may extend frontmatter with additional fields:
priority: high- skill loading priorityauto_load: true- automatic activation
Such extensions maintain backward compatibility with the base specification.
References
- 4-level architecture details: See references/4-level-architecture.md
- Navigation architecture: See references/navigation-architecture.md - SKILL.md and index.md structure patterns
- Domain identification: See references/domain-grouping.md
- Size enforcement: See references/size-constraints.md
- Operational prompts: See references/operational-prompts.md