Initial commit

2025-11-30 09:07:30 +08:00
commit cbbf141e75
6 changed files with 989 additions and 0 deletions
--- a/commands/create-subagent.md
+++ b/commands/create-subagent.md
@@ -0,0 +1,441 @@
+---
+argument-hint: [subagent-name] or leave empty for interactive creation
+description: Create a new Claude subagent based on recent session workflow or conversation history
+allowed-tools: [Write, Read, Glob, Bash, AskUserQuestion, Grep]
+---
+
+Create a new Claude subagent - a specialized AI assistant with its own context window and custom configuration. Subagents are automatically invoked by Claude based on task context or can be explicitly requested.
+
+## Usage Examples
+
+- `code-reviewer` - Create a code review specialist subagent
+- `api-tester` - Create an API testing subagent
+- `spec-analyst` - Create a requirements analysis subagent
+- Leave empty - Interactive mode with guided questions
+
+## Subagent Creation Process
+
+1. **Determine Mode**: If subagent name provided, use auto mode; otherwise, use interactive mode
+
+2. **Interactive Mode** (no arguments):
+   - Ask user about the subagent's role and specialization
+   - Ask what tasks/scenarios should trigger this subagent
+   - Ask what tools/capabilities the subagent needs
+   - Ask what model to use (sonnet, opus, haiku, or inherit)
+   - Analyze recent conversation history to extract workflow patterns
+
+3. **Auto Mode** (subagent name provided):
+   - Analyze recent session messages and tool calls
+   - Extract workflow patterns, common steps, and decision points
+   - Identify tools used frequently in the workflow
+   - Detect domain/context from file patterns and commands
+   - Generate subagent based on detected patterns
+
+4. **Generate Subagent File**:
+   - Create file: `~/.claude/agents/$1.md` (user-level) or `./.claude/agents/$1.md` (project-level)
+   - Write YAML frontmatter with metadata
+   - Craft detailed system prompt with role, responsibilities, and workflow
+   - Include deliverable templates if applicable
+
+5. **Verify and Test**:
+   - Check YAML syntax validity
+   - Verify description includes clear activation triggers
+   - Confirm tools list is appropriate
+   - Test invocation with example scenario
+
+## Storage Locations
+
+**User-Level**: `~/.claude/agents/subagent-name.md`
+- Available across all projects
+- For personal workflow automation
+
+**Project-Level**: `./.claude/agents/subagent-name.md`
+- Shared with team via git
+- For project-specific expertise
+- Higher priority than user-level (overrides on name conflict)
+
+**Default**: User-level unless project context detected or user specifies
+
+## Subagent File Structure
+
+```markdown
+---
+name: subagent-identifier
+description: Clear description of role AND when to invoke. Include specific keywords and scenarios for automatic activation.
+tools: Read, Write, Bash, Grep, Glob  # Optional: comma-separated list
+model: sonnet  # Optional: sonnet, opus, haiku, or inherit
+---
+
+# Role Definition
+
+You are a [specific role] specializing in [domain/task]. When invoked, you [primary objective].
+
+## Core Responsibilities
+
+1. **[Responsibility 1]**: Detailed description of what you do
+2. **[Responsibility 2]**: Another key responsibility
+3. **[Responsibility 3]**: Additional responsibilities
+
+## Workflow
+
+When activated, follow these steps:
+
+1. **Initial Analysis**:
+   - Analyze the current state/context
+   - Identify key issues or requirements
+   - Ask clarifying questions if needed
+
+2. **Main Task Execution**:
+   - Perform primary task with specific approach
+   - Use appropriate tools and techniques
+   - Follow best practices and standards
+
+3. **Quality Checks**:
+   - Verify work meets criteria
+   - Run tests/validations
+   - Document findings
+
+4. **Deliverables**:
+   - Produce specific outputs
+   - Provide recommendations
+   - Update relevant documentation
+
+## Best Practices
+
+- [Best practice 1]
+- [Best practice 2]
+- [Common pitfall to avoid]
+
+## Quality Criteria
+
+- [Criterion 1]: [Standard/threshold]
+- [Criterion 2]: [Standard/threshold]
+- [Criterion 3]: [Standard/threshold]
+
+## Output Format
+
+[Template or structure for agent's deliverables]
+
+## Example Scenarios
+
+**Scenario 1**: [Description]
+- Input: [What triggers this]
+- Action: [What you do]
+- Output: [What you produce]
+
+**Scenario 2**: [Another scenario]
+- Input: [Trigger]
+- Action: [Process]
+- Output: [Result]
+```
+
+## YAML Frontmatter Fields
+
+| Field | Required | Description | Example |
+|-------|----------|-------------|---------|
+| **name** | Yes | Lowercase identifier with hyphens | `code-reviewer`, `api-tester` |
+| **description** | Yes | Role + activation triggers + keywords | See examples below |
+| **tools** | No | Comma-separated tool list; inherits all if omitted | `Read, Write, Bash` |
+| **model** | No | Model alias or inherit from parent | `sonnet`, `opus`, `haiku`, `inherit` |
+
+## Description Best Practices
+
+**Poor**: "Helps review code"
+**Good**: "Expert code review specialist. Reviews code for quality, security, and maintainability. Use immediately after writing or modifying code, before commits, or when refactoring."
+
+**Poor**: "API testing tool"
+**Good**: "API testing specialist. Validates REST endpoints, response schemas, error handling, and performance. Use when testing APIs, debugging HTTP requests, or validating backend services."
+
+**Poor**: "Requirements analyst"
+**Good**: "Requirements analyst and project scoping expert. Elicits comprehensive requirements, creates user stories with acceptance criteria, and generates project briefs. Use when starting new projects, analyzing requirements, or creating specifications."
+
+## Interactive Questions
+
+When in interactive mode, ask:
+
+1. **Role Question**:
+   - Header: "Agent Role"
+   - Question: "What specialized role should this subagent fulfill?"
+   - Options:
+     - "Code quality expert" - Review, refactor, and improve code
+     - "Testing specialist" - Write and run tests, validate functionality
+     - "Architecture advisor" - Design systems, plan structure
+     - "Domain expert" - Provide specialized domain knowledge
+
+2. **Activation Question**:
+   - Header: "Activation"
+   - Question: "When should Claude automatically invoke this subagent?"
+   - Options:
+     - "After code changes" - Proactively review new/modified code
+     - "Specific keywords" - Trigger on certain terms (requirements, test, etc.)
+     - "File patterns" - Activate for specific file types/projects
+     - "Explicit request only" - Only when user directly asks
+
+3. **Tools Question** (multiSelect: true):
+   - Header: "Tool Access"
+   - Question: "Which tools should this subagent have access to?"
+   - Options:
+     - "File operations" - Read, Write, Edit, Glob, Grep
+     - "Shell commands" - Bash execution
+     - "Web access" - WebFetch, WebSearch
+     - "All tools (no restrictions)" - Inherits all available tools
+
+4. **Model Question**:
+   - Header: "Model"
+   - Question: "Which AI model should power this subagent?"
+   - Options:
+     - "Sonnet (recommended)" - Balanced performance and speed
+     - "Opus (advanced)" - Most capable, slower, expensive
+     - "Haiku (fast)" - Quick responses, lighter tasks
+     - "Inherit from parent" - Use same model as main conversation
+
+5. **Scope Question**:
+   - Header: "Scope"
+   - Question: "Where should this subagent be available?"
+   - Options:
+     - "User-level (all projects)" - Save to ~/.claude/agents/
+     - "Project-level (this project)" - Save to ./.claude/agents/
+     - "Let me decide later" - Recommend based on context
+     - "Both locations" - Create in both with option to choose
+
+## Workflow Extraction Logic
+
+When extracting from recent conversation:
+
+1. **Identify Domain Patterns**:
+   - Analyze file types worked with (*.py, *.go, *.ts, etc.)
+   - Track command patterns (pytest, npm test, git, curl, etc.)
+   - Detect frameworks/libraries mentioned
+   - Identify problem domains (testing, debugging, deployment, etc.)
+
+2. **Extract Tool Usage**:
+   - Count tool invocations (Read: 15, Bash: 8, Write: 5, etc.)
+   - Identify essential vs. optional tools
+   - Note tool sequences (Read → Edit → Bash pattern)
+   - Determine if web access needed
+
+3. **Detect Workflow Steps**:
+   - Find repeated action sequences
+   - Identify decision points and conditionals
+   - Extract verification/validation patterns
+   - Note output/deliverable formats
+
+4. **Generate System Prompt**:
+   - Define clear role based on domain
+   - Structure responsibilities from patterns
+   - Create step-by-step workflow
+   - Add quality criteria and best practices
+   - Include example scenarios from actual history
+
+5. **Set Activation Triggers**:
+   - Extract keywords from user messages
+   - Identify file patterns from glob/grep usage
+   - Note explicit requests ("test this", "review code")
+   - Generate description with trigger keywords
+
+## Subagent Categories & Examples
+
+### Code Quality & Review
+- **code-reviewer**: Reviews for quality, security, maintainability
+- **refactoring-expert**: Improves code structure and design
+- **security-auditor**: Identifies vulnerabilities and security issues
+
+### Testing & QA
+- **test-writer**: Creates comprehensive test suites
+- **test-runner**: Executes tests, diagnoses failures
+- **qa-validator**: Validates functionality against requirements
+
+### Architecture & Design
+- **backend-architect**: Designs server-side systems
+- **frontend-architect**: Plans client application structure
+- **database-designer**: Models data structures and schemas
+
+### Development Specialists
+- **api-developer**: Builds and documents REST/GraphQL APIs
+- **ui-implementer**: Creates user interfaces
+- **integration-specialist**: Connects external services
+
+### Analysis & Planning
+- **spec-analyst**: Elicits requirements, creates user stories
+- **spec-architect**: Designs system structure and interfaces
+- **spec-planner**: Breaks work into granular tasks
+
+### DevOps & Operations
+- **deployment-specialist**: Handles releases and deployments
+- **monitoring-expert**: Sets up observability and alerts
+- **infrastructure-engineer**: Manages cloud resources
+
+### Domain Experts
+- **performance-optimizer**: Improves speed and efficiency
+- **accessibility-expert**: Ensures WCAG compliance
+- **localization-specialist**: Handles i18n/l10n
+
+## Multi-Agent Coordination
+
+Subagents can work together in workflows:
+
+```bash
+# Sequential workflow
+"Use spec-analyst to analyze requirements, then spec-architect to design the system"
+
+# Parallel tasks
+"Have code-reviewer check quality while test-runner validates functionality"
+
+# Handoff pattern
+"spec-planner should create tasks, then spec-developer implements them"
+```
+
+## Advanced Patterns
+
+### Hub-and-Spoke Coordination
+Main agent coordinates multiple specialized subagents:
+- Main agent receives user request
+- Delegates to appropriate specialists
+- Collects and synthesizes results
+
+### Pipeline Workflow
+Sequential phases with quality gates:
+1. **Planning**: spec-analyst → spec-architect → spec-planner
+2. **Development**: spec-developer → test-writer
+3. **Validation**: code-reviewer → qa-validator
+
+### Specialist On-Demand
+Invoke domain experts as needed:
+- Security audit: security-auditor
+- Performance issue: performance-optimizer
+- Accessibility review: accessibility-expert
+
+## Output Format
+
+After creation, provide:
+
+```
+✅ Subagent created successfully: [name]
+   Location: ~/.claude/agents/[name].md (or project-level)
+   Role: [Role description]
+   Model: [sonnet/opus/haiku/inherit]
+   Tools: [tool list or "all tools"]
+
+📋 Subagent Details:
+   - Activates on: [keywords, patterns, or scenarios]
+   - Primary responsibilities: [list]
+   - Key capabilities: [list]
+
+🔍 How to Use:
+   Automatic: Claude will invoke when context matches
+   Explicit: "Use the [name] subagent to [task]"
+
+🧪 Test Command:
+   Try: "Use the [name] subagent to [example scenario]"
+
+📝 Next Steps:
+   1. Test the subagent with a relevant task
+   2. Refine system prompt based on results
+   3. Add to project agents if team-relevant
+   4. Document use cases for team members
+```
+
+## Validation Checks
+
+Before finalizing:
+
+1. **YAML Syntax**:
+   - Valid frontmatter delimiters (---)
+   - Proper field names (name, description, tools, model)
+   - Correct tool list format (comma-separated)
+   - Valid model value (sonnet/opus/haiku/inherit)
+
+2. **Description Quality**:
+   - Includes role definition
+   - Contains activation triggers
+   - Has specific keywords
+   - Describes when to use
+
+3. **System Prompt**:
+   - Clear role definition
+   - Structured responsibilities
+   - Step-by-step workflow
+   - Quality criteria
+   - Example scenarios
+
+4. **Tool Restrictions**:
+   - Appropriate for task
+   - Not too restrictive
+   - Not unnecessarily permissive
+   - Consider security implications
+
+## Notes
+
+- **Context Isolation**: Each subagent has its own context window, preventing main conversation pollution
+- **Automatic Invocation**: Claude Code proactively invokes subagents based on description and context
+- **Explicit Invocation**: Users can request specific subagents: "Use the [name] subagent to..."
+- **Priority**: Project-level subagents override user-level when names conflict
+- **Tool Inheritance**: Omit `tools` field to inherit all available tools
+- **Model Inheritance**: Use `model: inherit` to match parent conversation's model
+- **Version Control**: Project subagents can be committed to git for team sharing
+- **No Restart Needed**: Subagents are loaded dynamically
+
+## Examples
+
+```bash
+# Interactive mode - guided creation with questions
+/claude:create-subagent
+
+# Auto mode - extract from recent code review work
+/claude:create-subagent code-reviewer
+
+# Create API testing specialist
+/claude:create-subagent api-tester
+
+# Create requirements analyst
+/claude:create-subagent spec-analyst
+
+# Create performance optimizer
+/claude:create-subagent performance-optimizer
+```
+
+## Debugging Subagents
+
+If Claude doesn't invoke your subagent:
+
+1. **Check file location**:
+   ```bash
+   ls -la ~/.claude/agents/[name].md
+   ls -la ./.claude/agents/[name].md
+   ```
+
+2. **Verify YAML syntax**:
+   ```bash
+   head -10 ~/.claude/agents/[name].md
+   ```
+
+3. **Test description clarity**: Make it more specific with trigger keywords
+
+4. **Explicit invocation test**: "Use the [name] subagent to [task]"
+
+5. **Check tool restrictions**: Ensure required tools aren't blocked
+
+6. **Review logs**: Run `claude --debug` for error messages
+
+## Related Commands
+
+- `/agents` - Built-in interactive agent manager
+- `/claude:create-skill` - Create a skill (model-invoked instructions)
+- `/claude:create-command` - Create a slash command (user-invoked)
+
+## Skill vs. Subagent vs. Command
+
+| Feature | Skill | Subagent | Slash Command |
+|---------|-------|----------|---------------|
+| **Invocation** | Model-invoked | Model-invoked | User-invoked |
+| **Context** | Main conversation | Isolated context | Main conversation |
+| **Use Case** | Domain expertise | Complex workflows | Quick automation |
+| **Location** | `~/.claude/skills/` | `~/.claude/agents/` | `~/.claude/commands/` |
+| **Format** | Folder with SKILL.md | Single .md file | Single .md file |
+| **Best For** | Adding capabilities | Task specialization | User shortcuts |
+
+Choose subagents when:
+- Task requires isolated context (large operations)
+- Multiple specialized roles needed (multi-agent coordination)
+- Proactive invocation desired (automatic delegation)
+- Different model needed for sub-task