agentleFS
AgentJDrewAgentJDrew/agent-team-factory/.claude/skills/build-agent/SKILL.md

build-agent

Skill0 starsChanged 4 months agoMITView on GitHub

Create a single AI agent definition file. Use when adding an agent to an existing team, creating a specialist, defining a new role, or expanding a division.

9 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

16 rules. 0 are common, 11 are distinctive, and 5 are very specific to this project.

  • 0

    Common

    Most of the 9 edited versions we read keep these.

  • 11

    Distinctive

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read research/agent-architecture-playbook.md sections 2 (Agent Definition Template), 3 (Specialization Design), and 6 (Memory Architecture) …

    line 13
  2. Very specific:

    Read standards/floor-spec.md §2 — agent-file requirements: frontmatter with name, description, explicit model tier.

    line 14
  3. Distinctive:

    Tools: Read, Write, Edit, Grep, Glob, Bash, WebSearch, WebFetch, Agent?

    line 23
  4. Distinctive:

    If the agent spawns other agents or makes kill/advance decisions: opus

    line 37
  5. Distinctive:

    If the agent does substantive domain work (analysis, writing, code): sonnet

    line 38
  6. Distinctive:

    If the agent does mechanical transformation with no judgment: haiku

    line 39
  7. Distinctive:

    If uncertain: sonnet (safe default, upgrade to opus if quality issues emerge)

    line 40
  8. Very specific:

    Write the agent .md file using templates/agent-definition.md as the base:

    line 44
  9. Distinctive:

    No two agents write the same files.

    line 68
  10. Distinctive:

    Update board, post results, backward propagation on failure.

    line 86
  11. Distinctive:

    When this agent is spawned by an orchestrator, the spawn prompt MUST include:

    line 90
  12. Distinctive:

    After writing the agent .md file, update the team workspace so the new agent is discoverable:

    line 121
  13. Distinctive:

    Team roster: Add the agent to the roster table in the team's CLAUDE.md (row: role, spawn wave, tools, special authority).

    line 123
  14. Very specific:

    Spawn order: If the team has a spawn order (Wave 1/2/3), slot the new agent into the right wave and note why.

    line 124
  15. Very specific:

    File ownership audit: Read every other agent in .claude/agents/ and confirm no path in this agent's "Files Owned" overlaps with another …

    line 125
  16. Distinctive:

    Routing updates: If the team's CLAUDE.md has a "Routing" section, add any request types this new agent owns.

    line 126

“Common” is measured: kept by at least 6 in 10 of the 9 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Build Agent

Trigger

"Add an agent", "create a [role] agent", "I need a [specialist] for [team]", "expand [division] with a new role", "define an agent for [task]".

Research (Read Before Building)

  1. Read research/agent-architecture-playbook.md sections 2 (Agent Definition Template), 3 (Specialization Design), and 6 (Memory Architecture) for agent design patterns and anti-patterns.
  2. Read standards/floor-spec.md §2 — agent-file requirements: frontmatter with name, description, explicit model tier; exactly one authority tier (ADVISORY / COMMIT / BLOCK / VETO / HALT); Files Owned with no two agents owning the same path; dependency map; ≥3 autonomous failure triggers; On Completion postbacks.

Intake

Ask:

  1. Role name: What is this agent called? (kebab-case, e.g., "contract-reviewer", "qa-engineer")
  2. Division: Which team does it belong to?
  3. Mandate: One sentence: what is this agent's job?
  4. Model tier: See Model Selection below. Default: sonnet for specialists, opus for managers/orchestrators.
  5. Tools: Read, Write, Edit, Grep, Glob, Bash, WebSearch, WebFetch, Agent? Red team = disallow Write/Edit.
  6. Files owned: What files does this agent create/modify? (No overlap with other agents.)
  7. Feeds from / feeds to: Who gives it work? Who receives its output?
  8. Special authority: exactly one tier from the Floor Spec v2 ladder — ADVISORY / COMMIT / BLOCK / VETO / HALT. Read-only (red team)?

Model Selection Framework

TierModelUse WhenCost/Speed
OrchestratoropusMakes judgment calls, resolves disputes, owns pipeline state, spawns other agentsHighest cost, highest quality
SpecialistsonnetDomain work: writing, analysis, code, review. Most agents are here.Mid cost, fast
UtilityhaikuHigh-volume, low-judgment tasks: formatting, extraction, classification, routingLowest cost, fastest

