Agent Creator

This skill guides creation and validation of agent files in agents/. It is a maintenance tool for this repository — it does not get distributed to target projects.

Source of truth for all rules: CLAUDE.md § Authoring Standards.

---

Activation Flow

1. Ask the user: agent name, role description, and agent type (coding or non-coding)
2. Determine the correct model (see table below)
3. Present a plan showing: file path to be created, model chosen, sections to include, and any registration steps needed — then state "Awaiting your approval before proceeding."
4. Draft the agent file following the structure below
5. Run the Validation Checklist before presenting the result
6. Run the Post-Creation Checklist after the file is written

---

Model Assignment

Agent type	Model
Decision-making (architect, analyst, reviewer)	claude-opus-4-7
Execution (developer, specialist, writer)	claude-sonnet-4-6
Structured output only	claude-haiku-4-5-20251001

When in doubt, use claude-sonnet-4-6.

---

Required Structure

Every agent must have these sections in this order:

---
name: <agent-name>
description: <what it does and when to use it>
model: <see model table>
tools: Read, Write, Edit, Bash, Glob, Grep   ← adjust as needed
---

You are a **[Role Name]** — [one sentence defining the role and mindset].

## Foundational Rule — Load Context First

Before any action, load the project context in this order:

1. `README.md`, `CLAUDE.md`, `AGENTS.md` — project conventions
2. `docs/project.md` — synthesized project overview
3. `.claude/user-data/session-summary.md` — most recent entry only (topmost ## block)
4. `docs/backlog/` — current scope and task definition
5. `docs/development/` — architecture, tech stack, code standards
6. Run `git log --oneline -20` — recent patterns and active areas

**Project rules override base standards. Always.**

Follow `skills/shared/plan-mode/SKILL.md` before any non-trivial task.

---

## [Core Behavior Sections]

[Agent-specific behavior here. Keep each section focused.]

---

## Immutability Warning

This file is installed via symlink into user projects. Do not modify it
directly inside a project — changes will be lost on the next update.
To change behavior: edit the source in the dev-team-agents repository.

---

Worktree Isolation (coding agents only)

Coding agents — backend-developer, frontend-developer, database-specialist, devops-specialist, ui-ux-designer, backend-test-specialist, frontend-test-specialist — must include this section after Foundational Rule:

## Worktree Isolation

1. Read `.dev-team-agents/.worktree-session`:
   - If present: follow stored decision silently (`worktree=no` or `worktree=yes branch=<b>`)
   - If absent: ask the user once, write the decision, then act
2. On `worktree=yes`: load `skills/shared/worktree/SKILL.md` with the provided branch (default: `main`)

This ensures multi-agent workflows ask the worktree question exactly once.

---

Validation Checklist

Run before finalizing any agent file:

• Frontmatter has all four fields: name, description, model, tools
• name matches the filename (e.g., name: backend-developer → agents/backend-developer.md)
• description answers: what does it do + when to invoke it
• Model matches the agent type (see model table)
• ## Foundational Rule section present
• ## Immutability Warning section present
• If coding agent: ## Worktree Isolation section present with correct pattern
• No hardcoded framework, language, or tool references in core behavior
• File is ≤ 200 lines — move reference material to a skill if over the limit
• All content is in English

---

Post-Creation Checklist

Run after the file is written:

• Run orphan scan: bash helpers/orphan-skill-scan.sh — resolve any ACTION REQUIRED lines before closing
• Auto-Docs Rule: if the new agent changes observable behavior (new capability, renamed agent, changed tools list) → update README.md and README.pt-BR.md in the same session

---

Auditing an Existing Agent

To validate an existing agent without creating a new one:

1. Read the agent file
2. Run the Validation Checklist above
3. Report each violation with the line number and the fix required
4. Do not auto-fix — present findings and wait for approval

---

Registering the New Agent

After creating the file, check if the agent should be referenced from any existing agent. Common registration points:

Agent	Registers what
agents/setup-assistant.md	New agents that participate in project setup
agents/software-architect.md	Agents that make architectural or quality decisions
CLAUDE.md § User-Invocable Skills	Only if triggered directly via slash command