PlugWiki

observability-and-instrumentation Skill for Claude: Logs, Metrics, Traces

observability-and-instrumentation makes Claude add logging, metrics, tracing and alerts while it builds a feature, not after the first incident.

Installs
59K
on skills.sh
Stars
112.6K
on GitHub
Updated
Nov 2026
last repo commit

This skill, from Addy Osmani's agent-skills collection, starts with questions rather than tools. Claude writes down two to four questions an on-call engineer will ask about the feature, then adds only the signals that answer them. Logs say what happened, metrics say how often, and traces say where time went.

The SKILL.md sets concrete rules. Log JSON events with stable names and a correlation ID, label metrics only with small fixed sets, alert on symptoms users feel, and give every alert a runbook. Its examples use TypeScript with Express, prom-client and OpenTelemetry. The skill is one SKILL.md file with no bundled scripts.

Good for

  • Developers shipping a service, endpoint or background job to production
  • On-call engineers tired of incidents they cannot diagnose
  • Reviewers checking PRs that add retries, queues or cross-service calls

Install observability-and-instrumentation

Claude Code

  1. 1

    Copy this prompt.

    Install the observability-and-instrumentation skill in Claude Code. Run this command:

npx skills add https://github.com/addyosmani/agent-skills --skill observability-and-instrumentation

Then check that it loaded and tell me how to use it.
  2. 2

    Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

From its listing on skills.sh. Source.

What's in the skill

When it loads

Instruments code so production behavior is visible and diagnosable. Use when adding logging, metrics, tracing, or alerting. Use when shipping any feature that runs in production and you need evidence it works. Use when production issues are reported but you can't tell what happened from the available data.

Sections in SKILL.md

  1. Overview
  2. When to Use
  3. Process
  4. 1. Define "working" before instrumenting
  5. 2. Pick the right signal for each question
  6. 3. Structured logging
  7. 4. Metrics
  8. 5. Distributed tracing
  9. 6. Alerting
  10. 7. Verify the telemetry itself
  11. Common Rationalizations
  12. Red Flags
  13. Verification

Key facts

Author
addyosmani (GitHub repo owner)
Repo
addyosmani/agent-skills
Installs on skills.sh
59,003 as of 2026-11-02
GitHub stars (repo)
112,555 as of 2026-11-02
Last repo commit
2026-11-01
License
MIT
Files
1 file (SKILL.md only)
Works in
Claude Code, Cursor, Codex, Gemini CLI, Antigravity CLI, Windsurf, OpenCode, GitHub Copilot and Kiro (README lists setup for each)
skills.sh audits
Gen Agent Trust Hub pass, Socket pass, Snyk pass

What it includes

  • Write 2 to 4 on-call questions first

    Every signal added later must help answer one of them. If you cannot name the questions, the skill says you are not ready to instrument.

    1. Define 'working'

  • Log, metric or trace for each question

    Metrics tell you that something is wrong, traces tell you where, logs tell you why.

    2. Pick the right signal

  • JSON events, levels, correlation IDs

    Stable event names, consistent error/warn/info/debug levels, a request ID on every line, an entry-point field when several paths write to one log, and no secrets or full PII.

    3. Structured logging

  • RED for services, USE for resources

    Rate, errors and duration for endpoints and dependencies. Use histograms and percentiles, and keep labels to small fixed sets to avoid a cardinality blowup.

    4. Metrics

  • OpenTelemetry with auto-instrumentation

    Manual spans only around meaningful units of work, context carried across every async boundary, low head sampling by default.

    5. Distributed tracing

  • Alert on symptoms, two severities, runbook link

    Page for user-facing problems, ticket for degradation. Runbooks go in docs/runbooks/ and name what it means, the first check and who to escalate to.

    Write · 6. Alerting and runbooks

  • Trigger the paths and look at real output

    Force an error in staging, send test traffic, follow a request across services and fire each new alert once.

    7. Verify the telemetry

From the official docs

Questions

What does observability-and-instrumentation do?

It makes Claude treat telemetry as part of the feature. Claude decides what questions on-call will ask, adds structured logs, metrics, traces and symptom-based alerts to answer them, then checks the output is real.

How do I install it?

Use the install box above. The README gives npx skills add addyosmani/agent-skills --skill observability-and-instrumentation for one skill. The README says a per-skill install copies only skills/<name>/, not the repo-level references/ folder. The SKILL.md ends by pointing to ../../references/observability-checklist.md, which a per-skill install does not copy.

Is it only for Node and TypeScript?

The code examples are TypeScript, with Express, prom-client and OpenTelemetry's Node SDK. The SKILL.md says the metrics rules are the same on any backend, and it calls prom-client one common choice rather than the only one.

When should I not use it?

Not for diagnosing a failure happening right now, which the SKILL.md sends to debugging-and-error-recovery. Also not for profiling slowness (performance-optimization) or launch-day checklists (shipping-and-launch). All three are skills in the same repo.

Does it log everything?

No. The SKILL.md says more logs do not mean more observability. It asks for a few queryable events with stable names and warns against logging secrets, tokens or whole request bodies.

Does it need scripts or an API key?

It is a single SKILL.md of instructions with no bundled scripts, and its text names no API key. Any monitoring backend you pick has its own setup.

Is it safe to use?

It adds instrumentation code and alert rules to your project, so review the diff like any other change. The SKILL.md itself warns against logging secrets and tells Claude to spot-check real log output for them.

Information

updated Nov 2, 2026

Repository
addyosmani/agent-skills
Folder
skills/observability-and-instrumentation

addyosmani/agent-skillsskills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 2
  1. observability-and-instrumentation SKILL.md · github.com
  2. addyosmani/agent-skills README · github.com

Updated Nov 2, 2026.