File-backed read/write access to Claude Code's on-disk agent definitions.

Claude Code resolves user-level agents from ~/.claude/agents/<stem>.md. Each file is plain markdown with a YAML-style frontmatter block delimited by --- lines. The frontmatter carries the agent's metadata (name, description, optional tool allow-list, optional model); the body is the agent's system prompt.

This is distinct from ClaudeWrapper.Commands.Agents, which shells out to claude agents. This module reads and writes the files directly.

Two levels of granularity for reads:

• list/1 -- enumerate every agent at the root with summary metadata (name, description, tools, model, file path).
• get/2 -- read one agent's full record including the prompt body and unknown frontmatter keys.

Plus write/3, write_new/3, and delete/2 for mutations.

Frontmatter format

Real-world agents look like:

---
name: auditor
description: Multi-line folded description...
tools: Read, Glob, Grep, Bash
model: sonnet
---

You are an auditor. ...

The parser is permissive: only name, description, tools, and model are typed. tools is a comma-separated list. Any other key: value pairs land in Definition.extra so unknown future keys survive a round trip. Frontmatter is optional -- a body-only file parses fine, with name defaulting to the file stem.

List-valued and folded frontmatter keys (anything this parser cannot reduce to a single inline scalar) are tolerated by capturing their raw inline value into extra rather than failing the parse.

File stem vs name

By convention an agent's name matches its filename stem: auditor.md carries name: auditor. The two can diverge -- the parser keeps both. Lookup, write, and delete all key on the file stem (that's what the filesystem indexes), not the frontmatter name.

Example

{:ok, root} = ClaudeWrapper.Agents.home()
{:ok, summaries} = ClaudeWrapper.Agents.list(root)

for s <- summaries do
  IO.puts("#{s.file_stem}: #{s.description}")
end

{:ok, agent} = ClaudeWrapper.Agents.get(root, "auditor")
IO.puts(agent.body)