rand avatar

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-marketplace

Run it inside Claude Code after adding the marketplace with /plugin marketplace add rand/cc-polymath.

Contents

Discovered from source

Skills 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 patterns
  • references/code-patterns.md - Programming slop patterns
  • references/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 represents
  • result → name what the result contains
  • temp → name what you're temporarily storing
  • item → 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 .backup file when overwriting
  • Preview mode shows changes before applying
  • Preserves content meaning (non-aggressive mode)

Best Practices

Prevention Over Cure

When creating content:

  1. Write with specific audience in mind
  2. Use concrete examples over abstractions
  3. Lead with the point, skip preambles
  4. Choose words for precision, not impression
  5. 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

  1. Detect - Run detection scripts or manual review
  2. Analyze - Understand which patterns are truly problems
  3. Clean - Apply automated cleanup where safe
  4. Review - Manually verify changes maintain meaning
  5. 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

  1. Create initial content
  2. Run slop detection
  3. Apply automated cleanup
  4. Manual review and refinement
  5. 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:

  1. agentic-task-decomposition - Breaking complex goals into agent-executable steps, dependency graphs, re-planning
  2. agentic-tool-use - Function calling patterns, parallel tool use, error handling, tool selection heuristics
  3. 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

  1. Auto-activation: This skill loads automatically when Claude Code detects agentic workflow tasks
  2. Browse skills: Run Read ../agentic/INDEX.md for full category overview
  3. Load specific skills: Use commands above to load individual skills
  4. Follow workflows: Use recommended sequences for common agentic patterns
  5. 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:

  1. rest-api-design - RESTful resource modeling, HTTP semantics, URL conventions
  2. graphql-schema-design - GraphQL types, resolvers, N+1 problem prevention
  3. api-authentication - JWT, OAuth 2.0, API keys, session management
  4. api-authorization - RBAC, ABAC, policy engines, permission systems
  5. api-rate-limiting - Token bucket, sliding window, rate limiting algorithms
  6. api-versioning - API versioning, deprecation, backward compatibility
  7. api-error-handling - RFC 7807 errors, validation, standardized responses
  8. 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

  1. Auto-activation: This skill loads automatically when Claude Code detects API-related work
  2. Browse skills: Run Read ../api/INDEX.md for full category overview
  3. Load specific skills: Use bash commands above to load individual skills
  4. Follow workflows: Use recommended sequences for common API patterns
  5. 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):

  1. cd-deployment-patterns
  2. ci-optimization
  3. ci-security
  4. 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

  1. Auto-activation: This skill loads automatically when Claude Code detects cicd work
  2. Browse skills: Run Read ../cicd/INDEX.md for full category overview
  3. 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:

  1. pki-fundamentals - PKI, certificate authorities, X.509, trust chains
  2. tls-configuration - TLS 1.2/1.3 setup, cipher suites, server config
  3. ssl-legacy - SSL 2.0/3.0, TLS 1.0/1.1, deprecation, migration
  4. sni-routing - Server Name Indication, multi-domain TLS hosting
  5. certificate-management - Certificate lifecycle, Let's Encrypt, automation
  6. cryptography-basics - Symmetric/asymmetric encryption, hashing, signing
  7. 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

  1. Auto-activation: This skill loads automatically when Claude Code detects cryptography work
  2. Browse skills: Run Read ../cryptography/INDEX.md for full category overview
  3. 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:

  1. batch-processing - Orchestrating complex data pipelines with dependencies
  2. data-validation - Validating data schema before processing
  3. dataflow-coordination - Coordination patterns for distributed dataflow systems
  4. differential-dataflow - Differential computation for incremental updates and efficient joins
  5. etl-patterns - Designing data extraction from multiple sources
  6. pipeline-orchestration - Coordinating complex multi-step data workflows
  7. stream-processing - Processing real-time event streams (Kafka, Flink)
  8. streaming-aggregations - Windowing, sessionization, time-series aggregation
  9. 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

  1. Auto-activation: This skill loads automatically when Claude Code detects data work
  2. Browse skills: Run Read ../data/INDEX.md for full category overview
  3. 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):

  1. postgres-schema-design - Schema design, relationships, data types, normalization
  2. postgres-query-optimization - EXPLAIN plans, indexes, slow query debugging
  3. postgres-migrations - Schema changes, zero-downtime, rollback strategies
  4. mongodb-document-design - Document modeling, embedding vs referencing
  5. redis-data-structures - Caching, sessions, rate limiting, leaderboards
  6. database-connection-pooling - Pool configuration, debugging exhaustion
  7. orm-patterns - ORM best practices, N+1 prevention, eager loading
  8. 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 schemas
  • postgres-query-optimization.md - Optimize complex queries
  • postgres-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 projects
  • database-connection-pooling.md - All databases need this
  • orm-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

  1. Auto-activation: This skill loads automatically when Claude Code detects database work
  2. Browse skills: Run Read ../database/INDEX.md for full category overview
  3. Load specific skills: Use bash commands above to load individual skills
  4. Follow workflows: Use recommended sequences for common patterns
  5. Decision support: Start with database-selection.md for 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):

  1. browser-devtools
  2. concurrency-debugging
  3. container-debugging
  4. core-dump-analysis
  5. crash-debugging
  6. distributed-systems-debugging
  7. gdb-fundamentals
  8. lldb-macos-debugging
  9. memory-leak-debugging
  10. network-debugging
  11. performance-profiling
  12. production-debugging
  13. python-debugging
  14. 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

  1. Auto-activation: This skill loads automatically when Claude Code detects debugging work
  2. Browse skills: Run Read ../debugging/INDEX.md for full category overview
  3. 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)

  1. cap-theorem - CAP theorem, consistency vs availability trade-offs
  2. consensus-raft - RAFT consensus, leader election, log replication
  3. consensus-paxos - Paxos consensus, Basic/Multi-Paxos
  4. crdt-fundamentals - Conflict-free Replicated Data Types basics
  5. crdt-types - Specific CRDT implementations (LWW, OR-Set, RGA)
  6. dotted-version-vectors - Compact causality, sibling management
  7. interval-tree-clocks - Dynamic causality, fork/join
  8. vector-clocks - Causality tracking, happens-before
  9. logical-clocks - Lamport clocks, logical time
  10. eventual-consistency - Consistency levels, quorums, BASE
  11. conflict-resolution - LWW, multi-value, semantic resolution
  12. replication-strategies - Primary-backup, multi-primary, chain, quorum
  13. partitioning-sharding - Hash/range/consistent hashing, rebalancing
  14. distributed-locks - Redlock, ZooKeeper locks, fencing tokens
  15. leader-election - Bully, ring, consensus-based election
  16. gossip-protocols - Epidemic protocols, failure detection
  17. probabilistic-data-structures - Bloom filters, HyperLogLog, Count-Min Sketch

