/agent-authoring

name: agent-authoring
description: >-
  Guide for creating DAAF agent definition files. Covers 12-section template, hook registration, skills-in-frontmatter, integration checklist. Use when adding or revising agents. For SKILL.md files, use skill-authoring instead.
metadata:
  audience: any-agent
  domain: skill-development

Agent Authoring

Guide for creating new DAAF agent definition files with full ecosystem integration. Covers the 12-section agent template, cross-agent consistency standards, per-agent hook registration, skills-in-frontmatter assignment, and the complete integration checklist for wiring new agents into documentation. Use when adding a new specialized agent, revising agent structure, configuring per-agent hooks, or verifying agent integration completeness. For creating SKILL.md files (not agent definition files), use skill-authoring instead.

Create new DAAF agents that conform to the canonical template and are fully wired into the system documentation for discoverability and usability.

What This Skill Does

• Guides creation of agent `.md` files conforming to `agent_reference/AGENT_TEMPLATE.md` (12 mandatory sections)
• Ensures cross-agent consistency (standardized confidence model, Learning Signal, STOP format, etc.)
• Provides a **complete integration checklist** covering every file that references agents across the codebase to ensure it is discoverable and its invocation patterns are well-understood by the system agents
• Complements `skill-authoring`: this skill handles the behavioral protocol file; if the new agent also needs a companion skill, invoke `skill-authoring` separately

Decision Tree: What Do You Need?

What are you doing?
│
├─ Creating a brand-new agent
│   └─ Follow "New Agent Workflow" below
│
├─ Revising an existing agent to match the template
│   └─ Read: references/template-walkthrough.md
│          + agent_reference/AGENT_TEMPLATE.md (the canonical blueprint)
│
├─ Checking if an agent is fully integrated into the ecosystem
│   └─ Read: references/integration-checklist.md
│
├─ Understanding what must be identical across all agents
│   └─ Read: references/cross-agent-standards.md
│
└─ Understanding the current agent landscape before adding to it
    └─ Read: .claude/agents/README.md (Agent Index + "Commonly Confused Pairs")

New Agent Workflow

Phase 1: Design (before writing)

Before beginning, you MUST have a clear, coherent, and compelling answer to each of the following questions:

1. **Define the role** in one sentence — what does this agent do and why does it exist? 2. **Identify pipeline stage(s)** — which stage(s) does it operate in, or is it "any/on-demand"? 3. **Identify similar agents** — read `.claude/agents/README.md` (Agent Index + "Commonly Confused Pairs") to find the 1-3 most similar existing agents. You MUST differentiate from these in your Core Distinction table. 4. **Determine subagent type:**

• `general-purpose` — needs file writes, code execution, or tool access beyond reading
• `Plan` — read-only validation, discovery, or verification

5. **Determine skill dependencies** — will this agent need to invoke any skills? 6. **Determine hook requirements** — will this agent need per-agent hooks? (see "Per-Agent Hooks" below)

If any of these answers are vague, in doubt, or incomplete, the quality and reliability of the ensuing agent file will suffer. If the agent authoring process has been initiated by the user, make sure to ask these questions directly, and ask follow-up questions to enhance the quality of their responses as you go. Before proceeding to Phase 2, make sure the user agrees with your enhanced answers explicitly.

Phase 2: Author (write the definition)

1. Read `agent_reference/AGENT_TEMPLATE.md` for the canonical 12-section structure 2. Read `references/template-walkthrough.md` for section-by-section guidance and common mistakes 3. Read `references/cross-agent-standards.md` for mandatory standardized elements 4. Write the agent file to `.claude/agents/[agent-name].md` following the template exactly 5. Run self-validation:

• [ ] All 12 sections present (11 REQUIRED + 1 CONDITIONAL)
• [ ] Core Distinction table differentiates from identified similar agents
• [ ] Confidence Assessment uses standardized H/M/L model with rationale
• [ ] Learning Signal uses standardized 5-category model
• [ ] Anti-patterns in 4-column table format (# | Anti-Pattern | Problem | Correct Approach) (minimum 5)
• [ ] STOP Conditions use standardized format
• [ ] Invocation Pattern shows complete Agent() syntax with BASE_DIR
• [ ] COMPLETE criteria: minimum 3
• [ ] INCOMPLETE criteria: minimum 3
• [ ] Self-Check has minimum 4 questions
• [ ] Total length 400-700 lines (flag if approaching 800+)
• [ ] Large inline code blocks minimized (extract to `agent_reference/` only if shared across agents)
• [ ] Per-agent hooks registered in frontmatter if agent executes Python (see "Per-Agent Hooks" below)

Phase 3: Integrate (wire into the ecosystem)

1. Read `agent_reference/FRAMEWORK_INTEGRATION_CHECKLIST.md` § 2 for the canonical checklist of registration points 2. Execute all [M] (mandatory) items — A1-A5, A14 3. Review and execute applicable [C] (conditional) items — A6-A13, A15-A16 4. Run cross-cutting consistency checks (§ 6) — count words, cross-references, naming 5. For supplementary walkthrough detail, also consult `references/integration-checklist.md`

Phase 4: Validate (confirm completeness)

Run these verification checks:

# 1. Verify agent appears in all registry files
grep -l "agent-name" .claude/agents/README.md CLAUDE.md README.md

# 2. Cross-agent consistency (run for new agent file)
grep -c "HIGH.*MEDIUM.*LOW\|BLOCKER.*WARNING.*INFO\|Learning Signal\|STOP Conditions" .claude/agents/[agent-name].md

# 3. Verify agent count matches actual count
ls .claude/agents/*.md | grep -v README | grep -v _revised | wc -l
# Compare with the number in READ