crafting-agent-crafter-recipe

Crafting Agent Crafter Recipe

Quick Reference

---
name: agent-name
description: with trigger conditions
tools: mcp__tool1, mcp__tool2
model: inherit
color: blue|purple|red|green
---

<role>Expert Name</role>
<task>What agent does</task>
<instruction>How agent works</instruction>
<boundaries>What agent does/doesn't do</boundaries>
<workflow>
1_STEP_NAME:
  Action → Result
2_NEXT_STEP:
  Condition → action | alternative
</workflow>
<schema type="json">{"discipline":"name",...}</schema>
<execution>Rules and constraints</execution>
<success_criteria>When agent succeeds</success_criteria>

When to Use

Creating new agents → Apply contract FIRST
Validating agent files → Run validation checks
Agent fails orchestrator → Check contract compliance
Reviewing agent architecture → Verify structure

Agent Contracts

See contracts.md for complete contract specifications:

• Frontmatter contract (YAML fields)
• Required sections (all 8 sections)
• Input contract (context + sessionId)
• Output contract (JSON vs Markdown)
• Tool wrapping patterns
• Workflow requirements
• Output consolidation
• Optional patterns

Agent Validation (Execute After Agent Creation)

MANDATORY: Run after every agent creation or edit.

Check	EV Required	Pass	Fail
Frontmatter schema	YAML with name, description, model, color	All present	Missing fields
Required sections	All 8 sections present	Complete	Missing <role>, <task>, etc
Input contract	Documents context + sessionId + agent_results	Documented	Missing contract
Agent results usage	Documents how to use scope.agent_results	Explains extraction	No agent_results usage
Output contract	JSON schema OR markdown template	Format present	No output format
Tool wrapping	skill/subagentType/tools/agents	At least one	No tools wrapped
Workflow numbered	Steps use 1_, 2_, 3_	Numbered	Not numbered
Output consolidatable	Multiple outputs can merge	Consolidatable	Not mergeable
No file I/O	Agent returns data, no fs.writeFile/DB writes	Returns output	Writes files/DB
Boundaries clear	Defines what does/doesn't do	Clear	Ambiguous

Validation method:

1. Read agent file content (Read tool)
2. Check frontmatter YAML parsing (lines 1-N until ---)
3. Search for required section tags (<role>, <task>, etc)
4. Verify input contract in <instruction>/<context>
5. Verify output format in <schema> OR <output_template>
6. Search for tool references (skill:, subagentType:, tools:, agent calls)
7. Check workflow numbered steps (1_, 2_, 3_)
8. Verify output structure consolidatable with other agents
9. Cite line numbers for violations
10. Report Pass/Fail with evidence

Example validation report:

VALIDATION REPORT: security-reviewer.md

✓ Frontmatter: YAML valid [EV: lines 1-6]
  name: security-reviewer ✓
  description: present ✓
  model: inherit ✓
  color: red ✓

✓ Required sections: All 8 present
  <role> line 8 ✓
  <task> line 17 ✓
  <workflow> line 32 ✓
  <schema type="json"> line 108 ✓
  <boundaries> (via _shared-boundaries.md reference) ✓
  <execution> line 141 ✓
  <success_criteria> (implicit in execution) ✓

✓ Input contract: context + sessionId documented
  [EV: line 19 "accepts context and sessionId"]

✓ Output contract: JSON schema defined
  [EV: <schema type="json"> lines 108-122]
  discipline field: "security" ✓
  violations array: present ✓
  summary object: present ✓

✓ Tool wrapping: MCP tools in frontmatter
  [EV: tools declaration not present, uses gh CLI + cat commands]
  NOTE: Wraps system tools (gh, cat) - acceptable ✓

✓ Workflow numbered: Steps use 1_, 2_, 3_
  [EV: lines 33-106 use 1_DETERMINE_SCOPE, 2_FETCH_PR_DATA, etc]

✓ Output consolidatable: JSON structure with discipline field
  [EV: schema has "discipline": "security" - consolidatable]

✓ Boundaries clear: Explicit scope via _shared-boundaries.md reference
  [EV: line 24 references shared boundaries file]

RESULT: ALL CHECKS PASSED ✓

Example with violations:

VALIDATION REPORT: new-agent.md

✓ Frontmatter: YAML valid [EV: lines 1-5]
✗ FAIL: Missing required section <workflow>
  [EV: Searched file, no <workflow> tag found]
✗ FAIL: Input contract missing sessionId
  [EV: Line 12 only mentions context parameter]
✗ FAIL: No tool wrapping
  [EV: No skill:, subagentType:, or tools: found in file]
✗ FAIL: Workflow not numbered
  [EV: Lines 30-45 use bullets, not 1_, 2_, 3_]
✗ FAIL: Output format unclear
  [EV: No <schema> or <output_template> tag found]
✗ FAIL: File I/O found [EV: line 45]
  Pattern: fs.writeFileSync('/tmp/output.json', ...)
  Fix: Return data, let orchestrator persist
✗ FAIL: Direct DB write [EV: line 78]
  Pattern: mongodb.insertOne(...)
  Fix: Return data, orchestrator stores via service

VIOLATIONS (7): Fix all before agent is orchestrator-compatible

REQUIRED FIXES:
1. Add <workflow> section with numbered steps (1_, 2_, 3_)
2. Update input contract to include sessionId parameter
3. Add tool wrapping (skill:, subagentType:, or tools: in frontmatter)
4. Convert workflow bullets to numbered format
5. Add <schema type="json"> or <output_template> section
6. Remove fs.writeFileSync, return data instead
7. Remove mongodb.insertOne, return data for orchestrator to store

Templates & Examples

See:

• agent-template.md - Complete templates (reviewer, researcher, orchestrator)
• examples.md - Working examples with all patterns

Validation Workflow (Execute After Creation/Edit)

Phase	Action
1. Execute	Create/edit agent file
2. Validate	Read file content, gather evidence from output
3. Report	✓ ALL pass → Done | ✗ ANY fail → List violations with evidence
4. Fix	Violations found → Fix each → Re-run validation

Validation = Evidence gathering + Confirmation, NOT re-execution

Re-validation required after fixes. Repeat until ALL checks pass.