Name: readable-doc
Rating: 70.39999999999999 (1 reviews)
Author: AndreJorgeLopes

readable-doc

Use when you have a full spike, PRD, or long design doc and want a tight, scannable SUMMARY of it for a busy reviewer. Condenses the source into a super-short TLDR, one all-in-one diagram, the recommendation, spike goals, still-open options, open questions, open risks, the technical deltas (GraphQL / DB / query), additive migration, external dependencies, and feature-flag strategy, with a link back to the full doc. Clean team style, no emoji or tag overload. For the full spike itself use readable-doc-spike; for the content use write-spike.

Quality

88%

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

The canonical home for this skill is readable-doc in AndreJorgeLopes/devflow

Quality

Content

81%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 skill body with a clear validated workflow and clean sectioning. The main drags are inline provenance dates that hurt conciseness and a tool reference ('render-diagram') that lacks a concrete invocation example.

Suggestions

Move the inline provenance dates ('team feedback, 2026-07-16', 'verified 2026-07-14') out of section prose — either drop them or relocate to a dedicated provenance/deprecated note — to improve conciseness and avoid time-sensitive decay.

Add a concrete example invocation of `render-diagram` (or a one-line pointer to its usage) so the diagram-rendering step is copy-paste executable rather than implied.

Consider splitting the formatting 'Want/Use/Never' table and 'Common Mistakes' table into a short reference file if the skill grows, to keep SKILL.md a lean overview — though at current size it is acceptable inline.

Dimension	Reasoning	Score
Conciseness	The body is lean and assumes Claude's competence without explaining what a spike/PRD is, but inline time-sensitive provenance dates ('team feedback, 2026-07-16', 'verified 2026-07-14') are embedded in prose rather than placed in a deprecated/old-patterns section, a minor over-explanation penalty.	4 / 5
Actionability	Concrete executable guidance is present — 'PLANNOTATOR_REMOTE=1 PLANNOTATOR_PORT=<port> plannotator annotate <summary-path>', 'textstyle.py --smallcaps', the '<source-stem>-summary.md' naming convention, and a do/don't formatting table — but 'render one all-in-one diagram via render-diagram' references the tool without showing the invocation, a minor gap.	4 / 5
Workflow Clarity	The 'Running as a command' section gives a clear 1–6 sequence with an explicit validation checkpoint (step 5 self-check listing forbidden patterns) and a feedback loop (step 6 'Apply returned annotations and repeat'), matching the top anchor.	5 / 5
Progressive Disclosure	No bundle files exist (references/, scripts/, assets/ are absent) and the single SKILL.md is well-organized into clearly signaled sections with no nested references; it is slightly over the 50-line simple-skill threshold, so it sits at 4 rather than 5.	4 / 5
	Total	17 / 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 strong, specific description with a clear 'Use when' trigger, comprehensive enumeration of outputs, and explicit disambiguation from sibling skills. The only minor gap is slightly less than comprehensive synonym coverage in trigger terms.

Dimension	Reasoning	Score
Specificity	Enumerates many concrete actions — 'super-short TLDR, one all-in-one diagram, the recommendation, spike goals, still-open options, open questions, open risks, the technical deltas (GraphQL / DB / query), additive migration, external dependencies, and feature-flag strategy, with a link back' — giving comprehensive coverage of what the skill produces.	5 / 5
Completeness	Explicitly answers both: 'what' (condenses the source into the enumerated summary parts) and 'when' ('Use when you have a full spike, PRD, or long design doc and want a tight, scannable SUMMARY of it for a busy reviewer') with concrete trigger phrases.	5 / 5
Trigger Term Quality	Natural terms users would say are present ('full spike, PRD, or long design doc', 'tight, scannable SUMMARY', 'busy reviewer'), but a few common synonyms/variations are missing, so it sits just below the comprehensive anchor.	4 / 5
Distinctiveness Conflict Risk	Clear niche (reviewer-facing digest of a spike/PRD) with explicit sibling disambiguation — 'For the full spike itself use readable-doc-spike; for the content use write-spike' — minimizing wrong-skill triggering.	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, 1 suspicious	Warning

	Total	15 / 16 Passed

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

Reviewed: 9 hours 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.