Skip to content

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

skill-routing

Verified

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: 468kUpdated 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: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated 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: 321kUpdated Claude CodeCodexVerifiedInstall