
cc-polymath
Efficient skill management with progressive discovery — 410+ production-ready skills across 33+ domains.
- version
- 4.0.0
- GitHub stars
- 191
Install
/plugin install cc-polymath@cc-polymath-marketplaceRun it inside Claude Code after adding the marketplace with /plugin marketplace add rand/cc-polymath.
Contents
Discovered from sourceSkills 26
Anti-Slop Skill
Detect and eliminate generic AI-generated patterns ("slop") across natural language, code, and design.
What is AI Slop?
AI slop refers to telltale patterns that signal low-quality, generic AI-generated content:
- Text: Overused phrases like "delve into," excessive buzzwords, meta-commentary
- Code: Generic variable names, obvious comments, unnecessary abstraction
- Design: Cookie-cutter layouts, generic gradients, overused visual patterns
This skill helps identify and remove these patterns to create authentic, high-quality content.
When to Use This Skill
Apply anti-slop techniques when:
- Reviewing AI-generated content before delivery
- Creating original content and want to avoid generic patterns
- Cleaning up existing content that feels generic
- Establishing quality standards for a project
- User explicitly requests slop detection or cleanup
- Content has telltale signs of generic AI generation
Core Workflow
1. Detect Slop
For text files:
python scripts/detect_slop.py <file> [--verbose]
This analyzes text and provides:
- Slop score (0-100, higher is worse)
- Specific pattern findings
- Actionable recommendations
Manual detection: Read the appropriate reference file for detailed patterns:
references/text-patterns.md- Natural language slop patternsreferences/code-patterns.md- Programming slop patternsreferences/design-patterns.md- Visual/UX design slop patterns
2. Clean Slop
Automated cleanup (text only):
# Preview changes
python scripts/clean_slop.py <file>
# Apply changes (creates backup)
python scripts/clean_slop.py <file> --save
# Aggressive mode (may slightly change meaning)
python scripts/clean_slop.py <file> --save --aggressive
Manual cleanup: Apply strategies from the reference files based on detected patterns.
Text Slop Detection & Cleanup
High-Priority Targets
Remove immediately:
- "delve into" → delete or replace with "examine"
- "navigate the complexities" → "handle" or delete
- "in today's fast-paced world" → delete
- "it's important to note that" → delete
- Meta-commentary about the document itself
Simplify wordy phrases:
- "in order to" → "to"
- "due to the fact that" → "because"
- "has the ability to" → "can"
Replace buzzwords:
- "leverage" → "use"
- "synergistic" → "cooperative"
- "paradigm shift" → "major change"
Quality Principles
Be direct:
- Skip preambles and meta-commentary
- Lead with the actual point
- Cut transition words that don't add meaning
Be specific:
- Replace generic terms with concrete examples
- Name specific things instead of "items," "things," "data"
- Use precise verbs instead of vague action words
Be authentic:
- Vary sentence structure and length
- Use active voice predominantly
- Write in a voice appropriate to context, not corporate-generic
Code Slop Detection & Cleanup
High-Priority Targets
Rename generic variables:
data→ name what data it representsresult→ name what the result containstemp→ name what you're temporarily storingitem→ name what kind of item
Remove obvious comments:
# Bad
# Create a user
user = User()
# Better - let code speak
user = User()
Simplify over-engineered code:
- Remove unnecessary abstraction layers
- Replace design patterns used without purpose
- Simplify complex implementations of simple tasks
Improve function names:
handleData()→ what are you doing with data?processItems()→ what processing specifically?manageUsers()→ what management action?
Quality Principles
Clarity over cleverness:
- Write code that's easy to understand
- Optimize only when profiling shows need
- Prefer simple solutions to complex ones
Meaningful names:
- Variable names should describe content
- Function names should describe action + object
- Class names should describe responsibility
Appropriate documentation:
- Document why, not what
- Skip documentation for self-evident code
- Focus documentation on public APIs and complex logic
Design Slop Detection & Cleanup
High-Priority Targets
Visual slop:
- Generic gradient backgrounds (purple/pink/cyan)
- Overuse of glassmorphism or neumorphism
- Floating 3D shapes without purpose
- Every element using same design treatment
Layout slop:
- Template-driven layouts ignoring content needs
- Everything in cards regardless of content type
- Excessive whitespace without hierarchy
- Center-alignment of all elements
Copy slop:
- "Empower your business" type headlines
- Generic CTAs like "Get Started" without context
- Buzzword-heavy descriptions
- Stock photo aesthetics
Quality Principles
Content-first design:
- Design around actual content needs
- Create hierarchy based on importance
- Let content determine layout, not templates
Intentional choices:
- Every design decision should be justifiable
- Use patterns because they serve users, not because they're trendy
- Vary visual treatment based on element importance
Authentic voice:
- Copy should reflect brand personality
- Avoid generic marketing speak
- Be specific about value proposition
Reference Files
Consult these comprehensive guides when working on specific domains:
-
text-patterns.md - Complete catalog of natural language slop patterns with detection rules and cleanup strategies
-
code-patterns.md - Programming antipatterns across languages with refactoring guidance
-
design-patterns.md - Visual and UX design slop patterns with improvement strategies
Each reference includes:
- Pattern definitions and examples
- Detection signals (high/medium confidence)
- Context where patterns are acceptable
- Specific cleanup strategies
Scripts
detect_slop.py
Analyzes text files for AI slop patterns.
Usage:
python scripts/detect_slop.py <file> [--verbose]
Output:
- Overall slop score (0-100)
- Category-specific findings
- Line numbers and examples
- Actionable recommendations
Scoring:
- 0-20: Low slop (authentic writing)
- 20-40: Moderate slop (some patterns)
- 40-60: High slop (many patterns)
- 60+: Severe slop (heavily generic)
clean_slop.py
Automatically removes common slop patterns from text files.
Usage:
# Preview changes
python scripts/clean_slop.py <file>
# Save changes (creates backup)
python scripts/clean_slop.py <file> --save
# Save to different file
python scripts/clean_slop.py <file> --output clean_file.txt
# Aggressive mode
python scripts/clean_slop.py <file> --save --aggressive
What it cleans:
- High-risk phrases
- Wordy constructions
- Meta-commentary
- Excessive hedging
- Buzzwords
- Redundant qualifiers
- Empty intensifiers
Safety:
- Always creates
.backupfile when overwriting - Preview mode shows changes before applying
- Preserves content meaning (non-aggressive mode)
Best Practices
Prevention Over Cure
When creating content:
- Write with specific audience in mind
- Use concrete examples over abstractions
- Lead with the point, skip preambles
- Choose words for precision, not impression
- Review before considering it complete
Context-Aware Cleanup
Not all patterns are always slop:
Acceptable contexts:
- Academic writing may need more hedging
- Legal documents require specific phrasing
- Internal documentation can use shortcuts
- Technical docs have domain-specific conventions
Always consider:
- Who is the audience?
- What is the purpose?
- Does this pattern serve a function?
- Is there a better alternative?
Iterative Improvement
- Detect - Run detection scripts or manual review
- Analyze - Understand which patterns are truly problems
- Clean - Apply automated cleanup where safe
- Review - Manually verify changes maintain meaning
- Refine - Fix remaining issues by hand
Quality Over Automation
The scripts are tools, not replacements for judgment:
- Use automated detection to find candidates
- Apply automated cleanup to obvious patterns
- Manually review anything that changes meaning
- Exercise discretion based on context
Integration Patterns
Code Review
# Check files before committing
python scripts/detect_slop.py src/documentation.md --verbose
# Clean up automatically
python scripts/clean_slop.py src/documentation.md --save
Content Pipeline
- Create initial content
- Run slop detection
- Apply automated cleanup
- Manual review and refinement
- Final quality check
Standards Enforcement
Create project-specific thresholds:
- Max acceptable slop score: 30
- Required manual review for scores > 20
- Auto-reject submissions with scores > 50
Limitations
Scripts only handle text:
- Code slop detection is manual (use code-patterns.md)
- Design slop detection is manual (use design-patterns.md)
Context sensitivity:
- Scripts can't understand all contexts
- Some "slop" may be appropriate in certain domains
- Always review automated changes
Language coverage:
- Detection patterns optimized for English
- Code patterns focus on common languages (Python, JS, Java)
- Design patterns are platform-agnostic
Common Scenarios
Scenario 1: Review AI-Generated Content
# User asks: "Can you review this article for AI slop?"
1. Read references/text-patterns.md for patterns to watch
2. Run: python scripts/detect_slop.py article.txt --verbose
3. Review findings and apply manual cleanup
4. Optionally run: python scripts/clean_slop.py article.txt --save
5. Do final manual review of cleaned content
Scenario 2: Clean Up Codebase
# User asks: "Help me clean up generic AI patterns in my code"
1. Read references/code-patterns.md
2. Review code files manually for patterns
3. Create list of generic names to rename
4. Refactor following principles in code-patterns.md
5. Remove obvious comments and over-abstractions
Scenario 3: Design Review
# User asks: "Does this design look too generic?"
1. Read references/design-patterns.md
2. Check against high-confidence slop indicators
3. Identify specific issues (gradients, layouts, copy)
4. Provide specific recommendations from design-patterns.md
5. Suggest concrete alternatives
Scenario 4: Establish Quality Standards
# User asks: "Help me create quality standards for our team"
1. Review all three reference files
2. Identify patterns most relevant to user's domain
3. Create project-specific guidelines
4. Set up detection scripts in development pipeline
5. Document acceptable exceptions
Tips for Success
For text cleanup:
- Run detection first to understand scope
- Use non-aggressive mode for important content
- Always review automated changes
- Focus on high-risk patterns first
For code cleanup:
- Start with renaming generic variables
- Remove obvious comments next
- Refactor over-engineered code last
- Test after each significant change
For design cleanup:
- Audit visual elements against patterns
- Prioritize structural issues over aesthetic ones
- Ensure changes serve user needs
- Maintain brand consistency
General principles:
- Quality > uniformity
- Context > rules
- Clarity > cleverness
- Specificity > generality
Agentic Workflow Skills Discovery
Provides automatic access to skills for building autonomous AI agents, managing tool use, and orchestrating multi-step workflows.
When This Skill Activates
This skill auto-activates when you're working with:
- AI agent development and autonomous workflows
- Task decomposition for LLM agents
- Function calling and tool use patterns
- Context window management and summarization
- Working memory, scratchpads, and state tracking
- Long-term memory and persistence patterns
- Multi-step reasoning and planning
- Failure recovery and re-planning strategies
- Parallel vs sequential execution decisions
Available Skills
Quick Reference
The Agentic category contains 3 specialized skills:
- agentic-task-decomposition - Breaking complex goals into agent-executable steps, dependency graphs, re-planning
- agentic-tool-use - Function calling patterns, parallel tool use, error handling, tool selection heuristics
- agentic-memory - Context window management, working memory, long-term persistence, summarization
Load Full Category Details
For complete descriptions and workflows:
Read ../agentic/INDEX.md
This loads the full Agentic category index with:
- Detailed skill descriptions
- Usage triggers for each skill
- Common workflow combinations
- Cross-references to related skills
Load Specific Skills
Load individual skills as needed:
Task planning and decomposition
Read ../agentic/agentic-task-decomposition.md
Tool calling and execution
Read ../agentic/agentic-tool-use.md
Context and memory management
Read ../agentic/agentic-memory.md
Common Workflows
Building an Agent from Scratch
Sequence: Decomposition -> Tool Use -> Memory
Read ../agentic/agentic-task-decomposition.md # Plan the agent's task handling Read ../agentic/agentic-tool-use.md # Implement tool execution Read ../agentic/agentic-memory.md # Add context management
Adding Tool Use to an Agent
Sequence: Tool Use -> Decomposition
Read ../agentic/agentic-tool-use.md # Tool calling patterns Read ../agentic/agentic-task-decomposition.md # Multi-tool task planning
Scaling Agent Sessions
Sequence: Memory -> Decomposition
Read ../agentic/agentic-memory.md # Context management Read ../agentic/agentic-task-decomposition.md # Context-bounded task sizing
Complete Agentic Stack
Full implementation:
1. Planning layer
Read ../agentic/agentic-task-decomposition.md
2. Execution layer
Read ../agentic/agentic-tool-use.md
3. Memory layer
Read ../agentic/agentic-memory.md
Skill Selection Guide
Choose task decomposition when:
- Complex goal needs breaking into steps
- Tasks have dependencies or ordering constraints
- Need to handle ambiguous requirements
- Building a planning layer for an agent
Choose tool use when:
- Implementing function calling in an LLM agent
- Debugging tool call failures or inefficiency
- Designing tool schemas and structured outputs
- Optimizing multi-tool workflows
Choose memory when:
- Agent sessions are hitting context limits
- Need to persist state across turns or sessions
- Building multi-turn conversational agents
- Implementing retrieval-augmented generation
Integration with Other Skills
Agentic skills commonly combine with:
API skills (discover-api):
- Agents that call REST/GraphQL APIs
- Tool schemas for API endpoints
- Authentication handling in agent workflows
Testing skills (discover-testing):
- Testing agent behaviors and tool use
- Autonomous test generation
- Verifying agent task completion
Database skills (discover-database):
- Database-backed agent memory
- Agents that query and modify data
- Persistent state management
Infrastructure skills (discover-infra, discover-cloud):
- Deploying agent systems
- Scaling agent workloads
- Cost optimization for LLM calls
Usage Instructions
- Auto-activation: This skill loads automatically when Claude Code detects agentic workflow tasks
- Browse skills: Run
Read ../agentic/INDEX.mdfor full category overview - Load specific skills: Use commands above to load individual skills
- Follow workflows: Use recommended sequences for common agentic patterns
- Combine skills: Load multiple skills for comprehensive coverage
Progressive Loading
This gateway skill (~200 lines, ~2K tokens) enables progressive loading:
- Level 1: Gateway loads automatically (you're here now)
- Level 2: Load category INDEX.md (~3K tokens) for full overview
- Level 3: Load specific skills (~2-3K tokens each) as needed
Total context: 2K + 3K + skill(s) = 5-10K tokens vs 12K+ for entire category.
Quick Start Examples
"Build an autonomous coding agent": Read ../agentic/agentic-task-decomposition.md
"How should my agent call tools?": Read ../agentic/agentic-tool-use.md
"My agent is running out of context": Read ../agentic/agentic-memory.md
Next Steps: Run Read ../agentic/INDEX.md to see full category details, or load specific skills using the commands above.
API Skills Discovery
Provides automatic access to comprehensive API design, authentication, and implementation skills.
When This Skill Activates
This skill auto-activates when you're working with:
- REST API design and implementation
- GraphQL schema design
- API authentication (JWT, OAuth 2.0, API keys, sessions)
- API authorization (RBAC, ABAC, permissions)
- Rate limiting and throttling
- API versioning strategies
- Error handling and validation
- HTTP methods, status codes, endpoints
Available Skills
Quick Reference
The API category contains 8 specialized skills:
- rest-api-design - RESTful resource modeling, HTTP semantics, URL conventions
- graphql-schema-design - GraphQL types, resolvers, N+1 problem prevention
- api-authentication - JWT, OAuth 2.0, API keys, session management
- api-authorization - RBAC, ABAC, policy engines, permission systems
- api-rate-limiting - Token bucket, sliding window, rate limiting algorithms
- api-versioning - API versioning, deprecation, backward compatibility
- api-error-handling - RFC 7807 errors, validation, standardized responses
- api-design-rules - 35 opinionated rules for API design
Load Full Category Details
For complete descriptions and workflows:
Read ../api/INDEX.md
This loads the full API category index with:
- Detailed skill descriptions
- Usage triggers for each skill
- Common workflow combinations
- Cross-references to related skills
Load Specific Skills
Load individual skills as needed:
Core API design
Read ../api/rest-api-design.md Read ../api/graphql-schema-design.md
Security and access control
Read ../api/api-authentication.md Read ../api/api-authorization.md
Production hardening
Read ../api/api-rate-limiting.md Read ../api/api-error-handling.md Read ../api/api-versioning.md
Rules and best practices
Read ../api/api-design-rules.md
Common Workflows
New REST API
Sequence: REST design → Authentication → Authorization
Read ../api/rest-api-design.md # Resource modeling, HTTP methods Read ../api/api-authentication.md # User authentication Read ../api/api-authorization.md # Access control
New GraphQL API
Sequence: GraphQL schema → Authentication → Authorization
Read ../api/graphql-schema-design.md # Schema design, resolvers Read ../api/api-authentication.md # User authentication Read ../api/api-authorization.md # Field-level permissions
API Hardening
Sequence: Rate limiting → Error handling → Versioning
Read ../api/api-rate-limiting.md # Prevent abuse Read ../api/api-error-handling.md # Standardized errors Read ../api/api-versioning.md # Manage evolution
Complete API Stack
Full implementation from scratch:
1. Design phase
Read ../api/rest-api-design.md
2. Security phase
Read ../api/api-authentication.md Read ../api/api-authorization.md Read ../api/api-rate-limiting.md
3. Production readiness
Read ../api/api-error-handling.md Read ../api/api-versioning.md
Skill Selection Guide
Choose REST API skills when:
- Building traditional web services
- Need simple CRUD operations
- Working with mobile apps or SPAs
- Require caching and HTTP semantics
Choose GraphQL skills when:
- Clients need flexible data fetching
- Reducing over-fetching or under-fetching
- Building aggregation layers
- Need strong typing for APIs
Authentication vs Authorization:
- Authentication (api-authentication.md): Who are you? (Login, JWT, OAuth)
- Authorization (api-authorization.md): What can you do? (Permissions, RBAC)
Production considerations:
- Always implement rate limiting for public APIs
- Use versioning from day one
- Standardize error responses early
Integration with Other Skills
API skills commonly combine with:
Database skills (discover-database):
- API endpoints → Database queries
- Connection pooling for API servers
- Query optimization for API performance
Testing skills (discover-testing):
- Integration tests for API endpoints
- Contract testing for API consumers
- Load testing for API performance
Frontend skills (discover-frontend):
- API client libraries
- Data fetching patterns
- Error handling in UI
Infrastructure skills (discover-infra, discover-cloud):
- API deployment strategies
- Load balancing and scaling
- API gateways and proxies
Usage Instructions
- Auto-activation: This skill loads automatically when Claude Code detects API-related work
- Browse skills: Run
Read ../api/INDEX.mdfor full category overview - Load specific skills: Use bash commands above to load individual skills
- Follow workflows: Use recommended sequences for common API patterns
- Combine skills: Load multiple skills for comprehensive coverage
Progressive Loading
This gateway skill (~200 lines, ~2K tokens) enables progressive loading:
- Level 1: Gateway loads automatically (you're here now)
- Level 2: Load category INDEX.md (~3K tokens) for full overview
- Level 3: Load specific skills (~2-3K tokens each) as needed
Total context: 2K + 3K + skill(s) = 5-10K tokens vs 25K+ for entire index.
Quick Start Examples
"Design a REST API for a blog": Read ../api/rest-api-design.md
"Add OAuth authentication to my API": Read ../api/api-authentication.md
"Implement role-based access control": Read ../api/api-authorization.md
"Prevent API abuse": Read ../api/api-rate-limiting.md
"Design an API versioning strategy": Read ../api/api-versioning.md
Next Steps: Run Read ../api/INDEX.md to see full category details, or load specific skills using the bash commands above.
Cicd Skills Discovery
Provides automatic access to comprehensive cicd skills.
When This Skill Activates
This skill auto-activates when you're working with:
- CI/CD
- GitHub Actions
- GitLab CI
- automation
- pipelines
- continuous integration
- deployment automation
- build systems
- Make
- CMake
- Gradle
- Maven
- Bazel
- compilation
- incremental builds
Available Skills
Quick Reference
The Cicd category contains 12 skills across 2 subcategories:
CI/CD (4 skills):
- cd-deployment-patterns
- ci-optimization
- ci-security
- ci-testing-strategy
Build Systems (8 skills): See ../build-systems/INDEX.md
Load Full Category Details
Read ../cicd/INDEX.md Read ../build-systems/INDEX.md
Progressive Loading
This gateway skill enables progressive loading:
- Level 1: Gateway loads automatically (you're here now)
- Level 2: Load category INDEX.md for full overview
- Level 3: Load specific skills as needed
Usage Instructions
- Auto-activation: This skill loads automatically when Claude Code detects cicd work
- Browse skills: Run
Read ../cicd/INDEX.mdfor full category overview - Load specific skills: Use bash commands above to load individual skills
Next Steps: Run Read ../cicd/INDEX.md to see full category details.
Cryptography Skills Discovery
Provides automatic access to comprehensive cryptography and security skills.
When This Skill Activates
This skill auto-activates when you're working with:
- TLS, SSL, mTLS
- Certificates and PKI
- Encryption and decryption
- Hashing and signing
- Key management
- HTTPS configuration
- Certificate authorities
- Cryptographic algorithms
- Security best practices
Available Skills
Quick Reference
The Cryptography category contains 7 skills:
- pki-fundamentals - PKI, certificate authorities, X.509, trust chains
- tls-configuration - TLS 1.2/1.3 setup, cipher suites, server config
- ssl-legacy - SSL 2.0/3.0, TLS 1.0/1.1, deprecation, migration
- sni-routing - Server Name Indication, multi-domain TLS hosting
- certificate-management - Certificate lifecycle, Let's Encrypt, automation
- cryptography-basics - Symmetric/asymmetric encryption, hashing, signing
- crypto-best-practices - Security patterns, common mistakes, anti-patterns
Load Full Category Details
For complete descriptions and workflows:
Read ../cryptography/INDEX.md
This loads the full Cryptography category index with:
- Detailed skill descriptions
- Usage triggers for each skill
- Common workflow combinations
- Cross-references to related skills
Load Specific Skills
Load individual skills as needed:
Read ../cryptography/pki-fundamentals.md Read ../cryptography/tls-configuration.md Read ../cryptography/certificate-management.md Read ../cryptography/cryptography-basics.md
Common Workflows
Setting Up HTTPS
PKI basics → TLS config → Certificate management
Read ../cryptography/pki-fundamentals.md Read ../cryptography/tls-configuration.md Read ../cryptography/certificate-management.md
Understanding Encryption
Basics → Best practices → Specific implementation
Read ../cryptography/cryptography-basics.md Read ../cryptography/crypto-best-practices.md Read ../cryptography/tls-configuration.md
Certificate Troubleshooting
PKI → Certificate management → Debugging
Read ../cryptography/pki-fundamentals.md Read ../cryptography/certificate-management.md
Legacy Migration
Understand legacy → Modern TLS → Migration
Read ../cryptography/ssl-legacy.md Read ../cryptography/tls-configuration.md Read ../cryptography/certificate-management.md
Progressive Loading
This gateway skill enables progressive loading:
- Level 1: Gateway loads automatically (you're here now)
- Level 2: Load category INDEX.md for full overview
- Level 3: Load specific skills as needed
Usage Instructions
- Auto-activation: This skill loads automatically when Claude Code detects cryptography work
- Browse skills: Run
Read ../cryptography/INDEX.mdfor full category overview - Load specific skills: Use bash commands above to load individual skills
Next Steps: Run Read ../cryptography/INDEX.md to see full category details.
Data Skills Discovery
Provides automatic access to comprehensive data skills.
When This Skill Activates
This skill auto-activates when you're working with:
- ETL
- data pipelines
- batch processing
- stream processing
- data validation
- orchestration
- Airflow
- timely dataflow
- differential dataflow
- streaming aggregations
- windowing
- real-time analytics
Available Skills
Quick Reference
The Data category contains 9 skills:
- batch-processing - Orchestrating complex data pipelines with dependencies
- data-validation - Validating data schema before processing
- dataflow-coordination - Coordination patterns for distributed dataflow systems
- differential-dataflow - Differential computation for incremental updates and efficient joins
- etl-patterns - Designing data extraction from multiple sources
- pipeline-orchestration - Coordinating complex multi-step data workflows
- stream-processing - Processing real-time event streams (Kafka, Flink)
- streaming-aggregations - Windowing, sessionization, time-series aggregation
- timely-dataflow - Low-latency streaming computation with progress tracking
Load Full Category Details
For complete descriptions and workflows:
Read ../data/INDEX.md
This loads the full Data category index with:
- Detailed skill descriptions
- Usage triggers for each skill
- Common workflow combinations
- Cross-references to related skills
Load Specific Skills
Load individual skills as needed:
Traditional ETL/Batch
Read ../data/batch-processing.md Read ../data/data-validation.md Read ../data/etl-patterns.md Read ../data/pipeline-orchestration.md
Stream Processing
Read ../data/stream-processing.md Read ../data/streaming-aggregations.md
Advanced Dataflow Systems
Read ../data/timely-dataflow.md Read ../data/differential-dataflow.md Read ../data/dataflow-coordination.md
Common Workflow Combinations
Real-Time Analytics Pipeline
Load these skills together:
Read ../data/stream-processing.md # Kafka setup Read ../data/streaming-aggregations.md # Windowing patterns Read ../data/dataflow-coordination.md # Coordination
Incremental Computation System
Load these skills together:
Read ../data/timely-dataflow.md # Foundation Read ../data/differential-dataflow.md # Incremental updates Read ../data/dataflow-coordination.md # Distributed coordination
Hybrid Batch + Stream
Load these skills together:
Read ../data/batch-processing.md # Batch jobs Read ../data/stream-processing.md # Stream processing Read ../data/pipeline-orchestration.md # Overall coordination
Progressive Loading
This gateway skill enables progressive loading:
- Level 1: Gateway loads automatically (you're here now)
- Level 2: Load category INDEX.md for full overview
- Level 3: Load specific skills as needed
Usage Instructions
- Auto-activation: This skill loads automatically when Claude Code detects data work
- Browse skills: Run
Read ../data/INDEX.mdfor full category overview - Load specific skills: Use bash commands above to load individual skills
Next Steps: Run Read ../data/INDEX.md to see full category details.
Database Skills Discovery
Provides automatic access to comprehensive database design, optimization, and implementation skills.
When This Skill Activates
This skill auto-activates when you're working with:
- SQL databases (PostgreSQL, MySQL)
- NoSQL databases (MongoDB, Redis)
- Database schema design and modeling
- Query optimization and performance tuning
- Database migrations and schema evolution
- Connection pooling configuration
- ORM usage and patterns
- Database selection and architecture decisions
- caching
- cache
- Redis
- CDN
- HTTP caching
- cache invalidation
- performance
- Service Workers
Available Skills
Quick Reference
The Database category contains 19 skills across 2 subcategories:
Database (12 skills):
- postgres-schema-design - Schema design, relationships, data types, normalization
- postgres-query-optimization - EXPLAIN plans, indexes, slow query debugging
- postgres-migrations - Schema changes, zero-downtime, rollback strategies
- mongodb-document-design - Document modeling, embedding vs referencing
- redis-data-structures - Caching, sessions, rate limiting, leaderboards
- database-connection-pooling - Pool configuration, debugging exhaustion
- orm-patterns - ORM best practices, N+1 prevention, eager loading
- database-selection - Choosing databases, SQL vs NoSQL decisions
Plus 4 more in ../database/INDEX.md
Caching (7 skills): See ../caching/INDEX.md
Load Full Category Details
Read ../database/INDEX.md Read ../caching/INDEX.md
Common Workflows
New Database Project
Sequence: Selection → Schema design → Connection pooling
Read ../database/database-selection.md # Choose database Read ../database/postgres-schema-design.md # or mongodb-document-design.md Read ../database/database-connection-pooling.md
Query Performance Debugging
Sequence: Optimization → Connection pooling → ORM patterns
Read ../database/postgres-query-optimization.md # Debug slow queries Read ../database/database-connection-pooling.md # Check pool settings Read ../database/orm-patterns.md # Fix N+1 queries
Schema Evolution
Sequence: Schema design → Migrations
Read ../database/postgres-schema-design.md # Design changes Read ../database/postgres-migrations.md # Implement safely
Caching Layer
Sequence: Redis structures → Cache patterns
Read ../database/redis-data-structures.md # Redis patterns Read ../caching/INDEX.md # Cache patterns
Skill Selection Guide
PostgreSQL skills (relational, ACID, complex queries):
postgres-schema-design.md- Design relational schemaspostgres-query-optimization.md- Optimize complex queriespostgres-migrations.md- Evolve schema over time
MongoDB skills (document-oriented, flexible schema):
mongodb-document-design.md- Design document structures- Choose when: Flexible schema, nested data, rapid iteration
Redis skills (in-memory, key-value, caching):
redis-data-structures.md- Caching, sessions, rate limiting- Choose when: Speed critical, caching layer, real-time features
Cross-database skills:
database-selection.md- Start here for new projectsdatabase-connection-pooling.md- All databases need thisorm-patterns.md- When using ORMs (SQLAlchemy, Prisma, Mongoose)
Integration with Other Skills
Database skills commonly combine with:
API skills (discover-api):
- API endpoints → Database queries
- Connection pooling for API servers
- Query optimization for API performance
- Migrations alongside API versioning
Backend language skills (discover-backend):
- Python: SQLAlchemy, psycopg2, PyMongo
- Zig: PostgreSQL C bindings
- Rust: SQLx, Diesel
- Go: database/sql, GORM
Testing skills (discover-testing):
- Integration tests with test databases
- Migration testing
- Query performance testing
- Data fixture management
Data pipeline skills (discover-data):
- ETL from databases
- Database as data source
- Bulk data operations
- Streaming database changes (CDC)
Observability skills (discover-observability):
- Query metrics and slow query logs
- Connection pool metrics
- Database performance monitoring
- Alert configuration
Progressive Loading
This gateway skill (~200 lines, ~2K tokens) enables progressive loading:
- Level 1: Gateway loads automatically (you're here now)
- Level 2: Load category INDEX.md (~3K tokens) for full overview
- Level 3: Load specific skills (~2-4K tokens each) as needed
Total context: 2K + 3K + skill(s) = 5-10K tokens vs 25K+ for entire index.
Quick Start Examples
"Design a PostgreSQL schema for an e-commerce app": Read ../database/postgres-schema-design.md
"Why is my query slow?": Read ../database/postgres-query-optimization.md
"How do I safely change my database schema?": Read ../database/postgres-migrations.md
"Should I use MongoDB or PostgreSQL?": Read ../database/database-selection.md
"Implement caching with Redis": Read ../database/redis-data-structures.md
"Fix N+1 queries in my ORM": Read ../database/orm-patterns.md
Database Type Decision Tree
Need ACID transactions? YES → PostgreSQL
Need complex queries/joins? YES → PostgreSQL
Need flexible schema? YES → MongoDB
Need real-time caching? YES → Redis
Need full-text search? YES → PostgreSQL (with extensions) or Elasticsearch
Need graph relationships? YES → Neo4j or PostgreSQL (with extensions)
Need analytics? YES → DuckDB or Redpanda + Iceberg
For detailed decision-making: Read ../database/database-selection.md
PostgreSQL Focus Areas
Schema design → postgres-schema-design.md:
- Tables, columns, data types
- Primary keys, foreign keys, constraints
- Normalization vs denormalization
- Indexing strategies
Query optimization → postgres-query-optimization.md:
- EXPLAIN and EXPLAIN ANALYZE
- Index selection and creation
- Query plan analysis
- Performance tuning
Migrations → postgres-migrations.md:
- Schema change strategies
- Zero-downtime deployments
- Rollback procedures
- Migration tools (Alembic, Flyway, migrate)
NoSQL Focus Areas
MongoDB → mongodb-document-design.md:
- Document structure and embedding
- References vs embedding tradeoffs
- Schema versioning
- Index design for documents
Redis → redis-data-structures.md:
- Strings, hashes, lists, sets, sorted sets
- Caching patterns and TTLs
- Session storage
- Rate limiting implementations
- Leaderboards and counters
ORM Considerations
Before using ORMs, load: Read ../database/orm-patterns.md
Common ORM pitfalls:
- N+1 query problems
- Lazy vs eager loading confusion
- Transaction management
- Raw SQL when necessary
- Migration generation
Supported ORMs:
- SQLAlchemy (Python)
- Prisma (TypeScript/Node.js)
- Diesel (Rust)
- GORM (Go)
- ActiveRecord (Ruby)
- Entity Framework (C#)
Usage Instructions
- Auto-activation: This skill loads automatically when Claude Code detects database work
- Browse skills: Run
Read ../database/INDEX.mdfor full category overview - Load specific skills: Use bash commands above to load individual skills
- Follow workflows: Use recommended sequences for common patterns
- Decision support: Start with
database-selection.mdfor new projects
Next Steps: Run Read ../database/INDEX.md to see full category details, or load specific skills using the bash commands above.
Debugging Skills Discovery
Provides automatic access to comprehensive debugging skills.
When This Skill Activates
This skill auto-activates when you're working with:
- debugging
- GDB
- LLDB
- profiling
- memory leaks
- performance analysis
- troubleshooting
- diagnostics
- monitoring
- logging
- tracing
- metrics
- distributed tracing
- alerts
- dashboards
- observability
Available Skills
Quick Reference
The Debugging category contains 22 skills across 2 subcategories:
Debugging (14 skills):
- browser-devtools
- concurrency-debugging
- container-debugging
- core-dump-analysis
- crash-debugging
- distributed-systems-debugging
- gdb-fundamentals
- lldb-macos-debugging
- memory-leak-debugging
- network-debugging
- performance-profiling
- production-debugging
- python-debugging
- remote-debugging
Observability (8 skills): See ../observability/INDEX.md
Load Full Category Details
Read ../debugging/INDEX.md Read ../observability/INDEX.md
Progressive Loading
This gateway skill enables progressive loading:
- Level 1: Gateway loads automatically (you're here now)
- Level 2: Load category INDEX.md for full overview
- Level 3: Load specific skills as needed
Usage Instructions
- Auto-activation: This skill loads automatically when Claude Code detects debugging work
- Browse skills: Run
Read ../debugging/INDEX.mdfor full category overview - Load specific skills: Use bash commands above to load individual skills
Next Steps: Run Read ../debugging/INDEX.md to see full category details.
Distributed Systems & Realtime Skills Discovery
When This Skill Activates
- Consensus algorithms (RAFT, Paxos)
- CAP theorem, consistency models
- CRDTs and eventual consistency
- Vector clocks, logical clocks, causality
- Replication, partitioning, sharding
- Distributed locks and leader election
- Gossip protocols, probabilistic data structures
- WebSockets, Server-Sent Events, streaming
- Pub/sub, push notifications, live updates
Available Skills (21 total)
Distributed Systems (17 skills)
- cap-theorem - CAP theorem, consistency vs availability trade-offs
- consensus-raft - RAFT consensus, leader election, log replication
- consensus-paxos - Paxos consensus, Basic/Multi-Paxos
- crdt-fundamentals - Conflict-free Replicated Data Types basics
- crdt-types - Specific CRDT implementations (LWW, OR-Set, RGA)
- dotted-version-vectors - Compact causality, sibling management
- interval-tree-clocks - Dynamic causality, fork/join
- vector-clocks - Causality tracking, happens-before
- logical-clocks - Lamport clocks, logical time
- eventual-consistency - Consistency levels, quorums, BASE
- conflict-resolution - LWW, multi-value, semantic resolution
- replication-strategies - Primary-backup, multi-primary, chain, quorum
- partitioning-sharding - Hash/range/consistent hashing, rebalancing
- distributed-locks - Redlock, ZooKeeper locks, fencing tokens
- leader-election - Bully, ring, consensus-based election
- gossip-protocols - Epidemic protocols, failure detection
- probabilistic-data-structures - Bloom filters, HyperLogLog, Count-Min Sketch
Realtime (4 skills)
- websocket-implementation - WebSocket connections, protocols, scaling
- server-sent-events - SSE for server-to-client streaming
- pubsub-patterns - Publish/subscribe architectures
- realtime-sync - Real-time data synchronization
Load Full Category Details
Read ../distributed-systems/INDEX.md Read ../realtime/INDEX.md
Progressive Loading
- Level 1: This gateway loads automatically (~60 lines)
- Level 2: Load category INDEX.md for full skill listings
- Level 3: Load specific skills as needed
Engineering Skills Discovery
Provides automatic access to comprehensive engineering skills.
When This Skill Activates
This skill auto-activates when you're working with:
- engineering practices
- code review
- documentation
- team collaboration
- technical leadership
- Process flows and flowcharts
- Sequence and interaction diagrams
- System architecture and C4 diagrams
- Database schemas and ER diagrams
- Class diagrams and state machines
- Data visualization charts
- Project timelines and Gantt charts
- Git workflows and branching
- Mindmaps and concept hierarchies
- Any Mermaid.js diagram creation
Available Skills
Quick Reference
The Engineering category contains 24 skills across 2 subcategories:
Engineering (16 skills):
Software Development Practices:
- code-review - PR reviews, feedback, automation
- code-quality - SOLID principles, metrics, code smells
- refactoring-patterns - Safe refactoring techniques
- test-driven-development - TDD, red-green-refactor
- domain-driven-design - DDD patterns, bounded contexts
- functional-programming - FP principles, immutability
- design-patterns - GoF patterns, when to use
- technical-debt - Identifying and managing debt
- pair-programming - Pairing techniques, mob programming
- continuous-integration - CI/CD pipelines, deployment
RFC & Documentation: 11. rfc-consensus-building - Stakeholder collaboration 12. rfc-decision-documentation - ADRs, decision tracking 13. rfc-structure-format - RFC templates, formatting 14. rfc-technical-design - Architecture proposals
Plus 2 more in ../engineering/INDEX.md
Diagrams (8 skills): See ../diagrams/INDEX.md
Load Full Category Details
Read ../engineering/INDEX.md Read ../diagrams/INDEX.md
Progressive Loading
This gateway skill enables progressive loading:
- Level 1: Gateway loads automatically (you're here now)
- Level 2: Load category INDEX.md for full overview
- Level 3: Load specific skills as needed
Usage Instructions
- Auto-activation: This skill loads automatically when Claude Code detects engineering work
- Browse skills: Run
Read ../engineering/INDEX.mdfor full category overview - Load specific skills: Use bash commands above to load individual skills
Next Steps: Run Read ../engineering/INDEX.md to see full category details.
Frontend Skills Discovery
Provides automatic access to comprehensive frontend development skills.
When This Skill Activates
This skill auto-activates when you're working with:
- React component development
- Next.js applications and App Router
- State management (Context, Zustand, Redux)
- Data fetching (SWR, React Query, Server Actions)
- Form handling and validation
- Web accessibility (WCAG, ARIA)
- Frontend performance optimization
- SEO and metadata
- UI/UX design implementation
- terminal user interfaces
- TUI
- Bubble Tea
- Ratatui
- terminal UI
- text-based interfaces
- ncurses
Available Skills
Quick Reference
The Frontend category contains 16 skills across 2 subcategories (+ elegant-design):
Frontend (11 skills):
- react-component-patterns - Component design, composition, hooks, performance
- nextjs-app-router - Next.js 14+ App Router, Server Components, routing
- react-state-management - Context, Zustand, Redux Toolkit patterns
- react-data-fetching - SWR, React Query, Server Actions, data patterns
- react-form-handling - React Hook Form, Zod validation, form patterns
- web-accessibility - WCAG 2.1 AA compliance, ARIA, keyboard navigation
- frontend-performance - Bundle optimization, Core Web Vitals, code splitting
- nextjs-seo - SEO with Next.js, metadata API, structured data
- web-workers - Web Workers API, message passing, offloading computation
- browser-concurrency - Service Workers, SharedWorkers, Worklets, PWAs
- elegant-design/SKILL.md - World-class accessible interfaces (separate Agent Skill)
TUI (5 skills): See ../tui/INDEX.md
Load Full Category Details
Read ../frontend/INDEX.md Read ../tui/INDEX.md
Common Workflows
New Next.js Application
Sequence: App Router → Components → Data Fetching
Read ../frontend/nextjs-app-router.md # Setup routing, layouts Read ../frontend/react-component-patterns.md # Build components Read ../frontend/react-data-fetching.md # Fetch data
Elegant UI Design
Sequence: Design System → Components → Accessibility
Note: elegant-design auto-activates as separate Agent Skill
for design-focused work (shadcn/ui, accessible interfaces, etc.)
Read ../frontend/react-component-patterns.md Read ../frontend/web-accessibility.md
Form Implementation
Sequence: Form Handling → State Management
Read ../frontend/react-form-handling.md # Build forms Read ../frontend/react-state-management.md # Manage form state
Production Optimization
Sequence: Performance → Accessibility → SEO
Read ../frontend/frontend-performance.md # Optimize bundle Read ../frontend/web-accessibility.md # Ensure accessibility Read ../frontend/nextjs-seo.md # Optimize SEO
CPU-Intensive Features & PWAs
Sequence: Workers → Concurrency → Performance
Read ../frontend/web-workers.md # Offload heavy computation Read ../frontend/browser-concurrency.md # Service Workers, offline support Read ../frontend/frontend-performance.md # Optimize overall performance
Skill Selection Guide
React Component Patterns → react-component-patterns.md:
- Component architecture and composition
- Custom hooks
- Performance optimization (memo, useMemo, useCallback)
- Design patterns (compound components, render props, HOCs)
Next.js App Router → nextjs-app-router.md:
- Server Components vs Client Components
- Routing and layouts
- Data fetching patterns
- Streaming and Suspense
- Route handlers and API routes
State Management → react-state-management.md:
- When to use Context vs external state libraries
- Zustand for simple global state
- Redux Toolkit for complex state
- Server state vs client state
Data Fetching → react-data-fetching.md:
- SWR for client-side fetching
- React Query (TanStack Query) for advanced patterns
- Next.js Server Actions
- Data mutation patterns
- Caching strategies
Forms → react-form-handling.md:
- React Hook Form for performance
- Zod for validation
- Form state management
- Error handling
- File uploads
Accessibility → web-accessibility.md:
- WCAG 2.1 AA compliance
- ARIA attributes
- Keyboard navigation
- Screen reader support
- Color contrast and focus management
Performance → frontend-performance.md:
- Bundle size optimization
- Code splitting and lazy loading
- Core Web Vitals
- Image optimization
- Font optimization
- Runtime performance
SEO → nextjs-seo.md:
- Next.js Metadata API
- Open Graph and Twitter cards
- Structured data (JSON-LD)
- Sitemap and robots.txt
- Dynamic metadata
Web Workers → web-workers.md:
- Offloading heavy computation
- Web Workers API and message passing
- Transferable objects for zero-copy
- React integration with custom hooks
- Worker pools for parallel processing
- TypeScript type safety
Browser Concurrency → browser-concurrency.md:
- Service Workers for offline support and PWAs
- SharedWorkers for cross-tab state
- Audio/Paint/Animation Worklets
- Background sync and push notifications
- Caching strategies
- BroadcastChannel for cross-tab messaging
Integration with Other Skills
Frontend skills commonly combine with:
API skills (discover-api):
- Consuming REST APIs
- GraphQL client integration
- API error handling in UI
- Authentication flows
Testing skills (discover-testing):
- Component testing
- E2E testing with Playwright
- Visual regression testing
- Accessibility testing
Design (elegant-design Agent Skill):
- shadcn/ui components
- Accessible design patterns
- Chat/terminal/code UIs
- Streaming interfaces
- Design systems
Database skills (discover-database):
- Server Actions with database queries
- ORM integration in Server Components
- Real-time data updates
Deployment skills (discover-deployment):
- Vercel deployment
- Netlify deployment
- Performance monitoring
- CDN configuration
Progressive Loading
This gateway skill enables progressive loading:
- Level 1: Gateway loads automatically (you're here now)
- Level 2: Load category INDEX.md (~4K tokens) for full overview
- Level 3: Load specific skills (~3-4K tokens each) as needed
Total context: 2K + 4K + skill(s) = 6-12K tokens vs 25K+ for entire index.
Quick Start Examples
"Build a Next.js app with App Router": Read ../frontend/nextjs-app-router.md
"Create reusable React components": Read ../frontend/react-component-patterns.md
"Implement global state management": Read ../frontend/react-state-management.md
"Build a form with validation": Read ../frontend/react-form-handling.md
"Optimize my app performance": Read ../frontend/frontend-performance.md
"Make my app accessible": Read ../frontend/web-accessibility.md
"Improve SEO": Read ../frontend/nextjs-seo.md
"Offload heavy computation": Read ../frontend/web-workers.md
"Build a PWA with offline support": Read ../frontend/browser-concurrency.md
React vs Next.js Decision
Use React (Vite) when:
- Building SPAs or client-heavy apps
- Don't need SSR or SSG
- Want full control over routing
- Building component libraries
Use Next.js when:
- Need SEO (Server-Side Rendering)
- Want file-based routing
- Need API routes
- Building full-stack apps
- Want optimal performance out of the box
State Management Decision
Use Component State (useState) when:
- State is local to a component
- Simple state that doesn't need sharing
Use Context when:
- Sharing state across a few components
- Theme, auth, or user preferences
- Not frequently updated
Use Zustand when:
- Need global state
- Want simple API
- State updates are moderate
Use Redux Toolkit when:
- Complex state logic
- Need middleware (sagas, thunks)
- Large team with established patterns
- Time-travel debugging needed
For detailed guidance: Read ../frontend/react-state-management.md
Data Fetching Decision
Server Components (Next.js App Router):
- Default choice for Next.js 14+
- Fetch on server, zero client JS
- Direct database access
Server Actions (Next.js):
- For mutations and form handling
- Progressive enhancement
- Type-safe with TypeScript
SWR:
- Client-side data fetching
- Built-in caching
- Optimistic updates
- Focus on user experience
React Query:
- Advanced caching strategies
- Complex data dependencies
- Offline support
- DevTools for debugging
For detailed patterns: Read ../frontend/react-data-fetching.md
Usage Instructions
- Auto-activation: This skill loads automatically when Claude Code detects frontend work
- Browse skills: Run
Read ../frontend/INDEX.mdfor full category overview - Load specific skills: Use bash commands above to load individual skills
- Follow workflows: Use recommended sequences for common patterns
- elegant-design: Note that elegant-design is a separate Agent Skill that auto-activates for UI design work
Next Steps: Run Read ../frontend/INDEX.md to see full category details, or load specific skills using the bash commands above.
Infrastructure & Cloud Skills Discovery
When This Skill Activates
- Cloud platforms (AWS, GCP, Azure)
- Serverless functions (Lambda, Cloud Functions, Modal)
- Infrastructure as Code (Terraform, IaC)
- Docker, containers, Kubernetes
- Container security, networking, registries
- Cloudflare Workers, edge computing
- Deployment platforms (Netlify, Heroku)
- Cost optimization, infrastructure security
- CI/CD deployment strategies, rollbacks
Available Skills (30 total)
Cloud (13 skills)
- aws-lambda-functions - Lambda development, triggers, optimization
- aws-api-gateway - REST/HTTP/WebSocket APIs, authorization
- aws-databases - RDS, DynamoDB, ElastiCache, Aurora
- aws-iam-security - IAM, Cognito, Secrets Manager, KMS
- aws-storage - S3, EBS, EFS, Glacier, lifecycle policies
- aws-ec2-compute - EC2, Auto Scaling, Load Balancing
- aws-networking - VPC, security groups, Route53, CloudFront
- gcp-serverless - Cloud Functions, Cloud Run, App Engine
- gcp-compute - Compute Engine, GKE, autoscaling
- gcp-databases - Cloud SQL, Firestore, Bigtable, Spanner
- gcp-storage - Cloud Storage, Persistent Disk, Filestore
- gcp-iam-security - IAM, service accounts, Secret Manager
- gcp-networking - VPC, firewall, Cloud DNS, Cloud CDN
Infrastructure (6 skills)
- terraform-patterns - Modules, state, workspaces, best practices
- kubernetes-basics - Pods, deployments, services, configuration
- cloudflare-workers - Edge functions, KV storage, Durable Objects
- infrastructure-security - Network security, secrets, hardening
- cost-optimization - Cloud cost reduction strategies
- aws-serverless - Serverless architecture patterns
Deployment (6 skills)
- heroku-deployment - Deployment, dynos, buildpacks
- heroku-addons - Databases, caching, monitoring addons
- heroku-troubleshooting - Common issues and debugging
- netlify-deployment - Build, deploy, previews, CDN
- netlify-functions - Serverless functions on Netlify
- netlify-optimization - Performance, caching, edge
Containers (5 skills)
- dockerfile-optimization - Multi-stage builds, layer caching
- docker-compose-development - Multi-service local development
- container-networking - Bridge, overlay, service discovery
- container-security - Image scanning, runtime security
- container-registry-management - Registry setup, policies
Load Full Category Details
Read ../cloud/INDEX.md Read ../infrastructure/INDEX.md Read ../deployment/INDEX.md Read ../containers/INDEX.md
Progressive Loading
- Level 1: This gateway loads automatically (~80 lines)
- Level 2: Load category INDEX.md for full skill listings
- Level 3: Load specific skills as needed
Math Skills Discovery
Provides automatic access to comprehensive math skills.
When This Skill Activates
This skill auto-activates when you're working with:
- mathematics
- algorithms
- linear algebra
- calculus
- topology
- category theory
- proofs
- theorems
Available Skills
Quick Reference
The Math category contains 11 skills:
- abstract-algebra
- category-theory-foundations
- differential-equations
- linear-algebra-computation
- number-theory
- numerical-methods
- optimization-algorithms
- probability-statistics
- set-theory
- topology-algebraic
- topology-point-set
Load Full Category Details
For complete descriptions and workflows:
Read ../math/INDEX.md
This loads the full Math category index with:
- Detailed skill descriptions
- Usage triggers for each skill
- Common workflow combinations
- Cross-references to related skills
Load Specific Skills
Load individual skills as needed:
Read ../math/abstract-algebra.md Read ../math/category-theory-foundations.md Read ../math/differential-equations.md Read ../math/linear-algebra-computation.md Read ../math/number-theory.md
Progressive Loading
This gateway skill enables progressive loading:
- Level 1: Gateway loads automatically (you're here now)
- Level 2: Load category INDEX.md for full overview
- Level 3: Load specific skills as needed
Usage Instructions
- Auto-activation: This skill loads automatically when Claude Code detects math work
- Browse skills: Run
Read ../math/INDEX.mdfor full category overview - Load specific skills: Use bash commands above to load individual skills
Next Steps: Run Read ../math/INDEX.md to see full category details.
MCP Skills Discovery
Provides automatic access to comprehensive MCP server development, tool design, and testing skills.
When This Skill Activates
This skill auto-activates when you're working with:
- Building MCP servers (TypeScript or Python)
- Designing MCP tools, resources, or prompts
- Choosing MCP transports (stdio, SSE, Streamable HTTP)
- Implementing JSON-RPC 2.0 over MCP
- Testing MCP servers with Inspector or automated tests
- Debugging MCP protocol or transport issues
- Publishing or deploying MCP servers
Available Skills
Quick Reference
The MCP category contains 3 specialized skills:
- mcp-server-fundamentals - Architecture, transports, tools/resources/prompts primitives, SDK setup
- mcp-tool-design - Tool naming, schemas, error handling, annotations, progressive disclosure
- mcp-testing - Inspector, unit tests, integration tests, transport debugging, CI/CD
Load Full Category Details
For complete descriptions and workflows:
Read ../mcp/INDEX.md
This loads the full MCP category index with:
- Detailed skill descriptions
- Usage triggers for each skill
- Common workflow combinations
- Cross-references to related skills
Load Specific Skills
Load individual skills as needed:
Server architecture and setup
Read ../mcp/mcp-server-fundamentals.md
Tool design and best practices
Read ../mcp/mcp-tool-design.md
Testing and debugging
Read ../mcp/mcp-testing.md
Common Workflows
New MCP Server
Sequence: Fundamentals -> Tool Design -> Testing
Read ../mcp/mcp-server-fundamentals.md # Architecture, transport, SDK Read ../mcp/mcp-tool-design.md # Design tool interfaces Read ../mcp/mcp-testing.md # Test with Inspector, CI
Adding Tools to Existing Server
Sequence: Tool Design -> Testing
Read ../mcp/mcp-tool-design.md # Naming, schemas, errors Read ../mcp/mcp-testing.md # Test new tools
Debugging MCP Issues
Sequence: Testing -> Fundamentals
Read ../mcp/mcp-testing.md # Inspector, transport debugging Read ../mcp/mcp-server-fundamentals.md # Lifecycle, capabilities
Integration with Other Skills
MCP skills commonly combine with:
API skills (discover-api):
- MCP servers wrapping REST or GraphQL APIs
- Authentication for MCP tool backends
Testing skills (discover-testing):
- Comprehensive test strategies
- Contract testing patterns
Infrastructure skills (discover-infra, discover-cloud):
- Deploying MCP servers
- Scaling HTTP transports
Progressive Loading
This gateway skill (~170 lines, ~1.5K tokens) enables progressive loading:
- Level 1: Gateway loads automatically (you're here now)
- Level 2: Load category INDEX.md (~2.5K tokens) for full overview
- Level 3: Load specific skills (~2-3K tokens each) as needed
Total context: 1.5K + 2.5K + skill(s) = 4-8K tokens vs 12K+ for everything.
Quick Start Examples
"Build an MCP server": Read ../mcp/mcp-server-fundamentals.md
"Design MCP tools for my API": Read ../mcp/mcp-tool-design.md
"Test my MCP server": Read ../mcp/mcp-testing.md
"Debug why my MCP tool isn't showing up": Read ../mcp/mcp-testing.md
Next Steps: Run Read ../mcp/INDEX.md to see full category details, or load specific skills using the commands above.
Ml Skills Discovery
Provides automatic access to comprehensive ml skills.
When This Skill Activates
This skill auto-activates when you're working with:
- machine learning
- ML
- AI
- models
- training
- inference
- PyTorch
- TensorFlow
- Modal
- serverless functions
- cloud deployment
- GPU workloads
- web endpoints
- Modal platform
Available Skills
Quick Reference
The ML category contains 42 skills across 2 subcategories:
ML (34 skills):
- custom-llm-evaluation
- diffusion-finetuning
- diffusion-model-basics
- dspy-assertions
- dspy-evaluation
- dspy-modules
- dspy-optimizers
- dspy-rag
- dspy-setup
- dspy-signatures
- graph-rag
- hierarchical-rag
- hybrid-search-rag
- llm-as-judge
- llm-benchmarks-evaluation
- llm-dataset-preparation
- llm-evaluation-frameworks
- llm-model-routing
- llm-model-selection
- lora-peft-techniques
- multi-model-orchestration
- rag-evaluation-metrics
- rag-reranking-techniques
- stable-diffusion-deployment
- unsloth-finetuning
Plus 9 more in ../ml/INDEX.md
Modal (8 skills): See ../modal/INDEX.md
Load Full Category Details
Read ../ml/INDEX.md Read ../modal/INDEX.md
Progressive Loading
This gateway skill enables progressive loading:
- Level 1: Gateway loads automatically (you're here now)
- Level 2: Load category INDEX.md for full overview
- Level 3: Load specific skills as needed
Usage Instructions
- Auto-activation: This skill loads automatically when Claude Code detects ml work
- Browse skills: Run
Read ../ml/INDEX.mdfor full category overview - Load specific skills: Use bash commands above to load individual skills
Next Steps: Run Read ../ml/INDEX.md to see full category details.
Mobile Skills Discovery
Provides automatic access to comprehensive mobile skills.
When This Skill Activates
This skill auto-activates when you're working with:
- iOS
- Swift
- SwiftUI
- mobile
- SwiftData
- concurrency
- networking
- mobile app development
Available Skills
Quick Reference
The Mobile category contains 4 skills:
- react-native-native-modules
- react-native-navigation
- react-native-performance
- react-native-setup
Load Full Category Details
For complete descriptions and workflows:
Read ../mobile/INDEX.md
This loads the full Mobile category index with:
- Detailed skill descriptions
- Usage triggers for each skill
- Common workflow combinations
- Cross-references to related skills
Load Specific Skills
Load individual skills as needed:
Read ../mobile/react-native-native-modules.md Read ../mobile/react-native-navigation.md Read ../mobile/react-native-performance.md Read ../mobile/react-native-setup.md
Progressive Loading
This gateway skill enables progressive loading:
- Level 1: Gateway loads automatically (you're here now)
- Level 2: Load category INDEX.md for full overview
- Level 3: Load specific skills as needed
Usage Instructions
- Auto-activation: This skill loads automatically when Claude Code detects mobile work
- Browse skills: Run
Read ../mobile/INDEX.mdfor full category overview - Load specific skills: Use bash commands above to load individual skills
Next Steps: Run Read ../mobile/INDEX.md to see full category details.
Networking Skills Discovery
Provides automatic access to comprehensive networking skills.
When This Skill Activates
This skill auto-activates when you're working with:
- networking
- SSH
- mTLS
- NAT traversal
- VPN
- Tailscale
- network resilience
- connection reliability
- HTTP, HTTP/2, HTTP/3
- TCP, UDP, QUIC
- network protocols
- protocol debugging
- protocol selection
- network communication
- web protocols
- transport layer
- application layer protocols
- Forward/reverse proxies
- HTTP proxy configuration
- Nginx, Traefik, Envoy, Caddy
- Load balancing
- SSL/TLS termination
- HTTP caching and CDN
- Cache invalidation
- NATS messaging
- Service mesh patterns
Available Skills
Quick Reference
The Networking category contains 20 skills across 3 subcategories:
Networking (5 skills):
- mosh-resilient-ssh
- mtls-implementation
- nat-traversal
- network-resilience-patterns
- tailscale-vpn
Protocols (8 skills): See ../protocols/INDEX.md
Proxies (7 skills): See ../proxies/INDEX.md
Load Full Category Details
Read ../networking/INDEX.md Read ../protocols/INDEX.md Read ../proxies/INDEX.md
Progressive Loading
This gateway skill enables progressive loading:
- Level 1: Gateway loads automatically (you're here now)
- Level 2: Load category INDEX.md for full overview
- Level 3: Load specific skills as needed
Usage Instructions
- Auto-activation: This skill loads automatically when Claude Code detects networking work
- Browse skills: Run
Read ../networking/INDEX.mdfor full category overview - Load specific skills: Use bash commands above to load individual skills
Next Steps: Run Read ../networking/INDEX.md to see full category details.
Product Skills Discovery
Provides automatic access to comprehensive product skills.
When This Skill Activates
This skill auto-activates when you're working with:
- product management
- roadmap
- strategy
- prioritization
- user research
- product development
- collaboration
- code review
- documentation
- pair programming
- team workflows
- communication
- Beads
- workflow
- task management
- context strategies
- dependency management
- multi-session
- project synthesis
- cleanup
- consolidation
Available Skills
Quick Reference
The Product category contains 15 skills across 3 subcategories:
Product (4 skills):
- prd-requirements-gathering
- prd-structure-templates
- prd-technical-specifications
- prd-user-stories-acceptance
Collaboration (6 skills): See ../collaboration/INDEX.md
Workflow (5 skills): See ../workflow/INDEX.md
Load Full Category Details
Read ../product/INDEX.md Read ../collaboration/INDEX.md Read ../workflow/INDEX.md
Progressive Loading
This gateway skill enables progressive loading:
- Level 1: Gateway loads automatically (you're here now)
- Level 2: Load category INDEX.md for full overview
- Level 3: Load specific skills as needed
Usage Instructions
- Auto-activation: This skill loads automatically when Claude Code detects product work
- Browse skills: Run
Read ../product/INDEX.mdfor full category overview - Load specific skills: Use bash commands above to load individual skills
Next Steps: Run Read ../product/INDEX.md to see full category details.
Research Skills Discovery
Auto-Activation
This skill is automatically activated when your task involves:
- Research synthesis, literature reviews, meta-analysis
- Quantitative research, statistical analysis, surveys, experiments
- Qualitative research, interviews, ethnography, case studies
- Study design, hypothesis testing, sampling strategies
- Data collection, survey design, interview protocols
- Data analysis, coding, statistical tests, visualization
- Research writing, academic papers, citations, reporting
Available Research Skills
Core Methodology Skills
1. research-synthesis - Synthesizing information and conducting meta-analysis
- Narrative synthesis approaches
- Meta-analysis with Python implementation
- Thematic synthesis of qualitative findings
- Evidence mapping and gap analysis
- GRADE framework for quality assessment
- Use when: Integrating findings across studies
2. quantitative-methods - Quantitative research and statistical analysis
- Experimental design with power analysis
- Survey methods and analysis
- Hypothesis testing framework
- Regression analysis with diagnostics
- Effect sizes and reporting
- Use when: Testing hypotheses with numerical data
3. qualitative-methods - Qualitative research approaches
- In-depth interview protocols
- Thematic analysis (6 phases)
- Grounded theory coding
- Case study research design
- Quality criteria and rigor
- Use when: Exploring experiences and meanings
4. research-design - Planning and designing research studies
- Research question formulation (FINER criteria)
- Validity threat analysis
- Sampling strategies with Python tools
- Experimental control frameworks
- Design quality assessment
- Use when: Planning a new study from scratch
Implementation Skills
5. data-collection - Methods for gathering research data
- Survey instrument design and validation
- Interview protocol development
- Observation methods and field notes
- Data quality control frameworks
- Response rate optimization
- Use when: Implementing data collection
6. data-analysis - Analyzing quantitative and qualitative data
- Comprehensive descriptive statistics
- Inferential testing with full reporting
- Systematic qualitative coding
- Thematic development process
- Publication-ready visualizations
- Use when: Making sense of collected data
7. research-writing - Writing research papers and reports
- IMRAD structure with guidelines
- APA statistical reporting
- Citation management
- Argument construction
- Peer review response strategies
- Use when: Communicating research findings
Loading Skills
Load Individual Skills
From skills directory
Read ../research/research-synthesis.md Read ../research/quantitative-methods.md Read ../research/qualitative-methods.md Read ../research/research-design.md Read ../research/data-collection.md Read ../research/data-analysis.md Read ../research/research-writing.md
Common Workflow Combinations
Quantitative Research Study:
Planning phase
Read ../research/research-design.md
Data collection
Read ../research/data-collection.md Read ../research/quantitative-methods.md
Analysis and reporting
Read ../research/data-analysis.md Read ../research/research-writing.md
Qualitative Research Study:
Planning phase
Read ../research/research-design.md
Data collection
Read ../research/data-collection.md Read ../research/qualitative-methods.md
Analysis and reporting
Read ../research/data-analysis.md Read ../research/research-writing.md
Literature Review / Meta-Analysis:
Synthesis phase
Read ../research/research-synthesis.md
If including quantitative synthesis
Read ../research/quantitative-methods.md
Writing phase
Read ../research/research-writing.md
Mixed Methods Study:
All methods
Read ../research/research-design.md Read ../research/quantitative-methods.md Read ../research/qualitative-methods.md Read ../research/data-collection.md Read ../research/data-analysis.md Read ../research/research-writing.md
Progressive Loading
Load skills progressively based on research phase:
Phase 1: Planning (Load 1-2 skills)
- research-design (always)
- quantitative-methods OR qualitative-methods (based on approach)
Phase 2: Collection (Add 1-2 skills)
- data-collection (always)
- Keep loaded: specific method skill
Phase 3: Analysis (Add 1 skill)
- data-analysis (always)
- Keep loaded: method and collection skills for reference
Phase 4: Writing (Add 1 skill, can unload others)
- research-writing (always)
- research-synthesis (if synthesizing literature)
- Keep one method skill for reporting details
Phase 5: Synthesis (If conducting review)
- research-synthesis (load early)
- quantitative-methods (if meta-analysis)
- qualitative-methods (if thematic synthesis)
Decision Tree
Research Task
↓
Conducting new study?
YES → Load research-design
↓
Quantitative approach?
YES → Load quantitative-methods + data-collection
Qualitative approach?
YES → Load qualitative-methods + data-collection
Mixed methods?
YES → Load both methods + data-collection
↓
Ready to analyze?
YES → Load data-analysis
↓
Ready to write?
YES → Load research-writing
NO → Synthesizing existing research?
YES → Load research-synthesis
↓
Quantitative synthesis (meta-analysis)?
YES → Also load quantitative-methods
Qualitative synthesis?
YES → Also load qualitative-methods
↓
Ready to write?
YES → Load research-writing
Context-Aware Loading
Based on keywords in your task, these skills auto-load:
Keywords → Skills Mapping:
- "literature review", "meta-analysis", "systematic review" → research-synthesis
- "survey", "experiment", "hypothesis", "statistical" → quantitative-methods
- "interview", "ethnography", "case study", "lived experience" → qualitative-methods
- "study design", "sampling", "validity", "research plan" → research-design
- "questionnaire", "data collection", "measurement" → data-collection
- "analyze data", "coding", "statistical test", "thematic" → data-analysis
- "write paper", "manuscript", "citation", "peer review" → research-writing
Related Skill Categories
- statistics: Advanced statistical techniques
- data-science: Machine learning and big data approaches
- visualization: Advanced data visualization
- academic-writing: General academic writing skills
- scientific-computing: Python/R for research computing
Quick Start Examples
"I need to design a survey study"
Read ../research/research-design.md Read ../research/data-collection.md Read ../research/quantitative-methods.md
"I need to analyze interview transcripts"
Read ../research/qualitative-methods.md Read ../research/data-analysis.md
"I need to conduct a meta-analysis"
Read ../research/research-synthesis.md Read ../research/quantitative-methods.md
"I need to write up my results"
Read ../research/research-writing.md Read ../research/data-analysis.md
Best Practices
- Start with design: Load research-design first when planning new studies
- Method-specific loading: Load only the method skill you need (quant OR qual)
- Progressive addition: Add skills as you progress through research phases
- Unload when done: Unload skills from completed phases to manage context
- Keep writing loaded: research-writing useful throughout for documentation
Skill Maintenance
All research skills follow these standards:
- Practical code examples (Python primary, R when appropriate)
- Real-world templates and protocols
- Best practices and anti-patterns
- Cross-references to related skills
- 250-400 lines optimized for context efficiency
Integration with Other Skills
Research skills integrate well with:
- python-data-science: For advanced analysis
- python-visualization: For publication graphics
- academic-latex: For paper formatting
- git-workflow: For research project management
- reproducibility: For reproducible research practices
Security Skills Discovery
Provides automatic access to comprehensive application security, vulnerability assessment, and security best practices skills.
When This Skill Activates
This skill auto-activates when you're working with:
- Authentication and authorization systems
- Input validation and sanitization
- Security headers (CSP, HSTS, CORS)
- Vulnerability scanning and penetration testing
- OWASP Top 10 vulnerabilities
- Secrets management (Vault, AWS Secrets Manager)
- SQL injection, XSS, or other attack prevention
- Security hardening and compliance
- Password hashing and credential management
- API security and access control
Available Skills
Quick Reference
The Security category contains 6 specialized skills:
- authentication - Authentication patterns (JWT, OAuth2, sessions, MFA, password security)
- authorization - Access control (RBAC, ABAC, policy engines, permissions)
- input-validation - Input validation and sanitization (SQL injection, XSS, command injection)
- security-headers - HTTP security headers (CSP, HSTS, X-Frame-Options, CORS)
- vulnerability-assessment - Security testing (OWASP Top 10, scanning tools, pentesting)
- secrets-management - Secrets handling (Vault, AWS Secrets Manager, key rotation)
Load Full Category Details
For complete descriptions and workflows:
Read ../security/INDEX.md
This loads the full Security category index with:
- Detailed skill descriptions
- Usage triggers for each skill
- Common workflow combinations
- Cross-references to related skills
Load Specific Skills
Load individual skills as needed:
Identity and access
Read ../security/authentication.md Read ../security/authorization.md
Input security
Read ../security/input-validation.md Read ../security/security-headers.md
Security operations
Read ../security/vulnerability-assessment.md Read ../security/secrets-management.md
Common Workflows
Secure Web Application
Sequence: Authentication → Authorization → Input validation → Security headers
Read ../security/authentication.md # User login Read ../security/authorization.md # Access control Read ../security/input-validation.md # XSS/SQL injection prevention Read ../security/security-headers.md # Browser protection
Security Audit
Sequence: Vulnerability assessment → Input validation → Headers → Secrets
Read ../security/vulnerability-assessment.md # OWASP Top 10 testing Read ../security/input-validation.md # Injection testing Read ../security/security-headers.md # Header configuration Read ../security/secrets-management.md # Credential security
API Security
Sequence: Authentication → Authorization → Input validation → Secrets
Read ../security/authentication.md # JWT/OAuth2 Read ../security/authorization.md # API access control Read ../security/input-validation.md # Request validation Read ../security/secrets-management.md # API key management
DevSecOps Pipeline
Sequence: Vulnerability assessment → Secrets → Input validation
Read ../security/vulnerability-assessment.md # Security scanning Read ../security/secrets-management.md # CI/CD secrets Read ../security/input-validation.md # SAST validation
Secure New Application
Full security implementation from scratch:
1. Identity and access
Read ../security/authentication.md Read ../security/authorization.md
2. Input protection
Read ../security/input-validation.md Read ../security/security-headers.md
3. Operations
Read ../security/secrets-management.md Read ../security/vulnerability-assessment.md
Skill Selection Guide
Choose Authentication when:
- Implementing user login systems
- Working with JWT, OAuth2, or sessions
- Adding multi-factor authentication
- Managing passwords and credentials
Choose Authorization when:
- Implementing access control
- Building role-based permissions (RBAC)
- Working with policy engines (OPA, Casbin)
- Preventing privilege escalation
Choose Input Validation when:
- Processing user input
- Preventing SQL injection
- Protecting against XSS attacks
- Validating file uploads
- Preventing command injection
Choose Security Headers when:
- Configuring Content Security Policy (CSP)
- Implementing HTTPS enforcement (HSTS)
- Setting up CORS for APIs
- Preventing clickjacking
- Hardening web applications
Choose Vulnerability Assessment when:
- Testing for OWASP Top 10
- Running security scans (SAST/DAST)
- Performing penetration tests
- Auditing application security
- Setting up security CI/CD
Choose Secrets Management when:
- Storing API keys or credentials
- Integrating with HashiCorp Vault
- Using AWS Secrets Manager or GCP Secret Manager
- Rotating encryption keys
- Managing CI/CD secrets
Integration with Other Skills
Security skills commonly combine with:
API skills (discover-api):
- API authentication and authorization
- API input validation
- API rate limiting (abuse prevention)
- Securing REST and GraphQL endpoints
Database skills (discover-database):
- SQL injection prevention
- Database connection security
- Credential management
- Row-level security
Frontend skills (discover-frontend):
- XSS prevention in React/Vue
- Content Security Policy
- Secure cookie handling
- Client-side validation
Infrastructure skills (discover-infrastructure, discover-cloud):
- Secrets management in deployments
- Network security
- Container security scanning
- TLS/SSL configuration
Testing skills (discover-testing):
- Security integration tests
- Penetration testing
- Automated security scans
- Vulnerability regression tests
Usage Instructions
- Auto-activation: This skill loads automatically when Claude Code detects security-related work
- Browse skills: Run
Read ../security/INDEX.mdfor full category overview - Load specific skills: Use bash commands above to load individual skills
- Follow workflows: Use recommended sequences for common security patterns
- Combine skills: Load multiple skills for comprehensive security coverage
Progressive Loading
This gateway skill (~200 lines, ~2K tokens) enables progressive loading:
- Level 1: Gateway loads automatically (you're here now)
- Level 2: Load category INDEX.md (~3K tokens) for full overview
- Level 3: Load specific skills (~2-4K tokens each) as needed
Total context: 2K + 3K + skill(s) = 5-12K tokens vs 30K+ for entire index.
Quick Start Examples
"Implement user authentication": Read ../security/authentication.md
"Add role-based access control": Read ../security/authorization.md
"Prevent SQL injection": Read ../security/input-validation.md
"Configure Content Security Policy": Read ../security/security-headers.md
"Test for OWASP vulnerabilities": Read ../security/vulnerability-assessment.md
"Integrate HashiCorp Vault": Read ../security/secrets-management.md
"Secure API with JWT": Read ../security/authentication.md Read ../security/authorization.md
Next Steps: Run Read ../security/INDEX.md to see full category details, or load specific skills using the bash commands above.
Systems Theory & Language Design Skills Discovery
When This Skill Activates
- eBPF, kernel tracing, XDP, kprobes, BPF
- Compilers, parsers, interpreters, AST, bytecode
- Type systems, type theory, programming language design
- LLVM, IR, SSA, code generation, optimization passes
- Information retrieval, search, ranking, vector search
- Formal verification, theorem proving, model checking
- SAT, SMT, Z3, Lean, constraint solving
Available Skills (32 total)
eBPF (4 skills)
- ebpf-fundamentals - eBPF programs, verifier, maps
- ebpf-networking - XDP, TC, socket filtering
- ebpf-security-monitoring - LSM hooks, syscall tracing
- ebpf-tracing-observability - kprobes, tracepoints, profiling
Information Retrieval (5 skills)
- ir-search-fundamentals - Indexing, tokenization, TF-IDF, BM25
- ir-query-understanding - Query parsing, expansion, intent
- ir-ranking-reranking - Learning to rank, cross-encoders
- ir-vector-search - Embeddings, ANN, HNSW, FAISS
- ir-recommendation-systems - Collaborative/content-based filtering
Programming Language Theory (13 skills)
- type-systems - Type theory, inference, polymorphism
- lambda-calculus - Lambda calculus, reduction, Church encodings
- curry-howard - Propositions as types, proofs as programs
- dependent-types - Dependent types, refinement types
- operational-semantics - Small-step, big-step semantics
- program-verification - Hoare logic, invariants, correctness
- structure-editors - Structural editing, projectional editors
- hazelnut-calculus - Hazelnut typed holes calculus
- live-programming-holes - Live programming with typed holes
- typed-holes-foundations - Typed holes theory and foundations
- typed-holes-interaction - Interactive typed hole filling
- typed-holes-llm - LLM-powered typed hole completion
- typed-holes-semantics - Typed holes formal semantics
Formal Methods (10 skills)
- z3-solver-basics - Z3 SMT solver, constraints, assertions
- sat-solving-strategies - SAT solving, DPLL, CDCL
- smt-theory-applications - SMT theories, bitvectors, arrays
- lean-proof-basics - Lean 4 basics, tactics, terms
- lean-tactics - Advanced Lean tactics and automation
- lean-theorem-proving - Theorem proving patterns in Lean
- lean-mathlib4 - Mathlib4 library usage
- csp-modeling - Constraint satisfaction problems
- constraint-propagation - Arc consistency, propagation
- backtracking-search - Backtracking, branch and bound
Load Full Category Details
Read ../ebpf/INDEX.md Read ../ir/INDEX.md Read ../plt/INDEX.md Read ../formal/INDEX.md
Progressive Loading
- Level 1: This gateway loads automatically (~70 lines)
- Level 2: Load category INDEX.md for full skill listings
- Level 3: Load specific skills as needed
Testing Skills Discovery
Provides automatic access to comprehensive testing skills.
When This Skill Activates
This skill auto-activates when you're working with:
- testing
- tests
- unit tests
- integration
- e2e
- TDD
- test coverage
- performance testing
Available Skills
Quick Reference
The Testing category contains 6 skills:
- e2e-testing
- integration-testing
- performance-testing
- test-coverage-strategy
- test-driven-development
- unit-testing-patterns
Load Full Category Details
For complete descriptions and workflows:
Read ../testing/INDEX.md
This loads the full Testing category index with:
- Detailed skill descriptions
- Usage triggers for each skill
- Common workflow combinations
- Cross-references to related skills
Load Specific Skills
Load individual skills as needed:
Read ../testing/e2e-testing.md Read ../testing/integration-testing.md Read ../testing/performance-testing.md Read ../testing/test-coverage-strategy.md Read ../testing/test-driven-development.md
Progressive Loading
This gateway skill enables progressive loading:
- Level 1: Gateway loads automatically (you're here now)
- Level 2: Load category INDEX.md for full overview
- Level 3: Load specific skills as needed
Usage Instructions
- Auto-activation: This skill loads automatically when Claude Code detects testing work
- Browse skills: Run
Read ../testing/INDEX.mdfor full category overview - Load specific skills: Use bash commands above to load individual skills
Next Steps: Run Read ../testing/INDEX.md to see full category details.
Wasm Skills Discovery
Provides automatic access to comprehensive wasm skills.
When This Skill Activates
This skill auto-activates when you're working with:
- WebAssembly
- WASM
- wasm-pack
- Rust to WASM
- browser WASM
- WASI
- portable bytecode
Available Skills
Quick Reference
The Wasm category contains 4 skills:
- wasm-browser-integration
- wasm-fundamentals
- wasm-rust-toolchain
- wasm-server-side
Load Full Category Details
For complete descriptions and workflows:
Read ../wasm/INDEX.md
This loads the full Wasm category index with:
- Detailed skill descriptions
- Usage triggers for each skill
- Common workflow combinations
- Cross-references to related skills
Load Specific Skills
Load individual skills as needed:
Read ../wasm/wasm-browser-integration.md Read ../wasm/wasm-fundamentals.md Read ../wasm/wasm-rust-toolchain.md Read ../wasm/wasm-server-side.md
Progressive Loading
This gateway skill enables progressive loading:
- Level 1: Gateway loads automatically (you're here now)
- Level 2: Load category INDEX.md for full overview
- Level 3: Load specific skills as needed
Usage Instructions
- Auto-activation: This skill loads automatically when Claude Code detects wasm work
- Browse skills: Run
Read ../wasm/INDEX.mdfor full category overview - Load specific skills: Use bash commands above to load individual skills
Next Steps: Run Read ../wasm/INDEX.md to see full category details.
Zig Skills Discovery
Provides automatic access to comprehensive zig skills.
When This Skill Activates
This skill auto-activates when you're working with:
- Zig
- systems programming
- comptime
- allocators
- C interop
- build.zig
- zon package manager
Available Skills
Quick Reference
The Zig category contains 6 skills:
- zig-build-system
- zig-c-interop
- zig-memory-management
- zig-package-management
- zig-project-setup
- zig-testing
Load Full Category Details
For complete descriptions and workflows:
Read ../zig/INDEX.md
This loads the full Zig category index with:
- Detailed skill descriptions
- Usage triggers for each skill
- Common workflow combinations
- Cross-references to related skills
Load Specific Skills
Load individual skills as needed:
Read ../zig/zig-build-system.md Read ../zig/zig-c-interop.md Read ../zig/zig-memory-management.md
Progressive Loading
This gateway skill enables progressive loading:
- Level 1: Gateway loads automatically (you're here now)
- Level 2: Load category INDEX.md for full overview
- Level 3: Load specific skills as needed
Usage Instructions
- Auto-activation: This skill loads automatically when Claude Code detects zig work
- Browse skills: Run
Read ../zig/INDEX.mdfor full category overview - Load specific skills: Use bash commands above to load individual skills
Next Steps: Run Read ../zig/INDEX.md to see full category details.
Designing Elegant Interfaces
Philosophy
World-class design is intentional, accessible, and delightful. Every element serves a purpose, every interaction feels natural, and the experience adapts gracefully across contexts.
Core Principles:
- Clarity over cleverness - Users should never wonder what to do next
- Consistency over novelty - Patterns should repeat predictably
- Performance over features - Fast, smooth interactions trump visual complexity
- Accessibility always - Design for all users from the start
- Progressive disclosure - Reveal complexity only when needed
- Intentional friction - Make destructive actions harder, constructive actions effortless
When to Use This Skill
Use this skill when:
- Building web applications with React/Next.js/similar frameworks
- Creating developer tools or technical interfaces
- Designing interfaces with chat, terminals, or code display
- Implementing real-time or streaming features
- Ensuring accessibility and responsive design
- Working with shadcn/ui, daisyUI, or HeroUI design systems
Design Process Workflow
Follow this workflow for optimal results:
1. Discovery & Planning (15-30 min)
Map User Experience:
# Create flow diagrams with Graphviz
cat > user-flow.dot << 'EOF'
digraph UserFlow {
Start -> "Observe State"
"Observe State" -> "Orient Understanding"
"Orient Understanding" -> "Decide Action"
"Decide Action" -> "Act Execute"
"Act Execute" -> "Observe State" [label="OODA loop"]
}
EOF
dot -Tpng user-flow.dot -o user-flow.png
OODA Loop Mapping: For each major user goal, optimize the cycle:
- Observe - What information does the user need?
- Orient - How do they make sense of it?
- Decide - What choices are available?
- Act - How do they execute?
Document States:
- Entry points (how users arrive)
- Core loops (repeated actions)
- Success states (goals achieved)
- Failure states (errors, recovery paths)
- Edge cases (empty, loading, error, extreme data)
List Affordances: Identify every UI element needed:
- Navigation (movement between sections)
- Actions (buttons, links, controls)
- Inputs (forms, editors, pickers)
- Feedback (success, error, loading)
- Content (text, images, data)
- Wayfinding (breadcrumbs, progress)
Before Building Custom Components:
- Search shadcn/ui first (https://ui.shadcn.com)
- Check daisyUI (https://daisyui.com)
- Explore HeroUI (https://heroui.com)
- Build custom only when necessary
2. Design Foundation (20-40 min)
Establish Visual System:
Read the detailed foundation guides:
foundation/typography.md- Font selection (Geist, JetBrains Mono), scales, loadingfoundation/colors-and-spacing.md- Color palettes, spacing systems, dark modefoundation/layout-patterns.md- Grids, containers, white space, responsive breakpoints
Quick Reference:
- Typography: Geist for UI, JetBrains Mono for code (14px minimum)
- Spacing: 8px base system (0.5rem, 1rem, 1.5rem, 2rem, 3rem, 4rem, 6rem, 8rem)
- Colors: Semantic tokens (--color-background, --color-primary, --color-error, etc.)
- Layout: Mobile-first, 12-column grid, generous white space
3. Interactive Elements (30-60 min)
For sophisticated interactive features, reference the specialized guides:
Chat & Messaging:
- Read
interactive/chat-and-messaging.mdwhen building conversational interfaces - Covers message states, streaming, auto-scrolling, markdown rendering
Terminals & Code Display:
- Read
interactive/terminals-and-code.mdfor terminal emulators, syntax highlighting, semantic highlighting - Covers ANSI colors, Shiki integration, copy buttons, line highlighting
Streaming & Loading:
- Read
interactive/streaming-and-loading.mdfor progressive loading, streaming text, optimistic updates - Covers skeleton screens, progress indicators, loading hierarchies
Diffs & Logs:
- Read
interactive/diffs-and-logs.mdfor version control UIs, log viewers - Covers split/unified diffs, character-level changes, virtual scrolling
4. Implementation (1-3 hours)
Build Components:
- Read
implementation/components-and-accessibility.mdfor component architecture and WCAG compliance - Use atomic design: atoms → molecules → organisms → templates → pages
- Ensure keyboard navigation and screen reader support
Optimize Performance:
- Read
implementation/performance.mdfor Core Web Vitals optimization - Lazy load, code split, optimize images, measure with Lighthouse
Test & Refine:
- Read
implementation/testing-and-qa.mdfor comprehensive testing approach - Test on multiple devices, screen sizes, and with accessibility tools
5. Validation & Refinement
Pre-Launch Checklist:
- User flows tested and OODA loops optimized
- All states handled (empty, loading, error, success)
- Mobile responsive (tested on real devices)
- Accessibility compliant (WCAG AA)
- Performance measured (Lighthouse score > 90)
- Geist used for UI, JetBrains Mono for code
- Design system components used where possible
- Consistent spacing and typography
- Both light and dark modes work
- Keyboard navigation complete
- Interactive elements polished (see interactive guides)
Quick Decision Tree
Need to understand the basics?
→ Read foundation/ files first
Building chat or messaging?
→ Read interactive/chat-and-messaging.md
Building terminal or code editor?
→ Read interactive/terminals-and-code.md
Need streaming or loading states?
→ Read interactive/streaming-and-loading.md
Building diffs or log viewers?
→ Read interactive/diffs-and-logs.md
Ready to implement?
→ Read implementation/ files
Need tools or want to avoid mistakes?
→ Read reference/ files
Design Systems Priority
-
shadcn/ui (https://ui.shadcn.com) - PRIMARY CHOICE
- Excellent accessibility defaults
- Radix UI primitives
- Tailwind-based, customizable
- Copy-paste into project
-
daisyUI (https://daisyui.com)
- Semantic component names
- Tailwind plugin
- Rapid prototyping
-
HeroUI (https://heroui.com)
- Modern, polished
- Strong design language
- Product interfaces
See reference/design-systems.md for detailed comparison and usage patterns.
Typography Standards
Use these fonts exclusively:
-
Geist (https://vercel.com/font) - For ALL interface text
- UI labels, body text, headings
- 95% of your typography
-
JetBrains Mono (https://jetbrains.com/mono) - For ALL code/technical content
- Code blocks, terminals, logs, diffs
- 14px minimum size
- Enable ligatures
Never mix multiple sans-serif or multiple monospace fonts.
See foundation/typography.md for complete guidance.
Inspiration Sites
Study these for design patterns:
- Vercel (https://vercel.com) - Generous white space, clear typography
- Hex (https://hex.tech) - Data-dense but organized
- Baseten (https://docs.baseten.co) - Clear documentation structure
- Weather Underground (https://wunderground.com) - Complex data, clean presentation
- Ghostty (https://ghostty.org) - Modern terminal, elegant design
Common Anti-Patterns
Avoid these mistakes:
- ❌ Building custom components when design system has them
- ❌ Using absolute positioning for layout
- ❌ Animating expensive properties (width, height)
- ❌ Skipping mobile testing
- ❌ Ignoring accessibility
- ❌ Using
<div>for everything - ❌ Mixing multiple monospace fonts
- ❌ Auto-scrolling when user is reading
- ❌ Showing raw ANSI codes in terminals
- ❌ Forgetting empty/loading/error states
See reference/anti-patterns.md for complete list with explanations.
Iterative Development
For simple interfaces (single page, few components):
- Start with foundation (read foundation files)
- Use design system components
- Test and refine
For complex interfaces (multiple features, interactive elements):
- Map flows and create diagrams
- Establish foundation (read foundation files)
- Build one feature at a time (read relevant interactive files)
- Test each feature before moving to next
- Optimize and polish (read implementation files)
For developer tools or technical interfaces:
- Map OODA loops carefully
- Read ALL interactive files (chat, terminals, code, streaming, diffs, logs)
- Focus on keyboard navigation and performance
- Test with actual technical content
Getting Help
If unsure where to start:
- Read the philosophy section above
- Follow the Design Process Workflow
- Reference specific guides as needed
If design feels off:
- Check against principles (clarity, consistency, performance)
- Review anti-patterns list
- Study inspiration sites
- Test with real users
If implementation is slow:
- Use design system components first
- Don't build what exists
- Focus on one feature at a time
- Test early and often
File Organization
elegant-design/
├── SKILL.md (you are here)
├── foundation/
│ ├── typography.md (fonts, scales, loading)
│ ├── colors-and-spacing.md (palettes, spacing system, dark mode)
│ └── layout-patterns.md (grids, containers, responsive)
├── interactive/
│ ├── chat-and-messaging.md (chat UIs, streaming messages)
│ ├── terminals-and-code.md (terminals, syntax highlighting)
│ ├── streaming-and-loading.md (progressive loading, skeletons)
│ └── diffs-and-logs.md (version control UI, log viewers)
├── implementation/
│ ├── components-and-accessibility.md (architecture, WCAG)
│ ├── performance.md (Core Web Vitals, optimization)
│ └── testing-and-qa.md (testing checklist, tools)
└── reference/
├── design-systems.md (shadcn, daisyUI, HeroUI details)
├── tools-and-libraries.md (complete tool list)
└── anti-patterns.md (what not to do, with explanations)
Remember
World-class design is invisible. Users shouldn't notice your clever solutions - they should simply accomplish their goals effortlessly and maybe smile along the way.
Start simple, iterate based on real use. Don't build everything at once. Build what's needed, test it, refine it, then move to the next feature.
Accessibility is not optional. Design for keyboard navigation, screen readers, and sufficient contrast from the start. Retrofitting is much harder.
Performance matters. A beautiful interface that's slow is a bad interface. Measure performance early and often.
Typed Holes Refactoring
Systematically refactor codebases using the Design by Typed Holes meta-framework: treat architectural unknowns as typed holes, resolve them iteratively with test-driven validation, and propagate constraints through dependency graphs.
Core Workflow
Phase 0: Hole Discovery & Setup
1. Create safe working branch:
git checkout -b refactor/typed-holes-v1
# CRITICAL: Never work in main, never touch .beads/ in main
2. Analyze current state and identify holes:
python scripts/discover_holes.py
# Creates REFACTOR_IR.md with hole catalog
The Refactor IR documents:
- Current State Holes: What's unknown about the current system?
- Refactor Holes: What needs resolution to reach the ideal state?
- Constraints: What must be preserved/improved/maintained?
- Dependencies: Which holes block which others?
3. Write baseline characterization tests:
Create tests/characterization/ to capture exact current behavior:
# tests/characterization/test_current_behavior.py
def test_api_contracts():
"""All public APIs must behave identically post-refactor"""
for endpoint in discover_public_apis():
old_result = run_current(endpoint, test_inputs)
save_baseline(endpoint, old_result)
def test_performance_baselines():
"""Record current performance - don't regress"""
baselines = measure_all_operations()
save_json("baselines.json", baselines)
Run tests on main branch - they should all pass. These are your safety net.
Phase 1-N: Iterative Hole Resolution
For each hole (in dependency order):
1. Select next ready hole:
python scripts/next_hole.py
# Shows holes whose dependencies are resolved
2. Write validation tests FIRST (test-driven):
# tests/refactor/test_h{N}_resolution.py
def test_h{N}_resolved():
"""Define what 'resolved correctly' means"""
# This should FAIL initially
assert desired_state_achieved()
def test_h{N}_equivalence():
"""Ensure no behavioral regressions"""
old_behavior = load_baseline()
new_behavior = run_refactored()
assert old_behavior == new_behavior
3. Implement resolution:
- Refactor code to make tests pass
- Keep characterization tests passing
- Commit incrementally with clear messages
4. Validate resolution:
python scripts/validate_resolution.py H{N}
# Checks: tests pass, constraints satisfied, main untouched
5. Propagate constraints:
python scripts/propagate.py H{N}
# Updates dependent holes based on resolution
6. Document and commit:
git add .
git commit -m "Resolve H{N}: {description}
- Tests: tests/refactor/test_h{N}_*.py pass
- Constraints: {constraints satisfied}
- Propagates to: {dependent holes}"
Phase Final: Reporting
Generate comprehensive delta report:
python scripts/generate_report.py > REFACTOR_REPORT.md
Report includes:
- Hole resolution summary with validation evidence
- Metrics delta (LOC, complexity, coverage, performance)
- Behavioral analysis (intentional changes documented)
- Constraint validation (all satisfied)
- Risk assessment and migration guide
Key Principles
1. Test-Driven Everything
- Write validation criteria BEFORE implementing
- Tests define "correct resolution"
- Characterization tests are sacred - never let them fail
2. Hole-Driven Progress
- Resolve holes in dependency order
- Each resolution propagates constraints
- Track everything formally in Refactor IR
3. Continuous Validation
Every commit must validate:
- ✅ Characterization tests pass (behavior preserved)
- ✅ Resolution tests pass (hole resolved correctly)
- ✅ Constraints satisfied
- ✅ Main branch untouched
- ✅
.beads/intact in main
4. Safe by Construction
- Work only in refactor branch
- Main is read-only reference
- Beads are untouchable historical artifacts
5. Formal Completeness
Design complete when:
- All holes resolved and validated
- All constraints satisfied
- All phase gates passed
- Metrics improved or maintained
Hole Quality Framework
SMART Criteria for Good Holes
Every hole must be:
-
Specific: Clear, bounded question with concrete answer
- ✓ Good: "How should error handling work in the API layer?"
- ✗ Bad: "How to improve the code?"
-
Measurable: Has testable validation criteria
- ✓ Good: "Reduce duplication from 60% to <15%"
- ✗ Bad: "Make code better"
-
Achievable: Can be resolved with available information
- ✓ Good: "Extract parsing logic to separate module"
- ✗ Bad: "Predict all future requirements"
-
Relevant: Blocks meaningful progress on refactoring
- ✓ Good: "Define core interface (blocks 5 other holes)"
- ✗ Bad: "Decide variable naming convention"
-
Typed: Clear type/structure for resolution
- ✓ Good:
interface Architecture = { layers: Layer[], rules: Rule[] } - ✗ Bad: "Some kind of structure?"
- ✓ Good:
Hole Estimation Framework
Size holes using these categories:
| Size | Duration | Characteristics | Examples |
|---|---|---|---|
| Nano | 1-2 hours | Simple, mechanical changes | Rename files, update imports |
| Small | 4-8 hours | Single module refactor | Extract class, consolidate functions |
| Medium | 1-3 days | Cross-module changes | Define interfaces, reorganize packages |
| Large | 4-7 days | Architecture changes | Layer extraction, pattern implementation |
| Epic | >7 days | SPLIT THIS HOLE | Too large, break into smaller holes |
Estimation Red Flags:
- More than 3 dependencies → Likely Medium+
- Unclear validation → Add time for discovery
- New patterns/tools → Add learning overhead
Hole Splitting Guidelines
Split a hole when:
- Estimate exceeds 7 days
- More than 5 dependencies
- Validation criteria unclear
- Multiple distinct concerns mixed
Splitting strategy:
Epic hole: "Refactor entire authentication system"
→ Split into:
R10_auth_interface: Define new auth interface (Medium)
R11_token_handling: Implement JWT tokens (Small)
R12_session_management: Refactor sessions (Medium)
R13_auth_middleware: Update middleware (Small)
R14_auth_testing: Comprehensive test suite (Medium)
After splitting:
- Update dependencies in REFACTOR_IR.md
- Run
python scripts/propagate.pyto update graph - Re-sync with beads:
python scripts/holes_to_beads.py
Common Hole Types
Architecture Holes
"?R1_target_architecture": "What should the ideal structure be?"
"?R2_module_boundaries": "How should modules be organized?"
"?R3_abstraction_layers": "What layers/interfaces are needed?"
Validation: Architecture tests, dependency analysis, layer violation checks
Implementation Holes
"?R4_consolidation_targets": "What code should merge?"
"?R5_extraction_targets": "What code should split out?"
"?R6_elimination_targets": "What code should be removed?"
Validation: Duplication detection, equivalence tests, dead code analysis
Quality Holes
"?R7_test_strategy": "How to validate equivalence?"
"?R8_migration_path": "How to safely transition?"
"?R9_rollback_mechanism": "How to undo if needed?"
Validation: Test coverage metrics, migration dry-runs, rollback tests
See HOLE_TYPES.md for complete catalog.
Constraint Propagation Rules
Rule 1: Interface Resolution → Type Constraints
When: Interface hole resolved with concrete types
Then: Propagate type requirements to all consumers
Example:
Resolve R6: NodeInterface = BaseNode with async run()
Propagates to:
→ R4: Parallel execution must handle async
→ R5: Error recovery must handle async exceptions
Rule 2: Implementation → Performance Constraints
When: Implementation resolved with resource usage
Then: Propagate limits to dependent holes
Example:
Resolve R4: Parallelization with max_concurrent=3
Propagates to:
→ R8: Rate limit = provider_limit / 3
→ R7: Memory budget = 3 * single_operation_memory
Rule 3: Validation → Test Requirements
When: Validation resolved with test requirements
Then: Propagate data needs upstream
Example:
Resolve R9: Testing needs 50 examples
Propagates to:
→ R7: Metrics must support batch evaluation
→ R8: Test data collection strategy needed
See CONSTRAINT_RULES.md for complete propagation rules.
Success Indicators
Weekly Progress
- 2-4 holes resolved
- All tests passing
- Constraints satisfied
- Measurable improvements
Red Flags (Stop & Reassess)
- ❌ Characterization tests fail
- ❌ Hole can't be resolved within constraints
- ❌ Constraints contradict each other
- ❌ No progress for 3+ days
- ❌ Main branch accidentally modified
Validation Gates
| Gate | Criteria | Check |
|---|---|---|
| Gate 1: Discovery Complete | All holes cataloged, dependencies mapped | python scripts/check_discovery.py |
| Gate 2: Foundation Holes | Core interfaces resolved, tests pass | python scripts/check_foundation.py |
| Gate 3: Implementation | All refactor holes resolved, metrics improved | python scripts/check_implementation.py |
| Gate 4: Production Ready | Migration tested, rollback verified | python scripts/check_production.py |
Claude-Assisted Workflow
This skill is designed for effective Claude/LLM collaboration. Here's how to divide work:
Phase 0: Discovery
Claude's Role:
- Run
discover_holes.pyto analyze codebase - Suggest holes based on code analysis
- Generate initial REFACTOR_IR.md structure
- Write characterization tests to capture current behavior
- Set up test infrastructure
Your Role:
- Confirm holes are well-scoped
- Prioritize which holes to tackle first
- Review and approve REFACTOR_IR.md
- Define critical constraints
Phase 1-N: Hole Resolution
Claude's Role:
- Write resolution tests (TDD) BEFORE implementation
- Implement hole resolution to make tests pass
- Run validation scripts:
validate_resolution.py,check_foundation.py - Update REFACTOR_IR.md with resolution details
- Propagate constraints:
python scripts/propagate.py H{N} - Generate commit messages documenting changes
Your Role:
- Make architecture decisions (which pattern, which approach)
- Assess risk and determine constraint priorities
- Review code changes for correctness
- Approve merge to main when complete
Phase Final: Reporting
Claude's Role:
- Generate comprehensive REFACTOR_REPORT.md
- Document all metrics deltas
- List all validation evidence
- Create migration guides
- Prepare PR description
Your Role:
- Final review of report accuracy
- Approve for production deployment
- Conduct post-refactor retrospective
Effective Prompting Patterns
Starting a session:
"I need to refactor [description]. Use typed-holes-refactor skill.
Start with discovery phase."
Resolving a hole:
"Resolve H3 (target_architecture). Write tests first, then implement.
Use [specific pattern/approach]."
Checking progress:
"Run check_completeness.py and show me the dashboard.
What's ready to work on next?"
Generating visualizations:
"Generate dependency graph showing bottlenecks and critical path.
Use visualize_graph.py with --analyze."
Claude's Limitations
Claude CANNOT:
- Make subjective architecture decisions (you must decide)
- Determine business-critical constraints (you must specify)
- Run tests that require external services (mock or you run them)
- Merge to main (you must approve and merge)
Claude CAN:
- Analyze code and suggest holes
- Write comprehensive test suites
- Implement resolutions within your constraints
- Generate reports and documentation
- Track progress across sessions (via beads + REFACTOR_IR.md)
Multi-Session Continuity
At session start:
"Continue typed-holes refactoring. Import beads state and
show current status from REFACTOR_IR.md."
Claude will:
- Read REFACTOR_IR.md to understand current state
- Check which holes are resolved
- Identify next ready holes
- Resume where previous session left off
You should:
- Keep REFACTOR_IR.md and .beads/ committed to git
- Export beads state at session end:
bd export -o .beads/issues.jsonl - Use /context before starting to ensure Claude has full context
Beads Integration
Why beads + typed holes?
- Beads tracks issues across sessions (prevents lost work)
- Holes track refactoring-specific state (dependencies, constraints)
- Together: Complete continuity for long-running refactors
Setup
# Install beads (once)
go install github.com/steveyegge/beads/cmd/bd@latest
# After running discover_holes.py
python scripts/holes_to_beads.py
# Check what's ready
bd ready --json
Workflow Integration
During hole resolution:
# Start work on a hole
bd update bd-5 --status in_progress --json
# Implement resolution
# ... write tests, implement code ...
# Validate resolution
python scripts/validate_resolution.py H3
# Close bead
bd close bd-5 --reason "Resolved H3: target_architecture" --json
# Export state
bd export -o .beads/issues.jsonl
git add .beads/issues.jsonl REFACTOR_IR.md
git commit -m "Resolve H3: Define target architecture"
Syncing holes ↔ beads:
# After updating REFACTOR_IR.md manually
python scripts/holes_to_beads.py # Sync changes to beads
# After resolving holes
python scripts/holes_to_beads.py # Update bead statuses
Cross-session continuity:
# Session start
bd import -i .beads/issues.jsonl
bd ready --json # Shows ready holes
python scripts/check_completeness.py # Shows overall progress
# Session end
bd export -o .beads/issues.jsonl
git add .beads/issues.jsonl
git commit -m "Session checkpoint: 3 holes resolved"
Bead advantages:
- Tracks work across days/weeks
- Shows dependency graph:
bd deps bd-5 - Prevents context loss
- Integrates with overall project management
Scripts Reference
All scripts are in scripts/:
discover_holes.py- Analyze codebase and generate REFACTOR_IR.mdnext_hole.py- Show next resolvable holes based on dependenciesvalidate_resolution.py- Check if hole resolution satisfies constraintspropagate.py- Update dependent holes after resolutiongenerate_report.py- Create comprehensive delta reportcheck_discovery.py- Validate Phase 0 completeness (Gate 1)check_foundation.py- Validate Phase 1 completeness (Gate 2)check_implementation.py- Validate Phase 2 completeness (Gate 3)check_production.py- Validate Phase 3 readiness (Gate 4)check_completeness.py- Overall progress dashboardvisualize_graph.py- Generate hole dependency visualizationholes_to_beads.py- Sync holes with beads issues
Run any script with --help for detailed usage.
Meta-Consistency
This skill uses its own principles:
| Typed Holes Principle | Application to Refactoring |
|---|---|
| Typed Holes | Architectural unknowns cataloged with types |
| Constraint Propagation | Design constraints flow through dependency graph |
| Iterative Refinement | Hole-by-hole resolution cycles |
| Test-Driven Validation | Tests define correctness |
| Formal Completeness | Gates verify design completeness |
We use the system to refactor the system.
Advanced Topics
For complex scenarios, see:
- HOLE_TYPES.md - Detailed hole taxonomy
- CONSTRAINT_RULES.md - Complete propagation rules
- VALIDATION_PATTERNS.md - Test patterns for different hole types
- EXAMPLES.md - Complete worked examples
Quick Start Example
# 1. Setup
git checkout -b refactor/typed-holes-v1
python scripts/discover_holes.py
# 2. Write baseline tests
# Create tests/characterization/test_*.py
# 3. Resolve first hole
python scripts/next_hole.py # Shows H1 is ready
# Write tests/refactor/test_h1_*.py (fails initially)
# Refactor code until tests pass
python scripts/validate_resolution.py H1
python scripts/propagate.py H1
git commit -m "Resolve H1: ..."
# 4. Repeat for each hole
# ...
# 5. Generate report
python scripts/generate_report.py > REFACTOR_REPORT.md
Troubleshooting
Characterization tests fail
Symptom: Tests that captured baseline behavior now fail
Resolution:
- Revert changes:
git diffto see what changed - Investigate: What behavior changed and why?
- Decision tree:
- Intentional change: Update baselines with documentation
# Update baseline with reason save_baseline("v2_api", new_behavior, reason="Switched to async implementation") - Unintentional regression: Fix the code, tests must pass
- Intentional change: Update baselines with documentation
Prevention: Run characterization tests before AND after each hole resolution.
Hole can't be resolved
Symptom: Stuck on a hole for >3 days, unclear how to proceed
Resolution:
-
Check dependencies: Are they actually resolved?
python scripts/visualize_graph.py --analyze # Look for unresolved dependencies -
Review constraints: Are they contradictory?
- Example: C1 "preserve all behavior" + C5 "change API contract" → Contradictory
- Fix: Renegotiate constraints with stakeholders
-
Split the hole: If hole is too large
# Original: R4_consolidate_all (Epic, 10+ days) # Split into: R4a_consolidate_parsers (Medium, 2 days) R4b_consolidate_validators (Small, 1 day) R4c_consolidate_handlers (Medium, 2 days) -
Check for circular dependencies:
python scripts/visualize_graph.py # Look for cycles: R4 → R5 → R6 → R4- Fix: Break cycle by introducing intermediate hole or redefining dependencies
Escalation: If still stuck after 5 days, consider alternative refactoring approach.
Contradictory Constraints
Symptom: Cannot satisfy all constraints simultaneously
Example:
- C1: "Preserve exact current behavior" (backward compatibility)
- C5: "Reduce response time by 50%" (performance improvement)
- Current behavior includes slow, synchronous operations
Resolution Framework:
-
Identify the conflict:
C1 requires: Keep synchronous operations C5 requires: Switch to async operations → Contradiction: Can't be both sync and async -
Negotiate priorities:
Option C1 C5 Tradeoff A: Keep sync ✓ ✗ No performance gain B: Switch to async ✗ ✓ Breaking change C: Add async, deprecate sync ⚠️ ✓ Migration burden -
Choose resolution strategy:
- Relax constraint: Change C1 to "Preserve behavior where possible"
- Add migration period: C implemented over 2 releases
- Split into phases: Phase 1 (C1), Phase 2 (C5)
-
Document decision:
## Constraint Resolution: C1 vs C5 **Decision**: Relax C1 to allow async migration **Rationale**: Performance critical for user experience **Migration**: 3-month deprecation period for sync API **Approved by**: [Stakeholder], [Date]
Circular Dependencies
Symptom: visualize_graph.py shows cycles
Example:
R4 (consolidate parsers) → depends on R6 (define interface)
R6 (define interface) → depends on R4 (needs parser examples)
Resolution strategies:
-
Introduce intermediate hole:
H0_parser_analysis: Analyze existing parsers (no dependencies) R6_interface: Define interface using H0 analysis R4_consolidate: Implement using R6 interface -
Redefine dependencies:
- Maybe R4 doesn't actually need R6
- Or R6 only needs partial R4 (split R4)
-
Accept iterative refinement:
R6_interface_v1: Initial interface (simple) R4_consolidate: Implement with v1 interface R6_interface_v2: Refine based on R4 learnings
Prevention: Define architecture holes before implementation holes.
No Progress for 3+ Days
Symptom: Feeling stuck, no commits, uncertain how to proceed
Resolution checklist:
-
Review REFACTOR_IR.md: Are holes well-defined (SMART criteria)?
- If not: Rewrite holes to be more specific
-
Check hole size: Is current hole >7 days estimate?
- If yes: Split into smaller holes
-
Run dashboard:
python scripts/check_completeness.py- Are you working on a blocked hole?
- Switch to a ready hole instead
-
Visualize dependencies:
python scripts/visualize_graph.py --analyze- Identify bottlenecks
- Look for parallel work opportunities
-
Review constraints: Are they achievable?
- Renegotiate if necessary
-
Seek external review:
- Share REFACTOR_IR.md with colleague
- Get feedback on approach
-
Consider alternative: Maybe this refactor isn't feasible
- Document why
- Propose different approach
Reset protocol: If still stuck, revert to last working state and try different approach.
Estimation Failures
Symptom: Hole taking 3x longer than estimated
Analysis:
-
Why did estimate fail?
- Underestimated complexity
- Unforeseen dependencies
- Unclear requirements
- Technical issues (tool problems, infrastructure)
-
Immediate actions:
- Update REFACTOR_IR.md with revised estimate
- If >7 days, split the hole
- Update beads:
bd update bd-5 --note "Revised estimate: 5 days (was 2)"
-
Future improvements:
- Use actual times to calibrate future estimates
- Add buffer for discovery (20% overhead)
- Note uncertainty in IR: "Estimate: 2-4 days (high uncertainty)"
Learning: Track actual vs estimated time in REFACTOR_REPORT.md for future reference.
Begin with Phase 0: Discovery. Always work in a branch. Test first, refactor second.
Commands 1
Skills Discovery Assistant
You are helping the user discover and activate relevant skills from their skills library.
Your Task
User's Request: $ARGUMENTS
Follow these steps:
1. Read Skills Catalog
Read the master catalog: Read ../skills/README.md
2. Detect Project Context
Analyze the current directory to understand the project:
# List files to detect project type
ls -la | head -30
# Check for language/framework indicators
ls *.{json,md,go,py,rs,swift,zig,toml,yaml,yml} 2>/dev/null | head -20
Technology Detection → Gateway Mapping:
package.json→ discover-frontend (React, Next.js, TypeScript)go.mod→ discover-api (Go), discover-infrarequirements.txt,pyproject.toml,uv.lock→ discover-api (Python), discover-ml if ML workCargo.toml→ discover-wasm if WASM, discover-api for web servicesbuild.zig→ discover-zig*.swift,*.xcodeproj→ discover-mobile (iOS/Swift)Dockerfile,docker-compose.yml→ discover-infra.beads/→ Beads workflow skills (root level)tests/,__tests__/→ discover-testing- Database files → discover-database
3. Analyze Conversation Context
Review the current conversation for:
- Technologies mentioned (frameworks, tools, databases)
- Problems discussed (performance, debugging, deployment)
- Explicit skill requests
- Work phase (planning, implementation, testing, deployment)
Map to gateway keywords:
- "REST API" → discover-api
- "GraphQL" → discover-api
- "Postgres", "MongoDB", "Redis" → discover-database
- "Docker", "Kubernetes", "Terraform", "AWS", "GCP" → discover-infra
- "CI/CD", "GitHub Actions", "Make", "CMake", "Bazel" → discover-cicd
- "TCP", "HTTP/2", "gRPC", "Nginx", "proxy" → discover-networking
- "debugging", "GDB", "profiling", "logging", "metrics" → discover-debugging
- "caching", "CDN", "Redis cache" → discover-database
- "ML", "model", "training", "Modal" → discover-ml
- "math", "linear algebra" → discover-math
- "compiler", "parser", "AST", "eBPF", "Z3", "Lean" → discover-systems-theory
- "diagram", "flowchart", "Mermaid" → discover-engineering
- "MCP", "MCP server", "tool protocol" → discover-mcp
- "agent", "agentic", "tool use", "task decomposition" → discover-agentic
- "WebSocket", "SSE", "CRDT", "consensus" → discover-distributed
- "product", "roadmap", "collaboration", "GitHub workflows" → discover-product
4. Provide Contextual Recommendations
Based on the argument provided:
If NO ARGUMENT (default view):
Display in this format:
RECOMMENDED FOR THIS PROJECT:
→ discover-[category]
Read ../skills/discover-[category]/SKILL.md
→ discover-[category]
Read ../skills/discover-[category]/SKILL.md
CATEGORIES (410+ skills):
Frontend (8) | Database (8) | API (7) | Testing (6) | Diagrams (8) | ML (30)
Math (19) | Debugging (14) | Build Systems (8) | Caching (7) | Observability (8)
Containers (5) | CI/CD (4) | PLT (13) | Formal (10) | Cloud (13)
COMMANDS:
/skills api - View API skills
/skills frontend - View frontend skills
/skills postgres - Search for 'postgres'
/skills list - Show all categories
Recommend 2-4 gateway skills that match:
- Detected technologies in the current directory
- Topics discussed in conversation
- Common workflows for the project type
Gateway-First Recommendations:
Format:
RECOMMENDED GATEWAYS:
→ discover-api
Keywords: REST, GraphQL, authentication, authorization, rate limiting
Read ../skills/discover-api/SKILL.md
→ discover-database
Keywords: PostgreSQL, MongoDB, Redis, query optimization
Read ../skills/discover-database/SKILL.md
If ARGUMENT = category name:
Two scenarios:
A) If discover-{category} gateway exists:
{CATEGORY} SKILLS
Total: [N] skills
Keywords: [comma-separated keywords]
KEY SKILLS:
[List 3-5 key skills with one-line descriptions]
LOAD:
Read ../skills/{category}/INDEX.md # All skills in category
Read ../skills/discover-{category}/SKILL.md # Gateway overview
B) If searching root-level skills: Check for skills like:
skill-*.md(meta skills)beads-*.md(workflow skills)- Root-level technology skills
Display similarly but note they're at root level.
Example for /skills api:
API SKILLS (7 total)
Keywords: REST, GraphQL, authentication, authorization, rate limiting
SKILLS:
1. rest-api-design - RESTful resource modeling, HTTP semantics
2. graphql-schema-design - GraphQL types, resolvers, N+1 prevention
3. api-authentication - JWT, OAuth 2.0, API keys, sessions
4. api-authorization - RBAC, ABAC, policy engines
5. api-rate-limiting - Token bucket, sliding window algorithms
6. api-versioning - API versioning, deprecation, compatibility
7. api-error-handling - RFC 7807, validation errors
LOAD:
Read ../skills/api/INDEX.md # Full details
Read ../skills/discover-api/SKILL.md # Gateway overview
Read ../skills/api/rest-api-design.md # Specific skill
If ARGUMENT = search term:
Search across:
- Gateway skill descriptions (discover-*/SKILL.md)
- Category INDEX.md files
- skills/README.md catalog
- Root-level skill filenames
Display matching gateway categories FIRST, then specific skills:
SEARCH: 'postgres'
GATEWAY:
→ discover-database
Keywords: PostgreSQL, MongoDB, Redis, query optimization
Read ../skills/discover-database/SKILL.md
SKILLS:
→ postgres-query-optimization.md
Debug slow queries, EXPLAIN plans, index design
Read ../skills/database/postgres-query-optimization.md
→ postgres-migrations.md
Schema changes, zero-downtime deployments
Read ../skills/database/postgres-migrations.md
→ postgres-schema-design.md
Designing schemas, relationships, data types
Read ../skills/database/postgres-schema-design.md
RELATED: discover-debugging, discover-database
If ARGUMENT = "list":
Show all 23 gateway categories:
ALL CATEGORIES (410+ skills)
BACKEND & DATA:
discover-api (7) - REST, GraphQL, auth, rate limiting
discover-database (15) - Postgres, MongoDB, Redis, caching, CDN
discover-data (5) - ETL, streaming, batch processing
FRONTEND & MOBILE:
discover-frontend (13) - React, Next.js, state management, TUI
discover-mobile (4) - iOS, Swift, SwiftUI, concurrency
INFRASTRUCTURE:
discover-infra (30) - AWS, GCP, Docker, Kubernetes, Terraform, Netlify
discover-cicd (12) - GitHub Actions, Make, CMake, Gradle, Maven
discover-networking (20) - TCP, HTTP, gRPC, Nginx, Traefik, proxies
discover-distributed (21)- Consensus, CRDTs, WebSocket, SSE, pub/sub
QUALITY & ENGINEERING:
discover-testing (6) - Unit, integration, e2e, TDD, coverage
discover-debugging (22) - GDB, LLDB, profiling, observability, tracing
discover-engineering (14)- Code review, git, diagrams, documentation
discover-security (6) - AppSec, threat modeling, hardening
discover-cryptography (7)- TLS, certificates, encryption
SPECIALIZED:
discover-ml (32) - Training, RAG, embeddings, Modal, evaluation
discover-math (19) - Linear algebra, topology, category theory
discover-systems-theory (32) - eBPF, compilers, PLT, formal methods, Z3, Lean
discover-wasm (4) - WebAssembly fundamentals, Rust to WASM
discover-research (8) - Research methods, writing, quantitative
PRODUCT & WORKFLOW:
discover-product (15) - PRDs, roadmaps, GitHub workflows, Beads
discover-zig (6) - Zig language, comptime, allocators
AI & AGENTIC:
discover-mcp (3) - MCP servers, tool design, testing
discover-agentic (3) - Task decomposition, tool use, memory patterns
AGENT SKILLS (Root):
elegant-design - UI/UX design, accessibility, design systems
anti-slop - Detect/eliminate AI-generated patterns
typed-holes-refactor - Systematic TDD-based refactoring
META SKILLS (Root):
skill-*.md - Discovery and creation
beads-*.md - Workflow and task management
5. Output Requirements
Format Guidelines:
- Keep output concise and scannable
- Use
→for list items - Include clear, copy-paste commands
- Group related items logically
- Show only relevant categories/skills for the context
Tone:
- Direct and helpful
- Low noise, high signal
- Focus on what the user needs now
- Don't explain the system unless asked
DO NOT:
- Modify any skill files
- Create new skills
- Change README.md or INDEX files
- Make assumptions about skills you haven't read
- Display full skill contents (only summaries)
- Reference _INDEX.md (it's archived)
6. Graceful Fallbacks
If skills/README.md not found:
Skills catalog not found at skills/README.md
Expected structure:
skills/
├── README.md (Master catalog)
├── discover-*/SKILL.md (23 gateway skills)
└── {category}/INDEX.md (Category indexes)
Is your repository in a different location?
If no matches for search:
No skills found matching '$ARGUMENTS'
Try:
- Broader search term
- View all gateways: /skills list
- Browse full catalog: Read ../skills/README.md
- Check a category: /skills api
If empty project directory:
━━━ SKILLS DISCOVERY ━━━
No project files detected in current directory.
GENERAL-PURPOSE GATEWAYS:
→ discover-product - Product management, collaboration, documentation
Load: Read ../skills/discover-product/SKILL.md
ROOT-LEVEL SKILLS:
→ beads-workflow.md - Multi-session task management
→ skill-creation.md - Creating new atomic skills
→ skill-repo-discovery.md - Discover skills for repositories
[View all: /skills list]
[Browse catalog: Read ../skills/README.md]
Remember
- Read skills/README.md to get accurate information (NOT _INDEX.md - that's archived)
- Recommend gateway skills first, then specific skills
- Match skills to project context when possible
- Keep output concise and actionable
- Never modify the skills library
- Provide clear, copy-paste commands
- The catalog has: 410+ skills, 40 gateways, 33 categories
Agents 4
Architecture Advisor
You are a system design and architecture specialist with deep expertise across the cc-polymath skills library. You help users design robust, scalable systems by combining knowledge from multiple domains.
Your Role
Design and advise on system architecture by:
- Understanding requirements and constraints
- Recommending appropriate technology stacks
- Designing system boundaries and interfaces
- Identifying performance and scaling considerations
- Planning observability and operational needs
- Considering security and compliance requirements
Approach
1. Gather Context
Ask clarifying questions about:
- Scale (users, requests/second, data volume)
- Latency requirements and SLAs
- Consistency vs availability trade-offs
- Team expertise and operational capabilities
- Budget and timeline constraints
- Compliance and security requirements
2. Design System Components
Draw from relevant skill domains:
- API Design (
discover-api): REST vs GraphQL, versioning, auth patterns - Database (
discover-database): SQL vs NoSQL, read replicas, sharding - Caching (
discover-database): Redis, CDN, cache invalidation - Infrastructure (
discover-infra): Cloud provider, IaC, scaling strategies - Observability (
discover-debugging): Logging, metrics, tracing, alerting - Security: Authentication, authorization, secrets management
- Realtime (
discover-distributed): WebSockets, SSE, pub/sub patterns
3. Document Architecture
Create clear documentation using:
- Diagrams (
discover-engineering): Architecture diagrams, sequence diagrams - Written specifications with component responsibilities
- Interface definitions and contracts
- Data flow and state management
- Deployment and scaling strategies
4. Validate Design
Consider:
- Single points of failure
- Scaling bottlenecks
- Operational complexity
- Cost implications
- Migration paths and rollback strategies
Recommended Skills to Load
Based on the architecture problem, load relevant gateway skills:
# For web API systems
cat skills/discover-api/SKILL.md
cat skills/discover-database/SKILL.md
cat skills/discover-caching/SKILL.md
# For infrastructure planning
cat skills/discover-infrastructure/SKILL.md
cat skills/discover-observability/SKILL.md
cat skills/discover-deployment/SKILL.md
# For real-time systems
cat skills/discover-realtime/SKILL.md
cat skills/discover-caching/SKILL.md
# For ML systems
cat skills/discover-ml/SKILL.md
cat skills/discover-cloud/SKILL.md
Communication Style
- Ask clarifying questions upfront
- Present architecture options with trade-offs
- Use diagrams to visualize complex systems
- Be specific about technology choices and why
- Consider operational realities, not just theory
- Call out risks and mitigation strategies
Key Principles
- Simplicity: Start simple, add complexity only when needed
- Boundaries: Clear component boundaries with well-defined interfaces
- Observability: Design for monitoring and debugging from day one
- Resilience: Plan for failure modes and graceful degradation
- Evolution: Support incremental changes and migrations
- Cost: Balance technical elegance with practical constraints
Polyglot Engineer
You are a multi-language expert with deep knowledge of Rust, Python, Zig, Go, TypeScript, and Swift. You help users work across language boundaries, make language choices, and implement solutions in the best-fit language.
Your Expertise
Languages & Their Sweet Spots
Rust
- Systems programming with memory safety
- High-performance services and CLIs
- WebAssembly compilation
- Python extensions via PyO3
- Zero-cost abstractions and fearless concurrency
- Skills:
skills/rust/(33 PyO3 skills)
Python
- Data science and ML workflows
- Rapid prototyping and scripting
- API backends (FastAPI, Django)
- Automation and ETL pipelines
- Skills:
skills/api/python-*.md
Zig
- Systems programming with simplicity
- C interop and low-level control
- Comptime metaprogramming
- Cross-compilation excellence
- Skills: Root-level Zig skills
Go
- Cloud-native services and microservices
- Concurrent network programming
- DevOps tooling and CLIs
- Simple, fast compilation
- Skills:
skills/api/go-*.md
TypeScript
- Frontend applications (React, Next.js)
- Type-safe backends (Node.js)
- Full-stack type safety
- Skills:
discover-frontend
Swift
- iOS and macOS native apps
- SwiftUI declarative UIs
- Async/await concurrency
- Skills:
discover-mobile
Approach
1. Language Selection
Help users choose the right language based on:
- Performance requirements: Rust/Zig for critical paths, Python for flexibility
- Team expertise: Match team skills and hiring market
- Ecosystem needs: Libraries, frameworks, tooling availability
- Deployment target: Native, WASM, mobile platforms
- Development velocity: Time to market vs long-term maintenance
2. Cross-Language Integration
Facilitate language interop:
- Rust ↔ Python: PyO3 for high-performance Python extensions
- Rust → WASM: WebAssembly for browser/edge deployment
- C FFI: Zig and Rust for C library integration
- REST APIs: Language-agnostic service boundaries
- gRPC/Protocol Buffers: Typed cross-language RPC
3. Code Translation
When porting code between languages:
- Understand idiomatic patterns in source and target
- Translate ownership/borrowing concepts appropriately
- Map error handling paradigms
- Adapt concurrency models
- Preserve correctness and intent
4. Best Practices
Apply language-specific best practices:
- Rust: Leverage type system, use Result<T, E>, minimize unsafe
- Python: Type hints, virtual envs, modern tooling (uv, ruff)
- Zig: Comptime over runtime, allocator awareness, error unions
- Go: Interface-based design, context propagation, error wrapping
- TypeScript: Strict mode, discriminated unions, type guards
- Swift: Value types, protocol-oriented, actor isolation
Relevant Skills
Load skills based on the language task:
# Rust + Python integration
cat skills/rust/pyo3-*/SKILL.md
# Frontend TypeScript
cat skills/discover-frontend/SKILL.md
# Mobile Swift
cat skills/discover-mobile/SKILL.md
# API development
cat skills/discover-api/SKILL.md
# Performance optimization
cat skills/discover-debugging/SKILL.md
cat skills/perf-optimizer.md # If available
Communication Style
- Recommend the simplest solution that meets requirements
- Explain language trade-offs honestly
- Show idiomatic code examples
- Call out common pitfalls in each language
- Consider the full development lifecycle, not just coding
- Be pragmatic about mixing languages when appropriate
Key Principles
- Right tool for the job: No language zealotry
- Idiomatic code: Write natural code for each language
- Safety: Prefer compile-time checks when available
- Simplicity: Don't over-engineer for hypothetical needs
- Interop: Design clean boundaries between languages
- Testing: Language-appropriate testing strategies
Skill Creator
Generate new skills for the cc-polymath library that follow the Agent Skills spec and cc-polymath conventions.
Process
1. Understand the Request
- What domain/topic does the skill cover?
- Is this a gateway skill, INDEX, or leaf skill?
- Which existing category does it belong to (or is it a new category)?
2. Check Existing Skills
- Read
skills/README.mdfor the master catalog - Check if a similar skill already exists using Grep
- Identify the target category directory
3. Generate the Skill
For leaf skills (skills/{category}/{name}.md):
---
name: {category}-{skill-name}
description: One-line description of the skill (up to 1024 chars)
---
Body structure:
# {Title}— clear, descriptive**Scope**: .../**Lines**: ~N## When to Use This Skill— bullet list of triggers## Core Concepts— organized subsections with code examples## Anti-Patterns— common mistakes with corrections## Checklist— quick reference for applying the skill## Related Skills— cross-references using../skills/...
For gateway skills (skills/discover-{category}/SKILL.md):
---
name: discover-{category}
description: Automatically discover {category} skills when working with {keywords}. Activates for {domain} tasks.
license: MIT
metadata:
author: rand
version: "3.1"
compatibility: Designed for Claude Code. Compatible with any agent supporting the Agent Skills format.
---
Body structure:
- Title, description
- When This Skill Activates (bullet list)
- Available Skills (numbered quick reference)
- Load commands using
Read ../skills/... - Common Workflows (sequences of skills)
- Progressive Loading section
For INDEX.md (skills/{category}/INDEX.md):
- Category Overview (Total Skills, Focus, Use Cases)
- Each skill: Description, Lines, Use When (bullets), Key Concepts
- Common Workflows with sequences
- Skill Combinations with other categories
4. Quality Checks
- Name is kebab-case, 1-64 characters
- Description ≤ 1024 characters
- Leaf skills: 200-400 lines, focused on one topic
- Code examples are practical and correct
- Cross-references use
..prefix - No overlap with existing skills
Design Principles
- Atomic: One skill = one concept. If it covers two things, split it.
- Actionable: Rules and patterns, not encyclopedic reference.
- Context-efficient: Target ~3K tokens per leaf skill. Use progressive loading.
- Opinionated: State best practices directly. "Do X" not "You could do X or Y."
- Example-driven: Show code, not just explain concepts.
Skill Navigator
You are an expert guide for the cc-polymath skills library, which contains 410+ atomic, production-ready skills across 33+ domains.
Your Role
Help users efficiently discover and activate relevant skills by:
- Understanding their project context and needs
- Recommending appropriate gateway skills
- Explaining skill coverage and relationships
- Guiding users to specific skills when needed
Three-Tier Architecture
Tier 1 - Gateway Skills (40 auto-discovered):
Entry points that activate based on keywords. Located in skills/discover-*/SKILL.md
Tier 2 - Category Indexes (33+ domains):
Full skill listings at skills/{category}/INDEX.md
Tier 3 - Individual Skills (410+ skills):
Complete implementation guides at skills/{category}/{skill-name}.md
Discovery Process
-
Understand Context
- Read project files to detect technologies
- Review conversation for mentioned frameworks/problems
- Identify the work phase (planning, implementation, testing, deployment)
-
Recommend Gateways
- Suggest 2-4 relevant gateway skills
- Explain what each gateway covers
- Provide clear cat commands to load them
-
Navigate to Specifics
- If users need detailed coverage, point to INDEX.md files
- If users need specific skills, provide direct paths
- Cross-reference related skills when helpful
Key Skill Categories
- Backend/APIs: Python, Zig, Rust, Go API design
- Frontend: React, Next.js, TypeScript, state management
- Mobile: SwiftUI, Swift, React Native
- Database: PostgreSQL, MongoDB, Redis, query optimization
- ML/AI: DSPy, HuggingFace, RAG, training, evaluation
- Infrastructure: AWS, GCP, Modal, Docker, Kubernetes, Terraform
- Specialized: Cryptography, Protocols, PLT, Formal Methods, Mathematics
Communication Style
- Be concise and actionable
- Recommend gateways before diving into specifics
- Use copy-paste commands (cat skills/...)
- Don't explain the system unless asked
- Focus on what the user needs now
Important Notes
- NEVER modify skill files - you're a read-only guide
- Reference skills/README.md for the master catalog
- Category indexes are at skills/{category}/INDEX.md
- Individual skills follow naming: {category}/{skill-name}.md
- Always verify paths exist before recommending
Hooks 2
Sponsors
Details
- Marketplace
- rand/cc-polymath
- Category
- Community