Initial commit

2025-11-29 18:00:36 +08:00
commit c83b4639c5
49 changed files with 18594 additions and 0 deletions
--- a/skills/multi-agent-composition/patterns/decision-framework.md
+++ b/skills/multi-agent-composition/patterns/decision-framework.md
@@ -0,0 +1,434 @@
+# Decision Framework: Choosing the Right Claude Code Component
+
+This guide helps you choose the right Claude Code component for your specific task. **Always start with prompts**—master the primitive first before scaling to other components.
+
+## Table of Contents
+
+- [The Decision Tree](#the-decision-tree)
+- [Quick Reference: Decision Matrix](#quick-reference-decision-matrix)
+- [When to Use Each Component](#when-to-use-each-component)
+  - [Use Skills When](#use-skills-when)
+  - [Use Sub-Agents When](#use-sub-agents-when)
+  - [Use Slash Commands When](#use-slash-commands-when)
+  - [Use MCP Servers When](#use-mcp-servers-when)
+  - [Use Hooks When](#use-hooks-when)
+  - [Use Plugins When](#use-plugins-when)
+- [Use Case Examples from the Field](#use-case-examples-from-the-field)
+- [Composition Rules and Boundaries](#composition-rules-and-boundaries)
+  - [What Can Compose What](#what-can-compose-what)
+  - [Critical Composition Rules](#critical-composition-rules)
+- [The Proper Evolution Path](#the-proper-evolution-path)
+  - [Stage 1: Start with a Prompt](#stage-1-start-with-a-prompt)
+  - [Stage 2: Add Sub-Agent if Parallelism Needed](#stage-2-add-sub-agent-if-parallelism-needed)
+  - [Stage 3: Create Skill When Management Needed](#stage-3-create-skill-when-management-needed)
+  - [Stage 4: Add MCP if External Data Needed](#stage-4-add-mcp-if-external-data-needed)
+- [Common Decision Anti-Patterns](#common-decision-anti-patterns)
+  - [Anti-Pattern 1: Converting All Slash Commands to Skills](#anti-pattern-1-converting-all-slash-commands-to-skills)
+  - [Anti-Pattern 2: Using Skills for One-Off Tasks](#anti-pattern-2-using-skills-for-one-off-tasks)
+  - [Anti-Pattern 3: Skipping the Primitive](#anti-pattern-3-skipping-the-primitive)
+  - [Anti-Pattern 4: Using Sub-Agents When Context Matters](#anti-pattern-4-using-sub-agents-when-context-matters)
+  - [Anti-Pattern 5: Forgetting MCP is for External Only](#anti-pattern-5-forgetting-mcp-is-for-external-only)
+- [Decision Checklist](#decision-checklist)
+- [Summary: The Golden Rules](#summary-the-golden-rules)
+
+## The Decision Tree
+
+Start here when deciding which component to use:
+
+```text
+1. START HERE: Build a Prompt (Slash Command)
+   ↓
+2. Need parallelization or isolated context?
+   YES → Use Sub-Agent
+   NO → Continue
+   ↓
+3. External data/service integration?
+   YES → Use MCP Server
+   NO → Continue
+   ↓
+4. One-off task (simple, direct)?
+   YES → Use Slash Command
+   NO → Continue
+   ↓
+5. Repeatable workflow (pattern detection)?
+   YES → Use Agent Skill
+   NO → Continue
+   ↓
+6. Lifecycle event automation?
+   YES → Use Hook
+   NO → Continue
+   ↓
+7. Sharing/distributing to team?
+   YES → Use Plugin
+   NO → Default to Slash Command (prompt)
+```
+
+**Critical Rule:** Always start with **Prompts** (implemented as Slash Commands). Master the primitive first before scaling to other components.
+
+## Quick Reference: Decision Matrix
+
+| Task Type | Component | Reason |
+|-----------|-----------|---------|
+| Repeatable pattern detection | Agent Skill | Domain-specific workflow |
+| External data/service access | MCP Server | Integration point |
+| Parallel/isolated work | Sub-Agent | Context isolation |
+| Parallel workflow tasks | Sub-Agent | **Whenever you see "parallel", think sub-agents** |
+| One-off task | Slash Command | Simple, direct |
+| Lifecycle automation | Hook | Event-driven |
+| Team distribution | Plugin | Packaging |
+
+## When to Use Each Component
+
+### Use Skills When
+
+**Signal keywords:** "automatic," "repeat," "manage," "workflow"
+
+**Criteria:**
+
+- You have a **REPEAT** problem that needs **MANAGEMENT**
+- Multiple related operations need coordination
+- You want **automatic** behavior (agent-invoked)
+- The problem domain requires orchestration of multiple components
+
+**Example scenarios:**
+
+- Managing git work trees (create, list, remove, merge, update)
+- Detecting style guide violations across codebase
+- Automatic PDF text extraction and processing
+- Video processing workflows with multiple steps
+
+**NOT for:**
+
+- One-off tasks → Use Slash Command instead
+- Simple operations → Use Slash Command instead
+- Problems solved well by a single prompt → Don't over-engineer
+
+**Remember:** Skills are for managing problem domains, not solving one-off tasks.
+
+### Use Sub-Agents When
+
+**Signal keywords:** "parallel," "scale," "bulk," "isolated," "batch"
+
+**Criteria:**
+
+- **Parallelization** is needed
+- **Context isolation** is required
+- Scale tasks and batch operations
+- You're okay with losing context afterward
+- Each task can run independently
+
+**Example scenarios:**
+
+- Comprehensive security audits
+- Fix & debug tests at scale
+- Parallel workflow tasks
+- Bulk operations on multiple files
+- Isolated research that doesn't pollute main context
+
+**NOT for:**
+
+- Tasks that need to share context → Use main conversation
+- Sequential operations → Use Slash Command or Skill
+- Tasks that need to spawn more sub-agents → Hard limit: no nesting
+
+**Critical constraint:** You must be okay with losing context afterward. Sub-agent context doesn't persist in the main conversation (unless you use resumable sub-agents).
+
+**Golden rule:** "Whenever you see parallel, you should always just think sub-agents. Nothing else supports parallel calling."
+
+### Use Slash Commands When
+
+**Signal keywords:** "one-off," "simple," "quick," "manual"
+
+**Criteria:**
+
+- One-off tasks
+- Simple repeatable actions
+- You're starting a new workflow
+- Building the primitive before composing
+- You want manual control over invocation
+
+**Example scenarios:**
+
+- Git commit messages (one at a time)
+- Create UI component
+- Run specific code generation
+- Execute a well-defined task
+- Quick transformations
+
+**Philosophy:** "Have a strong bias towards slash commands. And then when you're thinking about composing many slash commands, sub-agents or MCPs, think about putting them in a skill."
+
+**Remember:** Slash commands are the primitive foundation. Master these first before anything else.
+
+### Use MCP Servers When
+
+**Signal keywords:** "external," "database," "API," "service," "integration"
+
+**Criteria:**
+
+- External integrations are needed
+- Data sources outside Claude Code
+- Third-party services
+- Database connections
+- Real-time data access
+
+**Example scenarios:**
+
+- Connect to Jira
+- Query databases (PostgreSQL, etc.)
+- Fetch real-time weather data
+- GitHub integration
+- Slack integration
+- Figma designs
+
+**NOT for:**
+
+- Internal orchestration → Use Skills instead
+- Pure computation → Use Slash Command or Skill
+
+**Clear rule:** External = MCP, Internal orchestration = Skills
+
+**Context consideration:** MCP servers can "torch your context window" by loading all their context at startup, unlike Skills which use progressive disclosure.
+
+### Use Hooks When
+
+**Signal keywords:** "lifecycle," "event," "automation," "deterministic"
+
+**Criteria:**
+
+- Deterministic automation at lifecycle events
+- Want to execute commands at specific moments
+- Need to balance agent autonomy with deterministic control
+- Workflow automation that should always happen
+
+**Example scenarios:**
+
+- Run linters before code submission
+- Auto-format code after generation
+- Trigger tests after file changes
+- Capture context at specific points
+
+**Philosophy:** "If you really want to scale, you need both" - agents AND deterministic workflows.
+
+**Use for:** Adding determinism rather than always relying on the agent to decide.
+
+### Use Plugins When
+
+**Signal keywords:** "share," "distribute," "package," "team"
+
+**Criteria:**
+
+- Sharing/distributing to team
+- Packaging multiple components together
+- Reusable work across projects
+- Team-wide extensions
+
+**Example scenarios:**
+
+- Distribute custom skills to team
+- Bundle MCP servers for automatic start
+- Share slash commands across projects
+- Package hooks and configurations
+
+**Philosophy:** "Plugins let you package and distribute these sets of work. This isn't super interesting. It's just a way to share and reuse cloud code extensions."
+
+## Use Case Examples from the Field
+
+Real examples with reasoning:
+
+| Use Case | Component | Reasoning |
+|----------|-----------|-----------|
+| Automatic PDF text extraction | Agent Skill | Keyword "automatic", repeat behavior |
+| Connect to Jira | MCP Server | External source |
+| Comprehensive security audit | Sub-Agent | Scale, isolated context, not automatic |
+| Generalized git commit messages | Slash Command | Simple one-step task |
+| Query database | MCP Server | External data source (start here) |
+| Fix/debug tests at scale | Sub-Agent | Parallel work, scale |
+| Detect style guide violations | Agent Skill | Repeat behavior pattern |
+| Fetch real-time weather | MCP Server | Third-party service integration |
+| Create UI component | Slash Command | Simple one-off task |
+| Parallel workflow tasks | Sub-Agent | Keyword "parallel" |
+
+## Composition Rules and Boundaries
+
+### What Can Compose What
+
+**Skills (Top Compositional Layer):**
+
+- ✅ Can use: MCP Servers
+- ✅ Can use: Sub-Agents
+- ✅ Can use: Slash Commands
+- ✅ Can use: Other Skills
+- ❌ Cannot: Nest sub-agents/prompts directly (must use SlashCommand tool)
+
+**Slash Commands (Primitive + Compositional):**
+
+- ✅ Can use: Skills (via SlashCommand tool)
+- ✅ Can use: MCP Servers
+- ✅ Can use: Sub-Agents
+- ✅ Acts as: BOTH primitive AND composition point
+
+**Sub-Agents (Execution Layer):**
+
+- ✅ Can use: Slash Commands (via SlashCommand tool)
+- ✅ Can use: Skills (via SlashCommand tool)
+- ❌ CANNOT use: Other Sub-Agents (hard limit)
+
+**MCP Servers (Integration Layer):**
+
+- ℹ️ Lower level unit, used BY skills
+- ℹ️ Not using skills
+- ℹ️ Expose services to all components
+
+### Critical Composition Rules
+
+1. **Sub-Agents cannot nest** - No sub-agent spawning other sub-agents (prevents infinite nesting)
+2. **Skills don't execute code** - They guide Claude to use available tools
+3. **Slash commands can be invoked manually or via SlashCommand tool**
+4. **Skills use the SlashCommand tool** to compose prompts and sub-agents
+5. **No circular dependencies** - Skills can use other skills but cannot nest circularly
+
+## The Proper Evolution Path
+
+When building new capabilities, follow this progression:
+
+### Stage 1: Start with a Prompt
+
+**Goal:** Solve the basic problem
+
+Create a simple prompt or slash command that accomplishes the core task.
+
+**Example (Git Work Trees):** Create one work tree
+
+```bash
+/create-worktree feature-branch
+```
+
+**When to stay here:** The task is one-off or infrequent.
+
+### Stage 2: Add Sub-Agent if Parallelism Needed
+
+**Goal:** Scale to multiple parallel operations
+
+If you need to do the same thing many times in parallel, use a sub-agent.
+
+**Example (Git Work Trees):** Create multiple work trees in parallel
+
+```bash
+Use sub-agent to create work trees for: feature-a, feature-b, feature-c in parallel
+```
+
+**When to stay here:** Parallel execution is the only requirement, no orchestration needed.
+
+### Stage 3: Create Skill When Management Needed
+
+**Goal:** Bundle multiple related operations
+
+When the problem grows to require management, create a skill.
+
+**Example (Git Work Trees):** Manage work trees (create, list, remove, merge, update)
+
+Now you have a cohesive work tree manager skill that:
+
+- Creates new work trees
+- Lists existing work trees
+- Removes old work trees
+- Merges work trees
+- Updates work tree status
+
+**When to stay here:** Most domain-specific workflows stop here.
+
+### Stage 4: Add MCP if External Data Needed
+
+**Goal:** Integrate external systems
+
+Only add MCP servers when you need data from outside Claude Code.
+
+**Example (Git Work Trees):** Query external repo metadata from GitHub API
+
+Now your skill can query GitHub for:
+
+- Branch protection rules
+- CI/CD status
+- Pull request information
+
+**Final state:** Full-featured work tree manager with external integration.
+
+## Common Decision Anti-Patterns
+
+### ❌ Anti-Pattern 1: Converting All Slash Commands to Skills
+
+**Mistake:** "I'm going to convert all my slash commands to skills because skills are better."
+
+**Why wrong:** Skills are for repeatable workflows that need management, not simple one-off tasks. Slash commands are the primitive—you need them.
+
+**Correct approach:** Keep slash commands for simple tasks. Only create a skill when you're managing a problem domain with multiple related operations.
+
+### ❌ Anti-Pattern 2: Using Skills for One-Off Tasks
+
+**Mistake:** "I need to create a UI component once, so I'll build a skill for it."
+
+**Why wrong:** Skills are for repeat problems. One-off tasks should use slash commands.
+
+**Correct approach:** Use a slash command for the one-off task. If you find yourself doing it repeatedly, then consider a skill.
+
+### ❌ Anti-Pattern 3: Skipping the Primitive
+
+**Mistake:** "I'm going to start by building a skill because it's more advanced."
+
+**Why wrong:** If you don't master prompts, you can't build effective skills. Everything is prompts in the end.
+
+**Correct approach:** Always start with a prompt. Build the primitive first. Scale up only when needed.
+
+### ❌ Anti-Pattern 4: Using Sub-Agents When Context Matters
+
+**Mistake:** "I'll use a sub-agent for this research task and then reference the findings later."
+
+**Why wrong:** Sub-agent context is isolated. You lose it after the sub-agent finishes (unless using resumable sub-agents).
+
+**Correct approach:** If you need the context later, do the work in the main conversation or use a resumable sub-agent.
+
+### ❌ Anti-Pattern 5: Forgetting MCP is for External Only
+
+**Mistake:** "I'll build an MCP server to orchestrate internal workflows."
+
+**Why wrong:** MCP servers are for external integrations. Internal orchestration should use skills.
+
+**Correct approach:** MCP = external, Skills = internal orchestration. Keep them separate.
+
+## Decision Checklist
+
+Before you start building, ask yourself:
+
+**Basic Questions:**
+
+- [ ] Have I started with a prompt? (Non-negotiable)
+- [ ] Is this a one-off task or repeatable?
+- [ ] Do I need external data or services?
+- [ ] Is parallelization required?
+- [ ] Am I okay losing context after execution?
+
+**Composition Questions:**
+
+- [ ] Am I trying to nest sub-agents? (Not allowed)
+- [ ] Am I converting a simple slash command to a skill? (Probably wrong)
+- [ ] Am I using MCP for internal orchestration? (Should use skills)
+- [ ] Have I considered the evolution path? (Prompt → Sub-agent → Skill → MCP)
+
+**Context Questions:**
+
+- [ ] Will this torch my context window? (MCP consideration)
+- [ ] Do I need progressive disclosure? (Skills benefit)
+- [ ] Is context isolation critical? (Sub-agent benefit)
+- [ ] Will I need this context later? (Don't use sub-agent)
+
+## Summary: The Golden Rules
+
+1. **Always start with prompts** - Master the primitive first
+2. **"Parallel" keyword = Sub-Agents** - Nothing else supports parallel calling
+3. **External = MCP, Internal = Skills** - Clear separation of concerns
+4. **One-off = Slash Command** - Don't over-engineer
+5. **Repeat + Management = Skill** - Only scale when needed
+6. **Don't convert all slash commands to skills** - Huge mistake
+7. **Skills compose upward, not downward** - Build from primitives
+
+Remember The Core 4: Context, Model, Prompt, Tools. Master these fundamentals, and you'll master the compositional units.