Skip to main content
skill CX Codex

cursor-subagent-creator — Claude Code skill for Cursor agents

cursor-subagent-creator is a Cursor skill for designing subagents, choosing their file location and settings, and defining workflows for complex, multi-step tasks.

MIT ★ 7,191 updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add tech-leads-club/agent-skills --skill cursor-subagent-creator -a claude-code
Open on GitHub

What cursor-subagent-creator does

This skill guides you through creating a specialized subagent for Cursor as a Markdown file. Put a project-level agent in .cursor/agents/ or a user-level one in ~/.cursor/agents/. The recommended filename style is kebab-case.

The file can define name, description, model, readonly, and is_background, followed by instructions that set the agent’s role, process, and expected output. The skill also covers model selection and foreground or background execution. It is aimed at reusable agents for multi-step work, not simple one-off tasks.

What it helps with

  • create a Cursor subagent to verify completed work
  • turn a multi-step workflow into clear agent instructions
  • restrict an agent to read-only analysis
  • configure background execution for a long-running task

Example prompts for the agent

  • Create a Cursor subagent that checks completed work and lists its verification steps.
  • Write a Cursor agent file for code analysis with write access disabled.
  • Set up a background subagent for a long workflow and define its report format.

How to install cursor-subagent-creator

1Skills CLI (Vercel)

npx skills add tech-leads-club/agent-skills --skill cursor-subagent-creator -a claude-code

2Manually: put the files in place

~/.claude/skills/cursor-subagent-creator/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/cursor-subagent-creator/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about cursor-subagent-creator

How do I install cursor-subagent-creator in Claude Code?

Run npx skills add tech-leads-club/agent-skills --skill cursor-subagent-creator -a claude-code. The skill file is at ~/.claude/skills/cursor-subagent-creator/SKILL.md.

What does cursor-subagent-creator do?

It helps define a Cursor subagent’s purpose, instructions, model settings, and execution mode. The result is a Markdown file in an agents directory.

Where should I save a Cursor subagent for one project?

Create it at .cursor/agents/agent-name.md. For use across projects, the user-level location is ~/.cursor/agents/agent-name.md.

Source text

SKILL.md · MIT
---
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". Do NOT use for generic subagent creation outside Cursor (use subagent-creator instead).
---

# 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

© tech-leads-club · MIT · tech-leads-club/agent-skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set130

The whole set →
ai-sdr ai-sdr helps founders and GTM teams design AI sales reps, automate lead qualification, and pick outbound tooling. CX Codex +1 ★ 7,191repo stars component-flattening-analysis The component-flattening-analysis skill finds classes placed outside their component and proposes a cleaner namespace hierarchy. Use it when component structure needs review or refactoring. CX Codex +1 ★ 7,191repo stars the-jury the-jury spawns 3 to 5 subagent jurors who form blind opinions, deliberate anonymously, then return one verdict with a confidence score, kept dissent and a next action. CX Codex +1 ★ 7,191repo stars gtm-engineering gtm-engineering architects revenue workflows, orchestrates GTM agents, and designs automation pipelines in Claude Code. Built for founders and RevOps focusing on systems over quick hacks. CX Codex +1 ★ 7,191repo stars social-selling social-selling — a skill that turns a LinkedIn presence into pipeline: profile audit, Sales Navigator filters, comment warm-up and direct-message sequences. CX Codex +1 ★ 7,191repo stars the-judge the-judge reviews GitHub pull requests via the gh CLI, verifying every finding with concrete evidence before posting a single review. CX Codex +1 ★ 7,191repo stars ai-ugc-ads The ai-ugc-ads skill for Claude Code plans UGC campaigns, from finding creators and preparing briefs to testing AI-made videos. It covers campaign launch and scaling. CX Codex +1 ★ 7,191repo stars domain-identification-grouping domain-identification-grouping sorts the components you already have into business domains, so a service-based architecture can be planned and namespaces lined up with it. CX Codex +1 ★ 7,191repo stars

Project sponsors

Companies that keep this analytics open