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

76%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./.agents/skills/good-readme/SKILL.md

Quality

Content

62%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

This skill provides a well-structured workflow for README creation and improvement with clear checklists and two distinct operational modes. Its main weaknesses are verbosity in the philosophy section (explaining things Claude already knows about good documentation) and a lack of concrete output examples showing what a good README actually looks like in practice. The referenced files would likely strengthen the skill significantly, but their absence makes it harder to fully evaluate progressive disclosure.

Suggestions

Trim the philosophy section to 2-3 sentences max — Claude already understands what makes documentation good or bad; focus on project-specific conventions instead.

Add a concrete example of a well-structured README output (even a short template) so Claude has a tangible target format, not just procedural steps.

Consolidate the 'Key Principles' and 'Per-Section Checklist' — there's overlap (e.g., 'test your examples' appears in both), and merging would save tokens while improving clarity.

Dimension	Reasoning	Score
Conciseness	The philosophy section explains concepts Claude already understands (what makes a good vs bad README, that developers decide quickly). The modes and checklists are useful but the opening philosophy could be significantly tightened. Some redundancy between the philosophy, key principles, and per-section checklist.	2 / 3
Actionability	Provides clear checklists and step-by-step processes for both create and improve modes, which is good. However, it lacks concrete examples of actual README output — no template, no before/after, no sample markdown. The guidance is procedural but not copy-paste ready in the way a code skill would be.	2 / 3
Workflow Clarity	Both modes have clearly sequenced workflows with explicit checklists. The 'Create' mode has a discovery phase before writing, and the 'Improve' mode mandates an audit-first approach with user review checkpoints. The feedback loops (present to user for review/approval) are appropriate for this non-destructive task.	3 / 3
Progressive Disclosure	References to anatomy.md, examples.md, anti-patterns.md, cloudflare.md, and quality-checklist.md are well-signaled and one level deep. However, no bundle files were provided, so we cannot verify these references exist. The main file itself could benefit from moving some content (like the philosophy section) to keep the overview leaner.	2 / 3
	Total	9 / 12 Passed

Description

89%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

This is a solid skill description that clearly communicates its purpose and provides explicit trigger guidance. It excels in completeness and distinctiveness, with good natural trigger terms. The main area for improvement is adding more specific concrete actions beyond 'create and improve' to better convey the full range of capabilities.

Suggestions

Add more specific concrete actions to boost specificity, e.g., 'Generate badges, write installation instructions, create table of contents, add usage examples, and structure contributing guidelines for README documents.'

Dimension	Reasoning	Score
Specificity	Names the domain (README documents for GitHub projects) and some actions (create, improve, audit quality), but doesn't list highly specific concrete actions like 'generate badges, write installation instructions, create table of contents, add contributing guidelines'.	2 / 3
Completeness	Clearly answers both 'what' (create and improve README documents for GitHub projects) and 'when' with an explicit 'Use when...' clause covering multiple trigger scenarios (write new, improve existing, audit quality, documentation best practices).	3 / 3
Trigger Term Quality	Includes strong natural trigger terms users would say: 'README', 'write a new README', 'improve', 'audit README quality', 'documentation best practices', 'repository'. These cover common variations of how users would phrase requests.	3 / 3
Distinctiveness Conflict Risk	Clearly scoped to README documents specifically for GitHub projects, which is a distinct niche. The triggers are specific enough (README, audit README quality, documentation best practices for repository) to avoid conflicting with general documentation or code writing skills.	3 / 3
	Total	11 / 12 Passed

Validation

90%

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 — 10 / 11 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	10 / 11 Passed

Repository: adewale/slide-maker
Commit: feaccfd

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