/cursor-subagent-creator

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

---
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.

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)

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)

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:

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:**

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 |