---
name: rudder-create-agent
description: Create new agents in Rudder through the `rudder` CLI with governance-aware hiring. Use when you need to inspect adapter configuration options, compare existing agent configs, draft a new agent prompt/config, and submit a hire request.
---

# Rudder Create Agent Skill

Use this skill when you are asked to hire or create an agent in Rudder.

## Preconditions

You need either:

- board access, or
- agent permission `canCreateAgents=true` in your org

If you do not have this permission, escalate to your CEO or board.

This workflow is **CLI-first**.

- Use `rudder ... --json` for structured reads and mutations.
- Use `references/cli-reference.md` as the canonical command catalog for this skill.
- Treat `references/api-reference.md` as internal/debug/compatibility documentation, not the normal runtime interface.
- Do not create agent directories, instruction files, or org metadata manually as a fallback.
- If CLI auth is unavailable in a heartbeat run, stop and report the auth problem instead of mutating the filesystem.

## Workflow

1. Confirm identity and organization context.

```sh
rudder agent me --json
```

If this returns `{"error":"Agent authentication required"}`, treat it as a run-auth failure:

- do not ask for `RUDDER_API_KEY` inside the heartbeat
- do not fall back to manual filesystem creation
- stop and report that injected agent authentication is missing or invalid for this run

2. Discover available adapter configuration docs for this Rudder instance.

```sh
rudder agent config index
```

3. Read adapter-specific docs for the runtime you plan to use.

```sh
rudder agent config doc codex_local
rudder agent config doc claude_local
```

4. Compare existing agents and redacted configurations in your organization.

```sh
rudder agent list --org-id "$RUDDER_ORG_ID" --json
rudder agent config list --org-id "$RUDDER_ORG_ID" --json
rudder agent config get "<agent-id>" --json
```

5. If the role needs organization skills on day one, inspect or import them before hiring.

```sh
rudder skill list --org-id "$RUDDER_ORG_ID" --json
rudder skill get "<skill-id>" --org-id "$RUDDER_ORG_ID" --json
rudder skill file "<skill-id>" --org-id "$RUDDER_ORG_ID" --path SKILL.md --json
rudder skill import --org-id "$RUDDER_ORG_ID" --source "<source>" --json
rudder skill scan-local --org-id "$RUDDER_ORG_ID" --roots "<csv>" --json
rudder skill scan-projects --org-id "$RUDDER_ORG_ID" --project-ids "<csv>" --workspace-ids "<csv>" --json
```

6. Draft the hire payload.

Required thinking:

- role / title / optional `name`
- `name` is optional; if omitted, Rudder assigns a distinct personal name automatically
- omit `icon` for normal hires; Rudder assigns a DiceBear Notionists avatar automatically
- only set `icon` when preserving an explicit DiceBear avatar reference or an uploaded `asset:<uuid>` image avatar reference provided by the board/UI
- reporting line (`reportsTo`)
- adapter type
- optional `desiredSkills` from the organization skill library
- adapter and runtime config aligned to this environment
- capabilities
- structured role/persona instructions for the new agent (`promptTemplate` when the CLI payload is the available surface; Rudder materializes this as `SOUL.md`)
- source issue linkage (`sourceIssueId` or `sourceIssueIds`) when this hire came from an issue

`role` is a fixed Rudder enum, not a free-form job title. Use one of:
`ceo`, `cto`, `cmo`, `cfo`, `engineer`, `designer`, `pm`, `qa`, `devops`, `researcher`, `general`.
Put specialization in `title`, `capabilities`, and `promptTemplate`. For example, a Founding Engineer hire should use
`"role": "engineer"` and `"title": "Founding Engineer"`, not `"role": "founding_engineer"`.

Do not copy Rudder's shared filesystem, memory, language, or safety contract into the hire prompt. Rudder injects that operating contract from runtime code for supported local runtimes. The hire-specific prompt should only define the new agent's role, identity, scope, tone, and durable responsibilities.

Draft `promptTemplate` as a durable SOUL document, not a one-line command. Use these sections when the role is not trivial:

- Opening: one sentence that captures who the agent is
- Mission: the outcome this agent owns
- Responsibilities: durable duties and ownership boundaries
- Boundaries: what the agent should not do or should escalate
- Decision Principles: role-specific judgment rules
- Voice: how the agent should communicate
- Continuity: what should become memory or explicit instruction updates over time

