| name | write-assistant |
| description | Use when creating, updating, refactoring, or reviewing an AI assistant or sub-agent system prompt - persona, role, capabilities, tools, output format, examples, and constraints. Covers Claude Code agents, OpenAI Codex / Responses-API agents, Pi assistants, and OpenCode agents. Use even if the user only says "agent prompt", "assistant", "subagent", "persona", or names the artefact by file path. |
Write Assistant
Author and maintain agent system prompts: the always-loaded persona, capabilities, and constraints that define a sub-agent. 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. Sub-agents selected by routing need a trigger-rich
description; user-invoked agents only need a name.
Required structure
---
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 shape 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.
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 a single correct shape.
- Output is short, structured, or fully constrained by a schema.
Keep examples compact. Use <example_input> / <example_output> tags.
Update flow
- Read the agent prompt and any companion command prompts.
- Identify original intent before changing it.
- Diagnose: voice, structure, redundancy, missing examples, contradictions.
- Flag contradictions explicitly before editing (e.g. "be concise" alongside "be thorough"); pick a default in the rewrite.
- Apply surgical edits. Preserve output format templates, few-shot examples, decision criteria, explicit constraints, tool-specific guidance, and numeric limits.
- Record the change as a changelog.
Output
When invoked to create, produce the complete agent prompt at the requested path.
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 sub-agent 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).
