CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

otel-instrumentation

Instrument applications with the OpenTelemetry SDK and prove the telemetry is good by validating it against a local Kopai backend. Use when setting up observability, adding tracing/logging/metrics, deciding what to instrument or which attributes to add, retrofitting OTel into an existing codebase, threading context through call chains, configuring sampling, or when traces/logs/metrics aren't appearing after setup. Also use when users say things like "my traces aren't showing up", "I don't see any data", or "how do I add observability to my app". Do NOT use to investigate existing telemetry for a root cause (use root-cause-analysis), to build dashboards (use create-dashboard), or to instrument LLM and agent calls (use otel-genai-instrumentation).

Quality

97%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

SKILL.md
Quality
Evals
Security

Quality

Content

92%Weight 40%Scale 1-5

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

A well-engineered skill body: an explicit validate-and-loop workflow with per-step done-when criteria, copy-paste commands, and clean one-level-deep progressive disclosure across a 35-file bundle. The only weakness is modest: the Naming and package-picking sections carry a few lines of standard OTel knowledge and setup detail that could be trimmed or pushed into references.

Suggestions

Trim the Naming section to only the house rules Claude wouldn't infer (low-cardinality span names, IDs-as-attributes, custom namespaces) and drop the restatement of standard OTel semantic conventions.

Move the package-manager detection and deprecation-checking details (lockfile mapping, npm view vs pnpm/yarn behavior, Yarn 4 commands) into setup-environment.md, leaving a one-line pointer in SKILL.md.

Link references/_sections.md from the body (or note it as the file inventory) so every bundle file is navigable from the skill root.

DimensionReasoningScore

Conciseness

The body is dense and largely assumes competence ("Emit wide events, then prove they are good"), but the Naming section restates standard knowledge Claude already has ("Follow OTel semantic conventions… http.route, db.system, rpc.service", "Attribute names are dot-namespaced") and the package-manager/deprecation section (~25 lines including Yarn-4-specific commands) is setup detail that belongs in setup-environment.md or a lang- rule. Not 5: these are minor but real instances of over-explanation and misplaced detail; not 3: the vast majority of the body is non-obvious, project-specific judgment with no padding.

4 / 5

Actionability

Everything is executable: a copy-paste health check ("curl -s -o /dev/null -w '%{http_code}' -X POST http://localhost:4318/v1/traces…"), a complete Node.js span pattern with error status and finally-end, a concrete registry check ("npm view @opentelemetry/instrumentation-<lib> deprecated"), and an operational decision rule ("Both yes → create a span. Otherwise → put an attribute on the span you already have"). Not 4: commands and code are complete and cover the common cases with no gaps.

5 / 5

Workflow Clarity

The 6-step workflow table pairs every step with an explicit "Done when" validation criterion (e.g., step 1's 2xx curl check, step 5's "Every assertion passes. The loop is green"), and steps 4–6 are declared a loop with recovery routing ("Return to step 4 and re-drive. Never stop on a red assertion"). Not 4: validation checkpoints are explicit per step and the error-recovery feedback loop is stated, plus a branch table for entry points.

5 / 5

Progressive Disclosure

The body is a genuine overview: a branch table routes to task-scoped rule files grouped by category (Setup, Language SDKs, What to instrument, Prove it, Fix it), deep dives are separated under "load only when the task needs them", and all 34 referenced files exist in references/ with links only one level deep (reference files cross-link peers, not nested chains). Not 4: navigation is well-signaled and the split is appropriate throughout; the only blemish is an unlinked references/_sections.md inventory file, which is too minor to drop a full anchor level.

5 / 5

Total

19

/

20

Passed

Description

100%Weight 40%Scale 1-5

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

An exemplary description: concrete capabilities, explicit use-when triggers with verbatim user phrasings, and explicit de-scoping against three named sibling skills. Dense without padding — every clause is either a capability, a trigger, or a boundary.

DimensionReasoningScore

Specificity

The description lists multiple concrete actions — "Instrument applications with the OpenTelemetry SDK", "prove the telemetry is good by validating it against a local Kopai backend", plus retrofitting OTel, "threading context through call chains", and "configuring sampling" — giving comprehensive coverage of the skill's capabilities. Not 4: coverage spans setup, instrumentation judgment, validation, and troubleshooting with no meaningful gaps.

5 / 5

Completeness

It explicitly answers both questions: what ("Instrument applications with the OpenTelemetry SDK and prove the telemetry is good by validating it against a local Kopai backend") and when ("Use when setting up observability, adding tracing/logging/metrics…" with concrete trigger phrases). Not 4: the 'when' is fully explicit with multiple concrete triggers rather than merely serviceable.

5 / 5

Trigger Term Quality

It includes literal user phrasings — "my traces aren't showing up", "I don't see any data", "how do I add observability to my app" — alongside natural synonyms (observability, tracing/logging/metrics, sampling, retrofitting OTel). Not 4: it goes beyond good keyword coverage by quoting the exact sentences users say.

5 / 5

Distinctiveness Conflict Risk

It carves a clear niche (OTel instrumentation validated against a local Kopai backend) and adds explicit negative boundaries — "Do NOT use to investigate existing telemetry for a root cause (use root-cause-analysis), to build dashboards (use create-dashboard), or to instrument LLM and agent calls (use otel-genai-instrumentation)" — minimizing conflict risk. Not 4: it doesn't just reduce overlap, it names and routes to the competing skills.

5 / 5

Total

20

/

20

Passed

Validation

100%

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

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

kopai-app/kopai-mono

Path

skills/otel-instrumentation/SKILL.md

Reviewed

Table of Contents

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.