Module artifacts 

Read-side access to Claude Code’s on-disk agent definitions.

Claude Code resolves user-level agents from ~/.claude/agents/<name>.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 module is read-only on purpose – mutations (create / update / delete) are tracked separately so consumers that only want to introspect the agent set don’t need to opt into write semantics.

Two levels of granularity:

• AgentsRoot::list – enumerate every agent at the root with summary metadata (name, description, tools, model, file path).
• AgentsRoot::get – read one agent’s full record including the prompt body.

Frontmatter format

Real-world agents look like:

---
name: rust-qa
description: Use PROACTIVELY before declaring Rust work done...
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a Rust quality gate. ...

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

Example

use claude_wrapper::artifacts::AgentsRoot;

let root = AgentsRoot::home()?;
for summary in root.list()? {
    println!("{}: {}", summary.name, summary.description.as_deref().unwrap_or(""));
}
let agent = root.get("rust-qa")?;
println!("{}", agent.body);

Slug, name, file stem

By convention an agent’s name matches its filename stem: rust-qa.md carries name: rust-qa. The two can diverge – the parser keeps both. AgentsRoot::get looks up by file stem (because that’s what the filesystem indexes), not by the frontmatter name.

Structs

Agent

Full agent record returned by AgentsRoot::get.

AgentSummary

Lightweight metadata for one agent, returned by AgentsRoot::list. Strips the body to keep listings cheap.

AgentWriteInput

Input to AgentsRoot::write / AgentsRoot::write_new.

AgentsRoot

Root directory of Claude Code’s user-level agent definitions. Defaults to ~/.claude/agents; override with AgentsRoot::at for tests or non-default installs.