Create Agent

Not an agent if:

• The steps are always the same regardless of input (→ workflow)
• It's a sequential checklist (→ workflow)
• It only provides context without taking action (→ knowledge base)
• It wraps a single tool or API (→ operational)

Step 1: Understand the Goal

Ask the user:

1. "What should the agent accomplish?" — The end goal, not the steps.
2. "What triggers it?" — When should Claude become this agent?
3. "What can it do?" — Which tools and actions are available?
4. "When should it stop?" — Success condition, failure condition, or both.
5. "How autonomous should it be?" — See autonomy levels below.

Autonomy Levels

Default to Guided unless the user explicitly requests more autonomy.

Step 2: Context Analysis

Before generating, scan the project:

1. Read AGENTS.md — Understand conventions and stack
2. Check ~/.codex/skills/ — Avoid duplicating existing agents
3. Detect stack — The agent's instructions should reference real tools and paths

Step 3: Design the Agent

3.1: Define the Execution Loop

Every agent has a loop. Design it explicitly:

┌─→ Observe (gather information)
│   ↓
│   Analyze (interpret what was found)
│   ↓
│   Decide (choose next action or stop)
│   ↓
│   Act (execute the chosen action)
│   ↓
│   Verify (check the result)
│   ↓
└── Loop back or Stop

For each phase, define:

• Observe: What to read/scan/check
• Analyze: What patterns or conditions to look for
• Decide: Decision criteria for each possible action
• Act: Concrete actions with tool usage
• Verify: How to confirm the action worked
• Stop: When to exit the loop

3.2: Define Stop Criteria

Every agent MUST have explicit stop criteria. Without them, it loops forever.

Success stops:

• Goal achieved (e.g., "all tests pass", "no issues found")
• All items processed (e.g., "reviewed all files in the changeset")

Failure stops:

• Max iterations reached (always set a limit)
• Blocked and can't proceed (e.g., "missing dependency, can't resolve")
• User cancels

Safety stops:

• About to do something destructive
• Confidence drops below threshold
• Outside defined scope

3.3: Define Safety Boundaries

Based on the autonomy level:

Read-only agents:

• allowed-tools restricts to Read, Glob, Grep
• No Write, Edit, or Bash in allowed-tools
• Skill text explicitly says "never modify files"

Guided agents:

• Can use Write, Edit, Bash but must present changes before applying
• Pattern: "Here's what I'd change: ... Apply this change?"

Semi-autonomous agents:

• Define a "safe zone" of automatic actions (e.g., formatting, adding imports)
• Define a "confirm zone" of risky actions (e.g., deleting files, changing APIs)
• Pattern: "I formatted 3 files automatically. I also want to delete unused.ts — OK?"

Autonomous agents:

• Full tool access
• Still must respect AGENTS.md rules and project conventions
• Should log actions for review

Step 4: Generate the SKILL.md

Structure:

---