Skip to main content
skill CX Codex

create-subagent — Claude Code skill: what it does, how to install

create-subagent helps create isolated subagents with targeted system prompts and YAML configurations for code reviews, debugging, and data tasks.

MIT ★ 328 updated 2026-10-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add coco-research/coco --skill create-subagent -a claude-code
Open on GitHub

What create-subagent does

This skill walks you through designing and saving isolated subagent markdown files. It structures the YAML frontmatter and builds custom system instructions tailored to specific workflows.

Configurations live in .cursor/agents/ for repository-specific agents or in ~/.cursor/agents/ across all local projects. When file names collide, the project-level agent takes precedence. Each configuration strictly requires a lowercase hyphenated name alongside a descriptive description that models inspect when delegating work.

Without specific delegation triggers or the "use proactively" hint in the description, models will routinely fail to dispatch tasks to your subagent.

What it helps with

  • isolate complex codebase exploration from main conversation context
  • configure a dedicated code reviewer agent with explicit checklists
  • define specialized prompts for root cause debugging and log analysis
  • store personal subagents globally across multiple local repositories

Example prompts for the agent

  • Help me set up a code reviewer subagent in .cursor/agents/
  • Create a dedicated debugging subagent focused on root-cause analysis
  • Generate a global data-scientist agent file for running SQL queries

How to install create-subagent

1Skills CLI (Vercel)

npx skills add coco-research/coco --skill create-subagent -a claude-code

2Manually: put the files in place

~/.claude/skills/create-subagent/SKILL.md

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

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

Questions about create-subagent

How to install create-subagent in Claude Code?

Run npx skills add coco-research/coco --skill create-subagent -a claude-code in your terminal.

What does the create-subagent skill do?

It guides the creation of subagent markdown files, generating custom system prompts and required YAML frontmatter metadata.

Where are subagents stored and which file takes priority?

Project subagents live in .cursor/agents/ and override user-level files located in ~/.cursor/agents/.

Source text

SKILL.md · MIT
---
name: create-subagent
description: Create custom subagents for specialized AI tasks. Use when the user wants to create a new type of subagent, set up task-specific agents, configure code reviewers, debuggers, or domain-specific assistants with custom prompts.
disable-model-invocation: true
---
# Creating Custom Subagents

This skill guides you through creating custom subagents for Cursor. Subagents are specialized AI assistants that run in isolated contexts with custom system prompts.

## When to Use Subagents

Subagents help you:
- **Preserve context** by isolating exploration from your main conversation
- **Specialize behavior** with focused system prompts for specific domains
- **Reuse configurations** across projects with user-level subagents

### Inferring from Context

If you have previous conversation context, infer the subagent's purpose and behavior from what was discussed. Create the subagent based on specialized tasks or workflows that emerged in the conversation.

## Subagent Locations

| Location | Scope | Priority |
|----------|-------|----------|
| `.cursor/agents/` | Current project | Higher |
| `~/.cursor/agents/` | All your projects | Lower |

When multiple subagents share the same name, the higher-priority location wins.

**Project subagents** (`.cursor/agents/`): Ideal for codebase-specific agents. Check into version control to share with your team.

**User subagents** (`~/.cursor/agents/`): Personal agents available across all your projects.

## Subagent File Format

Create a `.md` file with YAML frontmatter and a markdown body (the system prompt):

```markdown
---
name: code-reviewer
description: Reviews code for quality and best practices
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.
```

### Required Fields

| Field | Description |
|-------|-------------|
| `name` | Unique identifier (lowercase letters and hyphens only) |
| `description` | When to delegate to this subagent (be specific!) |

## Writing Effective Descriptions

The description is **critical** - the AI uses it to decide when to delegate.

```yaml
# BAD: Too vague
description: Helps with code

# GOOD: Specific and actionable
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
```

Include "use proactively" to encourage automatic delegation.

## Example Subagents

### Code Reviewer

```markdown
---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.
```

### Debugger

```markdown
---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

Focus on fixing the underlying issue, not the symptoms.
```

### Data Scientist

```markdown
---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
---

You are a data scientist specializing in SQL and BigQuery analysis.

When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Use BigQuery command line tools (bq) when appropriate
4. Analyze and summarize results
5. Present findings clearly

Key practices:
- Write optimized SQL queries with proper filters
- Use appropriate aggregations and joins
- Include comments explaining complex logic
- Format results for readability
- Provide data-driven recommendations

For each analysis:
- Explain the query approach
- Document any assumptions
- Highlight key findings
- Suggest next steps based on data

Always ensure queries are efficient and cost-effective.
```

## Subagent Creation Workflow

### Step 1: Decide the Scope

- **Project-level** (`.cursor/agents/`): For codebase-specific agents shared with team
- **User-level** (`~/.cursor/agents/`): For personal agents across all projects

### Step 2: Create the File

```bash
# For project-level
mkdir -p .cursor/agents
touch .cursor/agents/my-agent.md

# For user-level
mkdir -p ~/.cursor/agents
touch ~/.cursor/agents/my-agent.md
```

### Step 3: Define Configuration

Write the frontmatter with the required fields (`name` and `description`).

### Step 4: Write the System Prompt

The body becomes the system prompt. Be specific about:
- What the agent should do when invoked
- The workflow or process to follow
- Output format and structure
- Any constraints or guidelines

### Step 5: Test the Agent

Ask the AI to use your new agent:

```
Use the my-agent subagent to [task description]
```

## Best Practices

1. **Design focused subagents**: Each should excel at one specific task
2. **Write detailed descriptions**: Include trigger terms so the AI knows when to delegate
3. **Check into version control**: Share project subagents with your team
4. **Use proactive language**: Include "use proactively" in descriptions

## Troubleshooting

### Subagent Not Found
- Ensure file is in `.cursor/agents/` or `~/.cursor/agents/`
- Check file has `.md` extension
- Verify YAML frontmatter syntax is valid

© coco-research · MIT · coco-research/coco

Similar skills

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

From the same set82

The whole set →
redesign-existing-projects redesign-existing-projects — a Claude skill that audits an existing site or app for the usual AI-design tells and fixes them inside the current stack, leaving behaviour alone. CX Codex +1 ★ 328repo stars database-architect Get database architecture recommendations, data models, and migration plans. Use the subagent when shaping a schema, scaling a system, or splitting data across services. CX Codex ★ 328repo stars tailwind-patterns The tailwind-patterns skill guides Tailwind CSS v4 setup, responsive layouts, and design tokens. Use it when starting a v4 project or moving one from v3. CX Codex +1 ★ 328repo stars c4-architecture c4-architecture generates architecture documentation using C4 model: system context, containers, components and deployment as Mermaid diagrams. CX Codex +1 ★ 328repo stars create-skill create-skill guides you through authoring agent skills by defining directory layout, SKILL.md frontmatter, and precise description triggers. CX Codex +1 ★ 328repo stars ultra-think ultra-think is a Claude Code skill that examines architecture decisions from four viewpoints, compares approaches, and gives one recommendation. CX Codex +1 ★ 328repo stars generate-tests generate-tests writes tests for a file, module or component, after first detecting the project's framework and conventions. CX Codex +1 ★ 328repo stars m0-handoff m0-handoff saves session state into STATE.md and the local M0 daemon so another session or tool picks up right where you stopped. CX Codex +1 ★ 328repo stars

Project sponsors

Companies that keep this analytics open