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.
83
80%
Does it follow best practices?
Impact
Pending
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' effectively 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 table of contents, add usage examples, and structure contributing guidelines.'
| 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 instruction skill with strong workflow clarity and good progressive disclosure to reference files. Its main weaknesses are some verbosity in the philosophy section (explaining concepts Claude already knows about good vs bad documentation) and a lack of concrete output examples showing what a generated README section should look like. The checklists are practical and the two-mode structure is clear.
Suggestions
Trim the Philosophy section significantly — Claude already knows what makes documentation good or bad. Keep only the 'answer what/why/how in 30 seconds' framing and cut the good/bad README descriptions.
Add a concrete example of expected output — e.g., a sample title + one-liner + quick-start section for a hypothetical project, so Claude has a tangible template to follow.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The philosophy section explains 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 and add structure. | 2 / 3 |
Actionability | The skill provides clear checklists and process steps, which is good for an instruction-only skill. However, it lacks concrete examples of actual README output — no sample title+one-liner, no example quick-start section, no before/after of an improvement. The guidance is structured but remains somewhat abstract. | 2 / 3 |
Workflow Clarity | Both modes (Create and Improve) have clearly sequenced checklists with explicit validation steps — reading source first, auditing before improving, presenting to user for review before finalizing. The Improve mode specifically sequences 'audit first, then improve' with a logical ordering of fixes (factual accuracy → structure → clarity → removal). | 3 / 3 |
Progressive Disclosure | Excellent use of one-level-deep references: anatomy.md, examples.md, anti-patterns.md, cloudflare.md, and quality-checklist.md are all clearly signaled with descriptive context. The main skill stays focused on workflow while pointing to detailed reference materials. | 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
de27d96
- 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.