CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

good-readme

Create and improve README documents for GitHub projects. Use when the user wants to write a new README, improve an existing one, audit README quality, or asks about documentation best practices for their repository.

Quality

82%

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

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.

The content is well-structured, action-oriented, and uses progressive disclosure effectively with real reference files for the detailed material. The main improvements are tightening the Philosophy prose, adding an explicit validation feedback loop, and reconciling the body's cloudflare.md link with the frontmatter references list.

Suggestions

Add cloudflare.md to the frontmatter `references:` list so it matches the body link, or remove the body reference if the file is not intended as a bundled reference.

Tighten the Philosophy section to principles-only, trimming the descriptive 'good/bad READMEs' prose that largely restates what Claude already knows.

Add an explicit validate-then-fix feedback loop (e.g., 'if code examples fail when tested, fix and re-test before presenting to the user') to strengthen the Improve-mode workflow.

DimensionReasoningScore

Conciseness

The body is largely efficient and assumes Claude's competence, but the three-paragraph Philosophy section ("A README is the front door to your project...", "Bad READMEs are walls of text...") includes some explanatory framing that could be trimmed without losing value.

4 / 5

Actionability

Concrete, sequenced checklists ("Draft the title + one-line description", "Score against the quality checklist") and a copy-pasteable Per-Section Checklist give actionable guidance; no code is present, which is appropriate for a prose-writing skill, with only minor specificity gaps.

4 / 5

Workflow Clarity

Two modes each have a clear sequence (Before writing → Writing process; Audit first → Then improve) with review checkpoints ("Present draft to user", "Verify all code examples work"), but explicit error-recovery feedback loops (if-validate-fails-then-fix) are not stated.

4 / 5

Progressive Disclosure

The SKILL.md is a clear overview pointing to one-level-deep, real reference files (anatomy, examples, quality-checklist, anti-patterns) with descriptive links, but cloudflare.md is referenced in the body yet omitted from the frontmatter references list — a minor organization gap.

4 / 5

Total

16

/

20

Passed

Description

83%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 that clearly states the skill's purpose and provides explicit, natural-language trigger guidance across multiple README-related intents. It is concrete, scannable, and well-aligned with good examples, with only minor distinctiveness and synonym-coverage gaps.

DimensionReasoningScore

Specificity

Names the README domain and several concrete actions — "Create and improve README documents", "audit README quality", "asks about documentation best practices" — with only minor coverage gaps (e.g., no explicit translate/localize or maintain action).

4 / 5

Completeness

Explicitly answers both what ("Create and improve README documents for GitHub projects") and when ("Use when the user wants to write a new README, improve an existing one, audit README quality...") with concrete trigger phrases, matching the top anchor.

5 / 5

Trigger Term Quality

Includes natural phrases users would say — "write a new README", "improve an existing one", "audit README quality", "documentation best practices" — but misses a few synonyms/variations like "docs" or "documentation" standing alone.

4 / 5

Distinctiveness Conflict Risk

Targets a clear README niche with distinct triggers, but the "asks about documentation best practices for their repository" phrasing widens scope slightly and risks minor overlap with general documentation skills.

4 / 5

Total

17

/

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

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

15

/

16

Passed

Repository

adewale/slide-maker

Path

.agents/skills/good-readme/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.