agent-onboarding

Agent Onboarding

End-to-end checklist for bringing a new agent onto the bOpen team. Work through each phase in order. Do not skip steps.

Plugin repo: ~/code/prompts (bopen-tools on the marketplace) Pushing to master IS publishing — the marketplace picks up the latest commit automatically.

---

Phase 1: Design the Agent

Before writing a single file, define the agent's identity.

• Name — choose a lowercase-hyphenated identifier (e.g., code-auditor, front-desk). This becomes the filename and the subagent_type suffix.
• Display name — the character's name as it appears in chat (e.g., "Satchmo", "Martha", "Johnny").
• Historical/cultural inspiration — pick a real figure whose expertise mirrors the agent's domain. This grounds the avatar and the system prompt voice.
• Expertise scope — one clear sentence: what the agent does and what it explicitly does NOT handle.
• Trigger phrases — what kinds of tasks should route to this agent? List 5–10.
• Delegation targets — which other agents does this one hand off to?
• Model — use sonnet for most tasks; opus for complex reasoning, security, or architecture review.
• Color — pick one: red, orange, yellow, green, teal, blue, purple, pink, gray.
• Tools — list every tool and skill the agent needs. Agents without a tools: field get full MCP access. Agents with tools: only see what's listed, so be complete.

---

Phase 2: Write the Agent File

Agents use a folder-based package structure with a symlink for Claude Code compatibility:

agents/
  {name}.md → {name}/{name}.md   (symlink — Claude Code auto-discovers this)
  {name}/
    {name}.md                    (actual agent definition — source of truth)
    SOUL.md                      (optional — personality/persona)
    HEARTBEAT.md                 (optional — execution procedures for Paperclip)
    TOOLS.md                     (optional — tool reference)
    avatar.png                   (optional — agent portrait)

Creating the folder and symlink

mkdir -p agents/{name}
# Write the agent .md file inside the folder
# Then create the symlink at the top level:
ln -sf {name}/{name}.md agents/{name}.md

Claude Code discovers agents/{name}.md (the symlink). Paperclip and ClawNet can reference the folder for the full agent package.

Frontmatter format

---
name: agent-name
display_name: "Display Name"
version: 1.0.0
model: sonnet
description: One-sentence description of what this agent does and when to route to it.
tools: Read, Write, Edit, MultiEdit, Bash, Grep, Glob, WebFetch, Skill(bopen-tools:relevant-skill)
color: blue
---

System prompt structure

Write the body in this order:

1. Role statement — "You are a [domain] specialist." One sentence.
2. Mission — What you ship/produce. One sentence.
3. Self-announcement block — Copy from an existing agent and update the version and specialization. Every agent announces itself at task start.
4. Expertise section — Bullet list of specific capabilities. Be concrete, not vague.
5. Key documentation — WebFetch URLs or file references the agent should consult. Embedding these prevents the agent from doing unnecessary research from scratch.
6. Delegation rules — Explicit list of what this agent does NOT handle and which agent to route to instead.
7. Output standards — File format, code style, testing expectations.

Key documentation to include

Every agent should have at least one concrete documentation reference. Examples:

• nextjs: https://nextjs.org/docs, https://sdk.vercel.ai/docs
• database: https://docs.convex.dev, Bun SQL docs
• mcp: ~/code/prompts/agents/mcp.md (read the existing Orbit agent for patterns)

Look at existing agents in ~/code/prompts/agents/ for reference. The mcp.md, database.md, and agent-builder.md agents are good structural examples.

---

Phase 3: Generate an Avatar

Every agent needs a portrait avatar.

Generate with gemskills

Invoke Skill(gemskills:generate-image) or delegate to the gemskills:content agent.

Prompt template:

Portrait of [historical figure name], [brief description of who they are].
Professional headshot style. Clean background. High detail.
Consistent with a team of AI agent avatars.

Specs:

• Size: 1024x1024
• Format: PNG
• Save to: agents/avatars/{name}.png

ClawNet ICO (optional)

If the agent will run as a live ClawNet bot, also generate a 32x32 ICO version for the bot's profile icon. The ICO file goes in the same agents/avatars/ directory as {name}.ico.

---

Phase 4: Update the Plugin

• Open ~/code/prompts/.claude-plugin/plugin.json
• Bump the version (patch for new agents: e.g., 1.0.86 → 1.0.87)
• The agents array is not in plugin.json for bopen-tools — the plugin auto-discovers agent .md files from the agents/ directory. No manual registration needed.
• Update ~/code/prompts/skills/deploy-agent-team/references/agent-roster.md — add a row to the roster table with the new agent's subagent_type, model, and best-for summary.
• Stage all new/modified files: agent .md, avatar PNG, plugin.json, agent-roster.md
• Commit with a clear message: Add {name} agent with avatar
• Push to master — this publishes automatically

cd ~/code/prompts
git add agents/{name}.md agents/avatars/{name}.png .claude-plugin/plugin.json skills/deploy-agent-team/references/agent-roster.md
git commit -m "Add {name} agent with avatar"
git push

---

Phase 5: Update bOpen.ai Roster

• Visit bopen.ai to check the current team roster
• The roster may auto-update from the plugin manifest within a few minutes of the push
• If the agent does not appear after 5 minutes, check whether bopen.ai requires a manual trigger or cache clear
• Verify: correct display name, correct description, correct avatar

---

Phase 6: Register in Paperclip (When Applicable)

If the agent will run inside bOpen's Paperclip instance (paperclip.bopen.io), register it there. Paperclip is the control plane — it manages heartbeats, budgets, task assignment, and org hierarchy.

Paperclip agent model

