observability-and-instrumentation

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.

Quality

83%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

The canonical home for this skill is observability-and-instrumentation in addyosmani/agent-skills

Quality

Content

77%Scale 1-3

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

This is a strong, well-structured observability skill with excellent actionability — concrete code examples, clear signal selection guidance, and specific alerting rules. The workflow is well-sequenced with explicit verification steps. The main weakness is moderate verbosity: the 'Common Rationalizations' table, some conceptual explanations, and the 'Red Flags' section add persuasive/educational content that Claude doesn't need, and the referenced bundle file doesn't exist.

Suggestions

Remove or significantly trim the 'Common Rationalizations' table — it's persuasive content aimed at humans, not actionable guidance for Claude.

Provide the referenced `references/observability-checklist.md` bundle file, or remove the reference to avoid a dead link.

Dimension	Reasoning	Score
Conciseness	The skill is well-written but includes some unnecessary explanatory content that Claude already knows (e.g., defining observability, explaining what metrics/logs/traces are at a conceptual level, the 'Common Rationalizations' table which is persuasive rather than instructional). The tables and examples are efficient, but the overall document could be tightened by ~30% without losing actionable content.	2 / 3
Actionability	The skill provides fully executable TypeScript code examples for structured logging, metrics (Histogram with prom-client), distributed tracing (OpenTelemetry SDK setup), and correlation ID middleware. The alerting section gives concrete threshold examples. Every section has specific, copy-paste-ready guidance rather than abstract descriptions.	3 / 3
Workflow Clarity	The 7-step process is clearly sequenced from defining questions through verification. Step 7 explicitly covers validation of the telemetry itself with specific verification actions (force errors, check structured output, follow traces, test-fire alerts). The final verification checklist provides a comprehensive feedback loop. The workflow naturally builds from planning to implementation to validation.	3 / 3
Progressive Disclosure	The skill references `references/observability-checklist.md` and cross-references other skills (`debugging-and-error-recovery`, `performance-optimization`, `shipping-and-launch`, `security-and-hardening`), showing awareness of progressive disclosure. However, no bundle files are provided, so the referenced checklist doesn't exist. The document itself is quite long (~200+ lines) and the 'Common Rationalizations' and 'Red Flags' sections could potentially be split into a reference file to keep the main skill leaner.	2 / 3
	Total	10 / 12 Passed

Description

89%Scale 1-3

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

This is a strong description with excellent completeness and trigger term coverage. The three 'Use when' clauses effectively cover different scenarios that should trigger this skill. The main weakness is that the capability description could be more specific about concrete actions performed rather than listing high-level categories.

Suggestions

Add more specific concrete actions like 'adds structured log statements, configures distributed tracing spans, defines SLI/SLO metrics, sets up alerting rules' to improve specificity.

Dimension	Reasoning	Score
Specificity	The description names the domain ('instruments code') and lists some actions (logging, metrics, tracing, alerting), but doesn't describe specific concrete actions like 'add structured log statements', 'configure distributed tracing spans', or 'set up metric dashboards'. The actions listed are more categories than concrete tasks.	2 / 3
Completeness	Clearly answers both 'what' (instruments code for production visibility and diagnosability) and 'when' with three explicit 'Use when' clauses covering adding observability, shipping features to production, and debugging production issues.	3 / 3
Trigger Term Quality	Includes strong natural trigger terms users would actually say: 'logging', 'metrics', 'tracing', 'alerting', 'production issues', 'diagnosable', 'production behavior'. These cover the main variations a user would use when requesting observability/instrumentation work.	3 / 3
Distinctiveness Conflict Risk	The focus on observability/instrumentation is a clear niche with distinct triggers like 'logging', 'metrics', 'tracing', 'alerting', and 'production issues'. This is unlikely to conflict with general coding skills or debugging skills due to the specific production observability framing.	3 / 3
	Total	11 / 12 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: finlay611/agent-skills
Path: skills/observability-and-instrumentation/SKILL.md
Commit: 05472ac

Reviewed: 4 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.