---
name: cc-agent
description: |
  Create or update Claude Code agents (subagents) based on official documentation.
  Use this skill when:
  - Creating a new specialized agent
  - Updating an agent's tools, model, or permissions
  - Adding skills to an agent
argument-hint: "<create|update> [name] [--scope project|global|templates]"
disable-model-invocation: true
---

<objective>
Create or update Claude Code agents (subagents) following official conventions. Guides the user through agent design, generates properly structured .md files, and validates the result.
</objective>

<quick_start>

```bash
# Create a new agent
/cc-agent create my-agent
/cc-agent create my-agent --scope project
/cc-agent create my-agent --scope global
/cc-agent create my-agent --scope templates

# Update an existing agent
/cc-agent update my-agent
/cc-agent update my-agent --scope global
```

</quick_start>

<parameters>

<subcommands>
| Command | Description | Workflow |
|---------|-------------|----------|
| `create` | Create a new agent from scratch | init → design → generate → validate |
| `update` | Update an existing agent | init → analyze → apply → validate |
</subcommands>

<flags>
| Flag | Description |
|------|-------------|
| `--scope project` | Target `.claude/agents/` (default) |
| `--scope global` | Target `~/.claude/agents/` |
| `--scope templates` | Target `templates/agents/` (SmartStack CLI) |
| `--category <name>` | Place in subdirectory (e.g., efcore, gitflow) |
</flags>

<examples>
```bash
# Create a standalone agent
/cc-agent create test-runner

# Create a categorized agent
/cc-agent create migration --category efcore --scope templates

# Update an existing agent
/cc-agent update code-reviewer

# Create agent for SmartStack templates
/cc-agent create my-validator --scope templates
```
</examples>

</parameters>

<workflow>
**Create flow:**
1. Parse subcommand, name, scope, category
2. Design agent (model, tools, permissions, skills)
3. Generate agent .md file
4. Validate structure and conventions

**Update flow:**
1. Parse subcommand, name, scope
2. Read and analyze existing agent
3. Apply requested changes
4. Validate structure and conventions
</workflow>

<state_variables>
| Variable | Type | Description |
|----------|------|-------------|
| `{subcommand}` | string | create or update |
| `{agent_name}` | string | Agent name (unique identifier) |
| `{scope}` | string | project, global, or templates |
| `{target_dir}` | string | Resolved target directory |
| `{category}` | string | Subdirectory (null for standalone) |
| `{description}` | string | Agent description |
| `{model}` | string | haiku, sonnet, opus, or inherit |
| `{tools}` | string | Comma-separated tool list |
| `{disallowed_tools}` | string | Blocked tools |
| `{permission_mode}` | string | Permission handling mode |
| `{preloaded_skills}` | string[] | Skills to inject at startup |
| `{system_prompt}` | string | Agent's system prompt content |
</state_variables>

<entry_point>

**FIRST ACTION:** Load `steps/step-00-init.md`

</entry_point>

<step_files>
| Step | File | Purpose |
|------|------|---------|
| 00 | `steps/step-00-init.md` | Parse subcommand, name, scope, resolve target |
| 01 | `steps/step-01-design.md` | Design agent (model, tools, permissions, skills) |
| 02 | `steps/step-02-generate.md` | Generate agent .md file from template |
| 03 | `steps/step-03-validate.md` | Validate format and display summary |
</step_files>

<execution_rules>
- **Load one step at a time** - Progressive loading
- **Ask before generating** - Confirm design choices with user
- **Use templates** - Load from `templates/` directory for generation
- **Follow official conventions** - Based on Claude Code documentation
- **Validate at the end** - Check generated file
</execution_rules>

<success_criteria>
- Agent .md file created with valid frontmatter
- Description is clear enough for Claude to decide when to delegate
- Tools are appropriate for the agent's purpose
- Permission mode matches the agent's risk level
- Agent follows official Claude Code conventions
</success_criteria>
