← 2.1.0 Primitive tested · runtime-test

Custom agents

Model and tools ENFORCED, not filtered; the tool is absent. No hot-reload.

Across the graph 4 layers

One node in a single signed graph. Here is how this primitive connects across the other layers.

Composed in · workflow recipes 2 of the corpus
Model-Tiered Agent PipelineCustom agents let you define model + tools. Skills can route to specific agents. Together = cost-optimized pipelines with capability matching. (VALIDATED)
Sandboxed Third-Party SkillsCustom agents enforce tool access. Reference untrusted skill with restricted agent = sandboxed execution. (VALIDATED)

Custom agents are named agent definitions (model + tool set + instructions) stored in .claude/agents/ and referenced by skill to enforce a specific runtime sandbox.

How It Works

A custom agent is a YAML frontmatter document that declares a name, description, model (haiku/sonnet/opus), tools (comma-separated list), and optional thinking flag. Skills reference it via agent: agent-name in the skill YAML. When a skill routes to its agent, the harness enforces the model and tool set as hard constraints—not filters or suggestions. A skill with agent: cheap-researcher and context: fork spawns a Haiku worker with only Read, Grep, Glob available, period.

Location: .claude/agents/ (project), ~/.claude/agents/ (global), or plugins/*/agents/ (plugin scope).

What the Test Found

Runtime test 2026-01-07 validated three behaviors:

  1. Model and tool enforcement works. A skill referencing cheap-researcher routed correctly to Haiku and refused Bash access. Tools are enforced at availability level, not execution time.

  2. Invalid agent names fail silently. Specifying agent: totally-fake-agent-name doesn't error; the harness falls back to defaults with no warning. This is the most dangerous finding.

  3. No hot-reload. Modifying an agent definition requires session restart. Skills hot-reload, but agents do not. This limits iteration speed during development.

Use Cases and Limits

Custom agents unlock cost-optimized multi-tier workflows (cheap research via Haiku, safe edits via Sonnet-only) and domain-specific tool sandboxing (read-only research, no-bash safety roles). They are reusable: define once in .claude/agents/, use in multiple skills.

The key limit: once an agent is named in a skill, you cannot override the model in that skill's YAML. Defining agent: cheap-researcher + model: opus does not promote to Opus; the agent wins. This is intentional but worth knowing.

Interaction with allowed-tools in skill YAML is untested.

Evidence & receipt
◇ ed25519 receipt
idprimitive_2baf941eb2202b4f35f9f322
alged25519
pubkey9b87705613b1e2fd064d57fa75a6b679d2856ceafad6b1daa8f982493871b6dd
sig73ca0ecfdc3f79dbb217f3607e36aa62bf581cdb0ec5e1bdc80a9ed257d9a3e9aaa1fdf906ce5844ee7e4cc790374d4471ba5c50df82b302dfde6245beb9d108

Signed with an ed25519 key held off the repo. Anyone can verify against the published public key; nobody without the secret key can forge it. Click verify: it recomputes the signature in your browser. The signature proves integrity and authorship of this exact content — not a third-party timestamp or that the underlying claim is objectively true. signedAt is when the @f3/attest pipeline ran, not when the work happened; the evidence refs carry the source dates.

Connected
← Browse 2.1.0 Night Zero Work with me