Context-efficient development knowledge via progressive skill discovery

Claude Code Plugin: Install with /plugin install https://github.com/hanzoai/skills

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.

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.

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

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

Languages & Frameworks:

• Backend: Python (uv), Zig, Rust, Go (31 skills)
• Frontend: React, Next.js, TypeScript, Elegant Design (9 skills)
• Mobile: SwiftUI, Swift concurrency, SwiftData, React Native (10 skills)

Infrastructure & DevOps:

• Build Systems: Make, CMake, Gradle, Maven, Bazel, cross-platform (8 skills)
• Debugging: GDB, LLDB, Python, browser, memory, concurrency, production, distributed systems (14 skills)
• Cloud: AWS (7), GCP (6), Modal.com, Cloudflare Workers, Vercel (13 skills)
• Containers: Docker, Kubernetes, security (5 skills)
• CI/CD: GitHub Actions, pipelines (4 skills)
• Observability: Logging, metrics, tracing, OpenTelemetry, incident response (8 skills)

Data & APIs:

• Databases: Postgres, MongoDB, Redis, Redpanda, Iceberg, DuckDB (11 skills)
• Caching: Multi-layer (browser, HTTP, CDN, Redis), invalidation strategies (7 skills)
• API Design: REST, GraphQL, auth, rate limiting, versioning (7 skills)
• Data Engineering: ETL, streaming, batch processing (5 skills)
• Testing: Unit, integration, e2e, TDD, coverage (6 skills)

Machine Learning & AI (33 skills):

• LLM Evaluation: Benchmarks (MMLU, HellaSwag), frameworks (Arize Phoenix, Braintrust), LLM-as-judge (Prometheus, G-Eval), RAGAS metrics
• Model Routing: RouteLLM, model comparison, multi-model orchestration
• Advanced RAG: Hybrid search, reranking (cross-encoder, LLM), GraphRAG, hierarchical retrieval
• DSPy Framework: Signatures, modules, optimizers, RAG, assertions (7 skills)
• HuggingFace: Hub, Transformers, Datasets, Spaces, AutoTrain (5 skills)
• Fine-tuning: Unsloth, LoRA/PEFT, dataset prep (3 skills)

Information Retrieval (5 skills):

• Search fundamentals (TF-IDF, BM25, Elasticsearch)
• Vector search (dense retrieval, embeddings)
• Ranking & reranking (learning to rank, cross-encoders)
• Recommendation systems (collaborative, content-based, hybrid)
• Query understanding (expansion, spell correction, semantic search)

Programming Language Theory (13 skills):

• Lambda calculus, type systems, dependent types
• Curry-Howard correspondence, operational semantics
• Program verification with Hoare logic
• Typed Holes & Live Programming: Hazel/Hazelnut calculus, incremental typing
• AI-Assisted Programming: LLM + typed holes integration (OOPSLA 2024), type-driven code synthesis

Formal Methods (10 skills):

• SAT/SMT Solvers: Z3 basics, SAT strategies, SMT theory (3 skills)
• Lean 4: Proof basics, tactics, mathlib4, theorem proving (4 skills)
• Constraint Satisfaction: CSP modeling, propagation, backtracking (3 skills)

Advanced Mathematics (11 skills):

• Numerical: Linear algebra, optimization, probability/statistics (4 skills)
• Pure Math: Topology (point-set, algebraic), category theory, differential equations, abstract algebra, set theory, number theory (7 skills)

Systems Programming (8 skills):

• WebAssembly: Fundamentals, Rust toolchain, browser integration, server-side (4 skills)
• eBPF: Fundamentals, tracing/observability, networking, security monitoring (4 skills)

Collaboration & Process (14 skills):

• GitHub: Repository management, pull requests, issues/projects, security, Actions (5 skills)
• PRD Writing: Structure, requirements gathering, user stories, technical specs (4 skills)
• RFC Writing: Structure, technical design, consensus building, decision docs (4 skills)

