CtrlK
BlogDocsLog inGet started
Tessl Logo
PluginPublic

testland/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

83%

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 well-structured process skill: tabular specs, concrete attribute names, executable-looking tests, and an anti-patterns table give Claude exactly what to produce. Weaknesses are minor — duplicated status-mapping content, test fixtures that depend on sister skills, and a garbled feedback-loop sentence — and everything sits in one inline file where a bundle split could reduce context load.

Suggestions

Consolidate the status-semantics content: the mapping appears three times (Step 1 template, Step 3 table, and the verbatim SemConv quote). Keep the Step 3 table and drop the quoted passage and the inline template copy.

Make the Step 5 test example self-contained or explicitly flag its dependencies: note that use_tracer() and memory_exporter come from the opentelemetry-trace-assertions sister skill, or inline their setup so the example is copy-paste runnable.

Fix the garbled feedback-loop sentence ("any drift between any two surfaces") to an explicit instruction such as "run the trace tests after implementation; any failure indicates drift between spec, tests, or code — resolve before merging," and consider moving the ~80-line spec template into a references/ file to keep SKILL.md as an overview.

DimensionReasoningScore

Conciseness

The body is dense and tabular with no beginner-concept explainers, and the template and anti-patterns tables earn their tokens. Minor over-explanation could be trimmed: span status mapping appears in the Step 1 template, again as a table in Step 3, and then as a verbatim quoted passage from the HTTP SemConv ("Status remains unset for 1xx, 2xx, and 3xx responses..."). Anchor 4 (efficient, minor trims possible) fits; not 5 due to that redundancy, not 3 since padding is limited.

4 / 5

Actionability

Concrete throughout: exact attribute names and types ("order.id", "payment.amount_cents", ISO 4217), file paths (docs/observability/<feature>.md, INDEX.md), a copy-ready spec template, and a nearly executable pytest example. It falls short of anchor 5 because the test example depends on undefined fixtures ("use_tracer()", "memory_exporter", "create_order") from the sister skills, so it is not standalone copy-paste ready; it is well above anchor 3 since nothing is pseudocode or abstract.

4 / 5

Workflow Clarity

Seven clearly numbered steps each produce a concrete artifact, with a required-assertion checklist in Step 1 and PR-review enforcement in Step 6. It misses anchor 5 because the feedback-loop statement is garbled ("The spec ↔ test ↔ implementation triangle is the value: any drift between any two surfaces") and there is no explicit 'run tests, fix on drift' instruction; this is doc-writing rather than destructive/batch work, so the workflow-clarity cap at 3 does not apply.

4 / 5

Progressive Disclosure

Sections are well-organized, external OTel references are clearly labeled and one level deep, and there are no nested or buried references. There are no bundle files at all (no references/, scripts/, or assets/ directories), so all ~230 lines live inline in SKILL.md; the large spec template could plausibly be split into a bundle file. Anchor 4 (good structure, minor organization gaps) fits; not 5 because the skill exceeds 50 lines with content that could be offloaded, not 3 because nothing is buried or misplaced.

4 / 5

Total

16

/

20

Passed

Description

83%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, a clear articulation of the artifact produced and its downstream consumers, and three explicit, natural trigger scenarios. The main gaps are a few missing synonyms (tracing, observability, telemetry) and unmentioned capabilities (cardinality rules, status semantics) that keep specificity and trigger coverage just short of the top anchor.

DimensionReasoningScore

Specificity

"Writes a trace spec per feature (root and child spans, key attributes per OpenTelemetry conventions) that drives code review and trace tests" lists several concrete actions (write spec, define spans and attributes, drive review, drive tests), but coverage has minor gaps (cardinality rules, status semantics, change management are not mentioned). Anchor 4 fits better than 5 because of those gaps, and better than 3 because multiple specific actions are named, not just a domain.

4 / 5

Completeness

The description explicitly answers both questions: what ("Writes a trace spec per feature (root and child spans, key attributes per OpenTelemetry conventions) that drives code review and trace tests") and when ("Use before instrumenting a new feature, when spans have grown with no agreed shape, or after an incident where debugging stalled on missing attributes") with concrete trigger phrases. This matches the anchor-5 example structure exactly; anchor 4's weaker 'when could be more explicit' does not apply.

5 / 5

Trigger Term Quality

Triggers like "before instrumenting a new feature", "spans have grown with no agreed shape", and "after an incident where debugging stalled on missing attributes" use phrases an OTel user would naturally say, but common synonyms such as "tracing", "observability", or "telemetry" are missing. Anchor 4 (good coverage, a few natural terms missing) fits; not 5 due to the missing synonyms, not 3 since several natural phrases are present.

4 / 5

Distinctiveness Conflict Risk

Phrases like "trace spec", "spans have grown with no agreed shape", and "debugging stalled on missing attributes" carve a clear spec-authoring niche distinct from test-execution skills, but "instrumenting a new feature" is a trigger a generic instrumentation/observability skill could also claim. Mostly distinct with minor overlap risk — anchor 4, not 5 (minimal conflict risk not quite met), not 3 (the niche is far more specific than 'Works with document files').

4 / 5

Total

17

/

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