CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

write-a-spec

Scope a feature end to end and write an implementation spec under specs/ from an accepted proposal — current-system mapping, goals/non-goals, a Decision Log for one-way-door choices, a live Open Questions backlog, and a real migration + test plan. Read when asked to write a spec, scope this feature, turn this proposal into a spec, plan the implementation, or break this into tasks. Do NOT fire on frame a proposal or write the PRD (sibling frame-a-proposal — a PRD frames a change before it is accepted; this skill starts once one is), record a decision or write the ADR (record-a-decision), write a postmortem (write-a-postmortem), or review this design (review-a-design) — those are separate skills. Complements the platform open-knowledge skill; does not replace it.

Quality

92%

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

85%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 process skill: the workflow is rigorously sequenced with hard gates and validation loops, and the guidance is copy-paste actionable throughout. The two weaknesses are mild internal redundancy (the execution-order list and closing Non-goals restate step content) and the total absence of progressive disclosure — everything lives in one long file with no referenced detail documents or bundled templates.

Suggestions

Split step-detail content into referenced files to shorten SKILL.md into an overview-plus-workflow: e.g., move the Decision Log / Open Questions entry formats and the Step 9 plan.md/tasks.md guidance (needed only after greenlight) into references/templates.md, linked one level deep.

Drop the "Mandatory execution order" numbered list or compress it to the hard gates only — it duplicates the H2 step headers that immediately follow; alternatively merge the closing "## Non-goals" section into the steps that already state each rule.

Ship or reference the actual spec, spec-plan, and spec-tasks templates the skill invokes (or inline their skeletons) so the write({ template: ... }) calls are verifiable within the bundle.

DimensionReasoningScore

Conciseness

The body is dense with craft-specific guidance (one-way-door Decision Log format, temporal non-goals, migration states, verifiable tasks) and avoids explaining concepts Claude already knows. However, the "Mandatory execution order" list restates every step header that follows, and the closing "## Non-goals" section repeats rules already stated in Steps 1, 6, and 7 (don't skip mapping, don't write ADRs, don't silently resolve open questions) — trimmable redundancy that keeps it below the lean top anchor.

4 / 5

Actionability

Fully executable for an instruction-only skill: exact OpenKnowledge verb calls (exec("ls -A proposals/"), write({ document: { path: "specs/004-payment-retries/spec.md", template: "spec" } })), copy-paste markdown blocks for Decision Log and Open Questions entries, complete frontmatter YAML, and a recap template. Concrete examples cover the common cases at every step.

5 / 5

Workflow Clarity

A 12-step (0–11) explicitly sequenced process with HARD GATEs (parent proposal, current-system map, scoping STOP gate), an autonomy-mode table governing gate behavior, and an explicit validation feedback loop in Step 10 ("audit(...) returns clean (every lint violation + broken internal link) — fix every finding") plus a final recap checklist. This matches the top anchor: clear sequence, explicit validation, error-recovery loops, and a checklist.

5 / 5

Progressive Disclosure

This is a ~290-line monolithic SKILL.md with no bundle: no references/, scripts/, or assets/ directories exist, and the spec/spec-plan/spec-tasks templates it invokes are not part of this bundle. Internal sectioning and navigation are good, but nothing is split out — e.g., Step 9's plan.md/tasks.md detail is only needed post-greenlight and the DL/OQ template blocks could live in references — so it sits at "some structure but could be better organized" rather than the well-split 4, while clearly above the minimal-structure 2.

3 / 5

Total

17

/

20

Passed

Description

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

An exemplary description: comprehensive and concrete on capabilities, explicit on both positive and negative triggers, and sharply disambiguated from sibling skills in the same pack. The only nit is grammatical awkwardness in "Do NOT fire on frame a proposal" (missing "this"), which does not affect scoring.

DimensionReasoningScore

Specificity

The description lists multiple concrete actions covering the entire spec-writing workflow: "write an implementation spec under specs/ from an accepted proposal — current-system mapping, goals/non-goals, a Decision Log for one-way-door choices, a live Open Questions backlog, and a real migration + test plan". This matches the anchor for comprehensive coverage of specific concrete actions; a 4 would require a minor coverage gap, and none is present.

5 / 5

Completeness

Both what and when are answered explicitly and concretely: the what is the full enumeration of spec artifacts, and the when is the explicit "Read when asked to..." clause with five concrete trigger phrases plus negative triggers. It clearly matches the top anchor; a 4 would require the when to be only implicit or less specific.

5 / 5

Trigger Term Quality

"Read when asked to write a spec, scope this feature, turn this proposal into a spec, plan the implementation, or break this into tasks" provides natural trigger phrasings with synonym-level variation users would actually say. This is comprehensive keyword coverage per the top anchor, not merely good coverage with a few missing terms.

5 / 5

Distinctiveness Conflict Risk

It carves a clear niche (spec from an accepted proposal) and explicitly de-conflicts four siblings: "Do NOT fire on frame a proposal or write the PRD... record a decision or write the ADR (record-a-decision), write a postmortem (write-a-postmortem), or review this design (review-a-design)". Minimal conflict risk; the neighboring 4 anchor would imply only minor overlap risk with no explicit boundary.

5 / 5

Total

20

/

20

Passed

Validation

87%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 14 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

metadata_version

'metadata.version' is missing

Warning

relative_links

Relative link issues: 1 missing

Warning

Total

14

/

16

Passed

Repository

inkeep/open-knowledge

Path

packages/server/assets/skills/packs/software-lifecycle/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.