Write Assistant

Write Assistant

Author and maintain agent system prompts: the always-loaded persona, capabilities, and constraints that define a worker. One artefact, two flows: create from requirements or update in place.

Decide first

• Create vs update vs split. Split an agent when one prompt mixes different tools, guardrails, models, or output styles that diverge in practice.
• Examples vs no examples. Add 1-2 examples for subjective style or judgment work; omit for procedural agents.
• Triggers vs direct invocation. Workers selected by routing need a trigger-rich description; user-invoked agents only need a name.

Required native structure

This template shows native client output. In this repository, keep metadata in header.toml and the body in prompt.md without frontmatter (see Repository source).

---
name: <agent-name>
description: <one-sentence trigger summary>
---

# <Name> - <Role>

## Role & Approach

<2-4 sentences: persona, tone, core focus>

## Expertise

<bullet list of specific capabilities>

## Tool Usage

<only if tool guidance is non-default>

## Examples

<1-2 demonstrations for subjective or judgment tasks; omit for procedural agents>

## Output Format

<templates, JSON schema, or structure contract>

## Constraints

<what NOT to do>

The seven-element template (role, mission, capabilities, process, constraints, output format, examples) is the consensus across Anthropic, OpenAI, and Google guidance. See references/structure.md for filled examples per platform.

Repository source

Use the coordinator, worker, caller, parent/child, command owner, and context definitions in instructions/global.md. A worker never gains dispatch authority from a persona, command, or skill. Keep native client identifiers unchanged.

In this repository, author metadata in header.toml, not in the Markdown body. The composer generates native client frontmatter.

Use [common] description for the shared description. Agent names derive from directory names. Keep the agent body in prompt.md without frontmatter.

Use [claude], [opencode], [codex], and [pi] for native non-model fields. Put agent model and effort defaults under [routing.<provider>]. Pi defaults use [routing.pi.<inference-provider>] model and thinking.

Agent headers are the sole routing default source for Claude Code, Codex, and Pi. Their commands and ordinary skills remain model-neutral. Explicit launch-time child model, thinking, or effort overrides remain supported. Caller-context execution never changes the caller's model.

Pi uses only the exact active provider's agent route. Missing routes use native fallback. Generated Pi headers leave native model and thinking pins unset so launch arguments take effect. Separately installed native agent pins can take precedence over Agent arguments.

OpenCode agent and command model metadata support remains unchanged. Current OpenCode agents inherit the session model. Ordinary OpenCode skill routing remains rejected.

Missing provider tables mean no overrides, not disabled output. Omit fields to inherit defaults. TOML has no null.

Catalogues

Use the generated agent catalogue for descriptions and model defaults. Use the command catalogue for associations and client entry behaviour, and the skill catalogue for reusable skills.

After additions, removals, metadata changes, or routing changes, run just update-assistant-catalogue, then just check-assistant-catalogue. These shared recipes update and check all three catalogues. Edit source metadata, never generated rows. Never decrypt bodies for catalogue generation. Keep authoring explanations in documentation, not duplicate inventories.

Voice

• Second person, imperative. "You are…", "Use X when Y."
• No first person ("I will…" reduces adherence).
• No "you should" - use the bare imperative.
• No hedging or filler. Skip "IMPORTANT" / "YOU MUST" caps; Opus 4.5+ and Sonnet 4.6 over-trigger on aggressive language.
• One default per decision. Mention alternatives only if behaviour diverges.

See references/voice.md for imperative-vs-descriptive rewrites.

Token budgets

• 400-700 words / 500-3,000 chars / ≤200 lines.
• Up to 1,200 words / ~10,000 chars hard cap for prompts with examples.
• Keep OpenCode direct startup near the measured floor: about 15K tokens with MCPs disabled.
• Keep /ready close to direct startup and do not eager-load delegate-task; delegated sessions around 17K-18K are acceptable today.
• Under-10K total context remains useful compliance evidence, not a current OpenCode startup target; reduce delegate-task and always-listed skill or agent metadata first.
• Terse instructions outperform verbose ones (~5x fewer tokens, ~8% better compliance).

Identifier rules

• 3-50 characters. Lowercase a-z, 0-9, hyphens.
• 2-4 words. No underscores. No reserved words (anthropic, claude).
• Avoid generic terms (helper, assistant, agent, bot).
• Match the name: field, the directory name, and the file basename exactly.

Description and triggers

• One sentence. Front-load the use case.
• For sub-agents on Claude Code, add 2-4 <example> blocks (Context / user / assistant / <commentary>) inside the description. See references/triggers.md.
• For portable agents that target Codex, OpenCode, or Pi as well, keep the description plain prose; extra <example> blocks degrade gracefully on those platforms but add noise.

Description craft mirrors write-skill's doctrine for SKILL.md descriptions; the difference is voice. Agent descriptions read in the third person from the routing layer's perspective but are triggered by user intent, exactly like skills.

Tool guidance

• List tools the agent owns and tools it must not touch (least privilege).
• Tool documentation deserves as much engineering as the prompt itself.
• Omit the section entirely if the agent uses the default tool set.

Examples policy

Required when:

• Output style is subjective (voice, tone, structure).
• Judgement decides what to include or exclude.
• The format is complex enough that prose description loses fidelity.

Optional when:

• The task is procedural with one correct output form.
• Output is short, structured, or fully constrained by a schema.

Keep examples compact. Use <example_input> / <example_output> tags.

Update flow

1. Read the agent prompt and any companion command prompts.
2. Identify original intent before changing it.
3. Diagnose: voice, structure, redundancy, missing examples, contradictions.
4. Flag contradictions explicitly before editing (e.g. "be concise" alongside "be thorough"); pick a default in the rewrite.
5. Apply surgical edits. Preserve output format templates, few-shot examples, decision criteria, explicit constraints, tool-specific guidance, and numeric limits.
6. Apply the catalogue rules when the change affects catalogue sources.
7. Record the change as a changelog.

Output

When invoked to create, produce header.toml and prompt.md in this repository. Elsewhere, produce the complete native agent prompt.

When invoked to update, produce the edited prompt plus this changelog:

| Removed     | Rationale           |
| ----------- | ------------------- |
| `<section>` | `<why ineffective>` |

| Preserved   | Rationale          |
| ----------- | ------------------ |
| `<element>` | `<why it matters>` |

| Added       | Rationale        |
| ----------- | ---------------- |
| `<element>` | `<gap it fills>` |

Append a word count and a flag for any contradictions surfaced before editing.

If invoked as a worker for routing reasons, follow the response contract from delegate-task.

Anti-patterns

• Pre/post checklists or self-review instructions.
• Persona descriptions beyond 2-3 sentences.
• Vague terms with no criteria ("appropriate", "when needed", "if relevant").
• Repeated constraints across sections.
• Contradictions left unresolved.
• "Always use tools" / "never use tools" without a hierarchy.
• Output format described in prose rather than shown.
• Generic LLM behaviours ("be proactive", "ask clarifying questions").
• AGENTS.md content (project rules, build commands) inside the agent prompt - that belongs in AGENTS.md; see write-agents-md.
• Frontmatter fields beyond name and description on portable agents; see write-skill/references/portability.md for the field matrix.

References

• references/structure.md - filled examples of the seven-element template per platform (Claude Code, Codex, Pi/OpenCode).
• references/voice.md - imperative-vs-descriptive rewrites; do/don't pairs.
• references/triggers.md - sub-agent description craft and <example> block format.

Related skills: write-skill (for SKILL.md files; shares description-craft doctrine), write-agents-md (for project instruction files).