# spec-decomposer

> Decompose large unified specifications into agent skills with progressive disclosure. Use when converting documentation, frameworks, or knowledge bases exceeding 50KB into properly structured skills that Claude can navigate efficiently.

- Author: Pavel Goncharov
- Repository: pavelgnch/llm-role-pack
- Version: 20260125142811
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/pavelgnch/llm-role-pack
- Web: https://mule.run/skillshub/@@pavelgnch/llm-role-pack~spec-decomposer:20260125142811

---

---
name: spec-decomposer
description: Decompose large unified specifications into agent skills with progressive disclosure. Use when converting documentation, frameworks, or knowledge bases exceeding 50KB into properly structured skills that Claude can navigate efficiently.
license: Complete terms in LICENSE.txt
---

# 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

1. **Analyze** source spec structure and size
2. **Identify** semantic domains (not structural divisions)
3. **Map** atomic units to domains
4. **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)
5. **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: Operational Prompts

For complex skills, consider adding a `prompts/` folder with usage guidance:

| 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](references/operational-prompts.md) for details.

## References

- **4-level architecture details**: See [references/4-level-architecture.md](references/4-level-architecture.md)
- **Domain identification**: See [references/domain-grouping.md](references/domain-grouping.md)
- **Size enforcement**: See [references/size-constraints.md](references/size-constraints.md)
- **Operational prompts**: See [references/operational-prompts.md](references/operational-prompts.md)