Real-time & Networking (5 skills):

• WebSocket, Server-Sent Events, pub/sub patterns
• Tailscale VPN, mTLS, NAT traversal, Mosh
• Network resilience patterns

• Beads: AI-native task management, context strategies, multi-session workflows (4 skills)
• TUI Development: Bubble Tea (Go), Ratatui (Rust) (5 skills)
• Skill Discovery: Intelligent skill activation for repos and prompts (5 skills)
• Anti-Slop: Detection and cleanup of AI-generated patterns (Agent Skill)
• Elegant Design: World-class accessible interfaces, design systems (Agent Skill)
• Typed Holes Refactor: Systematic TDD-based refactoring (Agent Skill)

As Claude Code Plugin (Recommended):

/plugin install https://github.com/hanzoai/skills

That's it! All 350+ skills and the /skills command are immediately available.

Manual Installation: If automatic installation doesn't work, see INSTALL.md for detailed instructions and troubleshooting.

For local development or testing:

/plugin install /path/to/local/skills

Skills activate in three ways:

1. Auto-Discovery (Automatic) Gateway skills (discover-*) automatically activate when you mention relevant keywords:

• Say "REST API" → discover-api loads automatically
• Say "PostgreSQL" → discover-database loads automatically
• Say "machine learning" → discover-ml loads automatically

You don't need to do anything - just work naturally.

2. Manual Loading (Explicit) Load skills when you need specific knowledge:

# Load a skill to teach Claude about a topic
cat skills/api/rest-api-design.md

# Load multiple related skills
cat skills/database/postgres-schema-design.md
cat skills/database/postgres-query-optimization.md

Claude reads the skill and applies that knowledge to your project.

3. Tool Usage (Executable) Some skills include Python scripts and tools:

# First, load the skill so Claude knows how to use it
cat skills/anti-slop/SKILL.md

# Then Claude can run the tools
python skills/anti-slop/scripts/detect_slop.py file.md

# Or ask Claude: "Check this file for AI slop patterns"
# Claude will load the skill and run the tool automatically

How to Tell When Skills Are Active:

• Gateway skills mention themselves when they activate
• Claude will reference skill content in responses
• You can ask: "What skills are you currently using?"

When you need to browse or plan:

# Browse skills catalog
cat skills/README.md

# View a category
cat skills/api/INDEX.md          # All API skills
cat skills/database/INDEX.md     # All database skills

# Load a gateway
cat skills/discover-ml/SKILL.md  # ML gateway with quick reference

# Load specific skills
cat skills/api/rest-api-design.md
cat skills/database/postgres-query-optimization.md

Many skills include executable scripts and tools. Here's how to use them:

Anti-Slop Skill - Check for AI-generated patterns:

# Load the skill first (shows Claude how to detect slop)
cat skills/anti-slop/SKILL.md

# Run detection on a file
python skills/anti-slop/scripts/detect_slop.py path/to/file.md --verbose

# Clean up detected patterns
python skills/anti-slop/scripts/clean_slop.py path/to/file.md --save

# Preview changes without saving
python skills/anti-slop/scripts/clean_slop.py path/to/file.md

Example Output:

======================================================================
AI Slop Detection Report: document.md
======================================================================

Overall Slop Score: 0/100
Assessment: ✅ Low slop detected - Writing appears authentic and purposeful

Other Agent Skills with Tools:

• skills/elegant-design/ - UI design analysis and recommendations
• skills/typed-holes-refactor/ - Systematic refactoring with type-driven development
• skills/discover-*/ - Gateway skills that auto-activate on keywords

General Pattern:

