Custom agents

A custom agent is a role with a scope. It is defined in an .agent.md file — renamed from the older .chatmode.md — discovered from .github/agents/, .claude/agents/, or your user folder, and honored by the cloud agent too.^⊙ The frontmatter is small and worth memorizing: description, tools, model, handoffs, agents, and user-invocable. That is the entire surface. Most of an agent’s power comes from choosing its tools narrowly and writing a body that says, in plain words, what it must never do.

The anatomy

Here is the first agent of the roster — the librarian, which answers product questions from documentation and never from memory:

---
description: Answers product questions from documentation, never from memory.
tools: ['microsoft-learn', 'fetch']
model: Claude Sonnet 5
user-invocable: true
---

# The Demo Harness — drewbreyer.com/harness — starter file, as of 2026-07-06

# librarian

You answer questions about Microsoft, GitHub, and Anthropic products by
reading the documentation, never from memory. You exist because this ecosystem
changes monthly and memory goes stale.

## How you work
- Answer from the Microsoft Learn MCP server and the open web. Quote the doc and
  link it.
- State the status: GA, preview, or retired, with the date if the doc gives one.
- If the docs disagree or you cannot find a primary source, say so. Do not guess.

## What you never do
- Never state a product fact you cannot cite.
- Never soften a preview into GA, or the reverse.
- Never write to any environment or file outside your notes.

## Invocation
"@librarian what is the current status of computer use in Copilot Studio, and
where is that documented?"

Read the frontmatter as a set of decisions. tools is two entries, not twenty — the librarian reads docs and the web, nothing else. model is chosen for the job. user-invocable: true means you can call it directly. The body is where the honesty lives: three things it must never do, written as instructions, not aspirations.

Subagent-only, and why

Set user-invocable: false and an agent becomes something you delegate to rather than chat with. That is exactly right for a verifier: you do not want to casually chat with a fact-checker, you want it invoked as part of a pass over another agent’s output. Subagents run in parallel by default^⊙ , so a lead agent can fan several out and collect the results — the delegation habit that makes a roster more than a list.

The delegation habit

The move to practice is small and it compounds: when a task has a natural specialist, hand it over instead of doing it inline. Ask the librarian a documentation question rather than answering from memory, and the answer arrives with a citation attached. Over an engagement, that habit is the difference between a dossier you can defend and one you merely wrote.

In the field

Create .github/agents/librarian.agent.md from the file above. Then, in agent mode, ask it a live product question — something whose answer you think you know. Notice whether it agrees with you, and whether it cites a source. That gap is why the librarian exists.