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

81%

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

62%Weight 40%Scale 1-3

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

The body is well-structured with a strong, validated workflow and clearly signaled reference files, but it loses points for a time-sensitive status block outside a deprecation section, executable patterns deferred entirely to references, and an unreferenced bundled script. The migration workflow itself is exemplary.

Suggestions

Move the 'Status as of 2026-07-29' current-status detail (and the .NET Activity.RecordException/AddException note) into a dedicated 'Current status / deprecated' section so the time-sensitive information is isolated from evergreen guidance.

Reference scripts/scan-span-events.sh in step 1 (e.g. 'run scripts/scan-span-events.sh to find call sites') so the bundled tool is discoverable and the scan step is directly executable.

Inline at least one short before/after code example in step 3 (in addition to references/migration-patterns.md) so the core migration action is actionable without opening a reference file.

Dimension	Reasoning	Score
Conciseness	The body is mostly lean and task-specific, but the 'Status as of 2026-07-29' block and the .NET Activity.RecordException/AddException aside are time-sensitive details placed in Background rather than an 'old patterns' or 'deprecated' section, which the rubric penalizes.	2 / 3
Actionability	Gives specific scan targets and semconv attributes with concrete caveats (e.g. Go runtime.Stack), but defers all executable code to referenced files and never surfaces the bundled scripts/scan-span-events.sh, leaving the body's standalone actionability incomplete.	2 / 3
Workflow Clarity	Steps 0-5 are clearly sequenced with an explicit Required Completion Loop that re-reads files and re-checks checklist items, plus a status-coded Migration Checklist and Final Review Format providing strong feedback loops for a batch migration.	3 / 3
Progressive Disclosure	The four references/*.md files are well-signaled, one-level-deep, and verified to exist, but the bundled scripts/scan-span-events.sh has no navigation pointer anywhere in the body, so discovery across the full bundle is incomplete.	2 / 3
	Total	9 / 12 Passed

Description

100%Weight 40%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.

The description is specific, complete, and distinctive: it states concrete actions, names the relevant API methods, includes an explicit 'Use when' trigger clause, and occupies a clearly bounded niche. All four dimensions score at the top of the scale.

Dimension	Reasoning	Score
Specificity	Names concrete actions (migrate, review code, plan migration) plus the specific API surface (AddEvent, RecordException), the Logs API target, and the OTEP 4430 plan.	3 / 3
Completeness	Explicitly states what the skill does (migrate span events to the Logs API per OTEP 4430) and when to use it via an explicit 'Use when...' clause with three triggers.	3 / 3
Trigger Term Quality	'migrating instrumentation from span events to log-based events', 'reviewing code that still uses AddEvent or RecordException', and 'planning a codebase migration' are natural terms users would say, with good variation coverage.	3 / 3
Distinctiveness Conflict Risk	Targets a narrow, unmistakable OpenTelemetry span-event-to-logs niche with distinctive triggers, making conflict with other skills unlikely.	3 / 3
	Total	12 / 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 — 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: c5d2edc

Reviewed: about 2 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.