discover-workflow

Install in 30 seconds:

```

/plugin marketplace add rand/cc-polymath

/plugin install cc-polymath@cc-polymath

```

Your first 3 commands:

```bash

/skills # See what's recommended for your project

/discover-frontend # Load React, Next.js, TypeScript skills (example)

bash ~/.claude/plugins/cc-polymath/scripts/verify-install.sh # Verify installation

```

Learn more:

• 📖 [Getting Started Guide](docs/GETTING_STARTED.md) - 5-minute quick start
• 💬 [Example Conversations](docs/FIRST_CONVERSATIONS.md) - See it in action
• 🆘 [Troubleshooting](docs/TROUBLESHOOTING.md) - Common issues & solutions
• ❓ [FAQ](docs/FAQ.md) - Quick answers

---

This repository solves a tradeoff problem: how to give Claude Code access to comprehensive development knowledge without overwhelming its context window on boot. The solution is atomic, composable skills organized through a multi-tier discovery system.

Using the default mechanism with many atomic skills yields a dilemma:

• Load everything upfront → 25K+ tokens consumed before any real work begins
• Load nothing → Claude lacks essential patterns and best practices
• Manual loading → Users must know what exists to ask for it

This creates an challenging tradeoff between comprehensive coverage and context efficiency.

Atomic Skills (447 total)

Each skill is focused, self-contained, and composable:

• Average 320 lines - small enough to load quickly
• Single responsibility - covers one clear topic
• Production-tested - real patterns from building at scale
• Cross-referenced - links to related skills for composition

Why atomic matters: Loading 5 focused skills (1.5K tokens) beats loading one monolithic guide (8K tokens) when you only need specific knowledge. Granularity enables precision.

Three-Tier Architecture

Tier 1: Gateway Skills (31 auto-discovered Agent Skills)

Lightweight entry points that activate automatically based on keywords:

• discover-api → triggers on "REST", "GraphQL", "authentication"
• discover-database → triggers on "PostgreSQL", "MongoDB", "Redis"
• discover-zig → triggers on "Zig", "comptime", "allocators"

Each gateway is ~200 lines with quick reference and loading commands.

Tier 2: Category Indexes (30 detailed references)

Full skill listings with descriptions, use cases, and workflows:

• api/INDEX.md → All 7 API skills with integration patterns
• database/INDEX.md → All 11 database skills with decision trees
• Only loaded when browsing or planning work

Tier 3: Individual Skills (on-demand)

Complete implementation guides loaded only when needed:

• api/rest-api-design.md → Full REST patterns
• database/postgres-query-optimization.md → EXPLAIN plans, indexes

Why This Works

Context efficiency: 60-84% reduction vs monolithic index

• Old approach: Load 25K token index on boot
• New approach: Load 2-5K tokens of relevant gateways as needed
• Result: More context available for actual code and conversation

No boot overhead: Claude Code starts with zero skills loaded

• Gateway skills auto-discover based on your prompt keywords
• Manual loading available when auto-discovery isn't enough
• System scales to hundreds more skills without boot cost

Discoverability: Users don't need to know what exists

• Keywords in prompts trigger relevant gateways automatically
• Gateways show what's available in their domain
• Progressive loading: gateway → index → specific skill