feat: Apply progressive disclosure pattern to oversized skills
- Dominant language
- TypeScript
- Stars
- 72.7k
- Forks
- 8.6k
- Avg merge
- 2d 23h
- Merged PRs (30d)
- 83
Description
## Problem
Several skills in the `~/.claude/skills/` directory exceed the recommended 500-line limit for SKILL.md files. Large skill files increase token consumption and make maintenance difficult.
### Affected Skills
| Skill | Lines | Location |
|-------|-------|----------|
| hive-mind-advanced | 1568 | hive-mind-advanced/SKILL.md |
| swarm-advanced | 1484 | swarm-advanced/SKILL.md |
| flow-nexus-platform | 1360 | flow-nexus-platform/SKILL.md |
| sparc-methodology | 1307 | sparc-methodology/SKILL.md |
| github-workflow-automation | 1179 | github-workflow-automation/SKILL.md |
| flow-nexus-swarm | 1116 | flow-nexus-swarm/SKILL.md |
| github-release-management | 1045 | github-release-management/SKILL.md |
| agentdb-advanced | 1027 | agentdb-advanced/SKILL.md |
| reasoningbank-intelligence | 1004 | reasoningbank-intelligence/SKILL.md |
## Proposed Solution
Apply the **Progressive Disclosure Architecture** pattern:
1. **Main SKILL.md** (<500 lines): Quick Start, core concepts, behavioral classification
2. **Sub-files** loaded on demand:
- `reference.md` - Complete API/command reference
- `advanced.md` - Advanced patterns and configurations
- `troubleshooting.md` - Error handling and debugging
### Example Structure
```
hive-mind-advanced/
├── SKILL.md # Core documentation (<500 lines)
├── reference.md # Full API reference
├── advanced.md # Advanced patterns
└── troubleshooting.md
```
### Benefits
- **Reduced token consumption**: Only load what's needed
- **Better maintainability**: Smaller files easier to update
- **Consistent patterns**: Aligns with Skillsmith standards
## Related
- Skillsmith Linear Issue: SMI-1736
- ADR-025: Behavioral Classification Framework
## Implementation Notes
Each decomposed skill should also add a **Behavioral Classification** section to indicate its execution style:
```markdown
## Behavioral Classification
**Type**: [Autonomous Execution | Guided Decision | Interactive Exploration | Configurable Enforcement]
**Directive**: [EXECUTE, DON'T ASK | ASK, THEN EXECUTE | ASK THROUGHOUT | USER-CONFIGURED]
```
Contributor guide
Research direction
Start by reviewing the nine listed SKILL.md files under ~/.claude/skills/ and compare their sections with the proposed progressive-disclosure structure. The work is done when each main file is under 500 lines, supporting reference/advanced/troubleshooting files contain the deferred material, and every decomposed skill includes Behavioral Classification.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown
- Domain
- documentation
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100