jbvc/readme
When the user wants to create or update a README.md file for a project. Also use when the user says 'write readme,' 'create readme,' 'document this project,' 'project documentation,' or asks for help with README.md. This skill creates absurdly thorough documentation covering local setup, architecture, and deployment.
62
62%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Quality
Discovery
82%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 description with excellent trigger terms and clear completeness, explicitly stating both what the skill does and when to use it. Its main weaknesses are moderate specificity (could list more concrete actions beyond 'create or update') and some overlap risk with broader documentation skills due to generic terms like 'project documentation.' The informal tone ('absurdly thorough') is slightly unprofessional but doesn't significantly harm functionality.
Suggestions
List more specific concrete actions, e.g., 'Generates README.md files with sections for installation, architecture overview, API reference, deployment instructions, and contributing guidelines.'
Narrow the broader trigger terms to reduce conflict risk, e.g., change 'project documentation' to 'project README documentation' to distinguish from other documentation skills.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | It mentions creating/updating README.md and covers 'local setup, architecture, and deployment,' but the core actions are limited to 'create or update a README.md file' without listing more granular concrete actions like generating badges, writing API docs, or structuring sections. | 2 / 3 |
Completeness | Clearly answers both 'what' (creates/updates README.md covering local setup, architecture, and deployment) and 'when' (explicit 'Use when' triggers with multiple natural phrases). The trigger guidance is explicit and well-structured. | 3 / 3 |
Trigger Term Quality | Includes strong natural trigger terms: 'write readme,' 'create readme,' 'document this project,' 'project documentation,' 'README.md.' These are phrases users would naturally say when needing this skill. | 3 / 3 |
Distinctiveness Conflict Risk | While 'README.md' is fairly specific, terms like 'document this project' and 'project documentation' could overlap with other documentation-related skills (e.g., API docs, wiki pages, general documentation generators). The README focus helps but the broader documentation triggers introduce some conflict risk. | 2 / 3 |
Total | 10 / 12 Passed |
Implementation
27%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is essentially a massive README template with some workflow guidance prepended. While the structure and coverage are comprehensive, the content is far too verbose for a skill file—most of it is generic boilerplate that Claude can generate without instruction. The skill would be dramatically more effective as a concise set of principles, a structural outline, and references to example templates rather than inlining hundreds of lines of sample markdown.
Suggestions
Reduce the content by 70-80%: replace the full template sections with a concise structural outline (section names + 1-line descriptions of what each should contain) and trust Claude to generate appropriate content for each project.
Extract platform-specific deployment templates into separate reference files (e.g., DEPLOYMENT_TEMPLATES.md) and link to them from the main skill, rather than inlining Kamal, Docker, Heroku, Fly.io, Render, and VPS instructions.
Add a validation step after README generation: instruct Claude to verify that referenced files/commands actually exist in the codebase and that the tech stack description matches what was discovered during exploration.
Remove generic code examples (RSpec tests, React component tests, Rails credentials usage) that Claude already knows how to write—focus the skill on the unique decision-making logic (what to include, how deep to go, when to ask the user).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~500+ lines. The bulk of the content is generic Rails/React boilerplate examples that Claude already knows how to produce. The skill explains what a README is, what PostgreSQL connection strings look like, how to write RSpec tests, and includes lengthy template sections that are not project-specific guidance but rather filler. Most of this could be reduced to a structural outline with key principles. | 1 / 3 |
Actionability | The skill provides a clear structure and many concrete code examples, but they are generic templates rather than executable guidance for the skill itself. The examples are illustrative placeholders (e.g., 'myapp', generic schema) rather than instructions Claude can directly act on. The exploration steps (Step 1-3) are actionable checklists, which is good, but the massive template sections are more 'fill in the blanks' than truly actionable. | 2 / 3 |
Workflow Clarity | The three-step 'Before Writing' process (explore, identify deployment, ask if critical) provides a reasonable workflow. However, there are no validation checkpoints—no step to verify the generated README against the actual codebase, no feedback loop to check if sections are accurate or if referenced files actually exist. For a skill that generates documentation from code exploration, validation is important. | 2 / 3 |
Progressive Disclosure | This is a monolithic wall of text with no references to external files. The entire README template with all its sections (architecture, testing, deployment for 6+ platforms, troubleshooting) is inlined. The deployment section alone covers Kamal, Docker, Heroku, Fly.io, Render, and VPS—each could be a separate reference. The skill would benefit enormously from splitting templates and platform-specific guidance into separate files. | 1 / 3 |
Total | 6 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 9 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
skill_md_line_count | SKILL.md is long (843 lines); consider splitting into references/ and linking | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 9 / 11 Passed | |
Reviewed
Table of Contents