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.
66
80%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./.agents/skills/good-readme/SKILL.mdQuality
Discovery
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 covers the 'what' and 'when' well with natural language triggers. The main area for improvement is adding more specific concrete actions beyond 'create and improve' to better differentiate the full range of capabilities.
Suggestions
Add more specific concrete actions to boost specificity, e.g., 'Generate badges, write installation instructions, create usage examples, add contributing guidelines, and structure table of contents.'
| 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 |
Implementation
70%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-structured skill with strong workflow clarity and excellent progressive disclosure through well-signaled reference files. Its main weaknesses are moderate verbosity in the philosophy section (explaining concepts Claude already knows about good documentation) and a lack of concrete output examples — showing a sample README section or before/after transformation would significantly improve actionability.
Suggestions
Remove or drastically shorten the philosophy section — Claude already knows what makes good documentation. Keep only the 30-second rule and audience-awareness points.
Add a concrete example of a well-written README opening (title + one-liner + quick-start) so Claude has a tangible output pattern to follow, not just procedural steps.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The philosophy section spends tokens explaining what good and bad READMEs are — concepts Claude already understands well. The key principles section also restates common knowledge. However, the checklists and modes are reasonably efficient. | 2 / 3 |
Actionability | The skill provides structured checklists and clear steps for both create and improve modes, which is good. However, it lacks concrete examples of actual README output — no sample README snippets, no before/after examples, no specific templates. The guidance is procedural but not copy-paste ready. | 2 / 3 |
Workflow Clarity | Both modes have clearly sequenced workflows with explicit checklists. The create mode has a 'before writing' phase and a 'writing process' phase. The improve mode has an 'audit first' phase followed by 'then improve' with ordered priorities (fix inaccuracies first, then structure, then clarity). Both include user review checkpoints. | 3 / 3 |
Progressive Disclosure | Excellent use of progressive disclosure — the main skill is a focused overview with clear one-level-deep references to anatomy.md, examples.md, anti-patterns.md, cloudflare.md, and quality-checklist.md. Each reference is well-signaled with context about what it contains. | 3 / 3 |
Total | 10 / 12 Passed |
Validation
90%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
010d974
- 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.