Realtime (4 skills)

  1. websocket-implementation - WebSocket connections, protocols, scaling
  2. server-sent-events - SSE for server-to-client streaming
  3. pubsub-patterns - Publish/subscribe architectures
  4. 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:

  1. code-review - PR reviews, feedback, automation
  2. code-quality - SOLID principles, metrics, code smells
  3. refactoring-patterns - Safe refactoring techniques
  4. test-driven-development - TDD, red-green-refactor
  5. domain-driven-design - DDD patterns, bounded contexts
  6. functional-programming - FP principles, immutability
  7. design-patterns - GoF patterns, when to use
  8. technical-debt - Identifying and managing debt
  9. pair-programming - Pairing techniques, mob programming
  10. 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

  1. Auto-activation: This skill loads automatically when Claude Code detects engineering work
  2. Browse skills: Run Read ../engineering/INDEX.md for full category overview
  3. 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):

  1. react-component-patterns - Component design, composition, hooks, performance
  2. nextjs-app-router - Next.js 14+ App Router, Server Components, routing
  3. react-state-management - Context, Zustand, Redux Toolkit patterns
  4. react-data-fetching - SWR, React Query, Server Actions, data patterns
  5. react-form-handling - React Hook Form, Zod validation, form patterns
  6. web-accessibility - WCAG 2.1 AA compliance, ARIA, keyboard navigation
  7. frontend-performance - Bundle optimization, Core Web Vitals, code splitting
  8. nextjs-seo - SEO with Next.js, metadata API, structured data
  9. web-workers - Web Workers API, message passing, offloading computation
  10. browser-concurrency - Service Workers, SharedWorkers, Worklets, PWAs
  11. 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

  1. Auto-activation: This skill loads automatically when Claude Code detects frontend work
  2. Browse skills: Run Read ../frontend/INDEX.md for full category overview
  3. Load specific skills: Use bash commands above to load individual skills
  4. Follow workflows: Use recommended sequences for common patterns
  5. 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)

  1. aws-lambda-functions - Lambda development, triggers, optimization
  2. aws-api-gateway - REST/HTTP/WebSocket APIs, authorization
  3. aws-databases - RDS, DynamoDB, ElastiCache, Aurora
  4. aws-iam-security - IAM, Cognito, Secrets Manager, KMS
  5. aws-storage - S3, EBS, EFS, Glacier, lifecycle policies
  6. aws-ec2-compute - EC2, Auto Scaling, Load Balancing
  7. aws-networking - VPC, security groups, Route53, CloudFront
  8. gcp-serverless - Cloud Functions, Cloud Run, App Engine
  9. gcp-compute - Compute Engine, GKE, autoscaling
  10. gcp-databases - Cloud SQL, Firestore, Bigtable, Spanner
  11. gcp-storage - Cloud Storage, Persistent Disk, Filestore
  12. gcp-iam-security - IAM, service accounts, Secret Manager
  13. gcp-networking - VPC, firewall, Cloud DNS, Cloud CDN