Paperclip agents are NOT the same as Claude Code plugin agents. Key differences:

Concern	Claude Code Plugin	Paperclip
Identity	.md file in plugin repo	DB record via API/UI
Personality/prompt	Body of .md file	Prompt template or instructionsFilePath
Hierarchy	Flat peers	Strict tree (reportsTo)
Budget	None	budgetMonthlyCents with auto-pause at 100%
Execution	On-demand subagent	Heartbeat protocol (scheduled wakes)
Roles	Freeform	11 fixed: ceo, cto, cmo, cfo, engineer, designer, pm, qa, devops, researcher, general

Registration via Paperclip UI

1. Navigate to the Agents page, click "Create Agent"
2. Agent name — use the display_name from the .md file (e.g., "Martha", "Jerry")
3. Adapter type — Claude Code for all bOpen agents running Claude
4. Working directory — /paperclip/.agents/{slug} where {slug} is the name from the agent .md frontmatter (e.g., code-auditor). On Railway persistent volume.
5. Model — match the model: field from the .md frontmatter (sonnet → Claude Sonnet, opus → Claude Opus)
6. Role — map to the closest Paperclip enum. Use title field for the actual job description
7. Reports to — select the agent's manager in the org tree
8. Budget — set monthly spend limit in cents. Guidelines:
   • Opus agents: $50/month (5000 cents)
   • Sonnet agents: $20/month (2000 cents)
   • Haiku agents: $5/month (500 cents)
   • CEO/CTO: higher budgets as needed
9. Capabilities — paste the description: from the .md frontmatter
10. Environment check — click "Test now" to verify adapter, API key, and working directory

Role mapping guide

bOpen Agent Type	Paperclip Role	Title (freeform)
CEO / strategist	ceo	Chief Executive Officer
Engineering lead	cto	Chief Technology Officer
Directory/routing	cmo	Front Desk / Directory Service
Financial oversight	cfo	Chief Financial Officer
Most specialists	engineer	[Actual specialty] Specialist
UI/UX agents	designer	UI/UX Designer
Project coordinators	pm	Project Manager
Testing/auditing	qa	[Code Auditor / Tester]
Infra/CI/CD	devops	Infrastructure Lead
Research agents	researcher	Lead Researcher
Everything else	general	[Actual role description]

Heartbeat protocol awareness

Agents running in Paperclip must follow the heartbeat protocol defined in the Paperclip skill (see Quick Reference table for path). Reference that skill in the agent's system prompt or install it in their working directory.

Dual-ecosystem agents

Most bOpen agents exist in BOTH ecosystems:

• Claude Code plugin: personality, system prompt, tools, skills (source of truth)
• Paperclip: runtime config, hierarchy, budget, heartbeat scheduling

The .md file in the plugin repo is always the source of truth for who the agent IS. Paperclip owns HOW it runs (schedule, budget, reporting chain). Never duplicate the system prompt — reference it or paste it into Paperclip's prompt template field.

Environment requirements

For Paperclip on Railway:

• ANTHROPIC_API_KEY must be set as Railway env var
• Working directories on /paperclip/ volume persist across deploys
• First Claude Code invocation is slow (cold start) — environment check may timeout but still works
• Agents run as node user via gosu entrypoint (not root)

---

Phase 7: Deploy as ClawNet Bot (Optional)

Only if the agent needs a live, always-on bot instance (e.g., a 24/7 support agent, a monitoring bot).

• Invoke Skill(clawnet:clawnet-cli) for the deployment workflow
• Initialize a BAP identity for the bot — this is its permanent on-chain identity
• Configure the bot's connection to the ClawNet network
• ClawNet repos: ~/code/clawnet (core) and ~/code/clawnet-bot (bot runner)
• After deployment, hand off to Johnny (clawnet-bot:clawnet-mechanic) for ongoing health and maintenance

Johnny handles: uptime monitoring, reconnects, key rotation, and ClawNet-specific debugging.

---

Phase 8: Notify Martha

After any new agent is deployed:

• Tell Martha (bopen-tools:front-desk) about the new agent's name, trigger phrases, and delegation rules
• Martha handles routing for the team — she needs to know who's available and what they handle
• Update the skills/front-desk/references/service-providers.md file if Martha's routing reference needs updating

---

Phase 9: Verify

• Spawn the new agent with a simple test task relevant to its domain
• Confirm it announces itself correctly (name, version, specialization, mission)
• Confirm it has access to the right tools and skills (check the tools: field)
• Confirm it knows its documentation references (ask it to fetch one)
• Confirm it delegates correctly (give it a task outside its scope and verify it routes properly)
• Confirm the avatar appears on bopen.ai

---

Quick Reference

Item	Location
Agent files	~/code/prompts/agents/{name}.md
Avatars	~/code/prompts/agents/avatars/{name}.png
Plugin manifest	~/code/prompts/.claude-plugin/plugin.json
Agent roster	~/code/prompts/skills/deploy-agent-team/references/agent-roster.md
ClawNet core	~/code/clawnet
ClawNet bot runner	~/code/clawnet-bot
Bot maintenance	Johnny (clawnet-bot:clawnet-mechanic)
Routing updates	Martha (bopen-tools:front-desk)
Avatar generation	Skill(gemskills:generate-image) or gemskills:content agent
Paperclip instance	https://paperclip.bopen.io
Paperclip repo	~/code/paperclip (b-open-io/paperclip)
Paperclip skill	~/code/paperclip/skills/paperclip/SKILL.md
Tortuga plugin	~/code/tortuga-plugin (@bopen-io/tortuga-plugin)
Agent working dirs	/paperclip/.agents/{slug} (Railway volume)