Skip to content

naman10parikh/agentgrid / .claude/skills/skill-routing

skill-routing

Verified

FileKindSize
SKILL.mdskill md2.6 KB
# Skill Routing — Progressive Disclosure for Large Skill Libraries

## How Skills Scale Without Bloating Context

Claude Code's architecture already solves the "50,000 skills" problem:

### Three-Level Loading

1. **Level 1 (startup):** Only YAML frontmatter loaded (~70-100 tokens per skill). Claude sees name + description.
2. **Level 2 (on-demand):** Full SKILL.md content loaded when Claude determines the skill is relevant.
3. **Level 3 (supporting files):** Additional files loaded only when the skill explicitly references them.

### Rules for Progressive Disclosure

- `.claude/rules/` files use **glob patterns** — loaded ONLY when matching files are touched.
- Example: `typescript.md` with `paths: ["*.ts", "*.tsx"]` only loads when editing TypeScript.
- This means you can have 100 rules and Claude only sees the 2-3 relevant ones.

### MCP Tool Search

When MCP servers exceed ~10% of context:

- Enable: `ENABLE_TOOL_SEARCH=auto:5` (5% threshold)
- Effect: Tool schemas loaded on demand instead of upfront
- Supported on Sonnet 4+, Opus 4+

### Skill Organization Pattern

```
.claude/skills/
├── architect/SKILL.md       ← System design (loaded when planning)
├── loop-create/SKILL.md     ← Agent scaffolding (loaded when creating .loop)
├── sprint/SKILL.md          ← Sprint planning (loaded when planning work)
├── test-visual/SKILL.md     ← Browser testing (loaded when testing UI)
├── harness-review/SKILL.md  ← Harness audit (loaded when reviewing quality)
├── deep-think/SKILL.md      ← Reasoning (loaded for complex problems)
├── self-improve/SKILL.md    ← Meta-improvement (loaded for optimization)
├── integrate-resources/SKILL.md ← Knowledge processing (loaded for resources)
└── skill-routing/SKILL.md   ← THIS FILE (loaded when discussing skill management)
```

### Key Principle

CLAUDE.md stays under 2K tokens. Skills are the overflow valve — anything too detailed for CLAUDE.md becomes a skill. Claude discovers skills by name/description and loads them when needed. This means CLAUDE.md can reference 50 skills at ~70 tokens each (3,500 tokens of metadata) while actual skill content (potentially 100K+ tokens total) loads only on demand.

### When to Create a New Skill vs. a New Rule

- **Skill:** Reusable workflow invoked by name. Example: `/architect` for system design.
- **Rule:** Context-specific instructions activated by file pattern. Example: "When editing \*.test.ts, always use Vitest."
- **Command:** User-facing shortcut. Example: `/start` loads context.
- **Hook:** Automated action on lifecycle event. Example: format code after write.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall