Agents and Skills

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

---
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:

# 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. 38 ship built-in, covering methodology (tdd, solid, ddd, clarity), roles (reviewer, debugger, security-auditor, api-designer, researcher), coordination (task-coordinator, wave-coordinator, hivemind), and worker archetypes (ling, drone-worker, minimal).

;; 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.

# 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.