CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

write-a-spec

Extend a core journey in evals/core or write a one-off proof in evals/proofs that proves a PR's change to a human reviewer. Use when a PR changes user-visible behaviour, when a reviewer asks "show me", or when the coverage decision says a journey is missing.

Quality

90%

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

SKILL.md
Quality
Evals
Security

Quality

Content

88%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 exceptionally actionable, well-sequenced instruction skill: concrete code, exact commands, explicit validation loops, and clear decision tables for when not to write a spec. Its only costs are repetition across sections and a monolithic single-file structure that inlines some reference material.

DimensionReasoningScore

Conciseness

Dense and competent — it assumes Claude knows testing concepts and adds only repo-specific rules — but at ~250 lines some principles repeat (the caption-tells-the-story rule and 'read your own record' each appear twice) and a few parenthetical digressions could be trimmed. Not 5 due to this repetition; well above level 3 since nothing explains concepts Claude already knows.

4 / 5

Actionability

Fully executable guidance: a complete spec example with recordAssertionEvidence calls, a world-binding snippet, exact commands ('pnpm evals:e2e <slug> --local', 'gh workflow run pr-proof.yml --ref <branch> -f pr=<number>'), and tables mapping reviewer-visible strings to their code origins. Only the first title/steps example uses '…' placeholders.

5 / 5

Workflow Clarity

Clear sequence (pick lane → check do-not-write conditions → shape the proof → run locally and read your own record → design review → run on the PR) with explicit validation checkpoints and feedback loops: 'If the screenshots would not convince you, they will not convince the reviewer', fix-or-justify for design notes, and failed steps recorded and rethrown with later steps marked not-reached.

5 / 5

Progressive Disclosure

No bundle files exist; the single SKILL.md is well organized with headers, decision tables, and clearly signaled cross-references to sibling skills (run-tests, open-a-pr) and repo paths (evals/journeys.ts, evals/design-review/README.md). Not 5 because the ~250-line monolith inlines reference-style material (testkit channel API, desktop nativeReason list) that could live in a separate file.

4 / 5

Total

18

/

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 names two concrete, path-specific actions and gives an explicit 'Use when' clause with three concrete triggers including a quoted reviewer phrase. Weaknesses are minor — some internal jargon ('coverage decision', 'journey') and missing common synonyms like 'e2e test' or 'spec'.

DimensionReasoningScore

Specificity

Two concrete actions with exact paths ('Extend a core journey in evals/core', 'write a one-off proof in evals/proofs') and a stated deliverable ('proves a PR's change to a human reviewer'). More specific than the level-3 anchor's generic 1-2 actions, but minor coverage gaps (no mention of spec/test mechanics) keep it below comprehensive.

4 / 5

Completeness

Explicitly answers both what ('Extend a core journey... or write a one-off proof... that proves a PR's change') and when ('Use when a PR changes user-visible behaviour, when a reviewer asks "show me", or when the coverage decision says a journey is missing') with three concrete trigger phrases. Not 4 because the when-clause is fully explicit rather than vague or implicit.

5 / 5

Trigger Term Quality

Natural trigger phrases are present ('a PR changes user-visible behaviour', 'a reviewer asks "show me"'), but 'coverage decision' is internal jargon and common variations users would say ('e2e test', 'spec', 'evidence') are missing.

4 / 5

Distinctiveness Conflict Risk

Clear niche (PR proof specs in evals/core and evals/proofs) with distinct triggers tied to PR review; minimal conflict risk with other skills.

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

different-ai/openwork

Path

.opencode/skills/write-a-spec/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.