Decision rules:

  • If the agent spawns other agents or makes kill/advance decisions: opus
  • If the agent does substantive domain work (analysis, writing, code): sonnet
  • If the agent does mechanical transformation with no judgment: haiku
  • If uncertain: sonnet (safe default, upgrade to opus if quality issues emerge)

Generate

Write the agent .md file using templates/agent-definition.md as the base:

---
name: [role-name]
description: [One-line description of role and primary output]
model: [opus|sonnet|haiku]
tools:
  - Read
  - Write
  - Edit
  - Grep
  - Glob
  - Bash
disallowedTools: []  # [Write, Edit, Bash] for red team / read-only agents
---

Mandatory Sections

1. Identity and Mandate (2-3 sentences) Who you are, what you protect, your core operating principle.

2. Files Owned (explicit paths) No two agents write the same files. If shared files exist, define a coordination protocol.

3. Key Context (3-5 domain constraints) Critical knowledge the agent needs. Known pitfalls. Quality thresholds.

4. First Action (numbered spawn checklist) Exactly what to read before doing anything: division CLAUDE.md, memory, wire, board, inbox.

5. Autonomous Failure Triggers (pre-work checks) Conditions to check BEFORE starting assigned work. If any fire, report immediately.

6. Dependency Map (upstream, downstream, parallel) Who feeds this agent. Who consumes its output. Who runs concurrently.

7. Output Format (structured) DIVISION, TASK, STATUS, RESULT, ARTIFACTS, ESCALATION. Consistent format enables automated parsing.

8. On Completion (post-work checklist) Update board, post results, backward propagation on failure.

Spawn Prompt Pattern

When this agent is spawned by an orchestrator, the spawn prompt MUST include:

[AGENT NAME]: [SPECIFIC TASK with exact file paths].
Context: [What you need to know about current state].
Input: [Exact file path or data to read].
Output: [Exact file path to write, format expected].
Priority: [P1/P2/P3].
Done when: [Specific, verifiable completion criteria].

BAD: "Alpha, work on signals."

GOOD (multi-division team): "Signal Architect: derive 3 novel direction signals from cross-asset momentum literature. Read divisions/alpha-research/memory/MEMORY.md for existing signals (avoid duplication) and research/decision-engine.md for the signal specification schema. Output to divisions/alpha-research/outbox/2026-04-15-signals.md. P2. Done when 3 signals have mathematical specification, expected frequency estimate, and ExitProfile recommendation."

GOOD (single-team): "QA Engineer: expand regression coverage on the public API endpoints. Read memory/MEMORY.md for known edge cases and comms/board.md for the current endpoint list. Output test plan to outbox/2026-04-18-api-regression-plan.md and new tests to tests/integration/api/. P1. Done when every public endpoint has at least one happy-path and one failure-path test, and CI is green."

Quality Checks

  • Mandate is specific (not "help with things" or "assist the team")
  • File ownership is explicit (no shared ownership without coordination protocol)
  • First Action reads team/division memory (institutional knowledge prevents repeated mistakes)
  • Dependency map has both upstream and downstream (orphaned agents are useless agents)
  • Output format is structured (not free text -- consumers need parseable output)
  • Red team agents have Write/Edit/Bash in disallowedTools (separation of creation from critique)
  • Autonomous failure triggers are domain-specific (not generic placeholders)
  • Model tier matches the judgment requirements of the role
  • Paths match the team's structure: multi-division uses divisions/[name]/memory/ and divisions/[name]/outbox/; single-team uses memory/ and outbox/ at root

Post-Generation (Mandatory)

After writing the agent .md file, update the team workspace so the new agent is discoverable:

  1. Team roster: Add the agent to the roster table in the team's CLAUDE.md (row: role, spawn wave, tools, special authority).
  2. Spawn order: If the team has a spawn order (Wave 1/2/3), slot the new agent into the right wave and note why.
  3. File ownership audit: Read every other agent in .claude/agents/ and confirm no path in this agent's "Files Owned" overlaps with another agent's ownership. If overlap exists, resolve it before declaring done.
  4. Routing updates: If the team's CLAUDE.md has a "Routing" section, add any request types this new agent owns.
  5. Channel post: Post a handoff note to comms/channels/[team-domain].md announcing the new agent and what it owns.

A new agent isn't "added" until the workspace knows about it. Skipping these steps produces orphan agents.


Parallel Fan-Out Note

For any multi-item batch (N ≥ 2 posts, audits, reviews, analyses, cleanups), spawn one top-level agent per item, running in parallel, rather than routing the batch through a single orchestrator that processes items serially or via internal sub-agents invisible to the user.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.