Guide

Agent Startup Guide

This is the authoring guide for startup content: what should live in skills, what should live in guidance files, and how the layering model actually reaches an agent at boot time.

For raw schema fields, use AgentSpec and RigSpec.

Two startup categories

Context loading

Markdown files that shape who the agent is, how the team works, what project context matters, and how the environment should be understood. This is still the highest-value authoring path today.

Deterministic configuration

Projected hooks, runtime resources, permissions, MCP setup, and related environment configuration. The spec can describe it, but reliability still varies by runtime.

Skills vs guidance files

Put it in a skill when

The knowledge is reusable across rigs.

It teaches a procedure or methodology.

It could be used by multiple agent types.

Put it in startup or guidance when

The content is rig-specific or role-specific.

It defines identity, team context, or service/environment details.

It should change with the topology rather than with the reusable agent type.

Layering order

1. Agent layer — top-level startup in the AgentSpec

2. Profile layer — startup in the active profile

3. Rig layer — rig-wide startup block

4. Culture layer — the rig `culture_file`

5. Pod layer — startup scoped to one pod

6. Member layer — startup scoped to one member

7. Operator layer — system-injected runtime overlays

Most rigs only need a few layers in practice: role guidance at the agent level, a culture file at the rig level, and minimal pod/member overlays only where teams truly diverge.

Delivery mechanisms

files:
  - path: guidance/role.md
    delivery_hint: guidance_merge
    required: true
  - path: skills/openrig-user
    delivery_hint: skill_install
    required: true

actions:
  - type: send_text
    value: "Load openrig-user and verify your environment."
    phase: after_ready
    idempotent: true

`guidance_merge` and `skill_install` happen before harness boot.

`send_text` happens after the harness is ready and works best for identity grounding and explicit instructions to load projected skills.

`applies_on` lets you split fresh-start-only content from restore content.

Current support matrix

Guidance projection (`guidance_merge`)

Supported

Reliable. Primary delivery path.

Skill projection (`skill_install`)

Supported

Reliable. Files are projected before harness boot.

`send_text` after ready

Supported

Reliable when the harness TUI is ready.

Hook projection

Experimental

Files can be copied, but runtime integration varies.

Runtime resource projection

Experimental

Projection exists, runtime-specific handling is still maturing.

MCP installation

Experimental

Best treated as described desired state plus agent self-check.

System dependency installation

Not deterministic

Describe it in startup guidance and let the agent handle it.

Practical recommendation

Describe the desired end state in markdown first, include a system check, and let the local agent verify or repair the environment. The deterministic path in the spec is valuable, but the context-loading path is still the most dependable cross-runtime authoring technique.