claude-flow 2.7.0-alpha.8 → 2.7.0

package/docs/skills-tutorial.md

@@ -0,0 +1,1251 @@
+# 🎓 Claude Flow Skills: Complete Introduction Tutorial
+
+## Overview
+
+We’re shifting how Claude Flow evolves from here forward. This release marks the move from slash commands to a true skills-based system, our new foundation for intelligence, automation, and collaboration. Instead of memorizing /commands, you now just describe what you want. Claude reads the situation, identifies the right skills, and activates them automatically.
+
+The new Skill Builder is at the heart of this system. It lets you create modular instruction sets, small, well-defined units of capability that can be shared, versioned, and composed. Each skill is a self-contained block of context with metadata, description, and progressive disclosure. Claude scans these on startup, loads what’s relevant, and builds the workflow around your intent.
+
+We’ve already included practical skills across development, teamwork, and reasoning: SPARC Methodology for structured feature building, Pair Programming for real-time collaboration, AgentDB for persistent memory, and Swarm Orchestration for distributed work.
+
+There are GitHub skills that manage reviews, automate releases, and synchronize projects. Others focus on performance, quality verification, and adaptive learning through ReasoningBank.
+
+What this means in practice is simplicity. You just speak naturally: “Build a login feature with tests,” “Review this PR,” or “Find similar code.” The right skills activate instantly, keeping your context clean and focused.
+
+This is the direction forward: modular, intelligent, and adaptive. Skills turn Claude Flow from a set of commands into a living system that learns how you work and grows with you.
+
+## 🔄 What Changed: From Slash Commands to Skills
+
+I'm transitioning claude-flow from slash commands to Claude Code's native skills system. Here's why this matters and what I've learned.
+
+### The Old Way: Slash Commands
+
+Previously, claude-flow used slash commands stored in `.claude/commands/`:
+```bash
+# Old approach
+/.claude/commands/sparc-tdd.md
+/.claude/commands/github-review.md
+/.claude/commands/swarm-init.md
+```
+
+When you typed `/sparc-tdd`, Claude would load that markdown file as a prompt and execute it. This worked, but had limitations:
+
+**Issues I Found:**
+- Commands loaded every time, even when not needed (context pollution)
+- No metadata for discovery - Claude couldn't tell when a command was relevant
+- Flat structure - all commands mixed together
+- Manual invocation required - no automatic activation
+- Limited composability - commands didn't work well together
+
+### The New Way: Skills System
+
+Anthropic released the skills API in October 2025, and I immediately saw the potential. Skills solve the command problems elegantly:
+
+```bash
+# New approach
+/.claude/skills/sparc-methodology/SKILL.md
+/.claude/skills/github-code-review/SKILL.md
+/.claude/skills/swarm-orchestration/SKILL.md
+```
+
+Each skill has YAML frontmatter with metadata:
+```yaml
+---
+name: sparc-methodology
+description: SPARC development methodology for systematic feature building
+tags: [development, tdd, methodology]
+category: development
+---
+```
+
+**Why This Is Better (In My Opinion):**
+
+1. **Automatic Discovery**: Claude scans skills at startup, reads the metadata, and only loads full content when relevant. A task about "building a feature with tests" automatically triggers SPARC methodology - no slash command needed.
+
+2. **Progressive Disclosure**: Skills use a tiered structure (overview → details → advanced). Claude gets just enough information to decide if it's useful, then loads more if needed. This keeps context clean.
+
+3. **Composability**: Skills can reference other skills. The GitHub review skill can use swarm orchestration internally without you knowing or caring. Commands couldn't do this well.
+
+4. **Organization**: Skills live in categorized directories (development/, github/, memory/). Much easier to maintain than a flat commands folder.
+
+5. **Standards-Based**: Anthropic designed this. It works across Claude.ai, Claude Code CLI, and any other Claude implementation. Commands were claude-flow specific.
+
+### Migration Strategy
+
+I'm not removing commands immediately - that would break existing workflows. Instead:
+
+- **Phase 1** (Current): Both systems work. Skills are preferred, commands still function.
+- **Phase 2** (Next release): Deprecation warnings when using old commands.
+- **Phase 3** (Future): Commands removed, full skills migration.
+
+If you're using commands like `/sparc tdd`, they still work. But I recommend switching to skills:
+```bash
+# Instead of this:
+/sparc tdd "feature name"
+
+# Do this:
+npx claude-flow@alpha init --force  # Install skills
+# Then just ask: "Build a user authentication feature with TDD"
+# The SPARC skill activates automatically
+```
+
+### Honest Assessment
+
+**What Skills Do Better:**
+- Context efficiency (40% less token usage in my testing)
+- Automatic activation based on task matching
+- Better organization and maintainability
+- Cross-platform compatibility
+
+**What Commands Did Better:**
+- Explicit invocation - you knew exactly what ran
+- Simpler mental model - type `/command`, it runs
+- No "magic" - predictable behavior
+
+**The Trade-off:**
+Skills are more sophisticated but less explicit. Sometimes I miss the directness of `/command` - you knew what you were getting. With skills, Claude decides when to activate them. Usually it gets it right, but occasionally it misses or over-activates.
+
+That said, the context savings and automatic discovery outweigh the loss of explicitness. And you can still manually invoke skills with `/skill-name` if you want that control.
+
+### Bottom Line
+
+Skills are the future of claude-flow. They align with Anthropic's vision, work better with Claude Code, and solve real problems I had with commands. The migration takes effort, but it's worth it.
+
+If you're starting fresh, use skills. If you're on commands, plan to migrate. I'll support both for now, but my development focus is on skills.
+
+## 🚀 What's New: AgentDB Integration
+
+This release adds 4 new AgentDB skills that bring production-grade vector database capabilities to claude-flow:
+
+**Performance Improvements:**
+- **150x faster** pattern retrieval (<100µs vs 15ms)
+- **500x faster** batch operations (2ms vs 1s for 100 vectors)
+- **12,500x faster** large-scale queries (8ms vs 100s at 1M vectors)
+- **4-32x memory reduction** with quantization (3GB → 96MB with binary quantization)
+
+**New Skills:**
+
+1. **`reasoningbank-agentdb`** - ReasoningBank with AgentDB backend
+   - 150x-12,500x performance improvement over legacy ReasoningBank
+   - Trajectory tracking and verdict judgment
+   - 100% backward compatible migration path
+
+2. **`agentdb-learning`** - 9 Reinforcement Learning Algorithms
+   - Decision Transformer, Q-Learning, SARSA, Actor-Critic, Curiosity-Driven
+   - 10-100x faster training with WASM acceleration
+   - Create self-learning agents from historical data
+
+3. **`agentdb-optimization`** - Performance Tuning
+   - Binary quantization (32x compression, ~2-5% accuracy loss)
+   - Scalar quantization (4x compression, ~1-2% accuracy loss)
+   - HNSW indexing for sub-100µs searches
+   - Production deployment optimization
+
+4. **`agentdb-advanced`** - Enterprise Features
+   - QUIC synchronization (<1ms cross-node latency)
+   - Multi-database management with isolated namespaces
+   - Custom distance metrics (cosine, Euclidean, Hamming)
+   - Hybrid search (vector + metadata filtering)
+
+**Why AgentDB?**
+
+The original vector search and memory systems used ChromaDB and legacy ReasoningBank. While functional, they had performance limitations at scale. AgentDB provides:
+
+- **Native TypeScript**: No Python dependency, simpler deployment
+- **WASM Acceleration**: 10-100x faster neural operations
+- **Better Compression**: 4-32x memory reduction
+- **Sub-millisecond Latency**: <1ms pattern access
+- **Distributed Sync**: QUIC protocol for multi-node coordination
+
+These skills work alongside the existing `agentdb-memory-patterns` and `agentdb-vector-search` skills, giving you a complete vector database toolkit.
+
+---
+
+## 📚 Complete Skills Catalog (25 Skills)
+
+Claude Flow includes 25 specialized skills that activate automatically based on your task description. Just describe what you want in natural language - no commands needed.
+
+### Development & Methodology (3 skills)
+
+1. **`skill-builder`** - Create custom Claude Code skills with YAML frontmatter and progressive disclosure
+2. **`sparc-methodology`** - SPARC development methodology (Specification, Pseudocode, Architecture, Refinement, Completion) with TDD
+3. **`pair-programming`** - Driver/navigator pair programming with real-time verification and quality monitoring
+
+### Intelligence & Memory (6 skills)
+
+4. **`agentdb-memory-patterns`** - Persistent agent memory with session storage and long-term context management
+5. **`agentdb-vector-search`** - Semantic vector search for intelligent document retrieval and similarity matching
+6. **`reasoningbank-agentdb`** - ReasoningBank with 150x-12,500x faster AgentDB backend for experience learning
+7. **`agentdb-learning`** - 9 reinforcement learning algorithms (Decision Transformer, Q-Learning, SARSA, Actor-Critic, etc.)
+8. **`agentdb-optimization`** - Performance optimization with quantization (4-32x compression) and HNSW indexing
+9. **`agentdb-advanced`** - QUIC synchronization, multi-database management, custom metrics, hybrid search
+
+### Swarm Coordination (3 skills)
+
+10. **`swarm-orchestration`** - Multi-agent swarm coordination with parallel task execution and dynamic topology
+11. **`swarm-advanced`** - Advanced swarm patterns for research, development, testing, and complex workflows
+12. **`hive-mind-advanced`** - Queen-led hierarchical coordination with consensus mechanisms and persistent memory
+
+### GitHub Integration (5 skills)
+
+13. **`github-code-review`** - AI-powered comprehensive code reviews with multi-agent analysis
+14. **`github-workflow-automation`** - Intelligent CI/CD pipeline creation and optimization with GitHub Actions
+15. **`github-project-management`** - Issue tracking, project board automation, and sprint planning
+16. **`github-release-management`** - Release orchestration with versioning, testing, deployment, and rollback
+17. **`github-multi-repo`** - Cross-repository synchronization and multi-package integration
+
+### Automation & Quality (4 skills)
+
+18. **`hooks-automation`** - Pre/post task hooks with automated formatting, learning, and session management
+19. **`verification-quality`** - Truth scoring and automatic rollback with 0.95 accuracy threshold
+20. **`performance-analysis`** - Bottleneck detection and optimization recommendations for workflows
+21. **`stream-chain`** - Stream-JSON chaining for multi-agent pipelines and data transformation
+
+### Flow Nexus Platform (3 skills)
+
+22. **`flow-nexus-platform`** - Cloud platform management (authentication, sandboxes, apps, payments)
+23. **`flow-nexus-swarm`** - Cloud-based AI swarm deployment with event-driven workflow automation
+24. **`flow-nexus-neural`** - Distributed neural network training in E2B sandboxes with cloud compute
+
+### Reasoning & Learning (1 skill)
+
+25. **`reasoningbank-intelligence`** - Adaptive learning with pattern recognition and strategy optimization
+
+---
+
+## 📦 Getting Started: Installation & Setup
+
+### What Does `npx claude-flow@alpha init --force` Do?
+
+This command initializes your project with Claude Flow's complete skills system:
+
+**What It Does:**
+1. **Creates `.claude/skills/` directory** - Where all 25 skills are installed
+2. **Copies skill modules** - Installs pre-built skills for development, GitHub, memory, and more
+3. **Sets up configuration** - Creates `claude-flow.json` with default settings
+4. **Initializes hooks** - Installs automation hooks for pre/post task coordination
+5. **Creates statusline** - Adds terminal statusline showing active swarms and tasks
+6. **Force overwrites** - The `--force` flag replaces existing files (useful for updates)
+
+**When to Use It:**
+- Starting a new project with Claude Flow
+- Adding skills to an existing project
+- Updating to the latest skills (with `--force`)
+- Resetting corrupted skill configurations
+
+**Usage:**
+```bash
+# Initialize in current project
+npx claude-flow@alpha init --force
+
+# What you'll see:
+# ✓ Created .claude/skills/ directory
+# ✓ Installed 25 skills
+# ✓ Configured hooks automation
+# ✓ Setup statusline integration
+# ✓ Ready to use skills!
+```
+
+**After Installation:**
+- Skills are automatically discovered by Claude Code at startup
+- Skills activate automatically when your task description matches their purpose
+- **Use natural language** to invoke skills - just describe what you want to do
+- Example: Say "use vector search to find similar code" instead of typing `/agentdb-vector-search`
+- No configuration needed - it just works!
+
+---
+
+## 🎨 Development Skills
+
+### 1. `skill-builder` - Create Your Own Skills
+
+**What It Does:**
+Helps you create custom Claude Code skills with proper structure, YAML frontmatter, and progressive disclosure.
+
+**When to Use:**
+- Building domain-specific knowledge modules
+- Creating team-specific workflows
+- Documenting project patterns for AI to follow
+- Standardizing development approaches
+
+**Plain Language:**
+Think of it as a "skill factory" - it teaches Claude how to build new skills that other Claude instances can discover and use.
+
+**Usage:**
+```bash
+# Natural language invocation - skill activates automatically
+"Create a new skill for React component development following our team's patterns"
+"Build a custom skill for API endpoint testing with our authentication flow"
+"Help me make a skill that knows our database schema conventions"
+
+# The skill-builder skill activates when you mention creating/building skills
+```
+
+**What You Get:**
+- Properly formatted `SKILL.md` file
+- YAML frontmatter with metadata
+- Progressive disclosure sections
+- Auto-organized in `.claude/skills/`
+
+---
+
+### 2. `sparc-methodology` - Systematic Development
+
+**What It Does:**
+Implements SPARC (Specification, Pseudocode, Architecture, Refinement, Completion) - a five-phase development methodology for building features systematically.
+
+**When to Use:**
+- Building complex new features
+- Refactoring large systems
+- Planning before coding
+- Working with distributed teams
+
+**Plain Language:**
+SPARC breaks development into five steps: (1) Define what you need, (2) Write algorithm logic, (3) Design the system, (4) Build with tests, (5) Integrate everything. It prevents "code first, think later" problems.
+
+**Usage:**
+```bash
+# Full SPARC workflow
+npx claude-flow sparc tdd "user authentication system"
+
+# Individual phases
+npx claude-flow sparc run spec-pseudocode "shopping cart feature"
+npx claude-flow sparc run architect "payment processing"
+
+# Check available modes
+npx claude-flow sparc modes
+```
+
+**What You Get:**
+- Specification documents
+- Pseudocode algorithms
+- Architecture diagrams (as text)
+- Test-driven implementation
+- Integration plan
+
+---
+
+### 3. `pair-programming` - AI Pair Programming
+
+**What It Does:**
+Provides driver/navigator pair programming modes with real-time verification, quality monitoring, and automatic role switching.
+
+**When to Use:**
+- Learning new technologies
+- Debugging complex issues
+- Code reviews while coding
+- Test-driven development sessions
+
+**Plain Language:**
+Like having an experienced developer sitting next to you. Claude can "drive" (write code while you watch) or "navigate" (guide you while you code). Roles can switch automatically, and there's continuous quality checking.
+
+**Usage:**
+```bash
+# Natural language invocation - skill activates automatically
+"Let's pair program on this React component - you drive first"
+"Switch to navigator mode and review my authentication code"
+"I need help debugging - this function isn't working as expected"
+
+# The skill activates when you mention pair programming or collaborative coding
+```
+
+**Modes Available:**
+- **Driver Mode**: Claude writes code, you review
+- **Navigator Mode**: You code, Claude guides
+- **Switch Mode**: Automatic role swapping
+- **TDD Mode**: Test-first development
+- **Debug Mode**: Problem-solving focus
+
+---
+
+## 🧠 Intelligence & Memory Skills
+
+### 4. `agentdb-memory-patterns` - Persistent Agent Memory
+
+**What It Does:**
+Implements persistent memory patterns for AI agents - session memory, long-term storage, pattern learning, and context management.
+
+**When to Use:**
+- Building chatbots that remember conversations
+- Creating agents that learn from experience
+- Storing project context across sessions
+- Sharing knowledge between agents
+
+**Plain Language:**
+Gives Claude a "long-term memory" that survives beyond single conversations. Like taking notes that Claude can reference later, even in different sessions.
+
+**Usage:**
+```bash
+# Natural language invocation - skill activates automatically
+"Store our API design decisions in long-term memory"
+"Remember this user's preferences for future sessions"
+"Create a memory pattern for tracking bug fixes"
+
+# The skill activates when you mention memory, persistence, or storing context
+```
+
+**Memory Types:**
+- **Session Memory**: Temporary, conversation-scoped
+- **Long-term Storage**: Permanent, cross-session
+- **Pattern Learning**: Learns from past interactions
+- **Context Management**: Maintains relevant context
+
+---
+
+### 5. `agentdb-vector-search` - Semantic Search
+
+**What It Does:**
+Implements semantic vector search for intelligent document retrieval, similarity matching, and context-aware querying.
+
+**When to Use:**
+- Building RAG (Retrieval Augmented Generation) systems
+- Searching code by meaning, not just keywords
+- Finding similar issues/bugs
+- Intelligent documentation search
+
+**Plain Language:**
+Instead of searching for exact word matches, this searches by *meaning*. Ask "how do we handle errors?" and it finds relevant code even if it doesn't contain those exact words.
+
+**Usage:**
+```bash
+# Natural language invocation - skill activates automatically
+"Find all code that handles user authentication"
+"Search for functions similar to calculateDiscount()"
+"Use vector search to retrieve documentation about error handling patterns"
+
+# The skill activates when you mention semantic search, finding similar code, or vector search
+```
+
+**What You Get:**
+- Semantic similarity matching
+- Context-aware results
+- Ranked by relevance
+- Works with code, docs, and data
+
+---
+
+### 6. `reasoningbank-agentdb` - ReasoningBank Integration
+
+**What It Does:**
+Implements ReasoningBank adaptive learning with AgentDB's high-performance backend (150x-12,500x faster). Enables agents to learn from experiences, judge outcomes, distill memories, and improve decision-making over time.
+
+**When to Use:**
+- Building self-learning agents that improve from experience
+- Implementing experience replay and trajectory tracking
+- Optimizing decision-making through pattern recognition
+- Migrating from legacy ReasoningBank systems
+
+**Plain Language:**
+ReasoningBank teaches agents to learn from their experiences. Every time an agent completes a task, it stores what worked, what didn't, and why. Next time it faces a similar problem, it recalls successful patterns and avoids failures. AgentDB makes this 150x faster than before.
+
+**Usage:**
+```bash
+# Natural language invocation - skill activates automatically
+"Setup ReasoningBank with AgentDB for this project"
+"Remember this bug fix approach for future similar issues"
+"Migrate existing ReasoningBank data to AgentDB"
+
+# The skill activates when you mention ReasoningBank, learning from experiences, or pattern tracking
+```
+
+**Performance Benefits:**
+- **150x faster pattern retrieval** (100µs vs 15ms)
+- **500x faster batch operations** (2ms vs 1s for 100 patterns)
+- **12,500x faster large-scale queries** (8ms vs 100s at 1M patterns)
+- **<1ms memory access** for real-time decision making
+
+**Key Features:**
+- **Trajectory Tracking**: Records agent action sequences and outcomes
+- **Verdict Judgment**: Evaluates success/failure of approaches
+- **Memory Distillation**: Compresses experiences into learned patterns
+- **100% Backward Compatible**: Drop-in replacement for legacy ReasoningBank
+
+---
+
+### 7. `agentdb-learning` - Learning Plugins & Algorithms
+
+**What It Does:**
+Provides 9 reinforcement learning algorithms via AgentDB's plugin system. Create, train, and deploy learning plugins for autonomous agents that improve through experience - includes Decision Transformer, Q-Learning, SARSA, Actor-Critic, and more.
+
+**When to Use:**
+- Building self-learning autonomous agents
+- Implementing reinforcement learning systems
+- Training agents on custom tasks
+- Optimizing agent behavior through experience
+
+**Plain Language:**
+Instead of programming every behavior, you train agents to learn optimal strategies through trial and error. Like teaching a dog tricks - reward good behavior, correct mistakes, and the agent learns what works best.
+
+**Usage:**
+```bash
+# Natural language invocation - skill activates automatically
+"Create a Decision Transformer plugin for code optimization tasks"
+"Train a Q-Learning agent on our deployment success/failure data"
+"Show me all available learning plugin templates"
+
+# The skill activates when you mention reinforcement learning, training agents, or learning algorithms
+```
+
+**Available Algorithms:**
+
+1. **Decision Transformer** (Recommended)
+   - Sequence modeling approach to RL
+   - Learns from offline data (no environment needed)
+   - Best for: Code generation, task planning, decision sequences
+
+2. **Q-Learning**
+   - Value-based learning
+   - Learns optimal action values
+   - Best for: Discrete actions, simple environments
+
+3. **SARSA**
+   - On-policy temporal difference learning
+   - More conservative than Q-Learning
+   - Best for: Safety-critical applications
+
+4. **Actor-Critic**
+   - Policy gradient with value baseline
+   - Continuous action spaces
+   - Best for: Complex control tasks, optimization
+
+5. **Curiosity-Driven**
+   - Exploration-based learning
+   - Intrinsic motivation
+   - Best for: Sparse reward environments, discovery
+
+**Training Performance:**
+- 10-100x faster training with WASM acceleration
+- Supports batch learning from historical data
+- Real-time online learning capability
+
+---
+
+### 8. `agentdb-optimization` - Performance Optimization
+
+**What It Does:**
+Comprehensive performance optimization for AgentDB vector databases - quantization (4-32x memory reduction), HNSW indexing (150x faster search), caching strategies, and batch operations.
+
+**When to Use:**
+- Optimizing memory usage in vector databases
+- Improving search speed for large datasets
+- Scaling to millions of vectors
+- Deploying to memory-constrained environments (mobile, edge)
+
+**Plain Language:**
+Makes vector databases smaller and faster. Binary quantization compresses vectors by 32x (3GB becomes 96MB) with minimal accuracy loss. HNSW indexing makes searches 150x faster. Like compressing a movie file - it takes less space and loads faster, but you barely notice the quality difference.
+
+**Usage:**
+```bash
+# Natural language invocation - skill activates automatically
+"Benchmark my AgentDB performance"
+"Optimize this database with binary quantization for production"
+"Analyze memory usage and suggest optimizations"
+
+# The skill activates when you mention optimization, performance, quantization, or benchmarking
+```
+
+**Optimization Techniques:**
+
+**1. Binary Quantization (32x Compression)**
+- Converts float32 vectors to binary
+- 768-dim vector: 3072 bytes → 96 bytes
+- 1M vectors: 3GB → 96MB
+- Trade-off: ~2-5% accuracy loss
+- Use for: Mobile apps, large-scale deployments
+
+**2. Scalar Quantization (4x Compression)**
+- Converts float32 to int8
+- Balanced compression vs accuracy
+- 768-dim vector: 3072 bytes → 768 bytes
+- Trade-off: ~1-2% accuracy loss
+- Use for: Most production applications
+
+**3. HNSW Indexing**
+- Hierarchical navigable small world graphs
+- 150x faster search
+- Sub-100µs vector queries
+- Use for: Real-time search, high-throughput systems
+
+**4. Caching Strategies**
+- In-memory pattern cache
+- LRU eviction policy
+- <1ms access for frequent queries
+- Use for: Repeated pattern matching
+
+**Performance Numbers:**
+- Pattern Search: **<100µs** (150x faster)
+- Batch Insert: **2ms for 100 vectors** (500x faster)
+- Large-scale Query: **8ms at 1M vectors** (12,500x faster)
+
+---
+
+### 9. `agentdb-advanced` - Advanced Features
+
+**What It Does:**
+Master advanced AgentDB capabilities - QUIC synchronization (<1ms cross-node), multi-database management, custom distance metrics, hybrid search (vector + metadata), and distributed systems integration.
+
+**When to Use:**
+- Building distributed AI systems with multi-node coordination
+- Implementing custom similarity metrics for specialized domains
+- Creating hybrid search with metadata filtering
+- Deploying cross-datacenter vector databases
+
+**Plain Language:**
+Advanced features for production systems. QUIC sync lets multiple databases stay synchronized with sub-millisecond latency - like having a shared brain across multiple servers. Hybrid search combines semantic similarity with filters (find similar code, but only Python files modified this month).
+
+**Usage:**
+```bash
+# Natural language invocation - skill activates automatically
+"Setup QUIC sync between 3 database nodes"
+"Search for similar authentication code, but only in TypeScript files"
+"Use cosine similarity for text, Euclidean for embeddings"
+
+# The skill activates when you mention QUIC, distributed sync, hybrid search, or custom metrics
+```
+
+**Advanced Capabilities:**
+
+**1. QUIC Synchronization**
+- Sub-millisecond cross-node latency (<1ms)
+- Automatic retry and recovery
+- Built-in encryption (TLS 1.3)
+- Multiplexed streams
+- Use for: Distributed agents, multi-datacenter deployment
+
+**2. Multi-Database Management**
+- Manage multiple specialized databases
+- Per-domain vector spaces
+- Isolated namespaces
+- Use for: Multi-tenant systems, domain separation
+
+**3. Custom Distance Metrics**
+- Cosine similarity (text/embeddings)
+- Euclidean distance (spatial data)
+- Hamming distance (binary vectors)
+- Custom metrics via callbacks
+- Use for: Specialized similarity requirements
+
+**4. Hybrid Search**
+- Combine vector similarity + metadata filters
+- SQL-like filtering on vector results
+- Multi-field queries
+- Use for: Complex search requirements
+
+**Example QUIC Deployment:**
+```typescript
+// Node 1 syncs with Nodes 2 & 3
+const db1 = await createAdapter({
+  enableQUICSync: true,
+  syncPeers: ['node2:4433', 'node3:4433'],
+});
+
+// Pattern inserted on Node 1
+await db1.insertPattern({ /* ... */ });
+
+// Available on Nodes 2 & 3 within ~1ms
+```
+
+**Performance:**
+- QUIC Sync: <1ms cross-node latency
+- Hybrid Search: Maintains <100µs base vector search
+- Custom Metrics: Negligible overhead with WASM
+
+---
+
+### 10. `reasoningbank-intelligence` - Adaptive Learning
+
+**What It Does:**
+Implements adaptive learning with ReasoningBank for pattern recognition, strategy optimization, and continuous improvement.
+
+**When to Use:**
+- Building self-improving agents
+- Optimizing workflows over time
+- Learning from past mistakes
+- Meta-cognitive systems
+
+**Plain Language:**
+Claude learns from experience. If a certain approach works well, it remembers and uses it again. If something fails, it learns to avoid that pattern.
+
+**Usage:**
+```bash
+# Natural language invocation - skill activates automatically
+"Learn from this successful deployment and optimize future ones"
+"Analyze our testing patterns and suggest improvements"
+"Remember this bug fix strategy for similar issues"
+
+# The skill activates when you mention adaptive learning, pattern recognition, or strategy optimization
+```
+
+**Capabilities:**
+- Pattern recognition
+- Strategy optimization
+- Continuous improvement
+- Learning from feedback
+
+---
+
+## 🐝 Coordination Skills
+
+### 7. `swarm-orchestration` - Multi-Agent Coordination
+
+**What It Does:**
+Orchestrates multi-agent swarms with agentic-flow for parallel task execution, dynamic topology, and intelligent coordination.
+
+**When to Use:**
+- Complex projects needing multiple specialists
+- Parallel development tasks
+- Distributed problem-solving
+- Scaling beyond single agent limits
+
+**Plain Language:**
+Instead of one Claude doing everything, this spawns multiple specialized Claudes working together. One might research while another codes, another tests - all in parallel.
+
+**Usage:**
+```bash
+# Natural language invocation - skill activates automatically
+"Create a swarm to build a REST API - researcher, coder, tester, reviewer"
+"Orchestrate parallel agents for frontend, backend, and database work"
+"Spawn a swarm to analyze this codebase from multiple angles"
+
+# The skill activates when you mention swarms, multi-agent coordination, or parallel agents
+```
+
+**Topologies:**
+- **Mesh**: Peer-to-peer, all agents collaborate
+- **Hierarchical**: Tree structure, delegated tasks
+- **Ring**: Sequential processing
+- **Star**: Central coordinator
+
+---
+
+### 8. `swarm-advanced` - Advanced Swarm Patterns
+
+**What It Does:**
+Advanced swarm patterns for research, development, testing, and complex distributed workflows.
+
+**When to Use:**
+- Enterprise-scale projects
+- Research projects needing deep analysis
+- Complex testing scenarios
+- Multi-repo coordination
+
+**Plain Language:**
+Takes swarm orchestration to the next level with specialized patterns for specific workflows - research swarms dig deep into topics, development swarms handle full SDLC, testing swarms verify from multiple angles.
+
+**Usage:**
+```bash
+# Natural language invocation - skill activates automatically
+"Launch a research swarm to analyze market trends in our domain"
+"Deploy a development swarm for microservices architecture"
+"Create a testing swarm with unit, integration, and E2E specialists"
+
+# The skill activates when you mention advanced swarm patterns, research swarms, or complex workflows
+```
+
+**Patterns:**
+- **Research Swarm**: Multi-angle analysis
+- **Development Swarm**: Full-stack coordination
+- **Testing Swarm**: Comprehensive verification
+- **Optimization Swarm**: Performance tuning
+
+---
+
+### 9. `hive-mind-advanced` - Collective Intelligence
+
+**What It Does:**
+Queen-led hierarchical multi-agent coordination with consensus mechanisms and persistent memory.
+
+**When to Use:**
+- Large-scale projects needing central coordination
+- Decision-making with multiple perspectives
+- Complex systems requiring consensus
+- Strategic planning with tactical execution
+
+**Plain Language:**
+A "queen bee" agent coordinates specialized "worker" agents. The queen makes strategic decisions, workers execute tasks, and they reach consensus through voting mechanisms.
+
+**Usage:**
+```bash
+# Natural language invocation - skill activates automatically
+"Deploy a hive mind for our microservices migration project"
+"Create a queen coordinator with worker agents for each service"
+"Use consensus for architectural decisions"
+
+# The skill activates when you mention hive mind, queen coordinator, or consensus-based coordination
+```
+
+**Structure:**
+- **Queen**: Strategic coordinator
+- **Workers**: Specialized executors
+- **Scouts**: Information gatherers
+- **Consensus**: Democratic decision-making
+
+---
+
+## 🐙 GitHub Integration Skills
+
+### 10. `github-code-review` - AI Code Reviews
+
+**What It Does:**
+Deploy specialized AI agents for comprehensive, intelligent code reviews beyond traditional static analysis.
+
+**When to Use:**
+- Pull request reviews
+- Security audits
+- Code quality checks
+- Best practice enforcement
+
+**Plain Language:**
+Multiple AI reviewers examine your code from different angles: one checks security, another performance, another readability. Like having a senior dev team review every PR.
+
+**Usage:**
+```bash
+# Natural language invocation - skill activates automatically
+"Review PR #42 in this repository"
+"Analyze security vulnerabilities in the authentication module"
+"Check code quality and suggest improvements"
+
+# The skill activates when you mention PR review, code review, or security analysis
+```
+
+**Review Types:**
+- **Security**: Vulnerability scanning
+- **Performance**: Bottleneck detection
+- **Quality**: Code smells and patterns
+- **Best Practices**: Convention compliance
+
+---
+
+### 11. `github-workflow-automation` - CI/CD Intelligence
+
+**What It Does:**
+Creates intelligent, self-organizing CI/CD pipelines with adaptive multi-agent coordination and automated optimization.
+
+**When to Use:**
+- Setting up GitHub Actions
+- Optimizing build pipelines
+- Automating deployments
+- Creating test workflows
+
+**Plain Language:**
+Builds smart CI/CD pipelines that adapt to your project. They learn which tests fail often, optimize build times, and automatically handle common deployment patterns.
+
+**Usage:**
+```bash
+# Natural language invocation - skill activates automatically
+"Create a GitHub Actions workflow for Node.js testing and deployment"
+"Optimize our existing CI pipeline for faster builds"
+"Setup automated releases with semantic versioning"
+
+# The skill activates when you mention GitHub Actions, CI/CD, or workflow automation
+```
+
+**Features:**
+- Auto-generated workflows
+- Performance optimization
+- Intelligent caching
+- Self-healing pipelines
+
+---
+
+### 12. `github-project-management` - Project Coordination
+
+**What It Does:**
+Swarm-coordinated issue tracking, project board automation, and sprint planning.
+
+**When to Use:**
+- Managing GitHub Projects
+- Sprint planning and tracking
+- Issue triage and prioritization
+- Team coordination
+
+**Plain Language:**
+Automates project management tasks - triages issues, updates project boards, tracks sprint progress, and coordinates team work using AI swarms.
+
+**Usage:**
+```bash
+# Natural language invocation - skill activates automatically
+"Triage all open issues and categorize by priority"
+"Update project board based on PR statuses"
+"Plan next sprint based on velocity and priorities"
+
+# The skill activates when you mention issue triage, project boards, or sprint planning
+```
+
+**Capabilities:**
+- Issue triage
+- Board automation
+- Sprint planning
+- Progress tracking
+
+---
+
+### 13. `github-release-management` - Release Orchestration
+
+**What It Does:**
+Orchestrates complex releases using AI swarms for automated versioning, testing, deployment, and rollback management.
+
+**When to Use:**
+- Creating releases
+- Managing changelogs
+- Coordinating deployments
+- Handling rollbacks
+
+**Plain Language:**
+Manages the entire release process - bumps versions, generates changelogs, runs tests, deploys to environments, and can rollback if issues occur.
+
+**Usage:**
+```bash
+# Natural language invocation - skill activates automatically
+"Create a new release v2.1.0 with changelog"
+"Deploy to staging and run smoke tests"
+"Rollback production to previous version"
+
+# The skill activates when you mention releases, deployment, changelogs, or rollback
+```
+
+**Release Steps:**
+- Version bumping
+- Changelog generation
+- Testing coordination
+- Deployment orchestration
+- Rollback capability
+
+---
+
+### 14. `github-multi-repo` - Cross-Repository Sync
+
+**What It Does:**
+Cross-repository synchronization, version alignment, and multi-package integration with intelligent swarm orchestration.
+
+**When to Use:**
+- Monorepo management
+- Multi-package projects
+- Dependency synchronization
+- Cross-repo refactoring
+
+**Plain Language:**
+Coordinates changes across multiple repositories - updates versions together, syncs dependencies, propagates changes, and ensures everything stays compatible.
+
+**Usage:**
+```bash
+# Natural language invocation - skill activates automatically
+"Sync dependency versions across all our microservice repos"
+"Propagate this API change to all consuming packages"
+"Update shared configuration across the organization"
+
+# The skill activates when you mention multi-repo, cross-repository, or dependency sync
+```
+
+**Sync Types:**
+- Version alignment
+- Dependency updates
+- Configuration sync
+- Cross-repo refactoring
+
+---
+
+## 🔧 Automation Skills
+
+### 15. `hooks-automation` - Development Automation
+
+**What It Does:**
+Automated coordination, formatting, and learning from Claude Code operations using intelligent hooks with MCP integration.
+
+**When to Use:**
+- Automating repetitive tasks
+- Enforcing code standards
+- Learning from operations
+- Session management
+
+**Plain Language:**
+Hooks automatically run before/after operations. Save a file → auto-format. Complete a task → update memory. End session → export metrics. Like Git hooks, but for AI development.
+
+**Usage:**
+```bash
+# Natural language invocation - skill activates automatically
+"Setup pre-commit hooks for code formatting"
+"Configure post-task hooks to update documentation"
+"Enable session hooks for metric collection"
+
+# The skill activates when you mention hooks, automation, or pre/post task operations
+```
+
+**Hook Types:**
+- **Pre-Task**: Before operations start
+- **Post-Edit**: After file changes
+- **Post-Task**: After completion
+- **Session**: Start/end of sessions
+
+---
+
+### 16. `verification-quality` - Quality Assurance
+
+**What It Does:**
+Comprehensive truth scoring, code quality verification, and automatic rollback with 0.95 accuracy threshold.
+
+**When to Use:**
+- Ensuring code quality
+- Preventing bugs from merging
+- Automatic verification
+- Rollback protection
+
+**Plain Language:**
+Every change gets a "truth score" (0-1 accuracy rating). If it scores below 0.95, changes are automatically rolled back. Prevents low-quality code from entering your codebase.
+
+**Usage:**
+```bash
+# Natural language invocation - skill activates automatically
+"Run quality verification on recent changes"
+"Check truth scores for this PR"
+"Setup automatic rollback for low-quality commits"
+
+# The skill activates when you mention quality verification, truth scoring, or automatic rollback
+```
+
+**Verification Types:**
+- Truth scoring (accuracy)
+- Code quality metrics
+- Automatic rollback
+- Reliability tracking
+
+---
+
+### 17. `performance-analysis` - Bottleneck Detection
+
+**What It Does:**
+Comprehensive performance analysis, bottleneck detection, and optimization recommendations for Claude Flow swarms.
+
+**When to Use:**
+- Slow swarm execution
+- Performance optimization
+- Resource monitoring
+- Workflow efficiency
+
+**Plain Language:**
+Analyzes why operations are slow, identifies bottlenecks (network, CPU, memory, coordination), and suggests optimizations.
+
+**Usage:**
+```bash
+# Natural language invocation - skill activates automatically
+"Why is my swarm running slowly?"
+"Identify bottlenecks in this workflow"
+"Suggest optimizations for faster execution"
+
+# The skill activates when you mention performance, bottlenecks, or optimization analysis
+```
+
+**Analysis Areas:**
+- Coordination overhead
+- Network latency
+- Resource utilization
+- Agent efficiency
+
+---
+
+### 18. `stream-chain` - Pipeline Processing
+
+**What It Does:**
+Stream-JSON chaining for multi-agent pipelines, data transformation, and sequential workflows.
+
+**When to Use:**
+- Data processing pipelines
+- Multi-stage transformations
+- Sequential agent workflows
+- Stream processing
+
+**Plain Language:**
+Chains agents together like Unix pipes - output from one agent flows as input to the next. Great for ETL, data processing, and sequential transformations.
+
+**Usage:**
+```bash
+# Natural language invocation - skill activates automatically
+"Chain: fetch data → transform → validate → store"
+"Pipeline: parse logs → analyze errors → generate report"
+"Stream: read files → extract data → aggregate → visualize"
+
+# The skill activates when you mention pipelines, chaining, or stream processing
+```
+
+**Pipeline Stages:**
+- Input agents (fetch/read)
+- Transform agents (process)
+- Validate agents (check)
+- Output agents (store/report)
+
+---
+
+## ☁️ Flow Nexus Platform Skills
+
+### 19. `flow-nexus-platform` - Cloud Platform
+
+**What It Does:**
+Comprehensive Flow Nexus platform management - authentication, sandboxes, app deployment, payments, and challenges.
+
+**When to Use:**
+- Cloud-based development
+- Sandbox environments
+- Deploying applications
+- Managing platform resources
+
+**Plain Language:**
+Access to Flow Nexus cloud platform - create isolated sandboxes for testing, deploy apps, manage authentication, and access 70+ cloud tools.
+
+**Usage:**
+```bash
+# Natural language invocation - skill activates automatically
+"Create a sandbox for testing this Node.js app"
+"Deploy my application to Flow Nexus"
+"Setup authentication for cloud access"
+
+# The skill activates when you mention Flow Nexus, cloud platform, or sandboxes
+```
+
+**Features:**
+- Sandbox creation
+- App deployment
+- Authentication
+- Payment management
+
+---
+
+### 20. `flow-nexus-swarm` - Cloud Swarms
+
+**What It Does:**
+Cloud-based AI swarm deployment and event-driven workflow automation with Flow Nexus platform.
+
+**When to Use:**
+- Scalable swarm execution
+- Cloud-based coordination
+- Event-driven workflows
+- Distributed processing
+
+**Plain Language:**
+Runs swarms in the cloud instead of locally. Scale to hundreds of agents, handle events, and process distributed workloads without local resource limits.
+
+**Usage:**
+```bash
+# Natural language invocation - skill activates automatically
+"Deploy a 50-agent swarm in the cloud for this analysis"
+"Create event-driven workflow for CI/CD"
+"Scale swarm to handle high-volume processing"
+
+# The skill activates when you mention cloud swarms, event-driven workflows, or distributed processing
+```
+
+**Cloud Features:**
+- Massive scalability
+- Event-driven automation
+- Distributed execution
+- No local limits
+
+---
+
+### 21. `flow-nexus-neural` - Cloud Neural Training
+
+**What It Does:**
+Train and deploy neural networks in distributed E2B sandboxes with Flow Nexus.
+
+**When to Use:**
+- Neural network training
+- Distributed ML workloads
+- Model deployment
+- Large-scale inference
+
+**Plain Language:**
+Train machine learning models in the cloud using distributed sandboxes. No need for local GPUs - Flow Nexus handles the compute.
+
+**Usage:**
+```bash
+# Natural language invocation - skill activates automatically
+"Train a neural network for code classification"
+"Deploy distributed training across 10 sandboxes"
+"Run inference on this trained model"
+
+# The skill activates when you mention neural training, distributed ML, or cloud compute
+```
+
+**Capabilities:**
+- Distributed training
+- Cloud compute
+- Model deployment
+- Scalable inference
+
+---
+
+## 🚀 Quick Reference
+
+### How Skills Activate
+
+**Natural Language Invocation** - Skills activate automatically based on your task description. Just describe what you want to do in plain language:
+
+```bash
+# No slash commands needed - just describe your task
+"Let's pair program on this component"           → Activates pair-programming
+"Review this PR for security issues"             → Activates github-code-review
+"Create a swarm to build this API"               → Activates swarm-orchestration
+"Use vector search to find similar functions"    → Activates agentdb-vector-search
+```
+
+### Auto-Discovery
+
+Skills activate automatically when:
+- Task description matches skill purpose (e.g., "review code" → github-code-review)
+- Context indicates skill relevance (e.g., working with PRs → github skills)
+- Keywords trigger activation (e.g., "swarm", "pair", "optimize", "search")
+
+**You don't need to know skill names** - just describe what you want, and the right skills activate.
+
+### Common Workflows
+
+**New Feature Development:**
+```bash
+"Build a user authentication feature with TDD"
+# → Activates sparc-methodology for systematic development
+```
+
+**Code Review:**
+```bash
+"Review PR #42 for security and performance issues"
+# → Activates github-code-review with multi-agent analysis
+```
+
+**Performance Issues:**
+```bash
+"Why is my workflow running slowly? Find bottlenecks"
+# → Activates performance-analysis for optimization
+```
+
+**Team Coordination:**
+```bash
+"Create a swarm with frontend, backend, and testing specialists"
+# → Activates swarm-orchestration for parallel multi-agent work
+```
+
+**Search & Memory:**
+```bash
+"Find code similar to this authentication pattern"
+# → Activates agentdb-vector-search for semantic search
+```
+
+---
+
+## 📚 Next Steps
+
+1. **Install**: Run `npx claude-flow@alpha init --force`
+2. **Explore**: Say "create a custom skill for our API patterns"
+3. **Practice**: Say "let's pair program on this feature"
+4. **Scale**: Say "create a swarm to build this microservice"
+5. **Automate**: Say "setup hooks for automatic formatting"
+
+**Remember**: Just describe what you want in natural language - no commands to memorize!
+
+## 🔗 Resources
+
+- **Documentation**: https://github.com/ruvnet/claude-flow
+- **Issues**: https://github.com/ruvnet/claude-flow/issues
+- **Flow Nexus**: https://flow-nexus.ruv.io
+
+---
+
+**Remember**: Skills are discovered automatically - just start working, and Claude will use the right skills at the right time!