Infrastructure (6 skills)

  1. terraform-patterns - Modules, state, workspaces, best practices
  2. kubernetes-basics - Pods, deployments, services, configuration
  3. cloudflare-workers - Edge functions, KV storage, Durable Objects
  4. infrastructure-security - Network security, secrets, hardening
  5. cost-optimization - Cloud cost reduction strategies
  6. aws-serverless - Serverless architecture patterns

Deployment (6 skills)

  1. heroku-deployment - Deployment, dynos, buildpacks
  2. heroku-addons - Databases, caching, monitoring addons
  3. heroku-troubleshooting - Common issues and debugging
  4. netlify-deployment - Build, deploy, previews, CDN
  5. netlify-functions - Serverless functions on Netlify
  6. netlify-optimization - Performance, caching, edge

Containers (5 skills)

  1. dockerfile-optimization - Multi-stage builds, layer caching
  2. docker-compose-development - Multi-service local development
  3. container-networking - Bridge, overlay, service discovery
  4. container-security - Image scanning, runtime security
  5. 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:

  1. abstract-algebra
  2. category-theory-foundations
  3. differential-equations
  4. linear-algebra-computation
  5. number-theory
  6. numerical-methods
  7. optimization-algorithms
  8. probability-statistics
  9. set-theory
  10. topology-algebraic
  11. 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

  1. Auto-activation: This skill loads automatically when Claude Code detects math work
  2. Browse skills: Run Read ../math/INDEX.md for full category overview
  3. 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:

  1. mcp-server-fundamentals - Architecture, transports, tools/resources/prompts primitives, SDK setup
  2. mcp-tool-design - Tool naming, schemas, error handling, annotations, progressive disclosure
  3. 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):

  1. custom-llm-evaluation
  2. diffusion-finetuning
  3. diffusion-model-basics
  4. dspy-assertions
  5. dspy-evaluation
  6. dspy-modules
  7. dspy-optimizers
  8. dspy-rag
  9. dspy-setup
  10. dspy-signatures
  11. graph-rag
  12. hierarchical-rag
  13. hybrid-search-rag
  14. llm-as-judge
  15. llm-benchmarks-evaluation
  16. llm-dataset-preparation
  17. llm-evaluation-frameworks
  18. llm-model-routing
  19. llm-model-selection
  20. lora-peft-techniques
  21. multi-model-orchestration
  22. rag-evaluation-metrics
  23. rag-reranking-techniques
  24. stable-diffusion-deployment
  25. 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

  1. Auto-activation: This skill loads automatically when Claude Code detects ml work
  2. Browse skills: Run Read ../ml/INDEX.md for full category overview
  3. 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:

  1. react-native-native-modules
  2. react-native-navigation
  3. react-native-performance
  4. 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

  1. Auto-activation: This skill loads automatically when Claude Code detects mobile work
  2. Browse skills: Run Read ../mobile/INDEX.md for full category overview
  3. 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):

  1. mosh-resilient-ssh
  2. mtls-implementation
  3. nat-traversal
  4. network-resilience-patterns
  5. 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

  1. Auto-activation: This skill loads automatically when Claude Code detects networking work
  2. Browse skills: Run Read ../networking/INDEX.md for full category overview
  3. 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):

  1. prd-requirements-gathering
  2. prd-structure-templates
  3. prd-technical-specifications
  4. 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

  1. Auto-activation: This skill loads automatically when Claude Code detects product work
  2. Browse skills: Run Read ../product/INDEX.md for full category overview
  3. 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

  1. Start with design: Load research-design first when planning new studies
  2. Method-specific loading: Load only the method skill you need (quant OR qual)
  3. Progressive addition: Add skills as you progress through research phases
  4. Unload when done: Unload skills from completed phases to manage context
  5. 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:

  1. authentication - Authentication patterns (JWT, OAuth2, sessions, MFA, password security)
  2. authorization - Access control (RBAC, ABAC, policy engines, permissions)
  3. input-validation - Input validation and sanitization (SQL injection, XSS, command injection)
  4. security-headers - HTTP security headers (CSP, HSTS, X-Frame-Options, CORS)
  5. vulnerability-assessment - Security testing (OWASP Top 10, scanning tools, pentesting)
  6. 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

  1. Auto-activation: This skill loads automatically when Claude Code detects security-related work
  2. Browse skills: Run Read ../security/INDEX.md for full category overview
  3. Load specific skills: Use bash commands above to load individual skills
  4. Follow workflows: Use recommended sequences for common security patterns
  5. 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)

  1. ebpf-fundamentals - eBPF programs, verifier, maps
  2. ebpf-networking - XDP, TC, socket filtering
  3. ebpf-security-monitoring - LSM hooks, syscall tracing
  4. ebpf-tracing-observability - kprobes, tracepoints, profiling