7. Submit the canonical hire request.

```sh
rudder agent hire --org-id "$RUDDER_ORG_ID" --payload '{
  "role": "cto",
  "title": "Chief Technology Officer",
  "reportsTo": "<ceo-agent-id>",
  "capabilities": "Owns technical roadmap, architecture, staffing, execution",
  "desiredSkills": ["vercel-labs/agent-browser/agent-browser"],
  "agentRuntimeType": "codex_local",
  "agentRuntimeConfig": {
    "cwd": "/abs/path/to/repo",
    "model": "o4-mini",
    "promptTemplate": "# SOUL.md -- CTO Persona\n\nYou are the CTO.\n\n## Mission\nOwn technical strategy, architecture, engineering execution, and quality bars.\n\n## Responsibilities\n- Set technical direction and execution standards.\n- Review architecture and staffing trade-offs.\n- Keep delivery risks visible and actionable.\n\n## Boundaries\n- Do not approve risky shortcuts without naming the trade-off.\n- Escalate product or budget ambiguity instead of guessing.\n\n## Decision Principles\n- Prefer simple architectures with explicit trade-offs.\n- Treat reliability, developer velocity, and product learning as linked constraints.\n\n## Voice\nDirect, specific, and evidence-led.\n\n## Continuity\nPreserve durable technical standards, repeated failure patterns, and long-running architecture decisions in memory or explicit instructions."
  },
  "runtimeConfig": {"heartbeat": {"enabled": true, "intervalSec": 300, "wakeOnDemand": true, "maxConcurrentRuns": 3}},
  "sourceIssueId": "<issue-id>"
}' --json
```

`agent hire` is the canonical surface because it preserves the real server behavior:

- if the organization does not require approval, it creates the agent directly and returns `"approval": null`
- if the organization requires approval, it creates the agent in `pending_approval` and returns both `agent` and `approval`

Do **not** substitute `rudder approval create --type hire_agent` for this step unless you are doing low-level debugging. That bypasses the canonical direct-create vs pending-approval behavior.

8. Handle governance state.

If the hire response includes `approval`, monitor and discuss on the approval thread:

```sh
rudder approval get "<approval-id>" --json
cat > /tmp/rudder-approval-comment.md <<'EOF'
## CTO hire request submitted

- Approval: [<approval-id>](/<prefix>/messenger/approvals/<approval-id>)
- Pending agent: [<agent-ref>](/<prefix>/agents/<agent-url-key-or-id>)
- Source issue: [<issue-ref>](/<prefix>/issues/<issue-identifier-or-id>)

Updated prompt and adapter config per board feedback.
EOF
rudder approval comment "<approval-id>" --body-file /tmp/rudder-approval-comment.md --json
rudder approval resubmit "<approval-id>" --payload '{"title":"Revised title","agentRuntimeConfig":{"cwd":"/abs/path/to/repo","model":"o4-mini"}}' --json
rudder approval issues "<approval-id>" --json
```

When the board approves, you may be woken with `RUDDER_APPROVAL_ID`:

```sh
rudder approval get "$RUDDER_APPROVAL_ID" --json
rudder approval issues "$RUDDER_APPROVAL_ID" --json
```

For each linked issue, either:

- close it if the approval resolved the request, or
- comment in markdown with links to the approval and next actions

## Quality Bar

Before sending a hire request:

- if the role needs skills, make sure they already exist in the org library or import them first using the Rudder org-skills workflow
- reuse proven config patterns from related agents where possible
- omit `icon` for normal hires so the server generates the default DiceBear Notionists avatar
- avoid secrets in plain text unless required by adapter behavior
- ensure the reporting line is correct and in-org
- ensure the prompt is role-specific, operationally scoped, and structured enough to become the agent's durable `SOUL.md`
- include mission, responsibilities, boundaries, decision principles, voice, and continuity when the role has ongoing authority
- prefer `sourceIssueId` or `sourceIssueIds` in the hire payload instead of manual approval linking
- if board requests revision, update the payload and resubmit through the approval flow
- do not report success unless `rudder agent hire` itself succeeded and you can cite the returned `agent.id` or `approval.id`
- creating local directories or instruction files is not evidence that an agent exists in Rudder

For canonical command syntax and examples, read:
`references/cli-reference.md`

For low-level route shapes and underlying compatibility endpoints, read:
`references/api-reference.md`