# Agents and Skills

**Status**: Stable
**See also**: [[Presets]] | [[Core-Engine]] | [[Creating-Addons]]

hive-mcp has two ways to package reusable agent behaviour, and they solve different
problems. Both are **plain markdown files you can drop in, copy between machines, or
publish for others to install** — no code, no rebuild, no restart of the host.

| | **Agent definitions** | **Presets** |
|---|---|---|
| Answers | *Who is this agent?* | *How should it work?* |
| Format | Markdown + YAML frontmatter | Plain markdown |
| Carries | Identity, tool allowlist, model, hooks, MCP servers | System-prompt fragments — methodology, constraints, output format |
| Lives in | `.claude/agents/*.md` | `presets/*.md` + custom dirs, or the memory store |
| Composes by | Priority override — highest source wins | Concatenation — apply several at once |

Rule of thumb: **an agent definition is a role; a preset is a skill.** You give one agent
one definition, and as many presets as the job needs.

## Agent definitions

A definition is discovered from four sources. Higher priority overrides lower, so a user
can shadow a project's agent, and a project can shadow a built-in — without editing either.

| Priority | Source | Location |
|---:|---|---|
| 3 | `:user` | `~/.claude/agents/*.md` |
| 2 | `:project` | `.claude/agents/*.md` in the project root |
| 1 | `:plugin` | contributed by a mounted addon |
| 0 | `:built-in` | shipped with the host |

### Format

```markdown
---
name: reviewer
description: Reviews diffs for correctness and contract violations
tools: ["memory", "git", "fs"]
model: sonnet
---

You review changes. Lead with the defect, not the summary.
Every finding needs a concrete failure scenario.
```

`tools` is an allowlist of tool names, or `["*"]` for everything. Omit `model` to inherit
the caller's. `hooks` and `mcpServers` are optional and follow the same shape the harness
uses, so definitions written for Claude Code work here unchanged.

### Installing one

Drop the file in and it's live — discovery is per-invocation, not cached at boot:

```bash
# just for this project
mkdir -p .claude/agents && cp reviewer.md .claude/agents/

# everywhere
cp reviewer.md ~/.claude/agents/
```

Sharing is a `git clone` into `~/.claude/agents/`, or an addon that contributes definitions
at `:plugin` priority so a whole team gets them by adding one dependency.

## Presets

Presets are system-prompt fragments applied to a spawned agent. **47 ship built-in**,
covering methodology (`tdd`, `solid`, `ddd`, `clarity`), roles (`reviewer`, `debugger`,
`security-auditor`, `api-designer`, `researcher`), coordination (`task-coordinator`,
`hivemind`), and worker archetypes (`ling`, `minimal`).

```clojure
;; one role
{:tool "agent" :command "spawn" :name "rev" :presets ["reviewer"]}

;; stack them — applied in order, later can override earlier
{:tool "agent" :command "spawn" :name "dev" :presets ["clarity" "solid" "ddd" "tdd"]}
```

### Managing them

The `preset` tool is the whole lifecycle:

| Command | Does |
|---|---|
| `list` / `list_slim` | enumerate available presets |
| `get` / `core` / `header` | fetch full body, core rules, or just the header |
| `search` | **semantic** search across preset bodies |
| `add` / `delete` | create or remove at runtime |
| `status` / `migrate` | inspect and move the backing store |

DSL shorthand: `p?` list, `p@` get, `p/` search.

Because presets are stored in the memory backend, `search` finds one by describing the job
— *"strict about test coverage before merging"* — rather than needing its name.

### Writing one

Any `.md` file is a preset; the filename becomes its name.

```markdown
# Migration Reviewer

You review data migrations.

## Rules
- A migration without a rollback path is incomplete.
- Copy before delete. Never destructive-by-default.

## Output
Lead with the risk. Then the check that would catch it.
```

Custom directories load recursively, so `my-presets/domain/finance.md` is just `finance`.

### Best practice

Keep one concern per preset. A preset that covers testing *and* security *and* style can't
be composed with anything — the whole point is stacking small ones. Order matters: later
presets override earlier on conflict.

## Which do I write?

- Reusable **identity** with a fixed toolset, meant to be spawned by name → **agent definition**
- Reusable **discipline** you want to mix into many roles → **preset**
- Both, honestly, for anything you use daily: a thin definition that names the presets it wants.