# Write Assistant

> Write Assistant

- Skill: `wimpysworld/write-assistant` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add wimpysworld/write-assistant`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wimpysworld/write-assistant/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: wimpysworld (https://skillmd.com/u/wimpysworld)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/wimpysworld/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](#repository-source)).

```markdown
---
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](../../agents/README.md) for descriptions and model defaults. Use the [command catalogue](../../commands/README.md) for associations and client entry behaviour, and the [skill catalogue](../README.md) 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](#catalogues) 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:

```markdown
| 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).