---
name: writing-plugins
description: >
  Read this before authoring or substantially changing a plugin, agent, or skill
  for Archie. It's the conceptual playbook for building plugins that fit Archie's
  multi-agent, single-orchestrator model — what a plugin must respect, why every
  plugin usually needs an orchestrator-facing skill, and how to think about agents
  vs skills vs PM skills. Triggers on "write a plugin", "add an agent", "add a
  skill", "create a new domain", "make a new teammate". This is the "how to think
  about it" layer; the README's Plugins section and docs/architecture/plugin-system.md
  are the "how to wire it up" layer.
---

# Writing Plugins for Archie

The README's **Plugins** section and `docs/architecture/plugin-system.md` document the mechanics: directory layout, frontmatter fields, how an agent's prompt is composed, the new-plugin checklist. **Read those for the how.** This playbook is the *why* — the design principles that make a plugin actually work inside Archie, which are easy to miss if you only follow the mechanical steps.

This skill ships inside the example plugin set (`examples/plugins/`) so it travels with a copyable, runnable example — and it is itself an example of the `SKILL.md` format.

## The one thing to internalize: there is a single orchestrator

Archie is a multi-agent system with exactly **one user-facing agent: the PM** (the "Archie" persona the user talks to, over Slack or the CLI). Every other agent is **headless** — it has no user-messaging tools, never talks to the user, and never sees the conversation directly. A specialist agent receives a brief from the PM, does its work, and **hands content back to the PM**, which delivers it.

Everything you build has to respect this. The most common way a new plugin fails is by assuming its agent can talk to the user. It can't.

**Study the bundled `helper/` + `pm/` example as the reference implementation.** The `assistant-agent`:
- has no user-messaging tools — it produces a result *body* and hands it to the PM, which delivers it;
- references people and destinations by plain name and lets the PM resolve them at delivery time;
- has clear stopping points ("report back to the requesting agent, then stop").

Its PM-side counterpart (`pm/skills/example-task/SKILL.md`) owns the user conversation. That division — specialist produces, PM delivers — is the pattern to copy.

## What a well-formed plugin respects

1. **The hand-off pattern.** The agent returns content for the PM to deliver; it never assumes user access. Don't give a specialist user-messaging tools or tell it to "post to the user".
2. **An orchestrator-facing route.** The PM only knows how to use a new agent if there's a path to it. Usually that means a **PM skill** in `pm/skills/` that tells the PM when to route to your agent, what to collect first (intake), how to brief it, and how to present the result. Without this, your agent is unreachable — the PM won't invent a workflow for it.
   - **The exception: self-explanatory agents.** If the agent's `role`/`expertise` plus its self-describing MCP tools are enough for the PM to route a request and relay the answer (e.g. "ask the agent that can reach system X"), a dedicated PM skill may be unnecessary. Decide deliberately: if using the agent well requires *any* multi-step intake, sequencing, confirmation, or delivery shaping, it needs a PM skill. When in doubt, write one.
3. **Clear stopping points.** Every agent must know when to stop and hand back. Headless agents that keep working break the turn model. State the stopping points in the agent body.
4. **Discoverable integrations.** If the agent reaches an external system via MCP, give that server a clear one-line `description` in `.mcp.json`. The PM is shown these descriptions and uses them to route ("check the issue tracker" → the agent whose line lists it). A cryptic or missing description means the PM can't route to it.
5. **The right home for each piece of knowledge.** Identity and "which skills to load when" go in the **agent body**. Reusable craft, templates, reference data, and rules go in **agent skills**. Orchestration — intake, delegation, delivery — goes in **PM skills**. Don't put task detail in the agent body; don't put orchestration in an agent skill.
6. **Teach concepts, not mechanics.** Write so a non-developer could follow the skill end to end: say *what* to achieve and *what judgement to apply*, and trust the agent with its own tools and standard flows (delegating, edit mode, PRs, posting to the user). Don't name specific tools, hardcode call syntax, script those generic steps, or bake in harness internals (session ids, log files, symlinks, env vars, "auto-loaded into context") — they go stale and bury the intent. Domain procedure (what to check, which fields, what order for the work) is fair game; the tool and harness plumbing isn't. A specialist skill describes the **result to produce** (it's headless and hands content to the PM); a PM skill teaches routing and judgement. Keep concrete product facts (names, IDs, formats, character limits).

## Generic vs repo agents — pick the track

- **Generic (plugin) agent** (no `metadata.archie.repo[s]`): read-only, no git. For domains that reason over data, draft content, or query MCP systems — marketing, analytics, ops, support, research.
- **Repo agent** (`metadata.archie.repos: [...]`): gets git worktrees, branches, and PRs in edit mode. For work that changes code. An agent can mount **more than one repo** (list several under `repos`, mark one `primary`) when its work naturally spans related repositories.

The README's Plugins section has the exact frontmatter for each.

## A sane authoring order

1. **Decide the domain and the track** (generic vs repo). One plugin = one domain.
2. **Write the agent(s)** — frontmatter (`role`, `expertise`, optional `model`, repo metadata, `mcpServers`) plus a body that covers identity, which skills to load and when, coordination with peers, and stopping points. Keep it about *who the agent is*, not task detail.
3. **Write the agent skills** — the craft, templates, and reference material the agent loads on demand. Embed full reference content; the agent can't browse external docs.
4. **Write the PM orchestration skill** (`pm/skills/<name>/`) — unless the agent is genuinely self-explanatory. This is what makes the agent reachable. Give it a `description` rich with the trigger phrases the PM will match against.
5. **Wire MCP** — list servers in the agent's `mcpServers`; make sure each has a clear `description` in `.mcp.json`.
6. **Validate** — frontmatter parses; agent IDs are unique across *all* plugins (`<filename>-agent`); every referenced skill/file exists; there's a PM-facing route (or a deliberate self-explanatory decision).

## Common mistakes to avoid

- An agent that "posts to the user" or assumes it can see the conversation. (It's headless.)
- A new agent with no PM skill and no self-explanatory route — unreachable.
- Orchestration logic stuffed into the agent body, or task templates stuffed into the agent body instead of a skill.
- MCP servers with no `description` — the PM can't route to them.
- Hardcoded tool-call syntax inside skills instead of plain-language instructions.
- A duplicate agent ID (collision across plugins fails the registry at startup).

When the mechanics are unclear, go back to the README's Plugins section and `docs/architecture/plugin-system.md`. When the *design* is unclear, re-read how the `helper`/`pm` example splits work between its agent and its PM skill — that split is the heart of writing a plugin that fits Archie.