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

83%

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

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, actionable formatting skill with a clear sequenced workflow and validation feedback loop. It is consistently strong across dimensions but sits at 4 rather than 5 due to minor tightenability of long enumerations, deferred detail to sibling skills, and a manual rather than automated validation loop.

Suggestions

Tighten the long parenthetical section lists (e.g., recap of the full team-standard shape) into a compact bullet list or a reference to the Section skeleton to trim a few tokens.

For the destructive in-place rewrite, add an automated validation rerun (e.g., re-parse frontmatter / re-run self-check script) rather than relying on a manual checklist, to push workflow_clarity to the top anchor.

Inline one-line definitions or entry points for the referenced sibling skills (render-diagram, verify-first, textstyle.py) so the workflow is executable without context-switching, closing the minor actionability gap.

Dimension	Reasoning	Score
Conciseness	Dense and information-rich with no padding about concepts Claude already knows, but a few long parenthetical enumeration lists (e.g., the description-recap section list) could be tightened, fitting the 'efficient; minor instances that could be trimmed' anchor.	4 / 5
Actionability	Provides concrete commands (render-diagram, plannotator annotate with env vars, textstyle.py --smallcaps), a full section skeleton, and a concrete self-check list; minor gaps exist because several steps defer to sibling skills without inline detail.	4 / 5
Workflow Clarity	Numbered command sequence includes an explicit self-check validation gate (step 5) and a feedback loop ('Apply annotations and repeat' in step 6); the in-place rewrite is destructive and the self-check is a manual checklist rather than an automated validate-rerun loop, keeping it just below the top anchor.	4 / 5
Progressive Disclosure	Body is well-organized into clearly labeled sections with one-level references to sibling skills (render-diagram, write-spike, readable-doc, verify-first, textstyle.py); no bundle files exist to verify deeper references, and organization is good with only minor gaps.	4 / 5
	Total	16 / 20 Passed

Description

92%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 highly specific, trigger-rich description that clearly states both purpose and activation conditions while disambiguating from sibling skills. Minor room to broaden natural-language trigger synonyms keeps it just shy of perfect on trigger term quality.

Dimension	Reasoning	Score
Specificity	Comprehensively enumerates concrete formatting actions spanning metadata header, TLDR, per-goal investigation, options/recommendation, DB/GraphQL/query changes, migration, testing, phasing, and verification appendix, matching the 'multiple specific concrete actions; comprehensive coverage' anchor.	5 / 5
Completeness	Explicitly answers both what ('formatting a full engineering spike... into the complete team-standard shape') and when ('Use when formatting a full engineering spike, PRD, or design-of-record doc for review...') with concrete trigger phrases.	5 / 5
Trigger Term Quality	Natural trigger terms ('engineering spike', 'PRD', 'design-of-record doc', 'for review') are present and would be said by a user, but coverage leans slightly jargon-ward and lacks synonyms, fitting just below the comprehensive anchor.	4 / 5
Distinctiveness Conflict Risk	Clear niche (full spike formatting) with explicit boundary disambiguation ('For a short summary of a spike use readable-doc; for the content use write-spike'), yielding minimal conflict risk.	5 / 5
	Total	19 / 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: devflow-plugin/skills/readable-doc-spike/SKILL.md
Commit: bd4b70c

Reviewed: 4 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.