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).
67
80%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./honeycomb/skills/otel-migration/SKILL.mdQuality
Discovery
89%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 description excels at trigger term coverage and distinctiveness, with an impressive list of natural user phrases and explicit negative boundaries that prevent conflicts with related skills. Its main weakness is that the core capability statement is somewhat thin—it says it's a 'guide for retrofitting' but doesn't enumerate the specific actions or outputs the skill provides (e.g., generating migration plans, adding instrumentation code, configuring bridges). The trigger phrases implicitly convey capabilities but the description would benefit from a more explicit capability listing.
Suggestions
Replace the vague 'Guide for retrofitting OpenTelemetry' opener with specific concrete actions, e.g., 'Generates OTel migration plans, adds tracing instrumentation, configures logging and metrics bridges (Prometheus, slog, logback), and diagnoses context propagation issues like orphaned spans.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description names the domain (retrofitting OpenTelemetry) and mentions some actions like 'thread context through my code', 'bridge Prometheus metrics', 'logging bridge', but these are embedded in trigger phrases rather than stated as concrete capabilities the skill performs. The actual 'what it does' is vague: 'Guide for retrofitting OpenTelemetry into an existing, uninstrumented application.' | 2 / 3 |
Completeness | Clearly answers both 'what' (guide for retrofitting OpenTelemetry into existing uninstrumented applications) and 'when' (extensive trigger phrases plus explicit negative boundaries distinguishing from greenfield and Beeline-specific migration). The explicit 'NOT for' clause adds further clarity on when to use it. | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural trigger terms users would say, including variations like 'migrate existing app to OTel', 'add OpenTelemetry to existing project', 'traces are disconnected', 'orphaned spans', 'context propagation', 'slog bridge', 'logback bridge', and multiple framework-specific terms. These are realistic phrases users would naturally use. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive with explicit boundary-setting: 'NOT greenfield instrumentation (use otel-instrumentation) or Beeline-specific migration (use beeline-migration)'. This directly addresses potential conflicts with related skills and makes the niche very clear. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
70%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-structured migration guide with excellent workflow clarity and progressive disclosure. The six-phase approach with clear sequencing and verification checkpoints is strong. The main weakness is the lack of any inline executable code examples — all concrete implementation is deferred to reference files, which reduces immediate actionability. Some minor verbosity could be trimmed.
Suggestions
Add at least one concrete, executable code example inline (e.g., SDK initialization or middleware setup for one language) to improve actionability without requiring reference file lookups.
Trim the 'When to Use This Skill' section — the distinction from other skills can be a single line rather than a bulleted list, since this information is largely in the frontmatter description.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is mostly efficient and well-organized, but includes some unnecessary framing (e.g., 'When to Use This Skill' section repeats what should be in frontmatter, and some guidance like 'This is the hardest phase' is somewhat padded). The framework table is valuable but some rows with 'N/A' for common mistakes add marginal value. Overall reasonably lean but could be tightened. | 2 / 3 |
Actionability | The skill provides structured guidance with specific framework gotchas (e.g., Fiber c.Context() vs c.UserContext()) and a useful comparison table, but lacks any executable code examples directly in the body. All concrete code and commands are deferred to reference files. The phases describe what to do conceptually but don't show how with copy-paste ready snippets. | 2 / 3 |
Workflow Clarity | The six-phase migration is clearly sequenced, each phase is described as independently deployable and verifiable, and there's an explicit verification section after each phase. The ordering rationale is clear (SDK init first, context propagation as the bulk of work), and the real-world calibration section provides concrete effort expectations. The verification checklist reference provides the feedback loop. | 3 / 3 |
Progressive Disclosure | The skill body serves as a clear overview with well-signaled, one-level-deep references to specific files (framework-middleware.md, context-propagation-patterns.md, bridge-libraries.md, verification-checklist.md, etc.). Cross-references to sibling skills (otel-instrumentation, beeline-migration) are clearly delineated. Navigation is straightforward and content is appropriately split between overview and detail. | 3 / 3 |
Total | 10 / 12 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 — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
7f27e27
Table of Contents
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.