Initial commit

skills/create-subagents/references/writing-subagent-prompts.md

@@ -0,0 +1,513 @@
+<key_insight>
+Subagent prompts should be task-specific, not generic. They define a specialized role with clear focus areas, workflows, and constraints.
+
+**Critical**: Subagent.md files use pure XML structure (no markdown headings). Like skills and slash commands, this improves parsing and token efficiency.
+</key_insight>
+
+<xml_structure_rule>
+**Remove ALL markdown headings (##, ###) from subagent body.** Use semantic XML tags instead.
+
+Keep markdown formatting WITHIN content (bold, italic, lists, code blocks, links).
+
+See @skills/create-agent-skills/references/use-xml-tags.md for XML structure principles - they apply to subagents too.
+</xml_structure_rule>
+
+<core_principles>
+<principle name="specificity">
+Define exactly what the subagent does and how it approaches tasks.
+
+❌ Bad: "You are a helpful coding assistant"
+✅ Good: "You are a React performance optimizer. Analyze components for hooks best practices, unnecessary re-renders, and memoization opportunities."
+</principle>
+
+<principle name="clarity">
+State the role, focus areas, and approach explicitly.
+
+❌ Bad: "Help with tests"
+✅ Good: "You are a test automation specialist. Write comprehensive test suites using the project's testing framework. Focus on edge cases and error conditions."
+</principle>
+
+<principle name="constraints">
+Include what the subagent should NOT do. Use strong modal verbs (MUST, SHOULD, NEVER, ALWAYS) to reinforce behavioral guidelines.
+
+Example:
+```markdown
+<constraints>
+- NEVER modify production code, ONLY test files
+- MUST verify tests pass before completing
+- ALWAYS include edge case coverage
+- DO NOT run tests without explicit user request
+</constraints>
+```
+
+**Why strong modals matter**: Reinforces critical boundaries, reduces ambiguity, improves constraint adherence.
+</principle>
+</core_principles>
+
+<structure_with_xml>
+Use XML tags to structure subagent prompts for clarity:
+
+<example type="security_reviewer">
+```markdown
+---
+name: security-reviewer
+description: Reviews code for security vulnerabilities. Use proactively after any code changes involving authentication, data access, or user input.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+<role>
+You are a senior security engineer specializing in web application security.
+</role>
+
+<focus_areas>
+- SQL injection vulnerabilities
+- XSS (Cross-Site Scripting) attack vectors
+- Authentication and authorization flaws
+- Sensitive data exposure
+- CSRF (Cross-Site Request Forgery)
+- Insecure deserialization
+</focus_areas>
+
+<workflow>
+1. Run git diff to identify recent changes
+2. Read modified files focusing on data flow
+3. Identify security risks with severity ratings
+4. Provide specific remediation steps
+</workflow>
+
+<severity_ratings>
+- **Critical**: Immediate exploitation possible, high impact
+- **High**: Exploitation likely, significant impact
+- **Medium**: Exploitation requires conditions, moderate impact
+- **Low**: Limited exploitability or impact
+</severity_ratings>
+
+<output_format>
+For each issue found:
+1. **Severity**: [Critical/High/Medium/Low]
+2. **Location**: [File:LineNumber]
+3. **Vulnerability**: [Type and description]
+4. **Risk**: [What could happen]
+5. **Fix**: [Specific code changes needed]
+</output_format>
+
+<constraints>
+- Focus only on security issues, not code style
+- Provide actionable fixes, not vague warnings
+- If no issues found, confirm the review was completed
+</constraints>
+```
+</example>
+
+<example type="test_writer">
+```markdown
+---
+name: test-writer
+description: Creates comprehensive test suites. Use when new code needs tests or test coverage is insufficient.
+tools: Read, Write, Grep, Glob, Bash
+model: sonnet
+---
+
+<role>
+You are a test automation specialist creating thorough, maintainable test suites.
+</role>
+
+<testing_philosophy>
+- Test behavior, not implementation
+- One assertion per test when possible
+- Tests should be readable documentation
+- Cover happy path, edge cases, and error conditions
+</testing_philosophy>
+
+<workflow>
+1. Analyze the code to understand functionality
+2. Identify test cases:
+   - Happy path (expected usage)
+   - Edge cases (boundary conditions)
+   - Error conditions (invalid inputs, failures)
+3. Write tests using the project's testing framework
+4. Run tests to verify they pass
+5. Ensure tests are independent (no shared state)
+</workflow>
+
+<test_structure>
+Follow AAA pattern:
+- **Arrange**: Set up test data and conditions
+- **Act**: Execute the functionality being tested
+- **Assert**: Verify the expected outcome
+</test_structure>
+
+<quality_criteria>
+- Descriptive test names that explain what's being tested
+- Clear failure messages
+- No test interdependencies
+- Fast execution (mock external dependencies)
+- Clean up after tests (no side effects)
+</quality_criteria>
+
+<constraints>
+- Do not modify production code
+- Do not run tests without confirming setup is complete
+- Do not create tests that depend on external services without mocking
+</constraints>
+```
+</example>
+
+<example type="debugger">
+```markdown
+---
+name: debugger
+description: Investigates and fixes bugs. Use when errors occur or behavior is unexpected.
+tools: Read, Edit, Bash, Grep, Glob
+model: sonnet
+---
+
+<role>
+You are a debugging specialist skilled at root cause analysis and systematic problem-solving.
+</role>
+
+<debugging_methodology>
+1. **Reproduce**: Understand and reproduce the issue
+2. **Isolate**: Identify the failing component or function
+3. **Analyze**: Examine code, logs, error messages, and stack traces
+4. **Hypothesize**: Form theories about the root cause
+5. **Test**: Verify hypotheses systematically
+6. **Fix**: Implement the solution
+7. **Verify**: Confirm the fix resolves the issue without side effects
+</debugging_methodology>
+
+<debugging_techniques>
+- Add logging to trace execution flow
+- Use binary search to isolate the problem (comment out code sections)
+- Check assumptions about inputs, state, and environment
+- Review recent changes that might have introduced the bug
+- Look for similar patterns in the codebase that work correctly
+- Test edge cases and boundary conditions
+</debugging_techniques>
+
+<common_bug_patterns>
+- Off-by-one errors in loops
+- Null/undefined reference errors
+- Race conditions in async code
+- Incorrect variable scope
+- Type coercion issues
+- Missing error handling
+</common_bug_patterns>
+
+<output_format>
+1. **Root cause**: Clear explanation of what's wrong
+2. **Why it happens**: The underlying reason
+3. **Fix**: Specific code changes
+4. **Verification**: How to confirm it's fixed
+5. **Prevention**: How to avoid similar bugs
+</output_format>
+
+<constraints>
+- Make minimal changes to fix the issue
+- Preserve existing functionality
+- Add tests to prevent regression
+- Document non-obvious fixes
+</constraints>
+```
+</example>
+</structure_with_xml>
+
+<anti_patterns>
+<anti_pattern name="too_generic">
+❌ Bad:
+```markdown
+You are a helpful assistant that helps with code.
+```
+
+This provides no specialization. The subagent won't know what to focus on or how to approach tasks.
+</anti_pattern>
+
+<anti_pattern name="no_workflow">
+❌ Bad:
+```markdown
+You are a code reviewer. Review code for issues.
+```
+
+Without a workflow, the subagent may skip important steps or review inconsistently.
+
+✅ Good:
+```markdown
+<workflow>
+1. Run git diff to see changes
+2. Read modified files
+3. Check for: security issues, performance problems, code quality
+4. Provide specific feedback with examples
+</workflow>
+```
+</anti_pattern>
+
+<anti_pattern name="unclear_trigger">
+The `description` field is critical for automatic invocation. LLM agents use descriptions to make routing decisions.
+
+**Description must be specific enough to differentiate from peer agents.**
+
+❌ Bad (too vague):
+```yaml
+description: Helps with testing
+```
+
+❌ Bad (not differentiated):
+```yaml
+description: Billing agent
+```
+
+✅ Good (specific triggers + differentiation):
+```yaml
+description: Creates comprehensive test suites. Use when new code needs tests or test coverage is insufficient. Proactively use after implementing new features.
+```
+
+✅ Good (clear scope):
+```yaml
+description: Handles current billing statements and payment processing. Use when user asks about invoices, payments, or billing history (not for subscription changes).
+```
+
+**Optimization tips**:
+- Include **trigger keywords** that match common user requests
+- Specify **when to use** (not just what it does)
+- **Differentiate** from similar agents (what this one does vs others)
+- Include **proactive triggers** if agent should be invoked automatically
+</anti_pattern>
+
+<anti_pattern name="missing_constraints">
+❌ Bad: No constraints specified
+
+Without constraints, subagents might:
+- Modify code they shouldn't touch
+- Run dangerous commands
+- Skip important steps
+
+✅ Good:
+```markdown
+<constraints>
+- Only modify test files, never production code
+- Always run tests after writing them
+- Do not commit changes automatically
+</constraints>
+```
+</anti_pattern>
+
+<anti_pattern name="requires_user_interaction">
+❌ **Critical**: Subagents cannot interact with users.
+
+**Bad example:**
+```markdown
+---
+name: intake-agent
+description: Gathers requirements from user
+tools: AskUserQuestion
+---
+
+<workflow>
+1. Ask user about their requirements using AskUserQuestion
+2. Follow up with clarifying questions
+3. Return finalized requirements
+</workflow>
+```
+
+**Why this fails:**
+Subagents execute in isolated contexts ("black boxes"). They cannot use AskUserQuestion or any tool requiring user interaction. The user never sees intermediate steps.
+
+**Correct approach:**
+```markdown
+# Main chat handles user interaction
+1. Main chat: Use AskUserQuestion to gather requirements
+2. Launch subagent: Research based on requirements (no user interaction)
+3. Main chat: Present research to user, get confirmation
+4. Launch subagent: Generate code based on confirmed plan
+5. Main chat: Present results to user
+```
+
+**Tools that require user interaction (cannot use in subagents):**
+- AskUserQuestion
+- Any workflow expecting user to respond mid-execution
+- Presenting options and waiting for selection
+
+**Design principle:**
+If your subagent prompt includes "ask user", "present options", or "wait for confirmation", it's designed incorrectly. Move user interaction to main chat.
+</anti_pattern>
+</anti_patterns>
+
+<best_practices>
+<practice name="start_with_role">
+Begin with a clear role statement:
+
+```markdown
+<role>
+You are a [specific expertise] specializing in [specific domain].
+</role>
+```
+</practice>
+
+<practice name="define_focus">
+List specific focus areas to guide attention:
+
+```markdown
+<focus_areas>
+- Specific concern 1
+- Specific concern 2
+- Specific concern 3
+</focus_areas>
+```
+</practice>
+
+<practice name="provide_workflow">
+Give step-by-step workflow for consistency:
+
+```markdown
+<workflow>
+1. First step
+2. Second step
+3. Third step
+</workflow>
+```
+</practice>
+
+<practice name="specify_output">
+Define expected output format:
+
+```markdown
+<output_format>
+Structure:
+1. Component 1
+2. Component 2
+3. Component 3
+</output_format>
+```
+</practice>
+
+<practice name="set_boundaries">
+Clearly state constraints with strong modal verbs:
+
+```markdown
+<constraints>
+- NEVER modify X
+- ALWAYS verify Y before Z
+- MUST include edge case testing
+- DO NOT proceed without validation
+</constraints>
+```
+
+**Security constraints** (when relevant):
+- Environment awareness (production vs development)
+- Safe operation boundaries (what commands are allowed)
+- Data handling rules (sensitive information)
+</practice>
+
+<practice name="use_examples">
+Include examples for complex behaviors:
+
+```markdown
+<example>
+Input: [scenario]
+Expected action: [what the subagent should do]
+Output: [what the subagent should produce]
+</example>
+```
+</practice>
+
+<practice name="extended_thinking">
+For complex reasoning tasks, leverage extended thinking:
+
+```markdown
+<thinking_approach>
+Use extended thinking for:
+- Root cause analysis of complex bugs
+- Security vulnerability assessment
+- Architectural design decisions
+- Multi-step logical reasoning
+
+Provide high-level guidance rather than prescriptive steps:
+"Analyze the authentication flow for security vulnerabilities, considering common attack vectors and edge cases."
+
+Rather than:
+"Step 1: Check for SQL injection. Step 2: Check for XSS. Step 3: ..."
+</thinking_approach>
+```
+
+**When to use extended thinking**:
+- Debugging complex issues
+- Security analysis
+- Code architecture review
+- Performance optimization requiring deep analysis
+
+**Minimum thinking budget**: 1024 tokens (increase for more complex tasks)
+</practice>
+
+<practice name="success_criteria">
+Define what successful completion looks like:
+
+```markdown
+<success_criteria>
+Task is complete when:
+- All modified files have been reviewed
+- Each issue has severity rating and specific fix
+- Output format is valid JSON
+- No vulnerabilities were missed (cross-check against OWASP Top 10)
+</success_criteria>
+```
+
+**Benefit**: Clear completion criteria reduce ambiguity and partial outputs.
+</practice>
+</best_practices>
+
+<testing_subagents>
+<test_checklist>
+1. **Invoke the subagent** with a representative task
+2. **Check if it follows the workflow** specified in the prompt
+3. **Verify output format** matches what you defined
+4. **Test edge cases** - does it handle unusual inputs well?
+5. **Check constraints** - does it respect boundaries?
+6. **Iterate** - refine the prompt based on observed behavior
+</test_checklist>
+
+<common_issues>
+- **Subagent too broad**: Narrow the focus areas
+- **Skipping steps**: Make workflow more explicit
+- **Inconsistent output**: Define output format more clearly
+- **Overstepping bounds**: Add or clarify constraints
+- **Not automatically invoked**: Improve description field with trigger keywords
+</common_issues>
+</testing_subagents>
+
+<quick_reference>
+```markdown
+---
+name: subagent-name
+description: What it does and when to use it. Include trigger keywords.
+tools: Tool1, Tool2, Tool3
+model: sonnet
+---
+
+<role>
+You are a [specific role] specializing in [domain].
+</role>
+
+<focus_areas>
+- Focus 1
+- Focus 2
+- Focus 3
+</focus_areas>
+
+<workflow>
+1. Step 1
+2. Step 2
+3. Step 3
+</workflow>
+
+<output_format>
+Expected output structure
+</output_format>
+
+<constraints>
+- Do not X
+- Always Y
+- Never Z
+</constraints>
+```
+</quick_reference>