Guide · Agent skill
How to use the Observability and Instrumentation agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The observability-and-instrumentation skill is a set of instructions that tells your coding agent how to add logging, metrics and tracing to code that will run in production. It is written for engineers building services, endpoints or background jobs who want telemetry in place before the first incident. After this guide you will know how to install the skill, how to ask for it in plain language, and what to check in the output.
Observability and Instrumentationaddyosmani/agent-skills · MIT Download the skill Quick start
- 1Download the ZIP. Get the observability-and-instrumentation ZIP from this page. It contains SKILL.md.
- 2Unzip into a skills folder. Extract it into ~/.claude/skills/ for personal use, or into the project's .claude/skills/ for one project.
- 3Or upload it in the Claude apps. Go to Settings → Capabilities → Skills and upload the skill there.
- 4Confirm your stack. Make sure the service has a logging library such as pino, and decide whether you need a metrics backend.
- 5Ask for the feature with its telemetry. Describe the feature and say you want logging, metrics or tracing added alongside it.
- 6Answer the on-call questions. The agent will ask what on-call engineers need to know. Answer them, since every signal should map to one of these questions.
- 7Review the result. Check for structured events, consistent levels, correlation IDs and low-cardinality labels before merging.
What the skill makes the agent do
When the skill is active, the agent treats telemetry as part of the feature rather than an afterthought. Before writing instrumentation, it has you list the questions an on-call engineer will ask about the feature. It then chooses the right mix of structured logs, metrics and traces for those questions.
- Writes structured log events with stable event names and machine-readable fields instead of interpolated strings
- Applies consistent log levels (error, warn, info, debug)
- Attaches a request correlation ID to every log line, span and outbound call
- Instruments RED metrics for request-driven endpoints and dependencies, and USE metrics for resources
- Keeps metric labels low-cardinality and avoids user IDs or raw URLs as labels
- Warns against logging secrets, tokens, passwords or full personal data
Install the skill from the ZIP
Download the ZIP for this skill from this page. The skill is a single file, SKILL.md, inside the observability-and-instrumentation folder. Unzip it into one of two locations depending on how you want to use it:
- Personal use across projects: unzip into ~/.claude/skills/
- Single project only: unzip into the project's .claude/skills/ folder
- In the Claude apps: upload the skill under Settings → Capabilities → Skills
Trigger the skill with natural requests
You do not need a special command. The skill's description tells the agent when to use it, so ask for the outcome you want in ordinary language. Requests that match its description include adding logging, metrics, tracing or alerting, shipping a feature that runs in production, and investigating production issues where the data does not explain what happened.
- "Add logging and metrics to the new webhook handler so on-call can see failures."
- "Review this PR that adds a retry loop and a queue consumer. What telemetry is missing?"
- "Set up tracing for the checkout service across its HTTP calls to the payment provider."
- "We had an incident last night and couldn't tell what happened. Add the instrumentation we need for next time."
Check the output against the skill's rules
Review what the agent produces. The skill is most useful when you can point to the questions each signal answers. Check that log lines are structured, that metric labels come from small fixed sets, and that no secrets or personal data end up in telemetry.
- Each log, metric and span should help answer one of the listed questions
- Log levels match the on-call action described in the skill
- Histograms are used for latency, and percentiles (p50, p95, p99) rather than averages are the readout
Know what the skill needs and what it does not do
The skill assumes a running production system. It needs a logging library such as pino or an equivalent; the examples use a TypeScript logger. A metrics backend is optional. The examples use prom-client for Prometheus, but the skill says the vendor-neutral OpenTelemetry API is preferred. The skill does not run scripts and does not use the network.
The skill is not for diagnosing an outage that is happening right now. For that, it points to the debugging-and-error-recovery skill. For measured slowness, it points to performance-optimization.
What people use it for
- Adding structured logs and RED metrics to a new HTTP endpoint before it ships
- Reviewing a pull request that adds retries, queues or cross-service calls and identifying missing telemetry
- Adding OpenTelemetry tracing to a Node.js service so requests can be followed across hops
- Making background jobs traceable by stamping the entry point and run ID on every log line
- Setting up alerting rules that are backed by metrics the code actually emits
Frequently asked questions
How do I install the observability and instrumentation agent skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder for one project. In the Claude apps, you can instead upload it under Settings → Capabilities → Skills.
What do I need to use this skill?
You need a running production service and a logging library such as pino or an equivalent. A metrics backend is optional; the examples use prom-client for Prometheus, while the skill prefers the vendor-neutral OpenTelemetry API.
Is the observability and instrumentation skill free?
The skill is published under the MIT licence, as listed on this page. Check the licence file in the source repository for the full terms.
Does this skill run scripts or access the network?
No. The skill is listed as running no scripts and using no network. It is a SKILL.md instruction file that guides the agent's code changes.
Should I use this skill to fix an outage happening right now?
No. The skill says diagnosing a failure happening now is covered by the debugging-and-error-recovery skill. This skill helps you add the telemetry that makes future diagnosis faster.
How is this different from the performance-optimization skill?
This skill focuses on making production behaviour visible through logs, metrics and traces. The performance-optimization skill is for profiling and optimizing measured slowness.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you build services, endpoints or background jobs that run in production and your incidents are slow to diagnose because the data is missing. Skip it if you have no production system, or if you need help with an active outage or measured slowness, since the skill directs you to other skills for those.
Download the skill