scaffold-subagent

The sub-agent skeleton skill. Reads the fleet project's conventions, creates the agent directory + the AICP context trio (CLAUDE.md/SOUL.md/AGENTS.md) + agent.yaml manifest + source/test stubs, registers in fleet manifests. Sister to openclaw-add-agent which then activates the scaffolded agent in a running OpenClaw deployment.

Trigger phrases (when to load this skill)

Load when the conversation matches any of:

• Direct verb: operator says "scaffold an agent", "create a new sub-agent", "add the X agent", "stand up a new fleet agent role".
• Mission-bound: a fleet project has identified a gap (no architect agent, no QA agent, no integrator) — operator wants the structure created.
• Sister-project agent: openfleet adding a new agent class; sister projects (dspd, nnrt) following the same trio convention.

Do NOT load when:

• Whole new top-level project — load scaffold.
• Multi-package monorepo — load scaffold-monorepo.
• Adding a NEW MCP tool to an existing agent — that's an evolve-plugin-system concern.
• Deployment-time registration (gateway register, MC visibility) of an already-scaffolded agent — load openclaw-add-agent.
• Bootstrap an OpenClaw deployment from scratch — load openclaw-setup first.

Operations

This skill has 4 named operations. Execute in order.

Operation 1: Read fleet conventions + check preconditions

Trigger: skill loaded; operator named agent + (optional) fleet path.

Process:

1. Resolve inputs:
   • Agent name: from $0 arg. Convention: kebab-case, role-descriptive (e.g., architect, qa-runner, migration-specialist).
   • Fleet project path: from $1 arg, default current directory.
2. Verify fleet project exists and is structured:

   ls <fleet>/agents/ <fleet>/config/agent-tooling.yaml <fleet>/config/agent-identities.yaml 2>/dev/null
   

   If any are missing: stop, point operator to openclaw-setup first.
