otel-semantic-conventions

OpenTelemetry semantic convention lookup and naming guidance. Use when selecting released semantic convention groups, attributes, or span naming rules, or when checking semantic convention compliance.

Quality

90%

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

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

An exemplary lean skill body: fully executable commands, a well-sequenced workflow with fallback rules, and clean one-level-deep progressive disclosure into verified bundle files. The only minor gap is the absence of an explicit checkpoint for handling a failed or empty lookup result.

Suggestions

Add a brief instruction for what to do when a query returns no match (e.g., fall back to listing groups with --groups or consult references/semconv-selection.md) to give the workflow a complete feedback loop.

Clarify when the parser-change test step applies (e.g., mark it as 'only if you edited the script') so readers of the main lookup workflow can skip it.

Dimension	Reasoning	Score
Conciseness	The body is entirely lean, imperative directives ('do not load the full semantic convention spec into context', 'use required and recommended attributes before optional ones') with zero concept explanations or padding — every token earns its place, matching the anchor-5 example. The duplicated 'do not load the full spec' idea appears only once in the body, so anchor 4 does not apply.	5 / 5
Actionability	The workflow provides copy-paste-ready, verified commands covering the common cases: './scripts/query-otel-semantic-conventions.sh --groups', group lookup ('http'), kind lookup ('http spans'), exact-entry lookup ('http http.request.method'), env-var setup ('OTEL_SEMCONV_REPO=/path/to/semantic-conventions'), and a runnable regression test command. All referenced files exist in the bundle.	5 / 5
Workflow Clarity	A clear, well-sequenced 5-step workflow (start from released specs → choose group → query → apply rules → return with source context) with fallback rules ('if no released key exists, use a stable custom namespace'). It sits at anchor 4 rather than 5 because there is no explicit validation checkpoint for a failed or empty query result (e.g., what to do if the group or attribute is not found). The destructive/batch validation cap does not apply since these are read-only lookups.	4 / 5
Progressive Disclosure	The body is a lean overview with details correctly split into two real, one-level-deep reference files ('see references/semconv-selection.md', 'see references/otel-semantic-conventions.md') plus bundled scripts, all verified to exist and clearly signaled — matching the anchor-5 clear-overview pattern with no nesting.	5 / 5
	Total	19 / 20 Passed

Description

87%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 description that clearly and concisely states both what the skill does and when to use it, with concrete trigger conditions and a distinct domain niche. The only weakness is modest synonym coverage (e.g., 'otel', 'instrumentation') for trigger terms.

Suggestions

Add common trigger synonyms or abbreviations such as 'otel' or 'instrumentation attributes' to broaden natural keyword coverage.

Enumerate one or two more concrete actions (e.g., 'resolve the correct span name' or 'validate attribute usage') in place of the slightly abstract phrase 'naming guidance'.

Dimension	Reasoning	Score
Specificity	The description lists several specific capabilities — 'semantic convention lookup and naming guidance', 'selecting released semantic convention groups, attributes, or span naming rules', and 'checking semantic convention compliance' — matching the anchor for several specific actions with minor gaps. It falls short of anchor 5 only because 'lookup and naming guidance' is slightly more abstract than a fully enumerated action list.	4 / 5
Completeness	It explicitly answers both 'what' ('OpenTelemetry semantic convention lookup and naming guidance') and 'when' ('Use when selecting released semantic convention groups, attributes, or span naming rules, or when checking semantic convention compliance') with two concrete trigger conditions, matching the anchor-5 structure. The 'when' clause is fully explicit, so anchor 4's caveat about a less-explicit 'when' does not apply.	5 / 5
Trigger Term Quality	Natural terms a user would say are present: 'semantic convention', 'attributes', 'span naming', 'compliance', 'OpenTelemetry'. Good keyword coverage but missing common variations such as 'otel' or 'instrumentation', so it fits anchor 4 rather than the comprehensive synonym coverage of anchor 5.	4 / 5
Distinctiveness Conflict Risk	It occupies a clear niche — OpenTelemetry semantic conventions — with distinct domain-specific triggers (semconv groups, attributes, span naming rules, compliance), giving minimal overlap risk with other skills.	5 / 5
	Total	18 / 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-semantic-conventions/SKILL.md
Commit: ea1a940

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