readable-doc-spike

Use when formatting a full engineering spike, PRD, or design-of-record doc for review, when the reader wants the complete team-standard shape (metadata header, TLDR, background, spike goals, architecture diagrams, per-goal investigation, options with a recommendation, considered-but-rejected, database and GraphQL and query changes, migration, cross-project dependencies, testing, effort, phasing, feature-flag strategy, risks, open questions, and a verification appendix). Clean team style, no emoji or tag overload. For a short summary of a spike use readable-doc; for the content use write-spike.

Quality

89%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

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.

A lean, highly actionable instruction skill: an explicit numbered workflow with validation and a feedback loop, a concrete section skeleton, and a mistakes/fix table, with no filler. The main improvement space is in splitting the shared formatting-gotchas matrix into a reference file and inlining less of the sibling-skill delegation.

Suggestions

Move the plannotator-safe formatting matrix (the 'Same matrix as readable-doc' section) into a shared references/ file (e.g., references/plannotator-formatting.md) and link to it from both skills, so the duplicated rules live one level deep instead of inline.

Add one concrete invocation example for the delegated tools (e.g., the exact render-diagram call or textstyle.py usage for a verdict word) so the 'render via render-diagram' and 'small-caps' steps are executable without assuming the sibling skill's interface.

Consider moving the long per-section rules of the Section skeleton (items 9-17) into a short reference file, keeping only the ordered section names plus the two or three most error-prone rules in SKILL.md.

Dimension	Reasoning	Score
Conciseness	The ~74-line body is dense and lean: every line carries team-specific rules (section skeleton, plannotator gotchas, style constraints) and nothing explains concepts Claude already knows. It assumes competence and never pads, matching the anchor-5 'every token earns its place' example.	5 / 5
Actionability	Guidance is mostly executable: concrete commands with env vars ("PLANNOTATOR_REMOTE=1 PLANNOTATOR_PORT=<port> plannotator annotate <path>"), a specific self-check list ("no <u> / no em-dashes / no image \"title\" attr"), and a fix-it table. However, key steps delegate to sibling tools/skills whose interfaces are not shown ("Render the two diagrams via render-diagram", "textstyle.py --smallcaps"), leaving minor gaps versus the fully copy-paste-ready anchor 5.	4 / 5
Workflow Clarity	Six numbered steps form a clear sequence with an explicit validation checkpoint (step 5's self-check before handing back the link) and a feedback loop (step 6: "Apply annotations and repeat"). The risky in-place rewrite is guarded by the self-check, matching the anchor-5 validate-then-proceed pattern.	5 / 5
Progressive Disclosure	Sections are well organized with clear headers, but there are no bundle files at all, and the ~74-line body inlines content that could be split out — notably the plannotator-safe formatting matrix that is explicitly duplicated knowledge ("Same matrix as readable-doc") and the detailed section-by-section rules. This is good structure with minor organization gaps, matching anchor 4 rather than the fully split, reference-signaled anchor 5.	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 with an explicit 'Use when...' trigger, a concrete enumeration of the output shape, and explicit disambiguation from the sibling skills (readable-doc for short digests, write-spike for content). The only gaps are a couple of missing natural synonyms and a single-action focus, which keep specificity and trigger coverage at 4 rather than 5.

Dimension	Reasoning	Score
Specificity	The description names a concrete action ("formatting a full engineering spike, PRD, or design-of-record doc for review") and comprehensively enumerates the team-standard shape it produces ("metadata header, TLDR, background, spike goals, architecture diagrams, ... risks, open questions, and a verification appendix"). It centers on one formatting action rather than listing multiple distinct concrete actions, so it matches anchor 4 rather than 5, and is far above the vague/generic anchors.	4 / 5
Completeness	Both questions are answered explicitly: what the skill does ("formatting a full engineering spike... doc for review" into the "complete team-standard shape") and when to use it ("Use when formatting... when the reader wants the complete team-standard shape"). It even adds explicit negative triggers ("For a short summary of a spike use readable-doc"), matching the anchor-5 example structure.	5 / 5
Trigger Term Quality	Natural trigger terms are present: "engineering spike", "PRD", "design-of-record", "doc for review", "short summary" — phrases a team member would plausibly say. A few common synonyms (e.g., "design doc", "RFC") are missing, so it fits anchor 4 (good coverage, a few natural terms missing) rather than 5, and clearly above anchor 3's partial coverage.	4 / 5
Distinctiveness Conflict Risk	The description ends with explicit disambiguation: "For a short summary of a spike use readable-doc; for the content use write-spike." Combined with the narrow "full spike / PRD / design-of-record" niche, this gives a clear trigger boundary with minimal conflict risk, matching anchor 5.	5 / 5
	Total	18 / 20 Passed

Validation

93%

Warnings & errors only

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

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 1 missing	Warning

	Total	15 / 16 Passed

Repository: AndreJorgeLopes/devflow
Path: skills/readable-doc-spike/SKILL.md
Commit: bd4b70c

Reviewed: 7 days ago

Table of Contents

Discovery Implementation Validation

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.