CtrlK
BlogDocsLog inGet started
Tessl Logo

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.

70

Quality

88%

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

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 tight, highly actionable instruction skill: exact output conventions, a validated six-step workflow with a feedback loop, and a concrete do/never formatting table. The main deductions are inline dated provenance notes, tool references with no bundled backing, and shared conventions inlined rather than split into a common reference.

DimensionReasoningScore

Conciseness

The body is dense and operative: every section gives rules or exact syntax rather than background, and it never explains concepts Claude already knows. It is held below anchor 5 by inline time-sensitive provenance ("(team feedback, 2026-07-16)", "(correctness, verified 2026-07-14)"), which the guidelines say to penalize unless placed in a deprecated/old-patterns section, and by a few near-duplicated rules (the em-dash/tag limits appear in both Style and Common Mistakes). It is well above the midpoint: no padding, no conceptual filler.

4 / 5

Actionability

Guidance is highly concrete: exact output path ("<source-stem>-summary.md"), line budgets ("TLDR — 3 to 5 lines"), a fixed 13-section structure in order, a copy-ready command ("PLANNOTATOR_REMOTE=1 PLANNOTATOR_PORT=<port> plannotator annotate <summary-path>"), and an explicit do/never formatting table. Minor gaps keep it at 4: it invokes external tools (render-diagram, textstyle.py --smallcaps, plannotator) whose usage lives outside this skill and no bundle files are shipped to back them, and 'render one all-in-one diagram' stops short of what diagram content to include.

4 / 5

Workflow Clarity

The command workflow is a clear 6-step numbered sequence with an explicit validation checkpoint (step 5 self-check listing the exact failure conditions: no <u>, no em-dashes, no image title attr, no GFM alert inside details, no scattered ticket numbers) and a feedback loop (step 6: apply returned annotations and repeat). Content rules are additionally reinforced by a Common Mistakes table with fixes. This matches the explicit-validation-with-error-recovery anchor.

5 / 5

Progressive Disclosure

The single file is well-sectioned (When to Use, command steps, contents, style, renderer-safe table, Common Mistakes) and needs no external references to execute, so nothing is buried or nested. It sits at 4 rather than 5 because the ~80-line body inlines shared conventions that the text itself says are common to two skills ("Both this skill and readable-doc-spike follow it" for the renderer-safe table), i.e., content that naturally belongs in a shared reference file; and several referenced tools (textstyle.py, render-diagram) have no bundled paths to point to.

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 description: concrete, comprehensive action list, explicit third-person 'what' plus a concrete 'Use when' trigger clause, and explicit disambiguation from sibling skills. The only gap is a few missing natural synonyms for the summary request itself (e.g., 'digest', 'short version').

DimensionReasoningScore

Specificity

The description lists multiple concrete actions with comprehensive coverage: "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." This is a full enumeration of the deliverable's contents, matching the comprehensive multi-action anchor; it is not merely naming a domain with 1-2 actions.

5 / 5

Completeness

Both questions are answered explicitly: what it does ("Condenses the source into a super-short TLDR...") and when to use it ("Use when you have a full spike, PRD, or long design doc and want a tight, scannable SUMMARY of it for a busy reviewer"). It uses third person ("Condenses"), includes a concrete 'Use when' trigger clause, and adds scope boundaries. This matches the anchor 5 example structure exactly; score 4 would require the 'when' to be less explicit, which it is not.

5 / 5

Trigger Term Quality

Good natural keyword coverage: "spike", "PRD", "design doc", "SUMMARY", "TLDR", "tight, scannable", "busy reviewer" are phrasings a user would plausibly say. A few common variations are missing ("short version", "digest", "executive summary", "brief"), which keeps it just below the comprehensive-with-synonyms anchor 5, but it is clearly above the midpoint: it explicitly disambiguates the sibling skills, which is what the conflict anchor rewards, so anchor 5's minimal-conflict fit is arguably close; the missing natural variations on the summary ask keep it at 4.

4 / 5

Distinctiveness Conflict Risk

It carves out a clear niche (small reviewer-facing summary layer) and explicitly routes adjacent intents elsewhere: "For the full spike itself use readable-doc-spike; for the content use write-spike." Triggers are tied to a specific scenario (digest of a finished spike/PRD for a reviewer), so wrong-skill firing risk is minimal.

5 / 5

Total

19

/

20

Passed

Validation

93%

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

CriteriaDescriptionResult

relative_links

Relative link issues: 1 missing, 1 suspicious

Warning

Total

15

/

16

Passed

Repository
AndreJorgeLopes/devflow
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.