CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

spek-design

Author, bring in, revise or reference a design document.

Quality

71%

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

Fix and improve this skill with Tessl

tessl review fix ./skills/spek-design/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

73%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 an operationally precise playbook: four clearly discriminated intents, each with concrete commands, hard propose-then-confirm checkpoints, and explicit decline/cleanup handling. Its weaknesses are trimmable verbosity (pattern citation, repeated lifecycle-record explanation) and a couple of commands referenced by name only.

Suggestions

Compress the interview-pattern section to its rule (adaptive questions toward a stated goal, stop when answers stop changing the document) and drop the citation and pattern exposition, saving the load-bearing stopping condition.

State the two-classes distinction once and have the revise branch reference it in one line instead of re-explaining byte-for-byte storage and lifecycle records.

Show the full `spektacular design ref remove` invocation (its --data shape) as is done for ref add and ref list.

DimensionReasoningScore

Conciseness

The body is instruction-dense with no explaining of concepts Claude already knows, but it could be tightened: the Flipped Interaction citation and pattern exposition ("rather than asking the user to author the document from a blank prompt, you drive the conversation...") spends lines justifying a style one sentence could command, and the two-classes distinction (lifecycle record vs. stored-as-supplied) is explained at the top and re-explained in the revise branch. This fits 'mostly efficient but includes some unnecessary explanation or could be tightened'; it is not a 2 because the padding is stylistic rather than tutorial-level.

3 / 5

Actionability

Nearly every branch gives copy-paste-ready commands with explicit JSON payloads and flags (e.g. `spektacular design author --data '{"source":"<name>","path":"<path>"}' --from .spektacular/tmp/<slug>.md`, including `--document-status <draft|final|superseded|archived>`). The minor gap keeping it from 5: `spektacular design ref remove` is named with no invocation shown, so it is not fully copy-paste ready across all cases.

4 / 5

Workflow Clarity

Each of the four branches is a numbered, explicitly sequenced procedure with a hard validation checkpoint ("Present the draft to the user as ordinary readable text, in full, and get their explicit agreement before writing anything"), and the Decline handling section supplies a genuine error-recovery feedback loop (loop back and refine, or stop and remove the staged scratch file at `.spektacular/tmp/<slug>.md`), plus trace `--status error` on helper failure. This matches 'clear sequence with explicit validation steps; feedback loops for error recovery'.

5 / 5

Progressive Disclosure

The body is organized into well-labeled sections (version check, tracing, what/when, four intent branches, decline handling) with one topic per section, and it is a single-level skill with no nested references — no bundle files exist and none are referenced. It is not a 5 because at ~165 lines some self-contained material (the interview pattern exposition, the full command/flag reference) would sit better in a reference file, matching 'good structure; most content is appropriately placed; minor organization gaps'.

4 / 5

Total

16

/

20

Passed

Description

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

The description is concise and lists four concrete, correctly voiced actions, but it omits any 'Use when...' trigger guidance and lacks the natural synonyms (design doc, spec) users would actually say. Without trigger clauses it reads as capability-only, weakening both completeness and distinctiveness.

Suggestions

Append an explicit trigger clause, e.g. "Use when the user mentions a design document, design doc, or wants conversation turned into, stored as, or linked to a design."

Include natural user phrasings and synonyms — "design doc", "write this up as a design", "store our existing design" — so trigger matching works on what users actually say.

Briefly disambiguate the domain (e.g., designs feeding into specs) to reduce overlap with generic documentation or API-design skills.

DimensionReasoningScore

Specificity

"Author, bring in, revise or reference a design document" lists four concrete verbs tied to a named domain, matching the 'lists several specific actions; minor gaps in coverage' anchor. It falls short of the 5 anchor because the actions get no elaboration (what 'bring in' or 'reference' concretely involve is unstated) and coverage of the lifecycle is verb-level only.

4 / 5

Completeness

The 'what' is clear (four operations on design documents), but there is no 'Use when...' clause or equivalent explicit trigger guidance — the 'when' is entirely absent, capping this dimension at 3 per the judging guidelines. It is not a 2 because the 'what' is concrete and multi-part.

3 / 5

Trigger Term Quality

Relevant keywords exist ("design document", "author", "revise", "reference") but common variations users would naturally say — "design doc", "spec", "store a design", "update the design" — are missing. This matches 'some relevant keywords but missing common variations or synonyms' rather than the 4 anchor's good coverage.

3 / 5

Distinctiveness Conflict Risk

"A design document" carves out a recognizable niche, but the phrase alone (no mention of specs or the Spektacular toolchain) could overlap with general documentation, API-design, or architecture-diagram skills. This fits 'somewhat specific but could still overlap with similar skills' rather than the 4 anchor, which requires mostly distinct triggers.

3 / 5

Total

13

/

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

nicholasjackson/tcgreplay

Path

skills/spek-design/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.