Cursor Subagent Creator workflow skill. Use this skill when the user needs 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". Do NOT use for generic subagent creation outside Cursor (use subagent-creator instead) and the operator should preserve the upstream workflow, copied support files, and provenance before merging or handing off.
Cursor Subagent Creator workflow skill. Use this skill when the user needs 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". Do NOT use for generic subagent creation outside Cursor (use subagent-creator instead) and the operator should preserve the upstream workflow, copied support files, and provenance before merging or handing off.
This public intake copy packages packages/skills-catalog/skills/(creation)/cursor-subagent-creator from https://github.com/tech-leads-club/agent-skills into the native Omni Skills editorial shape without hiding its origin.
Use it when the operator needs the upstream workflow, support files, and repository context to stay intact while the public validator and private enhancer continue their normal downstream flow.
This intake keeps the copied upstream files intact and uses the external_source block in metadata.json plus ORIGIN.md as the provenance anchor for review.
Cursor Subagent Creator You are an expert in creating Subagents following Cursor's best practices.
Imported source sections that did not map cleanly to the public headings are still preserved below or in the support files. Notable imported sections: What are Subagents?, Subagent Structure, Field Configuration, Common Subagent Patterns, Using Subagents, Resuming Subagents.
When to Use This Skill
Use this section as the trigger filter. It should make the activation boundary explicit before the operator loads files, runs commands, or opens a pull request.
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
Use when the request clearly matches the imported source intent: 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/).....
Operating Table
Situation
Start here
Why it matters
First-time use
metadata.json
Confirms repository, branch, commit, and imported path through the external_source block before touching the copied workflow
Provenance review
ORIGIN.md
Gives reviewers a plain-language audit trail for the imported source
Workflow execution
SKILL.md
Starts with the smallest copied file that materially changes execution
Supporting context
SKILL.md
Adds the next most relevant copied source file without loading the entire package
Handoff decision
## Related Skills
Helps the operator switch to a stronger native skill when the task drifts
Workflow
This workflow is intentionally editorial and operational at the same time. It keeps the imported source useful to the operator while still satisfying the public intake standards that feed the downstream enhancer flow.
What specific responsibility does the subagent have?
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)
model:inherit# Uses the same model as parent agent (default)model:fast# Uses fast modelmodel: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)
readonly:true# Restricts write permissions
Use when the subagent should only read/analyze, not modify.
is_background (optional)
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:
Identity: "You are an [expert]..."
When invoked: Context of use
Process: Specific steps to follow
Expected output: Format and content of the result
Behavior: Approach and philosophy
Recommended structure:
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
Imported: 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
Examples
Example 1: Ask for the upstream workflow directly
Use @cursor-subagent-creator to handle <task>. Start from the copied upstream workflow, load only the files that change the outcome, and keep provenance visible in the answer.
Explanation: This is the safest starting point when the operator needs the imported workflow, but not the entire repository.
Example 2: Ask for a provenance-grounded review
Review @cursor-subagent-creator against metadata.json and ORIGIN.md, then explain which copied upstream files you would load first and why.
Explanation: Use this before review or troubleshooting when you need a precise, auditable explanation of origin and file selection.
Example 3: Narrow the copied support files before execution
Use @cursor-subagent-creator for <task>. Load only the copied references, examples, or scripts that change the outcome, and name the files explicitly before proceeding.
Explanation: This keeps the skill aligned with progressive disclosure instead of loading the whole copied package by default.
Example 4: Build a reviewer packet
Review @cursor-subagent-creator using the copied upstream files plus provenance, then summarize any gaps before merge.
Explanation: This is useful when the PR is waiting for human review and you want a repeatable audit packet.
Imported Usage Notes
Imported: 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
Imported: Complete Examples
Example 1: Code Reviewer
---
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
---
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.
Best Practices
Treat the generated public skill as a reviewable packaging layer around the upstream repository. The goal is to keep provenance explicit and load only the copied source material that materially improves execution.
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
Imported Operating Notes
Imported: 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.
Troubleshooting
Problem: The operator skipped the imported context and answered too generically
Symptoms: The result ignores the upstream workflow in packages/skills-catalog/skills/(creation)/cursor-subagent-creator, fails to mention provenance, or does not use any copied source files at all.
Solution: Re-open metadata.json, ORIGIN.md, and the most relevant copied upstream files. Check the external_source block first, then restate the provenance before continuing.
Problem: The imported workflow feels incomplete during review
Symptoms: Reviewers can see the generated SKILL.md, but they cannot quickly tell which references, examples, or scripts matter for the current task.
Solution: Point at the exact copied references, examples, scripts, or assets that justify the path you took. If the gap is still real, record it in the PR instead of hiding it.
Problem: The task drifted into a different specialization
Symptoms: The imported skill starts in the right place, but the work turns into debugging, architecture, design, security, or release orchestration that a native skill handles better.
Solution: Use the related skills section to hand off deliberately. Keep the imported provenance visible so the next skill inherits the right context instead of starting blind.
Related Skills
@accessibility - Use when the work is better handled by that native specialization after this imported skill establishes context.
@ai-cold-outreach - Use when the work is better handled by that native specialization after this imported skill establishes context.
@ai-pricing - Use when the work is better handled by that native specialization after this imported skill establishes context.
@ai-sdr - Use when the work is better handled by that native specialization after this imported skill establishes context.
Additional Resources
Use this support matrix and the linked files below as the operator packet for this imported skill. They should reflect real copied source material, not generic scaffolding.
Resource family
What it gives the reviewer
Example path
references
copied reference notes, guides, or background material from upstream
references/n/a
examples
worked examples or reusable prompts copied from upstream
examples/n/a
scripts
upstream helper scripts that change execution or validation
scripts/n/a
agents
routing or delegation notes that are genuinely part of the imported package
agents/n/a
assets
supporting assets or schemas copied from the source package
assets/n/a
Imported Reference Notes
Imported: Subagent Structure
A subagent is a markdown file in .cursor/agents/ (project) or ~/.cursor/agents/ (user).
File Format
---
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]
Imported: 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
Imported: Common Subagent Patterns
1. Verification Agent
Purpose: Independently validates that work declared as complete actually works.
---
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.
---
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.
---
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.
---
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.
---
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.
---
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
Imported: 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.
Imported: 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/.
Imported: Performance and Cost
Subagents have trade-offs:
Benefit
Trade-off
Context isolation
Startup overhead (each subagent collects its own context)
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
Imported: Quick Template
---
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]
Imported: 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)
Imported: Creation Outputs
When creating a subagent, you should:
Create the file: .cursor/agents/[agent-name].md
Confirm location: Inform where it was created
Explain usage: How to invoke/test the subagent
Show syntax: Invocation examples
Suggest improvements: If relevant, refinements
Imported: 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.
Imported: Remember
Subagents are for complex tasks with multiple steps that benefit from isolated context. For quick, one-off actions, use skills.
