DAAF-Contribution-Community/daaf / .claude/skills/agent-authoring
agent-authoring
VerifiedGuide 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 20.0 KB |
| references/cross-agent-standards.md | markdown | 9.4 KB |
| references/integration-checklist.md | markdown | 10.8 KB |
| references/template-walkthrough.md | markdown | 14.9 KB |
references/template-walkthrough.md
View on GitHub# Agent Template Walkthrough
> **Purpose:** Section-by-section guidance for writing agents that conform to
> `agent_reference/AGENT_TEMPLATE.md`. For each section: what to write, what NOT
> to write, and which existing agent exemplifies best practice.
>
> **Read alongside:** `agent_reference/AGENT_TEMPLATE.md` (the canonical blueprint)
>
> **Writing standard:** `agent_reference/DOCUMENTATION_STANDARDS.md` governs the
> prose in every section. Agent files are agent-facing (§ Audiences): internal
> terms are fine, present tense only (§ S5 Current State), and any user-facing
> message template follows § S3 Plain for Users. When an exemplar named below
> departs from the standard, follow the standard rather than the exemplar.
---
## Section 1: Title and Purpose
**What it is:** The agent's one-sentence identity and invocation type.
**Format:**
```markdown
# [Agent Name] Agent
**Purpose:** [One sentence — what this agent does and why it exists.]
**Invocation:** Via Agent tool with `subagent_type: "[general-purpose | search-agent]"`
```
**Guidance:**
- Title uses H1 (`#`) with agent name in title case + "Agent" suffix
- Purpose is ONE sentence, not a paragraph
- Purpose answers both "what" and "why" — not just "what"
| Good | Bad |
|------|-----|
| "Reviews executed scripts for correctness and methodology alignment, providing independent secondary QA after each Stage 5-8 execution." | "Helps with code review." |
| "Diagnoses execution failures using scientific hypothesis testing when root cause is unclear." | "Handles errors and debugging tasks." |
**Best exemplar:** `code-reviewer.md` — clear purpose with scope and timing.
---
## Section 2: Identity and Philosophy
**What it is:** The agent's worldview, default approach, and differentiation from similar agents.
**Components:**
1. **Identity paragraph** — Second person ("You are..."), ~5 sentences defining expertise and stance
2. **Philosophy maxim** — Quotable, 5-15 words, serves as decision heuristic
3. **Core Distinction table** — REQUIRED, differentiates from the 1-3 most similar agents
**Core Distinction Table (CRITICAL):**
This is the **#1 failure mode in multi-agent systems** — overlapping responsibilities. Before writing, consult `.claude/agents/README.md` for:
- The Agent Index table (Key Distinction column)
- The "Commonly Confused Pairs" subsection
Your Core Distinction table must use this format:
```markdown
### Core Distinction
| Aspect | This Agent | [Most Similar Agent] |
|--------|-----------|---------------------|
| Focus | [What you care about] | [What they care about] |
| Timing | [When invoked] | [When they're invoked] |
| Output | [What you produce] | [What they produce] |
```
**If you cannot fill this table clearly, the agent may not be distinct enough.** Consider whether the functionality belongs in an existing agent instead.
**Philosophy maxim examples from existing agents:**
- research-executor: "Write first. Execute once. Capture everything."
- code-reviewer: "Trust but verify. Every script passed primary validation — now prove it was the right validation."
- data-verifier: "The analysis is guilty until proven innocent."
**Best exemplar:** `data-verifier.md` — strong adversarial stance with clear philosophy.
---
## Section 3: Upstream Inputs
**What it is:** Explicit contract of what the orchestrator must provide.
**Format:**
```markdown
<upstream_input>
## Inputs
| Input | Source | Required | How Used |
|-------|--------|----------|----------|
| [Input 1] | Orchestrator Agent prompt | Yes | [Specific purpose] |
**Context the orchestrator MUST provide:**
- [ ] [Specific item 1 — e.g., "Script path (absolute)"]
- [ ] [Specific item 2]
</upstream_input>
```
**Guidance:**
- The checklist catches incomplete Agent prompts early — be specific
- Every input must state HOW it's used, not just that it exists
- Include "Required" column — some inputs are optional (e.g., prior QA findings)
**Common mistake:** Listing inputs without explaining how they're used. "Plan path" tells the orchestrator nothing. "Plan path — used to verify transformation aligns with methodology" tells them exactly why it's needed.
**Best exemplar:** `research-synthesizer.md` — most explicit I/O specification.
---
## Section 4: Core Behaviors
**What it is:** 3-7 behavioral principles that guide the agent's decision-making.
**Key distinction:** Behaviors are PRINCIPLES, not STEPS. Steps go in Protocol (Section 5).
| Principle (belongs here) | Step (belongs in Protocol) |
|--------------------------|---------------------------|
| "Always capture pre-state before transforming" | "Step 1: Run shape check on input data" |
| "Never fix code directly — report and recommend" | "Step 3: Return findings in the Output Format" |
**Guidance:**
- 3-7 numbered principles, each 2-5 sentences
- Hit the "Goldilocks zone" — specific enough to guide, flexible enough to be heuristic
- Include concrete examples or good/bad comparisons where the behavior is non-obvious
- Domain-specific agents should include methodology subsections here
**Common mistake:** Abstract platitudes like "Be thorough and careful." This tells the agent nothing. Instead: "Validate row counts before AND after every join. A join that silently duplicates rows is worse than one that fails, because the duplication propagates undetected."
**Best exemplar:** `research-executor.md` — strong file-first protocol as behavioral principle with concrete guidance.
---
## Section 5: Execution Protocol
**What it is:** Sequential steps for the main execution flow, plus decision trees for branching.
**Degrees of freedom:**
- **High freedom** (text): When multiple valid approaches exist
- **Medium freedom** (pseudocode): When a preferred pattern exists
- **Low freedom** (exact script): When the operation is fragile or must be precise
**Guidance:**
- Sequential steps for the happy path
- Decision trees or tables for branching logic
- Mark which steps are auto-execute vs. require confirmation
- Reference external files rather than inlining large code blocks (progressive disclosure)
- For code-heavy protocols: provide ONE representative example inline, link the rest
- When a step writes a Markdown file, name it with a date or stage/sequence prefix (`{date}_{Title}_Report.md`, `05_consistency_review.md`), never a basename starting with `report`, `summary`, `findings` or `analysis`: Claude Code rejects that Write for subagents (CLAUDE.md § Project Conventions > Subagent File Output). Agents without the Write tool return text instead of writing deliverable or report files
**Common mistake:** Mixing principles (Section 4) with protocol steps. If a step starts with "Always..." or "Never...", it's probably a principle.
**Best exemplar:** `code-reviewer.md` — Three-Phase Review Protocol with clear decision points and the Five Lenses framework.
---
## Section 6: Output Format
**What it is:** The exact structure the agent returns to the orchestrator.
**MANDATORY components (every agent):**
1. **Summary** with Status + Severity fields (two-field convention: Status captures outcome, Severity captures impact)
2. **Agent-specific content** (the main findings/results)
3. **Confidence Assessment** (standardized H/M/L — see `cross-agent-standards.md`)
4. **Issues Found** (if any, with severity levels)
5. **Learning Signal** (standardized 5-category — see `cross-agent-standards.md`)
6. **Recommendations** with proceed/revise/escalate decision
**Guidance:**
- Output must be parseable by the orchestrator without ambiguity
- Use tables for structured data, not prose paragraphs
- The Confidence Assessment rationale column must contain REASONING, not labels
| Good rationale | Bad rationale |
|----------------|---------------|
| "3 independent checks confirm row counts match expected range" | "Seems correct" |
| "Join key uniqueness verified but 2.3% null keys require investigation" | "Medium confidence" |
**Best exemplar:** `data-verifier.md` — comprehensive multi-layer output with clear reasoning.
---
## Section 7: Downstream Consumers
**What it is:** Who uses this agent's output and how.
**Format:**
```markdown
<downstream_consumer>
## Consumers
| Consumer | Receives | How They Use It |
|----------|----------|-----------------|
| Orchestrator | Status + Findings | Gate decision (proceed / revise / escalate) |
| [Next Agent] | [Specific fields] | [Specific purpose] |
**Severity-to-Action Mapping:**
| Your Status | Orchestrator Action |
|-------------|-------------------|
| PASSED | Proceed to next stage |
| WARNING | Log for Stage 10 aggregation; proceed |
| BLOCKER | Invoke revision flow (max 2 attempts) |
</downstream_consumer>
```
**Guidance:**
- ALWAYS include the orchestrator as a consumer
- The severity-to-action mapping makes the output contract explicit — no ambiguity
- Think about ALL consumers: orchestrator, next-stage agents, Plan.md, Plan_Tasks.md, STATE.md, LEARNINGS.md
**Common mistake:** Omitting the orchestrator. Every agent's primary consumer is the orchestrator.
---
## Section 8: Boundaries and Error Handling
**What it is:** Three-tier boundary system + STOP conditions + autonomous deviation rules.
**Components:**
1. **Always Do** — Mandatory behaviors, no exceptions
2. **Ask First Before** — Actions requiring orchestrator/user approval
3. **Never Do** — Hard stops, absolute prohibitions
4. **Autonomous Deviation Rules** — What the agent MAY change without asking
5. **STOP Conditions** — Circuit breakers that halt execution
**Guidance:**
- The three-tier system (Always/Ask/Never) is REQUIRED
- STOP Conditions define when the agent MUST halt and escalate
- Use "STOP Conditions" as the section header (standardized terminology)
- STOP format is standardized — see `cross-agent-standards.md`
**Autonomous Deviation Rules pattern:**
```markdown
You MAY deviate without asking for:
- **RULE 1:** Bug fixes — Fix syntax errors, type mismatches, missing imports. Document in output.
- **RULE 2:** Critical functionality — Add validation, error handling if missing. Document.
You MUST ask before:
- Scope expansion
- Methodology changes
- Removing validation
- Skipping checkpoints
```
**Best exemplar:** `research-executor.md` — clear deviation rules with documentation requirements.
---
## Section 9: Anti-Patterns
**What it is:** Agent-specific things NOT to do, with explanations.
**Format:** 4-column table (with `#` numbering) PLUS supplementary DO NOT paragraphs:
```markdown
<anti_patterns>
## Anti-Patterns
| # | Anti-Pattern | Problem | Correct Approach |
|---|--------------|---------|------------------|
| 1 | [Pattern 1] | [Why it's wrong] | [What to do instead] |
**DO NOT [specific prohibition].** [2-3 sentences explaining why and what to do instead.]
</anti_patterns>
```
**Guidance:**
- Minimum 5 anti-patterns, maximum ~20
- Anti-patterns must be SPECIFIC to this agent, not generic programming advice
- "Don't use global variables" is generic → "Don't modify the input parquet file in place" is specific
- The DO NOT paragraphs are for nuanced anti-patterns that need explanation beyond a table row
**Best exemplar:** `code-reviewer.md` — 15 specific anti-patterns with detailed explanations. `notebook-assembler.md` — excellent WRONG/RIGHT comparison examples.
---
## Section 10: Quality and Completion
**What it is:** Measurable completion criteria from both directions (complete/incomplete) plus self-check.
**Format:**
```markdown
## Quality Standards
**This [task] is COMPLETE when:**
1. [ ] [Measurable criterion 1]
2. [ ] [Measurable criterion 2]
3. [ ] [Measurable criterion 3]
**This [task] is INCOMPLETE if:**
- [Failure criterion 1]
- [Failure criterion 2]
### Self-Check
Before returning output, verify:
| Question | If NO |
|----------|-------|
| [Quality question 1] | [Remediation action] |
| [Quality question 2] | [Remediation action] |
```
**Guidance:**
- Minimum 3 COMPLETE criteria, 3 INCOMPLETE criteria, 4 self-check questions
- COMPLETE criteria should be objectively measurable ("All 5 QA checks executed" not "Good quality review")
- Self-check questions should be introspective ("Did I form my own understanding BEFORE checking the Plan?")
- The COMPLETE/INCOMPLETE duality catches quality issues from both directions
**Best exemplar:** `data-verifier.md` — 8 self-check questions with specific remediation actions.
---
## Section 11: Invocation Pattern
**What it is:** A pointer to the canonical invocation template in the appropriate `WORKFLOW_PHASE*.md` file or mode reference file.
**Format:**
```markdown
## Invocation
**Invocation type:** `subagent_type: "[general-purpose | search-agent]"`
See the appropriate `agent_reference/WORKFLOW_PHASE[N]_[NAME].md` for the canonical stage-specific invocation template with full context fields.
For agent landscape context, see `.claude/agents/README.md`.
```
**Guidance:**
- The `agent_reference/WORKFLOW_PHASE*.md` files and mode reference files are the sources of truth for invocation templates. The section may also show the full Agent() call as "the general shape" when seeing the whole prompt helps the agent check what it receives; keep it identical to the canonical template, field for field, and fix the example whenever the two differ (`AGENT_TEMPLATE.md` § Section 11). Exemplar: `paper-reader.md` § Invocation
- Specify `subagent_type` so readers know the agent's capability level at a glance
- Reference the relevant WORKFLOW_PHASE file for stage-specific invocation templates (e.g., `WORKFLOW_PHASE3_ACQUISITION.md` for Stage 5-6 agents)
- The invocation template must map to Upstream Inputs (Section 3)
---
## Section 12: References (CONDITIONAL)
**What it is:** External files the agent may need to read, with trigger conditions.
**Include when:** The agent references files outside its own definition.
**Format:**
```markdown
## References
Load on demand — do NOT read all at start:
| File | When to Read | Purpose |
|------|-------------|---------|
| `agent_reference/[file].md` | [Trigger condition] | [What it provides] |
```
**Guidance:**
- Progressive disclosure — reference, don't inline
- State WHEN to read each reference (trigger condition), not just what it contains
- Keep references one level deep from the agent file
- If the agent needs to read another agent's definition, that's a design smell — consider whether the orchestrator should coordinate instead
---
## Section Order Verification
After writing, verify sections appear in this exact order:
| # | Section | Tag Wrapper | Present? |
|---|---------|-------------|----------|
| — | YAML Frontmatter | `---` | [ ] |
| 1 | Title and Purpose | — | [ ] |
| 2 | Identity and Philosophy | — | [ ] |
| 3 | Upstream Inputs | `<upstream_input>` | [ ] |
| 4 | Core Behaviors | — | [ ] |
| 5 | Execution Protocol | — | [ ] |
| 6 | Output Format | — | [ ] |
| 7 | Downstream Consumers | `<downstream_consumer>` | [ ] |
| 8 | Boundaries and Error Handling | — | [ ] |
| 9 | Anti-Patterns | `<anti_patterns>` | [ ] |
| 10 | Quality and Completion | — | [ ] |
| 11 | Invocation Pattern | — | [ ] |
| 12 | References (if applicable) | — | [ ] |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |