Agents & MCP
Skills and prompts#
A recipe you have to remember to type is a recipe you will not use. This page is about making self-diagnosis automatic.
Agent instructions#
The lowest-effort version: a few lines in the file your agent reads on every
session — CLAUDE.md, AGENTS.md, or the equivalent for your runtime.
## Telemetry
The `clawmetry` MCP server exposes this machine's agent history across every
runtime. Use it, do not guess:
- Before starting a non-trivial task, check whether a previous session already
attempted it (`list_sessions`, then `get_session_trace`). Say what you found.
- If you hit an error, check whether it has happened before
(`list_events` with `event_type: "error"`) before debugging from scratch.
- If you make the same tool call with the same arguments three times, stop and
say so rather than trying a fourth.
- If a result comes back empty, call `get_health` before concluding nothing
happened — the daemon may be behind.That last line matters more than it looks. An agent that treats an empty result as fact will confidently tell you that you did no work last week.
A self-check skill#
For runtimes that support skills, wrap the review into one:
---
name: session-review
description: Review recent agent sessions with ClawMetry — spend, failures, and
repeated work. Use when asked how the week went, why spend rose, or whether a
task has been attempted before.
---
# Session review
1. `get_health` — confirm the daemon is current. If the last sync is stale, say
so and stop; every number below would be wrong.
2. `get_cost_summary` for the requested window, and for the equal window before
it. Report the change, not just the total.
3. `list_sessions` for the window. Flag any single session above 20% of the
total spend.
4. For each flagged session, `get_session_trace` and determine whether it
produced a durable result — a file change, a passing test, a merged fix — or
ended without one.
5. `list_events` with `event_type: "error"` for the window; group by tool.
Report: spend and its change; the sessions responsible; how much went to work
with no durable result; the tools failing most often. Name the runtimes you had
cost data for, and say which ones you did not — an unknown is not a zero.A pre-flight skill#
Shorter, and arguably more valuable, because it runs before the money is spent:
---
name: check-history
description: Before starting a task, check ClawMetry for previous attempts at
the same work and report what happened. Use at the start of any non-trivial
task.
---
# Check history
1. `list_sessions` with `since` set to 30 days ago.
2. Identify sessions plausibly about the current task, by title and by the files
their traces touch.
3. For the two most recent matches, `get_session_trace` and summarise: what was
attempted, how it ended, what it cost.
4. State clearly whether this task has been attempted before. If it has, say
what you will do differently.
Be honest about a negative result: "no previous attempt found" is a useful
answer and should not be padded.Prompt patterns that work#
Ask for the tool stream, not the narration. "List events of type error" is more reliable than "summarise what went wrong", because the events are facts and the past transcript's narration is a model's own account of itself.
Give a window. Without a since, the agent gets defaults and you get an
answer about an unclear period.
Ask it to state its coverage. "Say which runtimes you had cost data for" — without that, a comparison that silently excluded half the fleet looks authoritative.
Ask for one example, not all of them. "Show me one example of each failure" keeps the response readable and the token cost sane on a large store.
Anti-patterns#
- Do not ask for everything.
list_eventswith a 5000 limit on a large
store is a large response the agent then has to reason over. Filter first.
- Do not have the agent poll. A recipe that runs on every turn burns tokens
and adds nothing; these are start-of-task and end-of-week questions.
- Do not trust a summary of a summary. If the answer matters, ask for the
session id and read the trace yourself.
Sharing recipes#
If you build a skill that turns out to be genuinely useful, it is worth sharing — open an issue with the skill and what it caught. The good ones tend to be specific to a failure mode someone else also has.