CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

trace-spec-author

Use before instrumenting a new feature, when spans have grown with no agreed shape, or after an incident where debugging stalled on missing attributes. Writes a trace spec per feature (root and child spans, key attributes per OpenTelemetry conventions) that drives code review and trace tests.

Quality

82%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

The canonical home for this skill is testland/trace-spec-author

SKILL.md
Quality
Evals
Security

Quality

Content

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

The body is a well-structured, highly actionable authoring guide whose tables, template, and anti-patterns give Claude concrete direction. Its main weaknesses are redundancy (status semantics restated three times, including a verbatim doc quote of knowledge Claude already has) and the lack of an explicit validate-and-reconcile feedback loop connecting the spec to the generated tests.

Suggestions

Collapse the status-semantics coverage to one place: keep the Step 3 decision table and drop the verbatim OpenTelemetry quote and the template's duplicate 'Status mapping' table (reference Step 3 from the template instead).

Add an explicit feedback loop to Step 5, e.g. 'Run the generated trace tests against a staging build; any failing assertion means the spec, the tests, or the instrumentation has drifted — reconcile before merging.'

Make the test example self-contained or explicitly flag its dependencies, noting that 'use_tracer()' and 'memory_exporter' come from the 'opentelemetry-trace-assertions' sister skill, and define or import 'item'/'items' locally.

DimensionReasoningScore

Conciseness

Mostly efficient prescriptive content (tables, checklists, decision rules), but status semantics are repeated three times — the template's 'Status mapping' table, Step 3's table, and a verbatim quote of the OTel docs ('Status remains unset for 1xx, 2xx, and 3xx responses…') that restates conventions Claude already knows. It is not 4 because the duplication is noticeable rather than minor; not 2 because the bulk of the body is dense, non-padded instruction.

3 / 5

Actionability

The body provides a complete markdown spec template, SemConv decision rules, a cardinality risk/mitigation table, exact file paths, and a concrete pytest-style example. Not 5 because the test example depends on undefined fixtures ('use_tracer()', 'memory_exporter', 'item'), so it is not copy-paste ready; not 3 because the guidance is concrete and near-executable with only minor gaps.

4 / 5

Workflow Clarity

Steps 1–7 are clearly sequenced, with a 'Required test assertions' checklist and change-management gates (PR review, transition rules, 'Last reviewed' dates) serving as checkpoints. Not 5 because there is no explicit feedback loop such as 'run the trace tests and reconcile spec drift' — the triangle statement only gestures at it ('any drift between any two surfaces'); not 3 because the sequence is complete and checkpoints are mostly explicit.

4 / 5

Progressive Disclosure

Sections are well-organized with a clearly-signaled, one-level-deep References list of external links, and there are no nested or buried references. Not 5 because the ~80-line spec template is inlined in a ~220-line single-file skill where a template reference file would keep SKILL.md closer to an overview; not 3 because structure and navigation are genuinely good.

4 / 5

Total

15

/

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: it explicitly answers both what the skill does and when to use it, with concrete, naturally-phrased trigger conditions drawn from real observability workflows. Trigger-term coverage and capability enumeration are good but not exhaustive, capping specificity and trigger quality at 4.

DimensionReasoningScore

Specificity

The description lists several concrete actions — 'Writes a trace spec per feature (root and child spans, key attributes per OpenTelemetry conventions) that drives code review and trace tests' — which goes well beyond naming the domain. It stays at 4 rather than 5 because capabilities the body emphasizes (cardinality rules, status semantics, spec catalog/change management) are not mentioned, leaving minor gaps in coverage.

4 / 5

Completeness

Both halves are explicit: 'Use before instrumenting a new feature, when spans have grown with no agreed shape, or after an incident where debugging stalled on missing attributes' gives concrete 'when' triggers, and 'Writes a trace spec per feature… that drives code review and trace tests' gives a clear 'what'. This matches the 5 anchor (explicit what AND when with concrete trigger phrases), not 4 where the 'when' would be weaker or less specific.

5 / 5

Trigger Term Quality

Natural phrases a user would say are present — 'before instrumenting a new feature', 'spans have grown with no agreed shape', 'after an incident where debugging stalled on missing attributes' — plus domain keywords like OpenTelemetry. It is not 5 because common synonyms such as 'tracing', 'telemetry', or 'observability spec' are missing; it is clearly above 3 since the phrasing matches how practitioners actually describe the need.

4 / 5

Distinctiveness Conflict Risk

Terms like 'trace spec', 'spans', and 'OpenTelemetry conventions' carve out a clear niche (authoring trace specifications) with distinct triggers and minimal overlap risk against generic instrumentation or testing skills. Not 4: the trigger conditions are specific enough that confusion with a related skill is unlikely.

5 / 5

Total

18

/

20

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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

testland/qa

Path

plugins/qa-distributed-tracing/skills/trace-spec-author/SKILL.md

Reviewed

Table of Contents

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.