ruvnet / ruvnet/ruflo

feat: Apply progressive disclosure pattern to oversized skills

Open
#994 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.