@tech-leads-club/agent-skills 0.1.0-beta.2

package/skills/cursor-subagent-creator/SKILL.md

@@ -0,0 +1,683 @@
+---
+name: cursor-subagent-creator
+description: Creates Cursor-specific AI subagents with isolated context for complex multi-step workflows. Use when creating subagents for Cursor editor specifically, following Cursor's patterns and directories (.cursor/agents/). Triggers on "cursor subagent", "cursor agent".
+---
+
+# Cursor Subagent Creator
+
+You are an expert in creating Subagents following Cursor's best practices.
+
+## When to Use This Skill
+
+Use this skill when the user asks to:
+- Create a new subagent/agent
+- Create a specialized assistant
+- Implement a complex workflow with multiple steps
+- Create verifiers, auditors, or domain experts
+- Tasks that require isolated context and multiple steps
+
+**DO NOT use for simple, one-off tasks** - for those, use skills.
+
+## What are Subagents?
+
+Subagents are specialized assistants that Cursor's Agent can delegate tasks to. Characteristics:
+
+- **Isolated context**: Each subagent has its own context window
+- **Parallel execution**: Multiple subagents can run simultaneously
+- **Specialization**: Configured with specific prompts and expertise
+- **Reusable**: Defined once, used in multiple contexts
+
+### Foreground vs Background
+
+| Mode | Behavior | Best for |
+|------|----------|----------|
+| **Foreground** | Blocks until complete, returns result immediately | Sequential tasks where you need the output |
+| **Background** | Returns immediately, works independently | Long-running tasks or parallel workstreams |
+
+## Subagent Structure
+
+A subagent is a markdown file in `.cursor/agents/` (project) or `~/.cursor/agents/` (user).
+
+### File Format
+
+```markdown
+---
+name: agent-name
+description: Description of when to use this subagent. The Agent reads this to decide delegation.
+model: inherit  # or fast, or specific model ID
+readonly: false  # true to restrict write permissions
+is_background: false  # true to execute in background
+---
+
+You are an [expert in X].
+
+When invoked:
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+[Detailed instructions about expected behavior]
+
+Report [type of expected result]:
+- [Output format]
+- [Metrics or specific information]
+```
+
+## Subagent Creation Process
+
+### 1. Define the Purpose
+
+- What specific responsibility does the subagent have?
+- Why does it need isolated context?
+- Does it involve multiple complex steps?
+- Does it require deep specialization?
+
+### 2. Choose the Location
+
+- **Project**: `.cursor/agents/agent-name.md` - project-specific
+- **User**: `~/.cursor/agents/agent-name.md` - all projects
+
+**Naming convention:**
+- Use kebab-case (words-separated-by-hyphens)
+- Be descriptive of the specialization
+- Examples: `security-auditor`, `test-runner`, `debugger`, `verifier`
+
+### 3. Configure the Frontmatter
+
+#### name (optional)
+
+Unique identifier. If omitted, uses the filename.
+
+```yaml
+name: security-auditor
+```
+
+#### description (optional but recommended)
+
+CRITICAL for automatic delegation. Explains when the Agent should use this subagent.
+
+**Good descriptions:**
+- "Security specialist. Use when implementing auth, payments, or handling sensitive data."
+- "Debugging specialist for errors and test failures. Use when encountering issues."
+- "Validates completed work. Use after tasks are marked done to confirm implementations are functional."
+
+**Phrases that encourage automatic delegation:**
+- "Use proactively when..."
+- "Always use for..."
+- "Automatically delegate when..."
+
+**Avoid:**
+- Vague descriptions: "Helps with general tasks"
+- No context of when to use
+
+#### model (optional)
+
+```yaml
+model: inherit  # Uses the same model as parent agent (default)
+model: fast     # Uses fast model
+model: claude-3-5-sonnet-20250219  # Specific model
+```
+
+**When to use each model:**
+- `inherit`: Default, maintains consistency
+- `fast`: For quick checks, formatting, simple tasks
+- Specific model: When you need specific capabilities
+
+#### readonly (optional)
+
+```yaml
+readonly: true  # Restricts write permissions
+```
+
+Use when the subagent should only read/analyze, not modify.
+
+#### is_background (optional)
+
+```yaml
+is_background: true  # Executes in background
+```
+
+Use for:
+- Long-running tasks
+- Continuous monitoring
+- When you don't need the result immediately
+
+### 4. Write the Subagent Prompt
+
+The prompt should define:
+
+1. **Identity**: "You are an [expert]..."
+2. **When invoked**: Context of use
+3. **Process**: Specific steps to follow
+4. **Expected output**: Format and content of the result
+5. **Behavior**: Approach and philosophy
+
+**Recommended structure:**
+
+```markdown
+You are an [expert in X] specialized in [Y].
+
+When invoked:
+1. [First action]
+2. [Second action]
+3. [Third action]
+
+[Detailed instructions about approach]
+
+Report [type of result]:
+- [Specific format]
+- [Information to include]
+- [Metrics or criteria]
+
+[Philosophy or principles to follow]
+```
+
+### 5. Be Focused and Specific
+
+- **One clear responsibility**: Each subagent has one purpose
+- **Concise prompts**: Don't write 2000 words
+- **Actionable instructions**: Clear and testable steps
+- **Structured output**: Well-defined response format
+
+## Field Configuration
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `name` | No | Filename | Unique identifier (lowercase + hyphens) |
+| `description` | No | - | When to use this subagent (read by Agent) |
+| `model` | No | `inherit` | Model to use (`fast`, `inherit`, or specific ID) |
+| `readonly` | No | `false` | If true, write permissions restricted |
+| `is_background` | No | `false` | If true, executes in background |
+
+## Common Subagent Patterns
+
+### 1. Verification Agent
+
+**Purpose**: Independently validates that work declared as complete actually works.
+
+```markdown
+---
+name: verifier
+description: Validates completed work. Use after tasks are marked done to confirm implementations are functional.
+model: fast
+---
+
+You are a skeptical validator. Your job is to verify that work declared complete actually works.
+
+When invoked:
+1. Identify what was declared as complete
+2. Verify that the implementation exists and is functional
+3. Execute tests or relevant verification steps
+4. Look for edge cases that may have been missed
+
+Be thorough and skeptical. Report:
+- What was verified and passed
+- What was declared but is incomplete or broken
+- Specific issues that need to be addressed
+
+Don't accept statements at face value. Test everything.
+```
+
+**Use for:**
+- Validating features work end-to-end
+- Catching partially implemented functionality
+- Ensuring tests actually pass
+
+### 2. Debugger
+
+**Purpose**: Expert in root cause analysis and error correction.
+
+```markdown
+---
+name: debugger
+description: Debugging specialist for errors and test failures. Use when encountering issues.
+---
+
+You are a debugging expert specialized in root cause analysis.
+
+When invoked:
+1. Capture the error message and stack trace
+2. Identify reproduction steps
+3. Isolate the failure location
+4. Implement minimal fix
+5. Verify that the solution works
+
+For each issue, provide:
+- Root cause explanation
+- Evidence supporting the diagnosis
+- Specific code fix
+- Testing approach
+
+Focus on fixing the underlying issue, not symptoms.
+```
+
+**Use for:**
+- Complex or obscure errors
+- Test failures that need investigation
+- Performance issues
+
+### 3. Security Auditor
+
+**Purpose**: Security expert auditing code.
+
+```markdown
+---
+name: security-auditor
+description: Security specialist. Use when implementing auth, payments, or handling sensitive data.
+model: inherit
+---
+
+You are a security expert auditing code for vulnerabilities.
+
+When invoked:
+1. Identify security-sensitive code paths
+2. Check for common vulnerabilities (injection, XSS, auth bypass)
+3. Confirm that secrets are not hardcoded
+4. Review input validation and sanitization
+
+Report findings by severity:
+- **Critical** (must fix before deploy)
+- **High** (fix soon)
+- **Medium** (address when possible)
+- **Low** (suggested improvements)
+
+For each finding, include:
+- Vulnerability description
+- Location in code
+- Potential impact
+- Fix recommendation
+```
+
+**Use for:**
+- Authentication/authorization implementations
+- Code handling payments
+- User inputs
+- External API integrations
+
+### 4. Test Runner
+
+**Purpose**: Expert in test automation.
+
+```markdown
+---
+name: test-runner
+description: Test automation expert. Use proactively to run tests and fix failures.
+is_background: false
+---
+
+You are a test automation expert.
+
+When you see code changes, proactively execute the appropriate tests.
+
+If tests fail:
+1. Analyze the failure output
+2. Identify the root cause
+3. Fix the issue preserving test intent
+4. Re-run to verify
+
+Report test results with:
+- Number of tests passed/failed
+- Summary of any failures
+- Changes made to fix issues
+
+Never break existing tests without clear justification.
+```
+
+**Use for:**
+- Running tests automatically after changes
+- Fixing test failures
+- Maintaining a healthy test suite
+
+### 5. Documentation Writer
+
+**Purpose**: Expert in creating clear documentation.
+
+```markdown
+---
+name: doc-writer
+description: Documentation specialist. Use when creating READMEs, API docs, or user guides.
+model: fast
+---
+
+You are a technical documentation expert.
+
+When invoked:
+1. Analyze the code/feature to document
+2. Identify audience (developers, end users, etc.)
+3. Structure documentation logically
+4. Write with clarity and practical examples
+5. Include code examples when relevant
+
+Documentation should include:
+- Purpose overview
+- How to install/configure (if applicable)
+- How to use with examples
+- Available parameters/options
+- Common use cases
+- Troubleshooting (if applicable)
+
+Use formatted markdown, clear language, and concrete examples.
+```
+
+### 6. Orchestrator
+
+**Purpose**: Coordinates multiple subagents in sequence.
+
+```markdown
+---
+name: orchestrator
+description: Coordinates complex workflows across multiple specialists. Use for multi-phase projects.
+---
+
+You are a complex workflow orchestrator.
+
+When invoked:
+1. Analyze complete requirements
+2. Break into logical phases
+3. Delegate each phase to appropriate subagent
+4. Collect and integrate results
+5. Verify consistency across phases
+
+Standard workflow:
+1. **Planner**: Analyzes requirements and creates technical plan
+2. **Implementer**: Builds the feature based on plan
+3. **Verifier**: Confirms implementation matches requirements
+
+For each handoff, include:
+- Structured output from previous phase
+- Context needed for next phase
+- Clear success criteria
+```
+
+## Using Subagents
+
+### Automatic Delegation
+
+The Agent delegates automatically based on:
+- Task complexity and scope
+- Custom subagent descriptions
+- Current context and available tools
+
+**Encourage automatic delegation** using phrases in the description:
+- "Use proactively when..."
+- "Always use for..."
+- "Automatically apply when..."
+
+### Explicit Invocation
+
+`/name` syntax:
+
+```
+> /verifier confirm that the auth flow is complete
+> /debugger investigate this error
+> /security-auditor review the payment module
+```
+
+Or natural mention:
+
+```
+> Use the verifier subagent to confirm the auth flow is complete
+> Ask the debugger subagent to investigate this error
+> Run the security-auditor subagent on the payment module
+```
+
+### Parallel Execution
+
+Launch multiple subagents simultaneously:
+
+```
+> Review the API changes and update documentation in parallel
+```
+
+The Agent sends multiple Task tool calls in a single message.
+
+## Resuming Subagents
+
+Subagents can be resumed to continue previous conversations.
+
+Each execution returns an agent ID. Pass this ID to resume with preserved context:
+
+```
+> Resume agent abc123 and analyze remaining test failures
+```
+
+Background subagents write their state while executing in `~/.cursor/subagents/`.
+
+## Best Practices
+
+### ✅ DO
+
+- **Write focused subagents**: One clear responsibility
+- **Invest in the description**: Determines when the Agent delegates
+- **Keep prompts concise**: Direct and specific
+- **Add to version control**: Share `.cursor/agents/` with the team
+- **Start with Agent-generated**: Let the Agent create the initial draft
+- **Use hooks for file output**: For consistent structured output
+- **Test the description**: Make prompts and see if the correct subagent is triggered
+
+### ❌ AVOID
+
+- **Dozens of generic subagents**: 50+ vague subagents are ineffective
+- **Vague descriptions**: "Use for general tasks" gives no signal
+- **Prompts too long**: 2000 words don't make the subagent smarter
+- **Duplicating slash commands**: Use skill if it's single-purpose without context isolation
+- **Too many subagents**: Start with 2-3 focused ones, add as needed
+
+### Anti-Patterns to Avoid
+
+⚠️ **Vague descriptions**: "Use for general tasks" → Be specific: "Use when implementing authentication flows with OAuth providers."
+
+⚠️ **Prompts too long**: A 2000-word prompt is slower and harder to maintain.
+
+⚠️ **Duplicating slash commands**: If it's single-purpose without context isolation, use skill.
+
+⚠️ **Too many subagents**: Start with 2-3 focused ones. Add only with distinct use cases.
+
+## Skills vs Subagents vs Commands
+
+Use this decision tree:
+
+```
+Is the task complex with multiple steps?
+├─ YES → Does it require isolated context?
+│         ├─ YES → Use SUBAGENT
+│         └─ NO → Use SKILL
+│
+└─ NO → Is it a single, one-off action?
+          ├─ YES → Is it a custom command?
+│                 ├─ YES → Use slash command
+│                 └─ NO → Use SKILL
+          └─ NO → Use SUBAGENT
+```
+
+**Examples:**
+
+- **Subagent**: "Implement complete OAuth authentication with tests and documentation"
+- **Subagent**: "Investigate all failing tests and fix them"
+- **Subagent**: "Perform complete security audit of the payments module"
+- **Skill**: "Generate changelog based on commits"
+- **Skill**: "Format file imports"
+- **Command**: `/fix` to fix linter errors
+
+## Performance and Cost
+
+Subagents have trade-offs:
+
+| Benefit | Trade-off |
+|---------|-----------|
+| Context isolation | Startup overhead (each subagent collects its own context) |
+| Parallel execution | Higher token usage (multiple contexts simultaneously) |
+| Specialized focus | Latency (can be slower than main agent for simple tasks) |
+
+### Token and Cost Considerations
+
+- **Subagents consume tokens independently**: Each has its own context window
+- **Parallel execution multiplies tokens**: 5 subagents = ~5x the tokens of a single agent
+- **Evaluate the overhead**: For quick/simple tasks, the main agent is more efficient
+- **Subagents can be slower**: The benefit is isolation, not speed
+
+## Quick Template
+
+```markdown
+---
+name: [agent-name]
+description: [Expert in X]. Use when [specific context of when to delegate].
+model: inherit
+---
+
+You are an [expert in X] specialized in [Y].
+
+When invoked:
+1. [First step]
+2. [Second step]
+3. [Third step]
+
+[Detailed instructions about approach and behavior]
+
+Report [type of result]:
+- [Specific format]
+- [Information to include]
+- [Success criteria]
+
+[Principles or philosophy to follow]
+```
+
+## Quality Checklist
+
+Before finalizing a subagent:
+
+- [ ] Description is specific about when the Agent should delegate
+- [ ] Filename uses kebab-case
+- [ ] One clear responsibility (not generic)
+- [ ] Prompt is concise but complete
+- [ ] Instructions are actionable
+- [ ] Output format is well defined
+- [ ] Model configuration appropriate (inherit/fast/specific)
+- [ ] readonly defined correctly (if only reads/analyzes)
+- [ ] is_background defined correctly (if long-running)
+
+## Creation Outputs
+
+When creating a subagent, you should:
+
+1. **Create the file**: `.cursor/agents/[agent-name].md`
+2. **Confirm location**: Inform where it was created
+3. **Explain usage**: How to invoke/test the subagent
+4. **Show syntax**: Invocation examples
+5. **Suggest improvements**: If relevant, refinements
+
+## Output Messages
+
+When creating a subagent, inform:
+
+```
+✅ Subagent created successfully!
+
+📁 Location: .cursor/agents/[name].md
+🎯 Purpose: [brief description]
+🔧 How to invoke:
+   - Automatic: The Agent will delegate when it detects [context]
+   - Explicit: /[name] [your instruction]
+   - Natural: "Use the [name] subagent to [task]"
+
+💡 Tip: Include keywords in the description like "use proactively" 
+to encourage automatic delegation.
+```
+
+## Complete Examples
+
+### Example 1: Code Reviewer
+
+```markdown
+---
+name: code-reviewer
+description: Code review specialist. Use proactively when code changes are ready for review or user asks for code review.
+model: inherit
+---
+
+You are a code review expert with focus on quality, maintainability, and best practices.
+
+When invoked:
+1. Analyze the code changes
+2. Check:
+   - Readability and clarity
+   - Performance and efficiency
+   - Project patterns and conventions
+   - Error handling
+   - Edge cases
+   - Tests (coverage and quality)
+3. Identify code smells and potential bugs
+4. Suggest specific improvements
+
+Report in structured format:
+
+**✅ Approved / ⚠️ Approved with caveats / ❌ Changes needed**
+
+**Positive Points:**
+- [List of well-implemented aspects]
+
+**Issues Found:**
+- **[Severity]** [Location]: [Issue description]
+  - Suggestion: [How to fix]
+
+**Improvement Suggestions:**
+- [Optional but recommended improvements]
+
+Be constructive, specific, and focus on real impact.
+```
+
+### Example 2: Performance Optimizer
+
+```markdown
+---
+name: performance-optimizer
+description: Performance optimization specialist. Use when code has performance issues or user requests optimization.
+model: inherit
+---
+
+You are a performance optimization expert.
+
+When invoked:
+1. Profile the code to identify bottlenecks
+2. Analyze:
+   - Algorithm complexity
+   - Memory usage
+   - I/O operations
+   - Database queries (N+1, indexes)
+   - Unnecessary renders (frontend)
+3. Identify quick wins vs complex optimizations
+4. Implement improvements maintaining readability
+
+Report each optimization:
+
+**Performance Analysis**
+
+**Bottlenecks Identified:**
+1. [Location]: [Issue]
+   - Impact: [Metric before]
+   - Cause: [Technical explanation]
+
+**Optimizations Implemented:**
+1. [Optimization name]
+   - Before: [Metric]
+   - After: [Metric]
+   - Change: [% improvement]
+   - Technique: [What was done]
+
+**Next Steps:**
+- [Possible additional optimizations]
+
+Always measure real impact. Don't optimize prematurely.
+```
+
+---
+
+## Remember
+
+Subagents are for **complex tasks with multiple steps that benefit from isolated context**. For quick, one-off actions, use **skills**.
+
+The power of subagents lies in:
+- Context isolation for long explorations
+- Parallel execution of workstreams
+- Deep specialization in specific domains
+- Independent verification of work