CtrlK
BlogDocsLog inGet started
Tessl Logo
PluginPublic

testland/trace-spec-author

Build a trace specification document per feature - defines the trace shape (root span + child spans + key attributes per OpenTelemetry semantic conventions) that production code MUST emit. The spec drives both implementation reviews AND trace-assertion tests, so a single declarative document is the source of truth for what observability "looks like" for a feature. Use before instrumenting a new feature, when existing spans have grown organically with no agreed shape, or after an incident where a debugging session stalled on missing span attributes.

Quality

85%

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

Overview
Quality
Evals
Security
Files

Quality

Content

75%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 strong, concrete, well-sequenced process skill: the copy-paste spec template and the SemConv/cardinality/status decision rules give Claude exactly what to produce, and the anti-patterns table anticipates failure modes. It falls just short of top marks on the illustrative (not runnable) test snippet, a redundant quoted passage in Step 3, and the absence of an explicit validation feedback loop.

Suggestions

Trim the quoted OpenTelemetry passage in Step 3 — the preceding status-mapping table already states the rule; keep only the citation link.

Make the Step 5 test example executable (real TracerProvider/InMemoryExporter setup, defined variables) or explicitly label it as illustrative pseudocode.

Close the feedback loop after Step 5: add an explicit step such as 'run the trace assertions; on failure, fix the spec or implementation and re-run until green'.

DimensionReasoningScore

Conciseness

The body is dense and instructional throughout — a tabular spec template, SemConv decision rules, status-mapping and anti-cardinality tables — and assumes competence (no 'what is tracing' primer). Minor trimmable over-explanation remains: Step 3 re-quotes the full SemConv passage ('Status remains unset for 1xx, 2xx, and 3xx responses...') immediately after a table stating the same mapping, and the template's change-log/index rows add example filler.

4 / 5

Actionability

Step 1 provides a complete copy-paste spec template and Steps 2-7 give concrete decision rules ('Use SemConv attribute names - never invent parallels', 'Spec changes require a PR review by the spec owner'). The Step 5 Python snippet is illustrative rather than executable — `use_tracer()`, `memory_exporter`, and `create_order(items=[item])` reference a non-standard setup and an undefined `item` — so it falls short of the fully copy-paste-ready anchor.

4 / 5

Workflow Clarity

A clear seven-step sequence (template, SemConv mapping, status semantics, cardinality rules, test derivation, change management, catalog) with verification artifacts in the 'Required test assertions' checklist and the anti-patterns table. It misses an explicit validate-and-fix loop (e.g., run assertions, fix spec/implementation on failure, re-run), so checkpoints are present but partly implicit; the destructive/batch cap does not apply since this is document authoring.

4 / 5

Progressive Disclosure

No bundle files exist; the single-file skill is well organized with per-step sections, anti-patterns, limitations, and a References section whose external OpenTelemetry links are one level deep and clearly signaled. Not a 5 because the ~75-line inline spec template (and the Step 2 SemConv attribute listings) could be split into an assets/reference file to keep SKILL.md leaner.

4 / 5

Total

16

/

20

Passed

Description

88%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: third-person voice, concrete capabilities, and an explicit three-scenario trigger clause that clearly answers both what the skill does and when to use it. The only gap is modest synonym coverage ('distributed tracing', 'telemetry', tool names like Jaeger) and slight overlap signaling with its sister test-enforcement skills.

DimensionReasoningScore

Specificity

It names multiple concrete, specific actions with comprehensive coverage: 'Build a trace specification document per feature', 'defines the trace shape (root span + child spans + key attributes per OpenTelemetry semantic conventions)', and 'drives both implementation reviews AND trace-assertion tests'. This matches the anchor for multiple specific concrete actions with comprehensive coverage rather than the level below, which allows minor gaps.

5 / 5

Completeness

Both halves are explicit: the what ('Build a trace specification document per feature - defines the trace shape... that production code MUST emit') and a concrete when with three trigger scenarios ('Use before instrumenting a new feature, when existing spans have grown organically..., or after an incident...'). This clearly matches the anchor requiring both what and when with concrete trigger phrases, not merely an explicit-but-could-be-sharper 'when'.

5 / 5

Trigger Term Quality

Good natural trigger phrases for the domain: 'before instrumenting a new feature', 'when existing spans have grown organically with no agreed shape', 'after an incident where a debugging session stalled on missing span attributes'. It misses a few natural synonyms users might say ('distributed tracing', 'telemetry', 'Jaeger'), landing on 'good keyword coverage; a few natural terms missing' rather than comprehensive.

4 / 5

Distinctiveness Conflict Risk

A clear niche (authoring per-feature trace specs per OpenTelemetry semantic conventions) with triggers unlikely to fire for unrelated skills, but the description explicitly names 'trace-assertion tests' as a consumer — the domain of closely related sister skills (opentelemetry-trace-assertions, jaeger-trace-tests) — creating minor overlap risk with that family. Mostly distinct with minor overlap against closely related skills, not a fully conflict-free 5.

4 / 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.

Reviewed

On this page