3. Read existing agent conventions to copy (don't reinvent):

   ls <fleet>/agents/   # what other agents exist
   ls <fleet>/agents/<one-existing>/   # the trio shape: CLAUDE.md / SOUL.md / AGENTS.md / agent.yaml / src / tests
   

   Capture the exact directory structure used by existing agents. Match it.
4. Check for name collision:

   ls <fleet>/agents/<agent-name>/ 2>/dev/null && echo "AGENT EXISTS"
   grep -r "^\s*-\s*name:\s*<agent-name>" <fleet>/config/ 2>/dev/null
   

   If existing: stop and ask operator if this is a re-scaffold (rare; usually means abort and rename).
5. Identify the agent's MISSION + CAPABILITIES from operator. If unclear, surface specific questions:
   • What problem does this agent uniquely solve? (the mission, one sentence)
   • What 3-5 capabilities define its competence?
   • What stage(s) of work does it own (per fleet's stage map)?
   • What permission mode is its default — Think / Edit / Act?
   • What backend preference fits its work (cost-sensitive, audit-safe, fast)?

Quality bar (Operation 1 done when):

• Agent name + fleet path resolved.
• Fleet structure verified (agents dir + config files exist).
• Existing agent conventions captured (directory shape + file set).
• No name collision (or operator-authorized re-scaffold).
• Mission + capabilities + stages + mode + backend identified explicitly.

Operation 2: Create agent directory + the AICP trio

Trigger: Operation 1 inputs validated.

Process:

1. Create agent directory matching fleet convention:

   <fleet>/agents/<agent-name>/
   ├── agent.yaml          # manifest
   ├── CLAUDE.md           # Claude Code context for this agent
   ├── SOUL.md             # agent identity / personality / values
   ├── AGENTS.md           # cross-tool context (mission + rules + commands)
   ├── README.md           # human-facing — what this agent is, how to invoke
   ├── src/                # any agent-specific code
   │   └── __init__.py
   ├── tests/
   │   └── test_smoke.py
   └── prompts/            # if the agent has reusable prompt templates
       └── README.md
   

2. Author agent.yaml — the canonical manifest:

   name: <agent-name>
   mission: <one-sentence mission>
   stage: <stage(s) the agent owns, per fleet stage map>
   capabilities:
     - <capability-1>: <one-line>
     - <capability-2>: <one-line>
     - ...
   default_mode: think | edit | act
   backend_preference: <local | k2_6_openrouter | ollama_cloud | openrouter | claude>
   budget:
     max_cost_cad: <number>
     max_duration_seconds: <number>
   skills:               # which AICP skills this agent reaches for
     - <skill-name>
     - ...
   tools:                # which MCP / system tools needed
     - <tool>
   visibility:
     mission_control: true
     standing_orders: true
   

3. Author CLAUDE.md — Claude Code-specific:
   • Agent identity profile (name, mission, stage ownership).
   • Project context (this is part of <fleet> — pointer to fleet's CLAUDE.md).
   • Architecture summary (the agent's own internals + how it interacts with siblings).
   • Tech stack (matches fleet's stack — no agent-specific divergence unless explicitly justified).
   • Key principles (3-5 bullets, agent-specific).
   • Pointers (link to SOUL.md for values, AGENTS.md for cross-tool, fleet's CLAUDE.md for cross-agent).
4. Author SOUL.md — agent's identity, personality, values:
   • "I am the <name> agent. My job is <mission>."
   • 3-5 values that shape how the agent makes judgment calls (e.g., "I prefer fewer-but-clearer commits over many-but-fuzzy", "I always verify before acting").
   • 1-2 explicit anti-patterns (what this agent never does).
5. Author AGENTS.md — universal cross-tool context for the agent:
   • Hard rules (5-7 bullets the agent never violates).
   • Stage gates if applicable.
   • Quality gates (mode-bound: Think mode never edits, Edit mode never runs commands, etc.).
   • Common commands the agent reaches for.
   • Conventions specific to this agent (commit format, file layout, etc.).

Quality bar (Operation 2 done when):

• Agent directory matches fleet's existing-agent shape exactly.
• agent.yaml has all required fields populated.
• CLAUDE.md/SOUL.md/AGENTS.md trio authored with REAL agent-specific content (not boilerplate).
• Source + tests stubs exist.
• Mission, capabilities, mode, backend each appear consistently across the trio + agent.yaml.

Operation 3: Register in fleet manifests

Trigger: Operation 2 agent directory authored.

Process:

1. Update <fleet>/config/agent-tooling.yaml — add this agent's tooling section. Mirror the format used by existing agents:

   <agent-name>:
     skills:
       - <skill-1>
       - <skill-2>
     mcp_tools:
       - <tool-1>
     hooks: []
   

2. Update <fleet>/config/agent-identities.yaml — register the agent's identity:

   - name: <agent-name>
     mission: <copy from agent.yaml>
     workspace: agents/<agent-name>/
     enabled: true
   

3. Update <fleet>/config/skill-assignments.yaml (if it exists) — assign the agent to its stage(s).
4. If fleet uses Mission Control: add the agent to MC's known-agents config OR ensure MC's auto-discovery will pick it up on next reload.
5. If fleet uses standing-orders.yaml: add an introduction line so cross-agent communication includes the new agent.
6. Verify YAML validity:

   for f in <fleet>/config/*.yaml; do
     python3 -c "import yaml; yaml.safe_load(open('$f'))" || echo "INVALID: $f"
   done
   

Quality bar (Operation 3 done when):

• agent-tooling.yaml registers the agent's skills + MCP tools + hooks.
• agent-identities.yaml has the new identity entry.
• skill-assignments.yaml updated if applicable (or noted as "no skill-assignments tracking in this fleet").
• MC / standing-orders updated for visibility.
• All modified config YAMLs validate cleanly.

Operation 4: Smoke + commit + announce

Trigger: Operation 3 manifests updated.

Process:

1. Smoke the agent's basic existence:

   ls <fleet>/agents/<agent-name>/   # all files present
   cat <fleet>/agents/<agent-name>/agent.yaml | python3 -c "import yaml,sys; yaml.safe_load(sys.stdin)"
   pytest <fleet>/agents/<agent-name>/tests/ 2>&1 | tail -5   # smoke test passes
   

2. Verify cross-fleet consistency:

   grep -l "<agent-name>" <fleet>/config/*.yaml | wc -l   # at least 2 (tooling + identities)
   

3. Commit as a single, scoped commit:

   cd <fleet>
   git add agents/<agent-name>/ config/agent-tooling.yaml config/agent-identities.yaml [config/skill-assignments.yaml]
   git commit -m "scaffold(agent): add <agent-name> — <mission summary>"
   

4. Announce + suggest the next skill:
   • "Agent <agent-name> scaffolded at <fleet>/agents/<agent-name>/."
   • "Registered in: agent-tooling.yaml, agent-identities.yaml, [skill-assignments.yaml]."
   • "Next: load openclaw-add-agent to ACTIVATE this scaffolded agent in the running OpenClaw deployment (gateway registration + MC visibility verification)."
5. If the agent has a stage assignment that overlaps with existing agents: surface the overlap. The fleet may want resolution before activation.

Quality bar (Operation 4 done when):

• Agent directory present + agent.yaml validates + smoke test passes.
• Cross-fleet consistency verified (agent name appears in ≥2 config files).
• Single commit made naming the agent + mission.
• Operator told the next skill is openclaw-add-agent (activation, not scaffold).
• Stage overlaps with existing agents flagged (or "no overlap" stated).

Gotchas (known failure modes — read before doing)

Gotcha 1: Trio mismatch — different mission across CLAUDE.md / SOUL.md / agent.yaml

CLAUDE.md says "this agent reviews architectures". SOUL.md says "I author tests". agent.yaml says mission is "build foundation pieces". Three documents, three missions, none of them aligned. The agent is launched and acts inconsistently because its own context disagrees about what it is.

The rule: Operation 2 step 5 — mission appears LITERALLY THE SAME across CLAUDE.md, SOUL.md, AGENTS.md, agent.yaml, and README.md. Same sentence, same words. The trio is a multi-perspective view of ONE identity; if perspectives disagree, the identity is undefined. Always verify with grep "<mission-phrase>" <fleet>/agents/<agent-name>/*.md after authoring.

Gotcha 2: Copying another agent's content verbatim

Operator says "make a new agent like the architect agent". Skill copies architect's files, find-replaces the name, calls it done. New agent has architect's mission language, architect's skill list, architect's anti-patterns. It's not a new agent — it's a renamed clone.

The rule: Operation 2 — using existing agents as STRUCTURAL templates is correct (directory shape, file set, format). Copying CONTENT is wrong. Each agent's mission / capabilities / values / hard rules must be authored fresh from Operation 1's specification. Treat existing agents as "what shape goes where", not "what words go in it".

Gotcha 3: Forgetting fleet manifest registration

Skill creates the agent directory beautifully — agent.yaml, trio, src, tests, all there. Doesn't update agent-tooling.yaml or agent-identities.yaml. The agent EXISTS on disk but is INVISIBLE to the fleet — openclaw agents list doesn't show it, MC doesn't know about it, skill discovery skips it.

The rule: Operation 3 is non-negotiable. Without manifest registration, the agent is dead code. Operation 4's quality bar verifies the agent name appears in ≥2 config files; if it doesn't, the scaffold is incomplete.

Gotcha 4: Stage overlap with existing agents undocumented

New agent's stage assignment is "test" — but the fleet already has an existing test-runner agent. Two agents both claim the test stage; OpenClaw routes ambiguously, work doubles up or falls between them. The overlap was never surfaced.

The rule: Operation 1 step 5 captures stages explicitly; Operation 4 step 5 flags overlap with existing agents. If two agents claim the same stage, surface to operator BEFORE the commit — they may want one of: split scope, replace existing, or designate the new agent as primary with the existing as fallback.

Gotcha 5: Backend / mode default that contradicts the mission

Mission is "real-time fleet orchestration with sub-second decisions". Default mode is think and backend preference is claude (high-quality but high-latency cloud). The defaults guarantee the agent will fail at its mission — every invocation pays cloud-round-trip time, decisions are slow, orchestration falls behind.

The rule: Operation 1 step 5 — mode + backend defaults must serve the mission. A latency-sensitive agent gets local backend + act mode (no human checkpoint between decisions). An audit-sensitive agent gets k2_6_openrouter (pinned provider) + edit mode (human approves before act). Don't default to "safest" if "safest" is incompatible with the mission.

Reference exemplars

The Extension Standards reference exemplars for skills are the second brain's model-builder and wiki-agent skills — see ~/devops-solutions-research-wiki/skills/. This skill follows their structure: trigger phrases, multiple named operations, per-operation Process + Quality bar, Gotchas with detection + rule + reasoning. For sub-agent ARTIFACTS specifically, openfleet's existing 10 agents are the live exemplar of the AICP trio convention; their agent-identities.yaml is the registration target.

Domain context

This skill operates in the backend-ai-platform-python domain, but its primary target is the openfleet sister project where the OpenClaw fleet of 10 agents lives. AICP itself uses skills, not agents-with-trio-files — the skill assumption is "this skill is being invoked from openfleet (or a similar fleet-class project)". The AICP CLAUDE.md/SOUL.md/AGENTS.md trio convention is documented per CLAUDE.md and is the canonical agent-context shape across the AICP fleet ecosystem. Sister projects (dspd, nnrt) follow the same trio for their own agents. The MCP tool surface and skill library this skill registers FROM is AICP's; the deployment that activates the scaffolded agent is OpenClaw's gateway + Mission Control.

Related skills

Skill	When	Why distinct
openclaw-add-agent	ACTIVATE a scaffolded agent in OpenClaw	Activation; this skill is scaffold-only
openclaw-setup	Bootstrap OpenClaw fleet from scratch	Fleet bootstrap; this skill assumes fleet exists
scaffold	New top-level project	Top-level; this skill is sub-agent within fleet
scaffold-monorepo	Multi-package monorepo from day 1	Multi-package; this skill is one agent
openclaw-fleet-status	Snapshot of fleet operational state	Read-only state; this skill modifies fleet state
openclaw-health	System audit of fleet	Audit; this skill creates an addition to audit
evolve-plugin-system	Add NEW skill / MCP-tool / hook surface	Plugin system; this skill is a fleet-internal agent