1. Load the skill: cat skills/category/skill-name/SKILL.md
2. Use the tools: python skills/category/skill-name/scripts/tool.py
3. Check references: cat skills/category/skill-name/references/*.md

Skills are designed to combine for complex workflows:

Full-stack web app:

cat skills/api/rest-api-design.md
cat skills/frontend/nextjs-app-router.md
cat skills/database/postgres-schema-design.md
cat skills/caching/redis-caching-patterns.md
cat skills/cicd/github-actions-workflows.md

ML deployment with DSPy:

cat skills/ml/dspy-setup.md
cat skills/ml/dspy-modules.md
cat skills/modal/modal-gpu-workloads.md
cat skills/modal/modal-web-endpoints.md
cat skills/observability/structured-logging.md

Multi-layer caching strategy:

cat skills/caching/caching-fundamentals.md
cat skills/caching/service-worker-caching.md    # Browser
cat skills/caching/http-caching.md              # HTTP layer
cat skills/caching/cdn-edge-caching.md          # CDN edge
cat skills/caching/redis-caching-patterns.md    # Application
cat skills/caching/cache-invalidation-strategies.md

iOS app with streaming backend:

cat skills/mobile/swiftui-architecture.md
cat skills/mobile/swift-concurrency.md
cat skills/mobile/swiftdata-persistence.md
cat skills/mobile/ios-networking.md
cat skills/database/redpanda-streaming.md

.
├── CLAUDE.md              # Development guidelines & protocols
│                          # - Multi-agent orchestration
│                          # - Work Plan Protocol (4 phases)
│                          # - Language standards (uv, cargo, zig)
│                          # - Testing protocols
│                          # - Anti-patterns
│
├── README.md              # This file
│
└── skills/                # 283 atomic skills, 31 gateways, 30 categories
    │
    ├── README.md          # Skills catalog
    │
    ├── Gateway Skills (31 auto-discovered Agent Skills)
    │   ├── discover-api/           # REST, GraphQL, authentication
    │   ├── discover-database/      # PostgreSQL, MongoDB, Redis
    │   ├── discover-frontend/      # React, Next.js, UI components
    │   ├── discover-ml/            # Machine learning, models
    │   ├── discover-math/          # Mathematics, algorithms
    │   ├── discover-plt/           # Programming language theory
    │   ├── discover-formal/        # Formal methods, verification
    │   ├── discover-cloud/         # Serverless, cloud platforms
    │   ├── discover-zig/           # Zig systems programming
    │   ├── discover-networking/    # SSH, mTLS, VPN, resilience
    │   ├── discover-workflow/      # Beads, context strategies
    │   └── ... 20 more gateways
    │
    ├── Category Indexes (30 detailed references)
    │   ├── api/INDEX.md            # All API skills overview
    │   ├── database/INDEX.md       # All database skills overview
    │   ├── ml/INDEX.md             # All ML skills overview
    │   └── ... 27 more indexes
    │
    └── Skills by Category
        ├── api/           # REST, GraphQL, auth (7)
        ├── database/      # Postgres, MongoDB, Redis, streaming (11)
        ├── frontend/      # React, Next.js, performance (8)
        ├── mobile/        # iOS/Swift, SwiftUI, SwiftData (10)
        ├── testing/       # Unit, integration, e2e (6)
        ├── caching/       # Multi-layer caching (7)
        ├── build-systems/ # Make, CMake, Gradle, Maven, Bazel (8)
        ├── debugging/     # GDB, LLDB, production, memory (14)
        ├── cloud/         # AWS, GCP, Modal, serverless (13)
        ├── containers/    # Docker, Kubernetes (5)
        ├── cicd/          # GitHub Actions, pipelines (4)
        ├── observability/ # Logging, metrics, tracing (8)
        ├── ml/            # DSPy, HuggingFace, LLM, RAG (30)
        ├── ir/            # Information retrieval (5)
        ├── math/          # Linear algebra, topology, category theory (19)
        ├── plt/           # Type systems, verification, typed holes (13)
        ├── formal/        # SAT/SMT, Lean, CSP (10)
        ├── wasm/          # WebAssembly (4)
        ├── ebpf/          # eBPF kernel programming (4)
        ├── networking/    # SSH, mTLS, VPN, NAT traversal (5)
        ├── tui/           # Terminal UI: Bubble Tea, Ratatui (5)
        ├── zig/           # Zig systems programming (6)
        ├── workflow/      # Beads task management (4)
        ├── data/          # ETL, streaming, batch (5)
        ├── deployment/    # Heroku, Netlify (6)
        ├── realtime/      # WebSocket, SSE, pub/sub (4)
        ├── collaboration/ # GitHub, CodeTour (6)
        ├── product/       # PRD writing (4)
        ├── engineering/   # RFC writing (4)
        ├── infrastructure/# Terraform, Cloudflare Workers (6)
        │
        ├── Agent Skills (Root)
        │   ├── anti-slop/          # AI slop detection & cleanup
        │   ├── elegant-design/     # World-class UI design
        │   └── typed-holes-refactor/ # Systematic refactoring
        │
        └── Meta Skills (Root)
            ├── skill-repo-discovery.md    # Analyze repos for skills
            ├── skill-prompt-discovery.md  # Extract signals from prompts
            ├── skill-creation.md          # Create new skills
            └── skill-*-planning.md        # Planning workflows

• Focused: Each skill covers one topic (~320 lines)
• Self-contained: Can be loaded independently
• Cross-referenced: Links to related skills
• Production-tested: Real patterns from building at scale

• Zero boot cost: No skills loaded until needed
• Automatic activation: Gateway skills trigger on keywords
• Manual override: Browse and load specific skills
• Context efficient: Load only what's relevant

• ✅ Code Block Validation: 1100+ blocks syntax-checked
• ✅ Frontmatter Validation: 283 skills with YAML metadata
• ✅ Date Validation: No future dates in "Last Updated"
• ✅ CI/CD Pipeline: Automated validation on every commit
• ✅ Cross-References: Related skills linked for discoverability

This repository includes comprehensive development guidelines in CLAUDE.md:

• Multi-Agent Orchestration: Coordinated system with Orchestrator, Optimizer, Reviewer, Executor
• Work Plan Protocol: 4-phase development (Prompt→Spec→Full Spec→Plan→Artifacts)
• Beads Workflow: AI-native task management with dependencies
• Language Standards: Correct tools (uv not pip, etc.)
• Testing Protocol: Commit before testing (mandatory)
• Anti-Patterns: Critical violations and recovery procedures

cat skills/ml/dspy-setup.md              # Configure DSPy
cat skills/ml/dspy-modules.md            # Build RAG pipeline
cat skills/ml/dspy-optimizers.md         # Optimize prompts
cat skills/modal/modal-gpu-workloads.md  # Deploy on GPU
cat skills/modal/modal-web-endpoints.md  # Expose API
cat skills/api/rest-api-design.md        # Design contract
cat skills/api/api-rate-limiting.md      # Protect endpoint

cat skills/plt/type-systems.md           # Type soundness
cat skills/plt/dependent-types.md        # Π-types, Σ-types
cat skills/plt/program-verification.md   # Hoare logic
cat skills/formal/lean-proof-basics.md   # Formalize in Lean
cat skills/formal/z3-solver-basics.md    # SMT checking

cat skills/plt/typed-holes-foundations.md  # Gradual typing
cat skills/plt/typed-holes-llm.md          # LLM integration
cat skills/plt/live-programming-holes.md   # Real-time feedback

cat skills/caching/caching-fundamentals.md           # Core patterns
cat skills/caching/service-worker-caching.md         # Browser layer
cat skills/caching/http-caching.md                   # HTTP layer
cat skills/caching/cdn-edge-caching.md               # CDN layer
cat skills/caching/redis-caching-patterns.md         # Application layer
cat skills/caching/cache-invalidation-strategies.md  # Invalidation
cat skills/caching/cache-performance-monitoring.md   # Monitoring

In Progress: Building comprehensive Level 3 Resources for high-priority skills.

Each skill follows Anthropic's agent skills framework with three progressive levels:

• Level 1: Skill file (300-400 lines) - Core concepts, patterns, quick reference
• Level 2: Category INDEX - Detailed listings and workflows
• Level 3: Resources directory - Production tools, comprehensive references, examples

Level 3 Resources transform skills from guides into executable toolkits:

REFERENCE.md (1,500-4,000 lines):

• Comprehensive technical documentation
• Architecture patterns and best practices
• Troubleshooting guides and anti-patterns
• Integration examples and production patterns

Scripts (3 per skill, 550-800+ lines each):

• Production-ready Python tools
• Executable with --help and --json support
• Type hints and comprehensive error handling
• No TODOs or placeholders - fully implemented

Examples (7-10 per skill):

• Production-ready code across multiple languages/platforms
• Complete implementations with error handling
• Docker Compose setups, CI/CD workflows
• Monitoring and observability configurations

Status: 48/123 HIGH priority skills have Level 3 Resources (39%)

Wave 9 (6 skills, +51,979 lines):

• Cryptography: signing-verification, hsm-integration
• Protocols: amqp-rabbitmq, protobuf-schemas
• Engineering: sre-practices, feature-flags

Wave 10 (2 skills, +14,375 lines):

• Cryptography: secrets-rotation (completes 6/7 in category)
• Protocols: http3-quic

Target: 28 skills across Cryptography, Protocols, Engineering Progress: 18/28 complete (64%)

Cryptography: 6/7 complete (86%)

• ✅ encryption-at-rest, key-management, certificate-management, hsm-integration, signing-verification, secrets-rotation
• ⏳ pki-fundamentals (60% complete)

Protocols: 6/8 complete (75%)

• ✅ grpc-implementation, kafka-streams, mqtt-messaging, amqp-rabbitmq, protobuf-schemas, http3-quic
• ⏳ websocket-protocols (15% complete)
• ⏳ tcp-optimization

Engineering: 6/14 complete (43%)

• ✅ deployment-strategies, e2e-testing, monitoring-alerts, incident-response, sre-practices, feature-flags
• ⏳ ci-cd-pipelines (10% complete), capacity-planning (5% complete)
• ⏳ 6 more skills

Hybrid Approach: Combines manual quality control with template-based acceleration

• 24-35 completed skills serve as templates
• Pattern consistency enforced via quality gates
• 40-50% faster than pure manual while maintaining standards
• 6 parallel agents per wave (optimal throughput)

Quality Gates (enforced before commit):

• REFERENCE.md: 1,500-4,000 lines
• Scripts: 3 per skill, executable, --help/--json support, type hints
• Examples: 7-10 per skill, production-ready, no placeholders
• No TODO/stub/mock comments anywhere
• CI validation on all PRs

Automated validation runs on all resource changes:

• REFERENCE.md line count validation
• Script executability and shebang checks
• TODO/stub/mock comment detection
• Python syntax validation for examples
• Full validation results in PR comments

See .github/workflows/validate-resources.yml for details.

Next Sessions (tracked in .work/WAVE_10_INCOMPLETE.md):

• Complete 4 partial Wave 10 skills (pki-fundamentals, websocket-protocols, ci-cd-pipelines, capacity-planning)
• 6 additional skills to reach 100% strategic focus coverage
• Estimated: 30-40 hours across 2-3 sessions

Long-term: 75+ additional skills need Level 3 Resources to reach comprehensive coverage

This is a personal reference repository maintained through practical development experience. Skills are added when new technologies are mastered, updated when better patterns emerge, and refined based on production use.

Feel free to fork and adapt for your own use. Pull requests welcome.

350+ atomic skills • 41 gateway Agent Skills • 35+ categories • 100% CI-validated