otel-migration

Guide for retrofitting OpenTelemetry into an existing, uninstrumented application. Trigger phrases: "migrate existing app to OTel", "add OpenTelemetry to existing project", "retrofit OTel into my codebase", "thread context through my code", "context propagation", "bridge Prometheus metrics to OTel", "logging bridge", "migrate logging to OTel", "slog bridge", "logback bridge", "verify my instrumentation", "traces are disconnected", "orphaned spans", "migrate to OpenTelemetry", "OTel migration plan", "how do I sequence an OTel migration", "add tracing to existing code", "refactor for context propagation", "Fiber context gotcha", "keep existing logging working with OTel", "add OTel without breaking Prometheus", "bridge existing metrics", "coexist with existing monitoring", or any request about retrofitting OpenTelemetry into an existing application. This skill is for migrating existing codebases, NOT greenfield instrumentation (use otel-instrumentation) or Beeline-specific migration (use beeline-migration).

1.03x

Quality

89%

Does it follow best practices?

Impact

97%

1.03x

Average score across 3 eval scenarios

Securityby

Passed

No findings from the security scan

Quality

Content

85%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-architected migration guide: clear phased workflow with verification, strong progressive disclosure into real reference files, and concrete actionable directives. The main improvement area is conciseness, where the inline framework table and per-language list overlap with their reference files.

Suggestions

Trim the inline framework context table to the 2-3 highest-risk rows (e.g., Fiber, Gin, Spring thread pools) and defer the full matrix to framework-middleware.md to reduce duplication with the reference.

Move the per-language propagation-difficulty bullets into context-propagation-patterns.md, keeping only a one-line pointer in Phase 3, since the reference already covers language-specific patterns.

Drop editorial filler ('This is the highest-ROI step.') and the body's restatement of the description's first sentence to tighten the opening.

Dimension	Reasoning	Score
Conciseness	Mostly lean and migration-specific with little concept padding, but the inline framework context table and per-language difficulty list duplicate content that also lives in their respective reference files, leaving minor trim opportunities.	4 / 5
Actionability	Gives concrete, specific directives — exact framework API calls (c.UserContext() vs c.Context()), shutdown ordering, 10-30s timeout, multi-handler fan-out — and delegates full code to references; per the instruction-only scoring note, absence of code blocks is not penalized when guidance is this actionable.	4 / 5
Workflow Clarity	Six phases in explicit order, each 'independently deployable and verifiable', plus a dedicated Verification section, a checklist reference, and a bundled local-collector debug script providing explicit validation steps and feedback loops.	5 / 5
Progressive Disclosure	Clear overview body pointing to five well-signaled one-level-deep references (framework-middleware, context-propagation-patterns, bridge-libraries, verification-checklist, migration-pitfalls), all confirmed present and organized by phase; cross-skill references are clearly signaled with full plugin-root paths.	5 / 5
	Total	18 / 20 Passed

Description

95%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.

A strong, well-structured description that clearly states purpose, packs in natural trigger phrases, and explicitly separates itself from adjacent skills. The only minor weakness is that concrete capabilities are embedded in trigger phrasing rather than a clean action list.

Dimension	Reasoning	Score
Specificity	Names the domain and enumerates concrete capabilities (context propagation, Prometheus metrics bridge, logging bridge, verification) via trigger phrases, but the actions are scattered through triggers rather than a crisp capability list, so it sits just below the comprehensive-anchor 5.	4 / 5
Completeness	Explicitly answers both 'what' ('Guide for retrofitting OpenTelemetry into an existing, uninstrumented application') and 'when' (a long trigger-phrase list plus a catch-all 'any request about retrofitting...').	5 / 5
Trigger Term Quality	Comprehensive natural triggers including synonyms (OTel/OpenTelemetry), symptom phrases ('orphaned spans', 'traces are disconnected'), and framework-specific gotchas ('Fiber context gotcha') that users would realistically say.	5 / 5
Distinctiveness Conflict Risk	Carves a clear niche (retrofitting existing apps) and explicitly disambiguates from siblings: 'NOT greenfield instrumentation (use otel-instrumentation) or Beeline-specific migration (use beeline-migration)'.	5 / 5
	Total	19 / 20 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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: honeycombio/agent-skill
Path: honeycomb/skills/otel-migration/SKILL.md
Commit: 41214b7

Reviewed: 5 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.