create-agent

Files (1)

• SKILL.md

SKILL.md (first lines)

## Create/Edit Agent — Production-Grade Agent Engineering

Agents are the execution layer of this system. A poorly written agent produces poor results regardless of the skill or prompt that invokes it. This skill ensures every agent meets the quality bar that makes delegation reliable.

### Mode Detection

```
Target agent file exists? → Edit Mode (Steps E1-E5)
Target agent file missing? → Create Mode (Steps 1-5)
```

Check: `ls .claude/agents/{layer}/{agent-name}.md 2>/dev/null`

---

## Create Mode — New Agent (L1/L2 Only)

L3 agents (C-Suite executives) are architectural decisions requiring board-level review. This skill creates L1 and L2 agents only. L3 agents can be edited but not created here.

### Step 1: Role Analysis

Before writing any agent file, answer these questions:

1. **What gap does this agent fill?** — Name 2-3 specific situations where existing agents fail or produce suboptimal results. If you cannot name concrete failures, the agent may not be needed.
2. **Who invokes it?** — L1 agents are invoked by L2 orchestrators or directly by users. L2 agents are invoked by L3 executives or directly by users. This determines the report audience.
3. **What does it own?** — Every agent must have clear ownership. Overlapping ownership with existing agents creates confusion about which agent to invoke.

Scan for overlap:
```bash
grep -rl "{keywords}" .claude/agents/ 2>/dev/null
```

If significant overlap exists, consider editing the existing agent (switch to Edit Mode) rather than creating a new one.

### Step 2: Layer Decision

| Layer | Directory | Role | Characteristics |
|-------|-----------|------|-----------------|
| **L1** | `.claude/agents/l1-developer/` | Code writers, analyzers, testers | Has Read/Write/Edit/Bash. Produces structured reports. Takes specific tasks. |
| **L2** | `.claude/agents/l2-team/` | Orchestrators, supervisors, graders | Has Agent tool. Delegates to L1. Makes routing/prioritization decisions. |

**Decision heuristic:**
- Does the agent write or analyze code directly? → **L1**
- Does the agent delegate work to other agents? → **L2**
- Does the agent do both? → **L1 with Agent tool** (code + delegation is valid for L1)

### Model Selection

| Model | When | Reasoning |
|-------|------|-----------|
| `opus` | Complex judgment, multi-step reasoning, delegation, architecture decisions | Opus excels at nuanced judgment calls where the agent must weigh trade-offs, read long reports, or make decisions that compound. Orchestrators (L2) almost always need opus. |
| `sonnet` | Pattern matching, high-volume execution, simple validation, monitoring | Sonnet is faster and cheaper. Use it when the task is well-defined and the agent follows a clear checklist without ambiguous judgment. |

### Tools Selection

| Profile | Tools | When |
|---------|-------|------|
| Code writer | `["Read", "Write", "Edit", "Glob", "Grep", "Bash", "SendMessage", "Skill"]` | L1 agents that create/modify files |
| Orchestrator | `["Read", "Glob", "Grep", "Bash", "Agent", "SendMessage", "Skill"]` | L2 agents that delegate to L1 |
| Code + delegation | `["Read", "Write", "Edit", "Glob", "Grep", "Bash", "Agent", "SendMessage", "Skill"]` | L1 agents that both write code and spawn sub-agents |

### Step 3: Agent Writing

#### Frontmatter

```yaml
---
name: {kebab-case-name}
description: |
  {1-2 sentence role description explaining WHEN to use this agent.}

  <example>
  Context: {Situation where this agent is the right choice.}
  user: "{Realistic user prompt}"
  assistant: "{How the assistant would invoke this agent}"
  <commentary>
  {Why this agent is the right choice — what built-in knowledge it brings.}
  </commentary>
  </example>

  <example>
  Context: {Different situation — shows versatility.}
  user: "{Different realistic prompt}"
  assistant: "{Response}"
  <commentary>{Why}</commentary>
  </example>

  <example>
  Context: {Edge case or delegation scenario.}
  user: "{Prompt}"
  assistant: "{Response}"
  <commentary>{Why}</commentary>
  </example>
model: {opus|sonnet}
color: {color}
tools: [{tool list}]
---
```

**Description rules:**
- 3 examples minimum — they are the primary trigger mechanism for Claude to select the right agent
- Examples should cover: (1) direct user invocation, (2) delegation from a higher-layer agent, (3) an edge case or less obvious trigger
- Commentary explains WHY this agent over alternatives

#### L1 Body Template

```markdown
You are the **{Role Name}** — {1-sentence identity with judgment expectations}.

## Startup Sequence

Before starting any work:

1. **Read CLAUDE.md** at the project root — confirm all rules
2. **Read relevant manuals** based on file paths you'll touch
3. {Role-specific context loading — task files, previous reports, etc.}

## Skill Autonomy

From tyjpark0317/enterprise-os, MIT.

More from tyjpark0317/enterprise-os