Information Retrieval (5 skills)

  1. ir-search-fundamentals - Indexing, tokenization, TF-IDF, BM25
  2. ir-query-understanding - Query parsing, expansion, intent
  3. ir-ranking-reranking - Learning to rank, cross-encoders
  4. ir-vector-search - Embeddings, ANN, HNSW, FAISS
  5. ir-recommendation-systems - Collaborative/content-based filtering

Programming Language Theory (13 skills)

  1. type-systems - Type theory, inference, polymorphism
  2. lambda-calculus - Lambda calculus, reduction, Church encodings
  3. curry-howard - Propositions as types, proofs as programs
  4. dependent-types - Dependent types, refinement types
  5. operational-semantics - Small-step, big-step semantics
  6. program-verification - Hoare logic, invariants, correctness
  7. structure-editors - Structural editing, projectional editors
  8. hazelnut-calculus - Hazelnut typed holes calculus
  9. live-programming-holes - Live programming with typed holes
  10. typed-holes-foundations - Typed holes theory and foundations
  11. typed-holes-interaction - Interactive typed hole filling
  12. typed-holes-llm - LLM-powered typed hole completion
  13. typed-holes-semantics - Typed holes formal semantics

Formal Methods (10 skills)

  1. z3-solver-basics - Z3 SMT solver, constraints, assertions
  2. sat-solving-strategies - SAT solving, DPLL, CDCL
  3. smt-theory-applications - SMT theories, bitvectors, arrays
  4. lean-proof-basics - Lean 4 basics, tactics, terms
  5. lean-tactics - Advanced Lean tactics and automation
  6. lean-theorem-proving - Theorem proving patterns in Lean
  7. lean-mathlib4 - Mathlib4 library usage
  8. csp-modeling - Constraint satisfaction problems
  9. constraint-propagation - Arc consistency, propagation
  10. 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:

  1. e2e-testing
  2. integration-testing
  3. performance-testing
  4. test-coverage-strategy
  5. test-driven-development
  6. 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

  1. Auto-activation: This skill loads automatically when Claude Code detects testing work
  2. Browse skills: Run Read ../testing/INDEX.md for full category overview
  3. 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:

  1. wasm-browser-integration
  2. wasm-fundamentals
  3. wasm-rust-toolchain
  4. 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

  1. Auto-activation: This skill loads automatically when Claude Code detects wasm work
  2. Browse skills: Run Read ../wasm/INDEX.md for full category overview
  3. 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:

  1. zig-build-system
  2. zig-c-interop
  3. zig-memory-management
  4. zig-package-management
  5. zig-project-setup
  6. 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

  1. Auto-activation: This skill loads automatically when Claude Code detects zig work
  2. Browse skills: Run Read ../zig/INDEX.md for full category overview
  3. 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:

  1. Observe - What information does the user need?
  2. Orient - How do they make sense of it?
  3. Decide - What choices are available?
  4. 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:

  1. Search shadcn/ui first (https://ui.shadcn.com)
  2. Check daisyUI (https://daisyui.com)
  3. Explore HeroUI (https://heroui.com)
  4. 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, loading
  • foundation/colors-and-spacing.md - Color palettes, spacing systems, dark mode
  • foundation/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.md when building conversational interfaces
  • Covers message states, streaming, auto-scrolling, markdown rendering

Terminals & Code Display:

  • Read interactive/terminals-and-code.md for terminal emulators, syntax highlighting, semantic highlighting
  • Covers ANSI colors, Shiki integration, copy buttons, line highlighting

Streaming & Loading:

  • Read interactive/streaming-and-loading.md for progressive loading, streaming text, optimistic updates
  • Covers skeleton screens, progress indicators, loading hierarchies

Diffs & Logs:

  • Read interactive/diffs-and-logs.md for 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.md for 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.md for Core Web Vitals optimization
  • Lazy load, code split, optimize images, measure with Lighthouse

Test & Refine:

  • Read implementation/testing-and-qa.md for 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

  1. shadcn/ui (https://ui.shadcn.com) - PRIMARY CHOICE

    • Excellent accessibility defaults
    • Radix UI primitives
    • Tailwind-based, customizable
    • Copy-paste into project
  2. daisyUI (https://daisyui.com)

    • Semantic component names
    • Tailwind plugin
    • Rapid prototyping
  3. 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:

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):

  1. Start with foundation (read foundation files)
  2. Use design system components
  3. Test and refine

For complex interfaces (multiple features, interactive elements):

  1. Map flows and create diagrams
  2. Establish foundation (read foundation files)
  3. Build one feature at a time (read relevant interactive files)
  4. Test each feature before moving to next
  5. Optimize and polish (read implementation files)

For developer tools or technical interfaces:

  1. Map OODA loops carefully
  2. Read ALL interactive files (chat, terminals, code, streaming, diffs, logs)
  3. Focus on keyboard navigation and performance
  4. Test with actual technical content

Getting Help

If unsure where to start:

  1. Read the philosophy section above
  2. Follow the Design Process Workflow
  3. Reference specific guides as needed

If design feels off:

  1. Check against principles (clarity, consistency, performance)
  2. Review anti-patterns list
  3. Study inspiration sites
  4. Test with real users

If implementation is slow:

  1. Use design system components first
  2. Don't build what exists
  3. Focus on one feature at a time
  4. 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?"

Hole Estimation Framework

Size holes using these categories:

SizeDurationCharacteristicsExamples
Nano1-2 hoursSimple, mechanical changesRename files, update imports
Small4-8 hoursSingle module refactorExtract class, consolidate functions
Medium1-3 daysCross-module changesDefine interfaces, reorganize packages
Large4-7 daysArchitecture changesLayer extraction, pattern implementation
Epic>7 daysSPLIT THIS HOLEToo 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:

  1. Estimate exceeds 7 days
  2. More than 5 dependencies
  3. Validation criteria unclear
  4. 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.py to 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

GateCriteriaCheck
Gate 1: Discovery CompleteAll holes cataloged, dependencies mappedpython scripts/check_discovery.py
Gate 2: Foundation HolesCore interfaces resolved, tests passpython scripts/check_foundation.py
Gate 3: ImplementationAll refactor holes resolved, metrics improvedpython scripts/check_implementation.py
Gate 4: Production ReadyMigration tested, rollback verifiedpython 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.py to 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.md
  • next_hole.py - Show next resolvable holes based on dependencies
  • validate_resolution.py - Check if hole resolution satisfies constraints
  • propagate.py - Update dependent holes after resolution
  • generate_report.py - Create comprehensive delta report
  • check_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 dashboard
  • visualize_graph.py - Generate hole dependency visualization
  • holes_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 PrincipleApplication to Refactoring
Typed HolesArchitectural unknowns cataloged with types
Constraint PropagationDesign constraints flow through dependency graph
Iterative RefinementHole-by-hole resolution cycles
Test-Driven ValidationTests define correctness
Formal CompletenessGates verify design completeness

We use the system to refactor the system.

Advanced Topics

For complex scenarios, see:

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:

  1. Revert changes: git diff to see what changed
  2. Investigate: What behavior changed and why?
  3. 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

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:

  1. Check dependencies: Are they actually resolved?

    python scripts/visualize_graph.py --analyze
    # Look for unresolved dependencies
    
  2. Review constraints: Are they contradictory?

    • Example: C1 "preserve all behavior" + C5 "change API contract" → Contradictory
    • Fix: Renegotiate constraints with stakeholders
  3. 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)
    
  4. 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:

  1. Identify the conflict:

    C1 requires: Keep synchronous operations
    C5 requires: Switch to async operations
    → Contradiction: Can't be both sync and async
    
  2. Negotiate priorities:

    OptionC1C5Tradeoff
    A: Keep sync✓✗No performance gain
    B: Switch to async✗✓Breaking change
    C: Add async, deprecate sync⚠️✓Migration burden
  3. 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)
  4. 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:

  1. Introduce intermediate hole:

    H0_parser_analysis: Analyze existing parsers (no dependencies)
    R6_interface: Define interface using H0 analysis
    R4_consolidate: Implement using R6 interface
    
  2. Redefine dependencies:

    • Maybe R4 doesn't actually need R6
    • Or R6 only needs partial R4 (split R4)
  3. 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:

  1. Why did estimate fail?

    • Underestimated complexity
    • Unforeseen dependencies
    • Unclear requirements
    • Technical issues (tool problems, infrastructure)
  2. 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)"
  3. 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-infra
  • requirements.txt, pyproject.toml, uv.lock → discover-api (Python), discover-ml if ML work
  • Cargo.toml → discover-wasm if WASM, discover-api for web services
  • build.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.md for 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

  1. Understand Context

    • Read project files to detect technologies
    • Review conversation for mentioned frameworks/problems
    • Identify the work phase (planning, implementation, testing, deployment)
  2. Recommend Gateways

    • Suggest 2-4 relevant gateway skills
    • Explain what each gateway covers
    • Provide clear cat commands to load them
  3. 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

Sponsors

Details

Marketplace
rand/cc-polymath
Category
Community