<!--
Agent Creator
Part of the Bles Software agent skills repository:
https://www.bles-software.com/claude-skills

Install for Claude Code:
  mkdir -p ~/.claude/skills/agent-creator
  mv agent-creator.md ~/.claude/skills/agent-creator/SKILL.md

Install for Codex:
  mkdir -p ~/.codex/skills/agent-creator
  mv agent-creator.md ~/.codex/skills/agent-creator/SKILL.md

For Gemini CLI and other agents, drop the body of this file into the
project instruction file the agent already reads.

Note: in production this skill also ships 3 helper file(s) alongside
SKILL.md. The procedure below is complete and self-contained; the helpers are
convenience scripts you can rebuild from the steps described here.
-->

---
name: creating-agents
description: |
  Creates Claude Code subagents (custom AI agents) that can be spawned via the Task tool.
  Use when user wants to create an agent, build a subagent, make a specialist agent,
  or automate tasks with custom agents. Agents are markdown files in .claude/agents/.
allowed-tools: Read, Write, Bash, Glob, Grep
---

# Agent Creator

Create custom Claude Code subagents that run in isolated contexts via the Task tool.

## Quick Start

To create an agent, write a markdown file to `.claude/agents/` (project) or `~/.claude/agents/` (global):

```bash
mkdir -p .claude/agents
```

## Agent File Format

```yaml
---
name: agent-name-here
description: |
  When to use this agent and what it does.
  Be specific about triggers.
tools: Read, Write, Edit, Bash, Glob, Grep
---

# Agent Title

[Agent instructions and guidelines]
```

## Required Fields

| Field | Description |
|-------|-------------|
| `name` | Identifier (lowercase, hyphens) |
| `description` | When to invoke + capabilities |
| `tools` | Comma-separated tool list |

## Tools by Role

| Role | Tools |
|------|-------|
| Read-only | `Read, Grep, Glob` |
| Research | `Read, Grep, Glob, WebFetch, WebSearch` |
| Code writer | `Read, Write, Edit, Bash, Glob, Grep` |
| Full access | `Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch` |

## Agent Locations

| Location | Scope |
|----------|-------|
| `.claude/agents/` | Project (git-trackable) |
| `~/.claude/agents/` | Global (all projects) |

Project agents take precedence over global.

---

## Detailed References

- **Templates**: See [references/templates.md](references/templates.md)
- **Best Practices**: See [references/best-practices.md](references/best-practices.md)
- **Tool Permissions**: See [references/tools.md](references/tools.md)

---

## Creating an Agent

### Step 1: Define Purpose

```
Name: [agent-name]
Role: [code-reviewer | researcher | developer | specialist]
Triggers: [when should this agent be used?]
Tools needed: [minimal required tools]
```

### Step 2: Create File

```bash
cat > .claude/agents/my-agent.md << 'EOF'
---
name: my-agent
description: |
  Brief description of what this agent does.
  Use when [specific triggers].
tools: Read, Grep, Glob
---

# My Agent

## Role
[What this agent specializes in]

## Guidelines
- [Guideline 1]
- [Guideline 2]

## Workflow
1. [Step 1]
2. [Step 2]
3. [Step 3]
EOF
```

### Step 3: Test

Invoke manually:
```
Use the Task tool with subagent_type='my-agent' to [task]
```

Or let Claude auto-delegate based on description match.

---

## Common Agent Types

### Code Reviewer
```yaml
tools: Read, Grep, Glob
```
Reviews code without modifying.

### Researcher
```yaml
tools: Read, Grep, Glob, WebFetch, WebSearch
```
Gathers information from codebase and web.

### Developer
```yaml
tools: Read, Write, Edit, Bash, Glob, Grep
```
Creates and modifies code.

### Documentation Writer
```yaml
tools: Read, Write, Edit, Glob, Grep, WebFetch, WebSearch
```
Creates docs with research capability.

---

## Example: Create a PR Reviewer Agent

```bash
cat > .claude/agents/pr-reviewer.md << 'EOF'
---
name: pr-reviewer
description: |
  Reviews pull requests for code quality, bugs, and best practices.
  Use when user asks to review a PR, check code changes, or audit commits.
tools: Read, Grep, Glob, Bash
---

# PR Reviewer Agent

## Role
Expert code reviewer focusing on quality, security, and maintainability.

## Review Checklist
- [ ] Logic errors and bugs
- [ ] Security vulnerabilities
- [ ] Performance issues
- [ ] Code style consistency
- [ ] Test coverage
- [ ] Documentation completeness

## Workflow
1. Get changed files: `git diff --name-only origin/main`
2. Read each changed file
3. Analyze for issues
4. Provide structured feedback

## Output Format
For each issue found:
- **File**: path/to/file.ts:123
- **Severity**: Critical/Warning/Info
- **Issue**: Description
- **Suggestion**: How to fix
EOF
```

---

## Invoking Agents

### Automatic (via description match)
Claude reads agent descriptions and auto-delegates matching tasks.

### Manual (via Task tool)
```
Use the Task tool with subagent_type='agent-name' to perform [task]
```

### In CLAUDE.md
```markdown
When reviewing code, use the pr-reviewer agent.
```