feat: add Agent Skills and restructure documentation

- Add 47 Agent Skills across 14 plugins following Anthropic's specification - Python (5): async patterns, testing, packaging, performance, UV package manager - JavaScript/TypeScript (4): advanced types, Node.js patterns, testing, modern JS - Kubernetes (4): manifests, Helm charts, GitOps, security policies - Cloud Infrastructure (4): Terraform, multi-cloud, hybrid networking, cost optimization - CI/CD (4): pipeline design, GitHub Actions, GitLab CI, secrets management - Backend (3): API design, architecture patterns, microservices - LLM Applications (4): LangChain, prompt engineering, RAG, evaluation - Blockchain/Web3 (4): DeFi protocols, NFT standards, Solidity security, Web3 testing - Framework Migration (4): React, Angular, database, dependency upgrades - Observability (4): Prometheus, Grafana, distributed tracing, SLO - Payment Processing (4): Stripe, PayPal, PCI compliance, billing - API Scaffolding (1): FastAPI templates - ML Operations (1): ML pipeline workflow - Security (1): SAST configuration - Restructure documentation into /docs directory - agent-skills.md: Complete guide to all 47 skills - agents.md: All 85 agents with model configuration - plugins.md: Complete catalog of 63 plugins - usage.md: Commands, workflows, and best practices - architecture.md: Design principles and patterns - Update README.md - Add Agent Skills banner announcement - Reduce length by ~75% with links to detailed docs - Add What's New section showcasing Agent Skills - Add Popular Use Cases with real examples - Improve navigation with Core Guides and Quick Links - Update marketplace.json with skills arrays for 14 plugins All 47 skills follow Agent Skills Specification: - Required YAML frontmatter (name, description) - Use when activation clauses - Progressive disclosure architecture - Under 1024 character descriptions
2026-03-18 09:37:15 +00:00 · 2025-10-16 20:33:27 -04:00
parent 1962091501
commit 65e5cb093a
80 changed files with 32158 additions and 1025 deletions
--- a/docs/agent-skills.md
+++ b/docs/agent-skills.md
@@ -0,0 +1,224 @@
+# Agent Skills
+
+Agent Skills are modular packages that extend Claude's capabilities with specialized domain knowledge, following Anthropic's [Agent Skills Specification](https://github.com/anthropics/skills/blob/main/agent_skills_spec.md). This plugin ecosystem includes **47 specialized skills** across 14 plugins, enabling progressive disclosure and efficient token usage.
+
+## Overview
+
+Skills provide Claude with deep expertise in specific domains without loading everything into context upfront. Each skill includes:
+
+- **YAML Frontmatter**: Name and activation criteria
+- **Progressive Disclosure**: Metadata → Instructions → Resources
+- **Activation Triggers**: Clear "Use when" clauses for automatic invocation
+
+## Skills by Plugin
+
+### Kubernetes Operations (4 skills)
+
+| Skill | Description |
+|-------|-------------|
+| **k8s-manifest-generator** | Create production-ready Kubernetes manifests for Deployments, Services, ConfigMaps, and Secrets following best practices |
+| **helm-chart-scaffolding** | Design, organize, and manage Helm charts for templating and packaging Kubernetes applications |
+| **gitops-workflow** | Implement GitOps workflows with ArgoCD and Flux for automated, declarative deployments |
+| **k8s-security-policies** | Implement Kubernetes security policies including NetworkPolicy, PodSecurityPolicy, and RBAC |
+
+### LLM Application Development (4 skills)
+
+| Skill | Description |
+|-------|-------------|
+| **langchain-architecture** | Design LLM applications using LangChain framework with agents, memory, and tool integration |
+| **prompt-engineering-patterns** | Master advanced prompt engineering techniques for LLM performance and reliability |
+| **rag-implementation** | Build Retrieval-Augmented Generation systems with vector databases and semantic search |
+| **llm-evaluation** | Implement comprehensive evaluation strategies with automated metrics and benchmarking |
+
+### Backend Development (3 skills)
+
+| Skill | Description |
+|-------|-------------|
+| **api-design-principles** | Master REST and GraphQL API design for intuitive, scalable, and maintainable APIs |
+| **architecture-patterns** | Implement Clean Architecture, Hexagonal Architecture, and Domain-Driven Design |
+| **microservices-patterns** | Design microservices with service boundaries, event-driven communication, and resilience |
+
+### Blockchain & Web3 (4 skills)
+
+| Skill | Description |
+|-------|-------------|
+| **defi-protocol-templates** | Implement DeFi protocols with templates for staking, AMMs, governance, and lending |
+| **nft-standards** | Implement NFT standards (ERC-721, ERC-1155) with metadata and marketplace integration |
+| **solidity-security** | Master smart contract security to prevent vulnerabilities and implement secure patterns |
+| **web3-testing** | Test smart contracts using Hardhat and Foundry with unit tests and mainnet forking |
+
+### CI/CD Automation (4 skills)
+
+| Skill | Description |
+|-------|-------------|
+| **deployment-pipeline-design** | Design multi-stage CI/CD pipelines with approval gates and security checks |
+| **github-actions-templates** | Create production-ready GitHub Actions workflows for testing, building, and deploying |
+| **gitlab-ci-patterns** | Build GitLab CI/CD pipelines with multi-stage workflows and distributed runners |
+| **secrets-management** | Implement secure secrets management using Vault, AWS Secrets Manager, or native solutions |
+
+### Cloud Infrastructure (4 skills)
+
+| Skill | Description |
+|-------|-------------|
+| **terraform-module-library** | Build reusable Terraform modules for AWS, Azure, and GCP infrastructure |
+| **multi-cloud-architecture** | Design multi-cloud architectures avoiding vendor lock-in |
+| **hybrid-cloud-networking** | Configure secure connectivity between on-premises and cloud platforms |
+| **cost-optimization** | Optimize cloud costs through rightsizing, tagging, and reserved instances |
+
+### Framework Migration (4 skills)
+
+| Skill | Description |
+|-------|-------------|
+| **react-modernization** | Upgrade React apps, migrate to hooks, and adopt concurrent features |
+| **angular-migration** | Migrate from AngularJS to Angular using hybrid mode and incremental rewriting |
+| **database-migration** | Execute database migrations with zero-downtime strategies and transformations |
+| **dependency-upgrade** | Manage major dependency upgrades with compatibility analysis and testing |
+
+### Observability & Monitoring (4 skills)
+
+| Skill | Description |
+|-------|-------------|
+| **prometheus-configuration** | Set up Prometheus for comprehensive metric collection and monitoring |
+| **grafana-dashboards** | Create production Grafana dashboards for real-time system visualization |
+| **distributed-tracing** | Implement distributed tracing with Jaeger and Tempo to track requests |
+| **slo-implementation** | Define SLIs and SLOs with error budgets and alerting |
+
+### Payment Processing (4 skills)
+
+| Skill | Description |
+|-------|-------------|
+| **stripe-integration** | Implement Stripe payment processing for checkout, subscriptions, and webhooks |
+| **paypal-integration** | Integrate PayPal payment processing with express checkout and subscriptions |
+| **pci-compliance** | Implement PCI DSS compliance for secure payment card data handling |
+| **billing-automation** | Build automated billing systems for recurring payments and invoicing |
+
+### Python Development (5 skills)
+
+| Skill | Description |
+|-------|-------------|
+| **async-python-patterns** | Master Python asyncio, concurrent programming, and async/await patterns |
+| **python-testing-patterns** | Implement comprehensive testing with pytest, fixtures, and mocking |
+| **python-packaging** | Create distributable Python packages with proper structure and PyPI publishing |
+| **python-performance-optimization** | Profile and optimize Python code using cProfile and performance best practices |
+| **uv-package-manager** | Master the uv package manager for fast dependency management and virtual environments |
+
+### JavaScript/TypeScript (4 skills)
+
+| Skill | Description |
+|-------|-------------|
+| **typescript-advanced-types** | Master TypeScript's advanced type system including generics and conditional types |
+| **nodejs-backend-patterns** | Build production-ready Node.js services with Express/Fastify and best practices |
+| **javascript-testing-patterns** | Implement comprehensive testing with Jest, Vitest, and Testing Library |
+| **modern-javascript-patterns** | Master ES6+ features including async/await, destructuring, and functional programming |
+
+### API Scaffolding (1 skill)
+
+| Skill | Description |
+|-------|-------------|
+| **fastapi-templates** | Create production-ready FastAPI projects with async patterns and error handling |
+
+### Machine Learning Operations (1 skill)
+
+| Skill | Description |
+|-------|-------------|
+| **ml-pipeline-workflow** | Build end-to-end MLOps pipelines from data preparation through deployment |
+
+### Security Scanning (1 skill)
+
+| Skill | Description |
+|-------|-------------|
+| **sast-configuration** | Configure Static Application Security Testing tools for vulnerability detection |
+
+## How Skills Work
+
+### Activation
+
+Skills are automatically activated when Claude detects matching patterns in your request:
+
+```
+User: "Set up Kubernetes deployment with Helm chart"
+→ Activates: helm-chart-scaffolding, k8s-manifest-generator
+
+User: "Build a RAG system for document Q&A"
+→ Activates: rag-implementation, prompt-engineering-patterns
+
+User: "Optimize Python async performance"
+→ Activates: async-python-patterns, python-performance-optimization
+```
+
+### Progressive Disclosure
+
+Skills use a three-tier architecture for token efficiency:
+
+1. **Metadata** (Frontmatter): Name and activation criteria (always loaded)
+2. **Instructions**: Core guidance and patterns (loaded when activated)
+3. **Resources**: Examples and templates (loaded on demand)
+
+### Integration with Agents
+
+Skills work alongside agents to provide deep domain expertise:
+
+- **Agents**: High-level reasoning and orchestration
+- **Skills**: Specialized knowledge and implementation patterns
+
+Example workflow:
+```
+backend-architect agent → Plans API architecture
+  ↓
+api-design-principles skill → Provides REST/GraphQL best practices
+  ↓
+fastapi-templates skill → Supplies production-ready templates
+```
+
+## Specification Compliance
+
+All 47 skills follow the [Agent Skills Specification](https://github.com/anthropics/skills/blob/main/agent_skills_spec.md):
+
+- ✓ Required `name` field (hyphen-case)
+- ✓ Required `description` field with "Use when" clause
+- ✓ Descriptions under 1024 characters
+- ✓ Complete, non-truncated descriptions
+- ✓ Proper YAML frontmatter formatting
+
+## Creating New Skills
+
+To add a skill to a plugin:
+
+1. Create `plugins/{plugin-name}/skills/{skill-name}/SKILL.md`
+2. Add YAML frontmatter:
+   ```yaml
+   ---
+   name: skill-name
+   description: What the skill does. Use when [activation trigger].
+   ---
+   ```
+3. Write comprehensive skill content using progressive disclosure
+4. Add skill path to `marketplace.json`:
+   ```json
+   {
+     "name": "plugin-name",
+     "skills": ["./skills/skill-name"]
+   }
+   ```
+
+### Skill Structure
+
+```
+plugins/{plugin-name}/
+└── skills/
+    └── {skill-name}/
+        └── SKILL.md        # Frontmatter + content
+```
+
+## Benefits
+
+- **Token Efficiency**: Load only relevant knowledge when needed
+- **Specialized Expertise**: Deep domain knowledge without bloat
+- **Clear Activation**: Explicit triggers prevent unwanted invocation
+- **Composability**: Mix and match skills across workflows
+- **Maintainability**: Isolated updates don't affect other skills
+
+## Resources
+
+- [Anthropic Skills Repository](https://github.com/anthropics/skills)
+- [Agent Skills Documentation](https://docs.claude.com/en/docs/claude-code/skills)
--- a/docs/agents.md
+++ b/docs/agents.md
@@ -0,0 +1,325 @@
+# Agent Reference
+
+Complete reference for all **85 specialized AI agents** organized by category with model assignments.
+
+## Agent Categories
+
+### Architecture & System Design
+
+#### Core Architecture
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [backend-architect](../plugins/backend-development/agents/backend-architect.md) | opus | RESTful API design, microservice boundaries, database schemas |
+| [frontend-developer](../plugins/multi-platform-apps/agents/frontend-developer.md) | sonnet | React components, responsive layouts, client-side state management |
+| [graphql-architect](../plugins/backend-development/agents/graphql-architect.md) | opus | GraphQL schemas, resolvers, federation architecture |
+| [architect-reviewer](../plugins/comprehensive-review/agents/architect-review.md) | opus | Architectural consistency analysis and pattern validation |
+| [cloud-architect](../plugins/cloud-infrastructure/agents/cloud-architect.md) | opus | AWS/Azure/GCP infrastructure design and cost optimization |
+| [hybrid-cloud-architect](../plugins/cloud-infrastructure/agents/hybrid-cloud-architect.md) | opus | Multi-cloud strategies across cloud and on-premises environments |
+| [kubernetes-architect](../plugins/kubernetes-operations/agents/kubernetes-architect.md) | opus | Cloud-native infrastructure with Kubernetes and GitOps |
+
+#### UI/UX & Mobile
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [ui-ux-designer](../plugins/multi-platform-apps/agents/ui-ux-designer.md) | sonnet | Interface design, wireframes, design systems |
+| [ui-visual-validator](../plugins/accessibility-compliance/agents/ui-visual-validator.md) | sonnet | Visual regression testing and UI verification |
+| [mobile-developer](../plugins/multi-platform-apps/agents/mobile-developer.md) | sonnet | React Native and Flutter application development |
+| [ios-developer](../plugins/multi-platform-apps/agents/ios-developer.md) | sonnet | Native iOS development with Swift/SwiftUI |
+| [flutter-expert](../plugins/multi-platform-apps/agents/flutter-expert.md) | sonnet | Advanced Flutter development with state management |
+
+### Programming Languages
+
+#### Systems & Low-Level
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [c-pro](../plugins/systems-programming/agents/c-pro.md) | sonnet | System programming with memory management and OS interfaces |
+| [cpp-pro](../plugins/systems-programming/agents/cpp-pro.md) | sonnet | Modern C++ with RAII, smart pointers, STL algorithms |
+| [rust-pro](../plugins/systems-programming/agents/rust-pro.md) | sonnet | Memory-safe systems programming with ownership patterns |
+| [golang-pro](../plugins/systems-programming/agents/golang-pro.md) | sonnet | Concurrent programming with goroutines and channels |
+
+#### Web & Application
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [javascript-pro](../plugins/javascript-typescript/agents/javascript-pro.md) | sonnet | Modern JavaScript with ES6+, async patterns, Node.js |
+| [typescript-pro](../plugins/javascript-typescript/agents/typescript-pro.md) | sonnet | Advanced TypeScript with type systems and generics |
+| [python-pro](../plugins/python-development/agents/python-pro.md) | sonnet | Python development with advanced features and optimization |
+| [ruby-pro](../plugins/web-scripting/agents/ruby-pro.md) | sonnet | Ruby with metaprogramming, Rails patterns, gem development |
+| [php-pro](../plugins/web-scripting/agents/php-pro.md) | sonnet | Modern PHP with frameworks and performance optimization |
+
+#### Enterprise & JVM
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [java-pro](../plugins/jvm-languages/agents/java-pro.md) | sonnet | Modern Java with streams, concurrency, JVM optimization |
+| [scala-pro](../plugins/jvm-languages/agents/scala-pro.md) | sonnet | Enterprise Scala with functional programming and distributed systems |
+| [csharp-pro](../plugins/jvm-languages/agents/csharp-pro.md) | sonnet | C# development with .NET frameworks and patterns |
+
+#### Specialized Platforms
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [elixir-pro](../plugins/functional-programming/agents/elixir-pro.md) | sonnet | Elixir with OTP patterns and Phoenix frameworks |
+| [django-pro](../plugins/api-scaffolding/agents/django-pro.md) | sonnet | Django development with ORM and async views |
+| [fastapi-pro](../plugins/api-scaffolding/agents/fastapi-pro.md) | sonnet | FastAPI with async patterns and Pydantic |
+| [unity-developer](../plugins/game-development/agents/unity-developer.md) | sonnet | Unity game development and optimization |
+| [minecraft-bukkit-pro](../plugins/game-development/agents/minecraft-bukkit-pro.md) | sonnet | Minecraft server plugin development |
+| [sql-pro](../plugins/database-design/agents/sql-pro.md) | sonnet | Complex SQL queries and database optimization |
+
+### Infrastructure & Operations
+
+#### DevOps & Deployment
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [devops-troubleshooter](../plugins/incident-response/agents/devops-troubleshooter.md) | sonnet | Production debugging, log analysis, deployment troubleshooting |
+| [deployment-engineer](../plugins/cloud-infrastructure/agents/deployment-engineer.md) | sonnet | CI/CD pipelines, containerization, cloud deployments |
+| [terraform-specialist](../plugins/cloud-infrastructure/agents/terraform-specialist.md) | sonnet | Infrastructure as Code with Terraform modules and state management |
+| [dx-optimizer](../plugins/team-collaboration/agents/dx-optimizer.md) | sonnet | Developer experience optimization and tooling improvements |
+
+#### Database Management
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [database-optimizer](../plugins/observability-monitoring/agents/database-optimizer.md) | sonnet | Query optimization, index design, migration strategies |
+| [database-admin](../plugins/database-migrations/agents/database-admin.md) | sonnet | Database operations, backup, replication, monitoring |
+| [database-architect](../plugins/database-design/agents/database-architect.md) | opus | Database design from scratch, technology selection, schema modeling |
+
+#### Incident Response & Network
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [incident-responder](../plugins/incident-response/agents/incident-responder.md) | opus | Production incident management and resolution |
+| [network-engineer](../plugins/observability-monitoring/agents/network-engineer.md) | sonnet | Network debugging, load balancing, traffic analysis |
+
+### Quality Assurance & Security
+
+#### Code Quality & Review
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [code-reviewer](../plugins/comprehensive-review/agents/code-reviewer.md) | opus | Code review with security focus and production reliability |
+| [security-auditor](../plugins/comprehensive-review/agents/security-auditor.md) | opus | Vulnerability assessment and OWASP compliance |
+| [backend-security-coder](../plugins/data-validation-suite/agents/backend-security-coder.md) | opus | Secure backend coding practices, API security implementation |
+| [frontend-security-coder](../plugins/frontend-mobile-security/agents/frontend-security-coder.md) | opus | XSS prevention, CSP implementation, client-side security |
+| [mobile-security-coder](../plugins/frontend-mobile-security/agents/mobile-security-coder.md) | opus | Mobile security patterns, WebView security, biometric auth |
+
+#### Testing & Debugging
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [test-automator](../plugins/codebase-cleanup/agents/test-automator.md) | sonnet | Comprehensive test suite creation (unit, integration, e2e) |
+| [tdd-orchestrator](../plugins/backend-development/agents/tdd-orchestrator.md) | sonnet | Test-Driven Development methodology guidance |
+| [debugger](../plugins/error-debugging/agents/debugger.md) | sonnet | Error resolution and test failure analysis |
+| [error-detective](../plugins/error-debugging/agents/error-detective.md) | sonnet | Log analysis and error pattern recognition |
+
+#### Performance & Observability
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [performance-engineer](../plugins/observability-monitoring/agents/performance-engineer.md) | opus | Application profiling and optimization |
+| [observability-engineer](../plugins/observability-monitoring/agents/observability-engineer.md) | opus | Production monitoring, distributed tracing, SLI/SLO management |
+| [search-specialist](../plugins/content-marketing/agents/search-specialist.md) | haiku | Advanced web research and information synthesis |
+
+### Data & AI
+
+#### Data Engineering & Analytics
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [data-scientist](../plugins/machine-learning-ops/agents/data-scientist.md) | opus | Data analysis, SQL queries, BigQuery operations |
+| [data-engineer](../plugins/data-engineering/agents/data-engineer.md) | sonnet | ETL pipelines, data warehouses, streaming architectures |
+
+#### Machine Learning & AI
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [ai-engineer](../plugins/llm-application-dev/agents/ai-engineer.md) | opus | LLM applications, RAG systems, prompt pipelines |
+| [ml-engineer](../plugins/machine-learning-ops/agents/ml-engineer.md) | opus | ML pipelines, model serving, feature engineering |
+| [mlops-engineer](../plugins/machine-learning-ops/agents/mlops-engineer.md) | opus | ML infrastructure, experiment tracking, model registries |
+| [prompt-engineer](../plugins/llm-application-dev/agents/prompt-engineer.md) | opus | LLM prompt optimization and engineering |
+
+### Documentation & Technical Writing
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [docs-architect](../plugins/code-documentation/agents/docs-architect.md) | opus | Comprehensive technical documentation generation |
+| [api-documenter](../plugins/api-testing-observability/agents/api-documenter.md) | sonnet | OpenAPI/Swagger specifications and developer docs |
+| [reference-builder](../plugins/documentation-generation/agents/reference-builder.md) | haiku | Technical references and API documentation |
+| [tutorial-engineer](../plugins/code-documentation/agents/tutorial-engineer.md) | sonnet | Step-by-step tutorials and educational content |
+| [mermaid-expert](../plugins/documentation-generation/agents/mermaid-expert.md) | sonnet | Diagram creation (flowcharts, sequences, ERDs) |
+
+### Business & Operations
+
+#### Business Analysis & Finance
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [business-analyst](../plugins/business-analytics/agents/business-analyst.md) | sonnet | Metrics analysis, reporting, KPI tracking |
+| [quant-analyst](../plugins/quantitative-trading/agents/quant-analyst.md) | opus | Financial modeling, trading strategies, market analysis |
+| [risk-manager](../plugins/quantitative-trading/agents/risk-manager.md) | sonnet | Portfolio risk monitoring and management |
+
+#### Marketing & Sales
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [content-marketer](../plugins/content-marketing/agents/content-marketer.md) | sonnet | Blog posts, social media, email campaigns |
+| [sales-automator](../plugins/customer-sales-automation/agents/sales-automator.md) | haiku | Cold emails, follow-ups, proposal generation |
+
+#### Support & Legal
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [customer-support](../plugins/customer-sales-automation/agents/customer-support.md) | sonnet | Support tickets, FAQ responses, customer communication |
+| [hr-pro](../plugins/hr-legal-compliance/agents/hr-pro.md) | opus | HR operations, policies, employee relations |
+| [legal-advisor](../plugins/hr-legal-compliance/agents/legal-advisor.md) | opus | Privacy policies, terms of service, legal documentation |
+
+### SEO & Content Optimization
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [seo-content-auditor](../plugins/seo-content-creation/agents/seo-content-auditor.md) | sonnet | Content quality analysis, E-E-A-T signals assessment |
+| [seo-meta-optimizer](../plugins/seo-technical-optimization/agents/seo-meta-optimizer.md) | haiku | Meta title and description optimization |
+| [seo-keyword-strategist](../plugins/seo-technical-optimization/agents/seo-keyword-strategist.md) | haiku | Keyword analysis and semantic variations |
+| [seo-structure-architect](../plugins/seo-technical-optimization/agents/seo-structure-architect.md) | haiku | Content structure and schema markup |
+| [seo-snippet-hunter](../plugins/seo-technical-optimization/agents/seo-snippet-hunter.md) | haiku | Featured snippet formatting |
+| [seo-content-refresher](../plugins/seo-analysis-monitoring/agents/seo-content-refresher.md) | haiku | Content freshness analysis |
+| [seo-cannibalization-detector](../plugins/seo-analysis-monitoring/agents/seo-cannibalization-detector.md) | haiku | Keyword overlap detection |
+| [seo-authority-builder](../plugins/seo-analysis-monitoring/agents/seo-authority-builder.md) | sonnet | E-E-A-T signal analysis |
+| [seo-content-writer](../plugins/seo-content-creation/agents/seo-content-writer.md) | sonnet | SEO-optimized content creation |
+| [seo-content-planner](../plugins/seo-content-creation/agents/seo-content-planner.md) | haiku | Content planning and topic clusters |
+
+### Specialized Domains
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [arm-cortex-expert](../plugins/arm-cortex-microcontrollers/agents/arm-cortex-expert.md) | sonnet | ARM Cortex-M firmware and peripheral driver development |
+| [blockchain-developer](../plugins/blockchain-web3/agents/blockchain-developer.md) | sonnet | Web3 apps, smart contracts, DeFi protocols |
+| [payment-integration](../plugins/payment-processing/agents/payment-integration.md) | sonnet | Payment processor integration (Stripe, PayPal) |
+| [legacy-modernizer](../plugins/framework-migration/agents/legacy-modernizer.md) | sonnet | Legacy code refactoring and modernization |
+| [context-manager](../plugins/agent-orchestration/agents/context-manager.md) | haiku | Multi-agent context management |
+
+## Model Configuration
+
+Agents are assigned to specific Claude models based on task complexity and computational requirements.
+
+### Model Distribution Summary
+
+| Model | Agent Count | Use Case |
+|-------|-------------|----------|
+| Haiku | 47 | Fast execution tasks: testing, documentation, ops, database optimization, business |
+| Sonnet | 97 | Complex reasoning, architecture, language expertise, orchestration, security |
+
+### Model Selection Criteria
+
+#### Haiku - Fast Execution & Deterministic Tasks
+
+**Use when:**
+- Generating code from well-defined specifications
+- Creating tests following established patterns
+- Writing documentation with clear templates
+- Executing infrastructure operations
+- Performing database query optimization
+- Handling customer support responses
+- Processing SEO optimization tasks
+- Managing deployment pipelines
+
+#### Sonnet - Complex Reasoning & Architecture
+
+**Use when:**
+- Designing system architecture
+- Making technology selection decisions
+- Performing security audits
+- Reviewing code for architectural patterns
+- Creating complex AI/ML pipelines
+- Providing language-specific expertise
+- Orchestrating multi-agent workflows
+- Handling business-critical legal/HR matters
+
+### Hybrid Orchestration Patterns
+
+The plugin ecosystem leverages Sonnet + Haiku orchestration for optimal performance and cost efficiency:
+
+#### Pattern 1: Planning → Execution
+```
+Sonnet: backend-architect (design API architecture)
+  ↓
+Haiku: Generate API endpoints following spec
+  ↓
+Haiku: test-automator (generate comprehensive tests)
+  ↓
+Sonnet: code-reviewer (architectural review)
+```
+
+#### Pattern 2: Reasoning → Action (Incident Response)
+```
+Sonnet: incident-responder (diagnose issue, create strategy)
+  ↓
+Haiku: devops-troubleshooter (execute fixes)
+  ↓
+Haiku: deployment-engineer (deploy hotfix)
+  ↓
+Haiku: Implement monitoring alerts
+```
+
+#### Pattern 3: Complex → Simple (Database Design)
+```
+Sonnet: database-architect (schema design, technology selection)
+  ↓
+Haiku: sql-pro (generate migration scripts)
+  ↓
+Haiku: database-admin (execute migrations)
+  ↓
+Haiku: database-optimizer (tune query performance)
+```
+
+#### Pattern 4: Multi-Agent Workflows
+```
+Full-Stack Feature Development:
+Sonnet: backend-architect + frontend-developer (design components)
+  ↓
+Haiku: Generate code following designs
+  ↓
+Haiku: test-automator (unit + integration tests)
+  ↓
+Sonnet: security-auditor (security review)
+  ↓
+Haiku: deployment-engineer (CI/CD setup)
+  ↓
+Haiku: Setup observability stack
+```
+
+## Agent Invocation
+
+### Natural Language
+
+Agents can be invoked through natural language when you need Claude to reason about which specialist to use:
+
+```
+"Use backend-architect to design the authentication API"
+"Have security-auditor scan for OWASP vulnerabilities"
+"Get performance-engineer to optimize this database query"
+```
+
+### Slash Commands
+
+Many agents are accessible through plugin slash commands for direct invocation:
+
+```bash
+/backend-development:feature-development user authentication
+/security-scanning:security-sast
+/incident-response:smart-fix "memory leak in payment service"
+```
+
+## Contributing
+
+To add a new agent:
+
+1. Create `plugins/{plugin-name}/agents/{agent-name}.md`
+2. Add frontmatter with name, description, and model assignment
+3. Write comprehensive system prompt
+4. Update plugin definition in `.claude-plugin/marketplace.json`
+
+See [Contributing Guide](../CONTRIBUTING.md) for details.
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -0,0 +1,379 @@
+# Architecture & Design Principles
+
+This marketplace follows industry best practices with a focus on granularity, composability, and minimal token usage.
+
+## Core Philosophy
+
+### Single Responsibility Principle
+
+- Each plugin does **one thing well** (Unix philosophy)
+- Clear, focused purposes (describable in 5-10 words)
+- Average plugin size: **3.4 components** (follows Anthropic's 2-8 pattern)
+- **Zero bloated plugins** - all plugins focused and purposeful
+
+### Composability Over Bundling
+
+- Mix and match plugins based on needs
+- Workflow orchestrators compose focused plugins
+- No forced feature bundling
+- Clear boundaries between plugins
+
+### Context Efficiency
+
+- Smaller tools = faster processing
+- Better fit in LLM context windows
+- More accurate, focused responses
+- Install only what you need
+
+### Maintainability
+
+- Single-purpose = easier updates
+- Clear boundaries = isolated changes
+- Less duplication = simpler maintenance
+- Isolated dependencies
+
+## Granular Plugin Architecture
+
+### Plugin Distribution
+
+- **63 focused plugins** optimized for specific use cases
+- **23 clear categories** with 1-6 plugins each for easy discovery
+- Organized by domain:
+  - **Development**: 4 plugins (debugging, backend, frontend, multi-platform)
+  - **Security**: 4 plugins (scanning, compliance, backend-api, frontend-mobile)
+  - **Operations**: 4 plugins (incident, diagnostics, distributed, observability)
+  - **Languages**: 7 plugins (Python, JS/TS, systems, JVM, scripting, functional, embedded)
+  - **Infrastructure**: 5 plugins (deployment, validation, K8s, cloud, CI/CD)
+  - And 18 more specialized categories
+
+### Component Breakdown
+
+**85 Specialized Agents**
+- Domain experts with deep knowledge
+- Organized across architecture, languages, infrastructure, quality, data/AI, documentation, business, and SEO
+- Model-optimized (47 Haiku, 97 Sonnet) for performance and cost
+
+**15 Workflow Orchestrators**
+- Multi-agent coordination systems
+- Complex operations like full-stack development, security hardening, ML pipelines, incident response
+- Pre-configured agent workflows
+
+**44 Development Tools**
+- Optimized utilities including:
+  - Project scaffolding (Python, TypeScript, Rust)
+  - Security scanning (SAST, dependency audit, XSS)
+  - Test generation (pytest, Jest)
+  - Component scaffolding (React, React Native)
+  - Infrastructure setup (Terraform, Kubernetes)
+
+**47 Agent Skills**
+- Modular knowledge packages
+- Progressive disclosure architecture
+- Domain-specific expertise across 14 plugins
+- Spec-compliant (Anthropic Agent Skills Specification)
+
+## Repository Structure
+
+```
+claude-agents/
+├── .claude-plugin/
+│   └── marketplace.json          # Marketplace catalog (63 plugins)
+├── plugins/                       # Isolated plugin directories
+│   ├── python-development/
+│   │   ├── agents/               # Python language agents
+│   │   │   ├── python-pro.md
+│   │   │   ├── django-pro.md
+│   │   │   └── fastapi-pro.md
+│   │   ├── commands/             # Python tooling
+│   │   │   └── python-scaffold.md
+│   │   └── skills/               # Python skills (5 total)
+│   │       ├── async-python-patterns/
+│   │       ├── python-testing-patterns/
+│   │       ├── python-packaging/
+│   │       ├── python-performance-optimization/
+│   │       └── uv-package-manager/
+│   ├── backend-development/
+│   │   ├── agents/
+│   │   │   ├── backend-architect.md
+│   │   │   ├── graphql-architect.md
+│   │   │   └── tdd-orchestrator.md
+│   │   ├── commands/
+│   │   │   └── feature-development.md
+│   │   └── skills/               # Backend skills (3 total)
+│   │       ├── api-design-principles/
+│   │       ├── architecture-patterns/
+│   │       └── microservices-patterns/
+│   ├── security-scanning/
+│   │   ├── agents/
+│   │   │   └── security-auditor.md
+│   │   ├── commands/
+│   │   │   ├── security-hardening.md
+│   │   │   ├── security-sast.md
+│   │   │   └── security-dependencies.md
+│   │   └── skills/               # Security skills (1 total)
+│   │       └── sast-configuration/
+│   └── ... (60 more isolated plugins)
+├── docs/                          # Documentation
+│   ├── agent-skills.md           # Agent Skills guide
+│   ├── agents.md                 # Agent reference
+│   ├── plugins.md                # Plugin catalog
+│   ├── usage.md                  # Usage guide
+│   └── architecture.md           # This file
+└── README.md                      # Quick start
+```
+
+## Plugin Structure
+
+Each plugin contains:
+
+- **agents/** - Specialized agents for that domain (optional)
+- **commands/** - Tools and workflows specific to that plugin (optional)
+- **skills/** - Modular knowledge packages with progressive disclosure (optional)
+
+### Minimum Requirements
+
+- At least one agent OR one command
+- Clear, focused purpose
+- Proper frontmatter in all files
+- Entry in marketplace.json
+
+### Example Plugin
+
+```
+plugins/kubernetes-operations/
+├── agents/
+│   └── kubernetes-architect.md   # K8s architecture and design
+├── commands/
+│   └── k8s-deploy.md            # Deployment automation
+└── skills/
+    ├── k8s-manifest-generator/   # Manifest creation skill
+    ├── helm-chart-scaffolding/   # Helm chart skill
+    ├── gitops-workflow/          # GitOps automation skill
+    └── k8s-security-policies/    # Security policy skill
+```
+
+## Agent Skills Architecture
+
+### Progressive Disclosure
+
+Skills use a three-tier architecture for token efficiency:
+
+1. **Metadata** (Frontmatter): Name and activation criteria (always loaded)
+2. **Instructions**: Core guidance and patterns (loaded when activated)
+3. **Resources**: Examples and templates (loaded on demand)
+
+### Specification Compliance
+
+All skills follow the [Agent Skills Specification](https://github.com/anthropics/skills/blob/main/agent_skills_spec.md):
+
+```yaml
+---
+name: skill-name                  # Required: hyphen-case
+description: What the skill does. Use when [trigger]. # Required: < 1024 chars
+---
+
+# Skill content with progressive disclosure
+```
+
+### Benefits
+
+- **Token Efficiency**: Load only relevant knowledge when needed
+- **Specialized Expertise**: Deep domain knowledge without bloat
+- **Clear Activation**: Explicit triggers prevent unwanted invocation
+- **Composability**: Mix and match skills across workflows
+- **Maintainability**: Isolated updates don't affect other skills
+
+See [Agent Skills](./agent-skills.md) for complete details on the 47 skills.
+
+## Model Configuration Strategy
+
+### Two-Tier Architecture
+
+The system uses Claude Opus and Sonnet models strategically:
+
+| Model | Count | Use Case |
+|-------|-------|----------|
+| Haiku | 47 agents | Fast execution, deterministic tasks |
+| Sonnet | 97 agents | Complex reasoning, architecture decisions |
+
+### Selection Criteria
+
+**Haiku - Fast Execution & Deterministic Tasks**
+- Generating code from well-defined specifications
+- Creating tests following established patterns
+- Writing documentation with clear templates
+- Executing infrastructure operations
+- Performing database query optimization
+- Handling customer support responses
+- Processing SEO optimization tasks
+- Managing deployment pipelines
+
+**Sonnet - Complex Reasoning & Architecture**
+- Designing system architecture
+- Making technology selection decisions
+- Performing security audits
+- Reviewing code for architectural patterns
+- Creating complex AI/ML pipelines
+- Providing language-specific expertise
+- Orchestrating multi-agent workflows
+- Handling business-critical legal/HR matters
+
+### Hybrid Orchestration
+
+Combine models for optimal performance and cost:
+
+```
+Planning Phase (Sonnet) → Execution Phase (Haiku) → Review Phase (Sonnet)
+
+Example:
+backend-architect (Sonnet) designs API
+  ↓
+Generate endpoints (Haiku) implements spec
+  ↓
+test-automator (Haiku) creates tests
+  ↓
+code-reviewer (Sonnet) validates architecture
+```
+
+## Performance & Quality
+
+### Optimized Token Usage
+
+- **Isolated plugins** load only what you need
+- **Granular architecture** reduces unnecessary context
+- **Progressive disclosure** (skills) loads knowledge on demand
+- **Clear boundaries** prevent context pollution
+
+### Component Coverage
+
+- **100% agent coverage** - all plugins include at least one agent
+- **100% component availability** - all 85 agents accessible across plugins
+- **Efficient distribution** - 3.4 components per plugin average
+
+### Discoverability
+
+- **Clear plugin names** convey purpose immediately
+- **Logical categorization** with 23 well-defined categories
+- **Searchable documentation** with cross-references
+- **Easy to find** the right tool for the job
+
+## Design Patterns
+
+### Pattern 1: Single-Purpose Plugin
+
+Each plugin focuses on one domain:
+
+```
+python-development/
+├── agents/           # Python language experts
+├── commands/         # Python project scaffolding
+└── skills/           # Python-specific knowledge
+```
+
+**Benefits:**
+- Clear responsibility
+- Easy to maintain
+- Minimal token usage
+- Composable with other plugins
+
+### Pattern 2: Workflow Orchestration
+
+Orchestrator plugins coordinate multiple agents:
+
+```
+full-stack-orchestration/
+└── commands/
+    └── full-stack-feature.md    # Coordinates 7+ agents
+```
+
+**Orchestration:**
+1. backend-architect (design API)
+2. database-architect (design schema)
+3. frontend-developer (build UI)
+4. test-automator (create tests)
+5. security-auditor (security review)
+6. deployment-engineer (CI/CD)
+7. observability-engineer (monitoring)
+
+### Pattern 3: Agent + Skill Integration
+
+Agents provide reasoning, skills provide knowledge:
+
+```
+User: "Build FastAPI project with async patterns"
+  ↓
+fastapi-pro agent (orchestrates)
+  ↓
+fastapi-templates skill (provides patterns)
+  ↓
+python-scaffold command (generates project)
+```
+
+### Pattern 4: Multi-Plugin Composition
+
+Complex workflows use multiple plugins:
+
+```
+Feature Development Workflow:
+1. backend-development:feature-development
+2. security-scanning:security-hardening
+3. unit-testing:test-generate
+4. code-review-ai:ai-review
+5. cicd-automation:workflow-automate
+6. observability-monitoring:monitor-setup
+```
+
+## Versioning & Updates
+
+### Marketplace Updates
+
+- Marketplace catalog in `.claude-plugin/marketplace.json`
+- Semantic versioning for plugins
+- Backward compatibility maintained
+- Clear migration guides for breaking changes
+
+### Plugin Updates
+
+- Individual plugin updates don't affect others
+- Skills can be updated independently
+- Agents can be added/removed without breaking workflows
+- Commands maintain stable interfaces
+
+## Contributing Guidelines
+
+### Adding a Plugin
+
+1. Create plugin directory: `plugins/{plugin-name}/`
+2. Add agents and/or commands
+3. Optionally add skills
+4. Update marketplace.json
+5. Document in appropriate category
+
+### Adding an Agent
+
+1. Create `plugins/{plugin-name}/agents/{agent-name}.md`
+2. Add frontmatter (name, description, model)
+3. Write comprehensive system prompt
+4. Update plugin definition
+
+### Adding a Skill
+
+1. Create `plugins/{plugin-name}/skills/{skill-name}/SKILL.md`
+2. Add YAML frontmatter (name, description with "Use when")
+3. Write skill content with progressive disclosure
+4. Add to plugin's skills array in marketplace.json
+
+### Quality Standards
+
+- **Clear naming** - Hyphen-case, descriptive
+- **Focused scope** - Single responsibility
+- **Complete documentation** - What, when, how
+- **Tested functionality** - Verify before committing
+- **Spec compliance** - Follow Anthropic guidelines
+
+## See Also
+
+- [Agent Skills](./agent-skills.md) - Modular knowledge packages
+- [Agent Reference](./agents.md) - Complete agent catalog
+- [Plugin Reference](./plugins.md) - All 63 plugins
+- [Usage Guide](./usage.md) - Commands and workflows
--- a/docs/plugins.md
+++ b/docs/plugins.md
@@ -0,0 +1,374 @@
+# Complete Plugin Reference
+
+Browse all **63 focused, single-purpose plugins** organized by category.
+
+## Quick Start - Essential Plugins
+
+> 💡 **Getting Started?** Install these popular plugins for immediate productivity gains.
+
+### Development Essentials
+
+**code-documentation** - Documentation and technical writing
+
+```bash
+/plugin install code-documentation
+```
+
+Automated doc generation, code explanation, and tutorial creation for comprehensive technical documentation.
+
+**debugging-toolkit** - Smart debugging and developer experience
+
+```bash
+/plugin install debugging-toolkit
+```
+
+Interactive debugging, error analysis, and DX optimization for faster problem resolution.
+
+**git-pr-workflows** - Git automation and PR enhancement
+
+```bash
+/plugin install git-pr-workflows
+```
+
+Git workflow automation, pull request enhancement, and team onboarding processes.
+
+### Full-Stack Development
+
+**backend-development** - Backend API design and architecture
+
+```bash
+/plugin install backend-development
+```
+
+RESTful and GraphQL API design with test-driven development and modern backend architecture patterns.
+
+**frontend-mobile-development** - UI and mobile development
+
+```bash
+/plugin install frontend-mobile-development
+```
+
+React/React Native component development with automated scaffolding and cross-platform implementation.
+
+**full-stack-orchestration** - End-to-end feature development
+
+```bash
+/plugin install full-stack-orchestration
+```
+
+Multi-agent coordination from backend → frontend → testing → security → deployment.
+
+### Testing & Quality
+
+**unit-testing** - Automated test generation
+
+```bash
+/plugin install unit-testing
+```
+
+Generate pytest (Python) and Jest (JavaScript) unit tests automatically with comprehensive edge case coverage.
+
+**code-review-ai** - AI-powered code review
+
+```bash
+/plugin install code-review-ai
+```
+
+Architectural analysis, security assessment, and code quality review with actionable feedback.
+
+### Infrastructure & Operations
+
+**cloud-infrastructure** - Cloud architecture design
+
+```bash
+/plugin install cloud-infrastructure
+```
+
+AWS/Azure/GCP architecture, Kubernetes setup, Terraform IaC, and multi-cloud cost optimization.
+
+**incident-response** - Production incident management
+
+```bash
+/plugin install incident-response
+```
+
+Rapid incident triage, root cause analysis, and automated resolution workflows for production systems.
+
+### Language Support
+
+**python-development** - Python project scaffolding
+
+```bash
+/plugin install python-development
+```
+
+FastAPI/Django project initialization with modern tooling (uv, ruff) and production-ready architecture.
+
+**javascript-typescript** - JavaScript/TypeScript scaffolding
+
+```bash
+/plugin install javascript-typescript
+```
+
+Next.js, React + Vite, and Node.js project setup with pnpm and TypeScript best practices.
+
+---
+
+## Complete Plugin Catalog
+
+### 🎨 Development (4 plugins)
+
+| Plugin | Description | Install |
+|--------|-------------|---------|
+| **debugging-toolkit** | Interactive debugging and DX optimization | `/plugin install debugging-toolkit` |
+| **backend-development** | Backend API design with GraphQL and TDD | `/plugin install backend-development` |
+| **frontend-mobile-development** | Frontend UI and mobile development | `/plugin install frontend-mobile-development` |
+| **multi-platform-apps** | Cross-platform app coordination (web/iOS/Android) | `/plugin install multi-platform-apps` |
+
+### 📚 Documentation (2 plugins)
+
+| Plugin | Description | Install |
+|--------|-------------|---------|
+| **code-documentation** | Documentation generation and code explanation | `/plugin install code-documentation` |
+| **documentation-generation** | OpenAPI specs, Mermaid diagrams, tutorials | `/plugin install documentation-generation` |
+
+### 🔄 Workflows (3 plugins)
+
+| Plugin | Description | Install |
+|--------|-------------|---------|
+| **git-pr-workflows** | Git automation and PR enhancement | `/plugin install git-pr-workflows` |
+| **full-stack-orchestration** | End-to-end feature orchestration | `/plugin install full-stack-orchestration` |
+| **tdd-workflows** | Test-driven development methodology | `/plugin install tdd-workflows` |
+
+### ✅ Testing (2 plugins)
+
+| Plugin | Description | Install |
+|--------|-------------|---------|
+| **unit-testing** | Automated unit test generation (Python/JavaScript) | `/plugin install unit-testing` |
+| **tdd-workflows** | Test-driven development methodology | `/plugin install tdd-workflows` |
+
+### 🔍 Quality (3 plugins)
+
+| Plugin | Description | Install |
+|--------|-------------|---------|
+| **code-review-ai** | AI-powered architectural review | `/plugin install code-review-ai` |
+| **comprehensive-review** | Multi-perspective code analysis | `/plugin install comprehensive-review` |
+| **performance-testing-review** | Performance analysis and test coverage review | `/plugin install performance-testing-review` |
+
+### 🛠️ Utilities (4 plugins)
+
+| Plugin | Description | Install |
+|--------|-------------|---------|
+| **code-refactoring** | Code cleanup and technical debt management | `/plugin install code-refactoring` |
+| **dependency-management** | Dependency auditing and version management | `/plugin install dependency-management` |
+| **error-debugging** | Error analysis and trace debugging | `/plugin install error-debugging` |
+| **team-collaboration** | Team workflows and standup automation | `/plugin install team-collaboration` |
+
+### 🤖 AI & ML (4 plugins)
+
+| Plugin | Description | Install |
+|--------|-------------|---------|
+| **llm-application-dev** | LLM apps and prompt engineering | `/plugin install llm-application-dev` |
+| **agent-orchestration** | Multi-agent system optimization | `/plugin install agent-orchestration` |
+| **context-management** | Context persistence and restoration | `/plugin install context-management` |
+| **machine-learning-ops** | ML training pipelines and MLOps | `/plugin install machine-learning-ops` |
+
+### 📊 Data (2 plugins)
+
+| Plugin | Description | Install |
+|--------|-------------|---------|
+| **data-engineering** | ETL pipelines and data warehouses | `/plugin install data-engineering` |
+| **data-validation-suite** | Schema validation and data quality | `/plugin install data-validation-suite` |
+
+### 🗄️ Database (2 plugins)
+
+| Plugin | Description | Install |
+|--------|-------------|---------|
+| **database-design** | Database architecture and schema design | `/plugin install database-design` |
+| **database-migrations** | Database migration automation | `/plugin install database-migrations` |
+
+### 🚨 Operations (4 plugins)
+
+| Plugin | Description | Install |
+|--------|-------------|---------|
+| **incident-response** | Production incident management | `/plugin install incident-response` |
+| **error-diagnostics** | Error tracing and root cause analysis | `/plugin install error-diagnostics` |
+| **distributed-debugging** | Distributed system tracing | `/plugin install distributed-debugging` |
+| **observability-monitoring** | Metrics, logging, tracing, and SLO | `/plugin install observability-monitoring` |
+
+### ⚡ Performance (2 plugins)
+
+| Plugin | Description | Install |
+|--------|-------------|---------|
+| **application-performance** | Application profiling and optimization | `/plugin install application-performance` |
+| **database-cloud-optimization** | Database query and cloud cost optimization | `/plugin install database-cloud-optimization` |
+
+### ☁️ Infrastructure (5 plugins)
+
+| Plugin | Description | Install |
+|--------|-------------|---------|
+| **deployment-strategies** | Deployment patterns and rollback automation | `/plugin install deployment-strategies` |
+| **deployment-validation** | Pre-deployment checks and validation | `/plugin install deployment-validation` |
+| **kubernetes-operations** | K8s manifests and GitOps workflows | `/plugin install kubernetes-operations` |
+| **cloud-infrastructure** | AWS/Azure/GCP cloud architecture | `/plugin install cloud-infrastructure` |
+| **cicd-automation** | CI/CD pipeline configuration | `/plugin install cicd-automation` |
+
+### 🔒 Security (4 plugins)
+
+| Plugin | Description | Install |
+|--------|-------------|---------|
+| **security-scanning** | SAST analysis and vulnerability scanning | `/plugin install security-scanning` |
+| **security-compliance** | SOC2/HIPAA/GDPR compliance | `/plugin install security-compliance` |
+| **backend-api-security** | API security and authentication | `/plugin install backend-api-security` |
+| **frontend-mobile-security** | XSS/CSRF prevention and mobile security | `/plugin install frontend-mobile-security` |
+
+### 🔄 Modernization (2 plugins)
+
+| Plugin | Description | Install |
+|--------|-------------|---------|
+| **framework-migration** | Framework upgrades and migration planning | `/plugin install framework-migration` |
+| **codebase-cleanup** | Technical debt reduction and cleanup | `/plugin install codebase-cleanup` |
+
+### 🌐 API (2 plugins)
+
+| Plugin | Description | Install |
+|--------|-------------|---------|
+| **api-scaffolding** | REST/GraphQL API generation | `/plugin install api-scaffolding` |
+| **api-testing-observability** | API testing and monitoring | `/plugin install api-testing-observability` |
+
+### 📢 Marketing (4 plugins)
+
+| Plugin | Description | Install |
+|--------|-------------|---------|
+| **seo-content-creation** | SEO content writing and planning | `/plugin install seo-content-creation` |
+| **seo-technical-optimization** | Meta tags, keywords, and schema markup | `/plugin install seo-technical-optimization` |
+| **seo-analysis-monitoring** | Content analysis and authority building | `/plugin install seo-analysis-monitoring` |
+| **content-marketing** | Content strategy and web research | `/plugin install content-marketing` |
+
+### 💼 Business (3 plugins)
+
+| Plugin | Description | Install |
+|--------|-------------|---------|
+| **business-analytics** | KPI tracking and financial reporting | `/plugin install business-analytics` |
+| **hr-legal-compliance** | HR policies and legal templates | `/plugin install hr-legal-compliance` |
+| **customer-sales-automation** | Support and sales automation | `/plugin install customer-sales-automation` |
+
+### 💻 Languages (7 plugins)
+
+| Plugin | Description | Install |
+|--------|-------------|---------|
+| **python-development** | Python 3.12+ with Django/FastAPI | `/plugin install python-development` |
+| **javascript-typescript** | JavaScript/TypeScript with Node.js | `/plugin install javascript-typescript` |
+| **systems-programming** | Rust, Go, C, C++ for systems development | `/plugin install systems-programming` |
+| **jvm-languages** | Java, Scala, C# with enterprise patterns | `/plugin install jvm-languages` |
+| **web-scripting** | PHP and Ruby for web applications | `/plugin install web-scripting` |
+| **functional-programming** | Elixir with OTP and Phoenix | `/plugin install functional-programming` |
+| **arm-cortex-microcontrollers** | ARM Cortex-M firmware and drivers | `/plugin install arm-cortex-microcontrollers` |
+
+### 🔗 Blockchain (1 plugin)
+
+| Plugin | Description | Install |
+|--------|-------------|---------|
+| **blockchain-web3** | Smart contracts and DeFi protocols | `/plugin install blockchain-web3` |
+
+### 💰 Finance (1 plugin)
+
+| Plugin | Description | Install |
+|--------|-------------|---------|
+| **quantitative-trading** | Algorithmic trading and risk management | `/plugin install quantitative-trading` |
+
+### 💳 Payments (1 plugin)
+
+| Plugin | Description | Install |
+|--------|-------------|---------|
+| **payment-processing** | Stripe/PayPal integration and billing | `/plugin install payment-processing` |
+
+### 🎮 Gaming (1 plugin)
+
+| Plugin | Description | Install |
+|--------|-------------|---------|
+| **game-development** | Unity and Minecraft plugin development | `/plugin install game-development` |
+
+### ♿ Accessibility (1 plugin)
+
+| Plugin | Description | Install |
+|--------|-------------|---------|
+| **accessibility-compliance** | WCAG auditing and inclusive design | `/plugin install accessibility-compliance` |
+
+## Plugin Structure
+
+Each plugin contains:
+
+- **agents/** - Specialized agents for that domain
+- **commands/** - Tools and workflows specific to that plugin
+- **skills/** - Optional modular knowledge packages (progressive disclosure)
+
+Example:
+```
+plugins/python-development/
+├── agents/
+│   ├── python-pro.md
+│   ├── django-pro.md
+│   └── fastapi-pro.md
+├── commands/
+│   └── python-scaffold.md
+└── skills/
+    ├── async-python-patterns/
+    ├── python-testing-patterns/
+    ├── python-packaging/
+    ├── python-performance-optimization/
+    └── uv-package-manager/
+```
+
+## Installation
+
+### Step 1: Add the Marketplace
+
+```bash
+/plugin marketplace add wshobson/agents
+```
+
+This makes all 63 plugins available for installation, but **does not load any agents or tools** into your context.
+
+### Step 2: Install Specific Plugins
+
+Browse available plugins:
+
+```bash
+/plugin
+```
+
+Install only the plugins you need:
+
+```bash
+/plugin install python-development
+/plugin install backend-development
+```
+
+Each installed plugin loads **only its specific agents and commands** into Claude's context.
+
+## Plugin Design Principles
+
+### Single Responsibility
+- Each plugin does **one thing well** (Unix philosophy)
+- Clear, focused purposes (describable in 5-10 words)
+- Average plugin size: **3.4 components** (follows Anthropic's 2-8 pattern)
+
+### Minimal Token Usage
+- Install only what you need
+- Each plugin loads only its specific agents and tools
+- No unnecessary resources loaded into context
+- Better context efficiency with granular plugins
+
+### Composability
+- Mix and match plugins for complex workflows
+- Workflow orchestrators compose focused plugins
+- Clear boundaries between plugins
+- No forced feature bundling
+
+## See Also
+
+- [Agent Skills](./agent-skills.md) - 47 specialized skills across plugins
+- [Agent Reference](./agents.md) - Complete agent catalog
+- [Usage Guide](./usage.md) - Commands and workflows
+- [Architecture](./architecture.md) - Design principles
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -0,0 +1,371 @@
+# Usage Guide
+
+Complete guide to using agents, slash commands, and multi-agent workflows.
+
+## Overview
+
+The plugin ecosystem provides two primary interfaces:
+
+1. **Slash Commands** - Direct invocation of tools and workflows
+2. **Natural Language** - Claude reasons about which agents to use
+
+## Slash Commands
+
+Slash commands are the primary interface for working with agents and workflows. Each plugin provides namespaced commands that you can run directly.
+
+### Command Format
+
+```bash
+/plugin-name:command-name [arguments]
+```
+
+### Discovering Commands
+
+List all available slash commands from installed plugins:
+
+```bash
+/plugin
+```
+
+### Benefits of Slash Commands
+
+- **Direct invocation** - No need to describe what you want in natural language
+- **Structured arguments** - Pass parameters explicitly for precise control
+- **Composability** - Chain commands together for complex workflows
+- **Discoverability** - Use `/plugin` to see all available commands
+
+## Natural Language
+
+Agents can also be invoked through natural language when you need Claude to reason about which specialist to use:
+
+```
+"Use backend-architect to design the authentication API"
+"Have security-auditor scan for OWASP vulnerabilities"
+"Get performance-engineer to optimize this database query"
+```
+
+Claude Code automatically selects and coordinates the appropriate agents based on your request.
+
+## Command Reference by Category
+
+### Development & Features
+
+| Command | Description |
+|---------|-------------|
+| `/backend-development:feature-development` | End-to-end backend feature development |
+| `/full-stack-orchestration:full-stack-feature` | Complete full-stack feature implementation |
+| `/multi-platform-apps:multi-platform` | Cross-platform app development coordination |
+
+### Testing & Quality
+
+| Command | Description |
+|---------|-------------|
+| `/unit-testing:test-generate` | Generate comprehensive unit tests |
+| `/tdd-workflows:tdd-cycle` | Complete TDD red-green-refactor cycle |
+| `/tdd-workflows:tdd-red` | Write failing tests first |
+| `/tdd-workflows:tdd-green` | Implement code to pass tests |
+| `/tdd-workflows:tdd-refactor` | Refactor with passing tests |
+
+### Code Quality & Review
+
+| Command | Description |
+|---------|-------------|
+| `/code-review-ai:ai-review` | AI-powered code review |
+| `/comprehensive-review:full-review` | Multi-perspective analysis |
+| `/comprehensive-review:pr-enhance` | Enhance pull requests |
+
+### Debugging & Troubleshooting
+
+| Command | Description |
+|---------|-------------|
+| `/debugging-toolkit:smart-debug` | Interactive smart debugging |
+| `/incident-response:incident-response` | Production incident management |
+| `/incident-response:smart-fix` | Automated incident resolution |
+| `/error-debugging:error-analysis` | Deep error analysis |
+| `/error-debugging:error-trace` | Stack trace debugging |
+| `/error-diagnostics:smart-debug` | Smart diagnostic debugging |
+| `/distributed-debugging:debug-trace` | Distributed system tracing |
+
+### Security
+
+| Command | Description |
+|---------|-------------|
+| `/security-scanning:security-hardening` | Comprehensive security hardening |
+| `/security-scanning:security-sast` | Static application security testing |
+| `/security-scanning:security-dependencies` | Dependency vulnerability scanning |
+| `/security-compliance:compliance-check` | SOC2/HIPAA/GDPR compliance |
+| `/frontend-mobile-security:xss-scan` | XSS vulnerability scanning |
+
+### Infrastructure & Deployment
+
+| Command | Description |
+|---------|-------------|
+| `/observability-monitoring:monitor-setup` | Setup monitoring infrastructure |
+| `/observability-monitoring:slo-implement` | Implement SLO/SLI metrics |
+| `/deployment-validation:config-validate` | Pre-deployment validation |
+| `/cicd-automation:workflow-automate` | CI/CD pipeline automation |
+
+### Data & ML
+
+| Command | Description |
+|---------|-------------|
+| `/machine-learning-ops:ml-pipeline` | ML training pipeline orchestration |
+| `/data-engineering:data-pipeline` | ETL/ELT pipeline construction |
+| `/data-engineering:data-driven-feature` | Data-driven feature development |
+
+### Documentation
+
+| Command | Description |
+|---------|-------------|
+| `/code-documentation:doc-generate` | Generate comprehensive documentation |
+| `/code-documentation:code-explain` | Explain code functionality |
+| `/documentation-generation:doc-generate` | OpenAPI specs, diagrams, tutorials |
+
+### Refactoring & Maintenance
+
+| Command | Description |
+|---------|-------------|
+| `/code-refactoring:refactor-clean` | Code cleanup and refactoring |
+| `/code-refactoring:tech-debt` | Technical debt management |
+| `/codebase-cleanup:deps-audit` | Dependency auditing |
+| `/codebase-cleanup:tech-debt` | Technical debt reduction |
+| `/framework-migration:legacy-modernize` | Legacy code modernization |
+| `/framework-migration:code-migrate` | Framework migration |
+| `/framework-migration:deps-upgrade` | Dependency upgrades |
+
+### Database
+
+| Command | Description |
+|---------|-------------|
+| `/database-migrations:sql-migrations` | SQL migration automation |
+| `/database-migrations:migration-observability` | Migration monitoring |
+| `/database-cloud-optimization:cost-optimize` | Database and cloud optimization |
+
+### Git & PR Workflows
+
+| Command | Description |
+|---------|-------------|
+| `/git-pr-workflows:pr-enhance` | Enhance pull request quality |
+| `/git-pr-workflows:onboard` | Team onboarding automation |
+| `/git-pr-workflows:git-workflow` | Git workflow automation |
+
+### Project Scaffolding
+
+| Command | Description |
+|---------|-------------|
+| `/python-development:python-scaffold` | FastAPI/Django project setup |
+| `/javascript-typescript:typescript-scaffold` | Next.js/React + Vite setup |
+| `/systems-programming:rust-project` | Rust project scaffolding |
+
+### AI & LLM Development
+
+| Command | Description |
+|---------|-------------|
+| `/llm-application-dev:langchain-agent` | LangChain agent development |
+| `/llm-application-dev:ai-assistant` | AI assistant implementation |
+| `/llm-application-dev:prompt-optimize` | Prompt engineering optimization |
+| `/agent-orchestration:multi-agent-optimize` | Multi-agent optimization |
+| `/agent-orchestration:improve-agent` | Agent improvement workflows |
+
+### Testing & Performance
+
+| Command | Description |
+|---------|-------------|
+| `/performance-testing-review:ai-review` | Performance analysis |
+| `/application-performance:performance-optimization` | App optimization |
+
+### Team Collaboration
+
+| Command | Description |
+|---------|-------------|
+| `/team-collaboration:issue` | Issue management automation |
+| `/team-collaboration:standup-notes` | Standup notes generation |
+
+### Accessibility
+
+| Command | Description |
+|---------|-------------|
+| `/accessibility-compliance:accessibility-audit` | WCAG compliance auditing |
+
+### API Development
+
+| Command | Description |
+|---------|-------------|
+| `/api-testing-observability:api-mock` | API mocking and testing |
+
+### Context Management
+
+| Command | Description |
+|---------|-------------|
+| `/context-management:context-save` | Save conversation context |
+| `/context-management:context-restore` | Restore previous context |
+
+## Multi-Agent Workflow Examples
+
+Plugins provide pre-configured multi-agent workflows accessible via slash commands.
+
+### Full-Stack Development
+
+```bash
+# Command-based workflow invocation
+/full-stack-orchestration:full-stack-feature "user dashboard with real-time analytics"
+
+# Natural language alternative
+"Implement user dashboard with real-time analytics"
+```
+
+**Orchestration:** backend-architect → database-architect → frontend-developer → test-automator → security-auditor → deployment-engineer → observability-engineer
+
+**What happens:**
+
+1. Database schema design with migrations
+2. Backend API implementation (REST/GraphQL)
+3. Frontend components with state management
+4. Comprehensive test suite (unit/integration/E2E)
+5. Security audit and hardening
+6. CI/CD pipeline setup with feature flags
+7. Observability and monitoring configuration
+
+### Security Hardening
+
+```bash
+# Comprehensive security assessment and remediation
+/security-scanning:security-hardening --level comprehensive
+
+# Natural language alternative
+"Perform security audit and implement OWASP best practices"
+```
+
+**Orchestration:** security-auditor → backend-security-coder → frontend-security-coder → mobile-security-coder → test-automator
+
+### Data/ML Pipeline
+
+```bash
+# ML feature development with production deployment
+/machine-learning-ops:ml-pipeline "customer churn prediction model"
+
+# Natural language alternative
+"Build customer churn prediction model with deployment"
+```
+
+**Orchestration:** data-scientist → data-engineer → ml-engineer → mlops-engineer → performance-engineer
+
+### Incident Response
+
+```bash
+# Smart debugging with root cause analysis
+/incident-response:smart-fix "production memory leak in payment service"
+
+# Natural language alternative
+"Debug production memory leak and create runbook"
+```
+
+**Orchestration:** incident-responder → devops-troubleshooter → debugger → error-detective → observability-engineer
+
+## Command Arguments and Options
+
+Many slash commands support arguments for precise control:
+
+```bash
+# Test generation for specific files
+/unit-testing:test-generate src/api/users.py
+
+# Feature development with methodology specification
+/backend-development:feature-development OAuth2 integration with social login
+
+# Security dependency scanning
+/security-scanning:security-dependencies
+
+# Component scaffolding
+/frontend-mobile-development:component-scaffold UserProfile component with hooks
+
+# TDD workflow cycle
+/tdd-workflows:tdd-red User can reset password
+/tdd-workflows:tdd-green
+/tdd-workflows:tdd-refactor
+
+# Smart debugging
+/debugging-toolkit:smart-debug memory leak in checkout flow
+
+# Python project scaffolding
+/python-development:python-scaffold fastapi-microservice
+```
+
+## Combining Natural Language and Commands
+
+You can mix both approaches for optimal flexibility:
+
+```
+# Start with a command for structured workflow
+/full-stack-orchestration:full-stack-feature "payment processing"
+
+# Then provide natural language guidance
+"Ensure PCI-DSS compliance and integrate with Stripe"
+"Add retry logic for failed transactions"
+"Set up fraud detection rules"
+```
+
+## Best Practices
+
+### When to Use Slash Commands
+
+- **Structured workflows** - Multi-step processes with clear phases
+- **Repetitive tasks** - Operations you perform frequently
+- **Precise control** - When you need specific parameters
+- **Discovery** - Exploring available functionality
+
+### When to Use Natural Language
+
+- **Exploratory work** - When you're not sure which tool to use
+- **Complex reasoning** - When Claude needs to coordinate multiple agents
+- **Contextual decisions** - When the right approach depends on the situation
+- **Ad-hoc tasks** - One-off operations that don't fit a command
+
+### Workflow Composition
+
+Compose multiple plugins for complex scenarios:
+
+```bash
+# 1. Start with feature development
+/backend-development:feature-development payment processing API
+
+# 2. Add security hardening
+/security-scanning:security-hardening
+
+# 3. Generate comprehensive tests
+/unit-testing:test-generate
+
+# 4. Review the implementation
+/code-review-ai:ai-review
+
+# 5. Set up CI/CD
+/cicd-automation:workflow-automate
+
+# 6. Add monitoring
+/observability-monitoring:monitor-setup
+```
+
+## Agent Skills Integration
+
+Agent Skills work alongside commands to provide deep expertise:
+
+```
+User: "Set up FastAPI project with async patterns"
+→ Activates: fastapi-templates skill
+→ Invokes: /python-development:python-scaffold
+→ Result: Production-ready FastAPI project with best practices
+
+User: "Implement Kubernetes deployment with Helm"
+→ Activates: helm-chart-scaffolding, k8s-manifest-generator skills
+→ Guides: kubernetes-architect agent
+→ Result: Production-grade K8s manifests with Helm charts
+```
+
+See [Agent Skills](./agent-skills.md) for details on the 47 specialized skills.
+
+## See Also
+
+- [Agent Skills](./agent-skills.md) - Specialized knowledge packages
+- [Agent Reference](./agents.md) - Complete agent catalog
+- [Plugin Reference](./plugins.md) - All 63 plugins
+- [Architecture](./architecture.md) - Design principles