otel-span-events-to-logs-migration

Migrate OpenTelemetry Span Events (AddEvent, RecordException, and language equivalents) to the Logs API following the accepted OTEP 4430 migration plan. Use when migrating instrumentation from span events to log-based events, reviewing code that still uses AddEvent or RecordException, or planning a codebase migration while preserving trace correlation.

Quality

86%

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

Quality

Content

81%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-structured, actionable migration skill with strong workflow validation and clean reference splitting. The main improvements are isolating time-sensitive status text and surfacing the bundled scan script rather than inlining its patterns.

Suggestions

Move the 'Status as of 2026-09-09' date and spec version into a clearly labeled 'Current status / deprecated' section so the lean core stays evergreen.

Reference scripts/scan-span-events.sh in workflow step 1 instead of (or alongside) inlining the grep patterns, so the provided bundle is discoverable and maintained in one place.

Add at least one compact before/after code example inline in step 3 for the most common case, so users get copy-paste-ready guidance without always opening migration-patterns.md.

Dimension	Reasoning	Score
Conciseness	Mostly lean, assuming OpenTelemetry competence, but the Background/status paragraph carries time-sensitive specifics ('Status as of 2026-09-09', 'v1.60.0') that are not isolated in a deprecated/old-patterns section, a trim candidate per the time-sensitivity guideline.	4 / 5
Actionability	Concrete and executable -- explicit grep search terms, specific Go APIs ('log.Record.AddAttributes accepts attribute.KeyValue: use attribute.String(...)'), and required semconv attributes -- but before/after code is deferred to references and the bundled scan script is not surfaced, leaving minor gaps from fully copy-paste-ready.	4 / 5
Workflow Clarity	A clearly sequenced 0-5 migration workflow backed by a Required Completion Loop with explicit validation ('re-open the changed files and confirm each checklist item with codebase evidence', 'do not finish until every checklist item is completed') and a checklist with feedback loops, appropriate for this batch code-modification task.	5 / 5
Progressive Disclosure	Well-signaled one-level-deep references to four real files (deprecation-plan.md, decision-tree.md, migration-patterns.md, backward-compat.md) with content appropriately split, but the provided scripts/scan-span-events.sh bundle is not referenced from the body while equivalent grep patterns are inlined -- a minor organization gap.	4 / 5
	Total	17 / 20 Passed

Description

92%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, third-person description that clearly states the capability and gives explicit 'Use when' triggers tied to concrete migration scenarios. The only soft spot is trigger-term quality, which leans on API names and spec identifiers rather than the full range of natural user phrasings.

Dimension	Reasoning	Score
Specificity	Names multiple concrete actions -- 'Migrate OpenTelemetry Span Events (AddEvent, RecordException, and language equivalents) to the Logs API', 'reviewing code that still uses AddEvent or RecordException', 'planning a codebase migration while preserving trace correlation' -- with comprehensive coverage of the migration domain.	5 / 5
Completeness	Explicitly answers both what ('Migrate ... Span Events ... to the Logs API following the accepted OTEP 4430 migration plan') and when ('Use when migrating instrumentation ..., reviewing code ..., or planning a codebase migration ...') with concrete trigger phrases.	5 / 5
Trigger Term Quality	Good natural-phrase coverage ('migrating instrumentation from span events to log-based events', 'planning a codebase migration'), but the dominant terms (AddEvent, RecordException, OTEP 4430) skew technical and a few common user phrasings are absent.	4 / 5
Distinctiveness Conflict Risk	A clear niche (OpenTelemetry span-event-to-logs migration under OTEP 4430) with distinct, specialized triggers and minimal realistic overlap with other skills.	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: ollygarden/opentelemetry-agent-skills
Path: skills/otel-span-events-to-logs-migration/SKILL.md
Commit: 8e6ed41

Reviewed: 13 hours 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.