documentation-readme
Generates a detailed README file based on provided project data and parameters.
35
30%
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 ./skills/documentation-readme/SKILL.mdQuality
Discovery
32%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description identifies its core purpose (README generation) but is too terse and lacks critical details. It has no 'Use when...' clause, provides no specific actions beyond 'generates', and uses vague language like 'project data and parameters' without clarifying what those are. It would benefit significantly from explicit trigger terms and a clearer enumeration of capabilities.
Suggestions
Add a 'Use when...' clause with trigger terms like 'README', 'readme.md', 'project documentation', 'repository setup', 'describe my project'.
List specific concrete actions such as 'generates sections including installation instructions, usage examples, API reference, contributing guidelines, and license information'.
Replace vague 'project data and parameters' with specific inputs like 'codebase structure, package.json, project configuration files, or user-provided project details'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (README generation) and one action (generates a detailed README file), but doesn't list specific concrete actions like what sections are included, what formats are supported, or what 'project data and parameters' means. | 2 / 3 |
Completeness | Describes what it does (generates a README) but completely lacks a 'Use when...' clause or any explicit trigger guidance for when Claude should select this skill. Per rubric guidelines, missing 'Use when' caps completeness at 2, and the 'what' is also weak, so this scores a 1. | 1 / 3 |
Trigger Term Quality | Includes 'README' which is a natural keyword users would say, but misses common variations like 'readme.md', 'project documentation', 'repo description', or 'markdown documentation'. | 2 / 3 |
Distinctiveness Conflict Risk | README generation is a somewhat specific niche, but 'based on provided project data and parameters' is vague enough that it could overlap with general documentation generation or markdown writing skills. | 2 / 3 |
Total | 7 / 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 generic prompt to 'write a README' with a list of standard sections that Claude already knows. It lacks actionable guidance such as example outputs, templates, or specific formatting conventions. The content could be reduced to a few lines specifying only what's unique (maintainer info, any project-specific conventions) rather than restating common knowledge.
Suggestions
Add a concrete example README template or sample output showing the expected format, style, and level of detail for each section.
Remove the enumeration of standard README sections (Title, Description, Installation, etc.) since Claude already knows these — instead focus on project-specific conventions or style preferences that differentiate this skill.
Add actionable steps for the workflow: e.g., 'First read package.json/pyproject.toml for dependencies, then check for existing README, then generate/update with the following template...'
Include a concrete example input (project details) paired with expected output to make the skill copy-paste actionable.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill explains basic concepts Claude already knows (what a README is, what sections it should contain). The enumerated sections (Project Title, Description, Installation, etc.) are standard knowledge that doesn't need to be spelled out. The 'When to Use This Skill' section is also unnecessary padding. | 1 / 3 |
Actionability | The skill provides only vague, abstract direction ('Create a README file based on the provided project details') with no concrete examples, templates, or executable guidance. There are no example inputs/outputs, no sample README structure, and no specific formatting patterns to follow. | 1 / 3 |
Workflow Clarity | The sections are listed in a logical order and the skill describes what to include, but there's no actual workflow sequence for generating the README (e.g., analyze codebase first, then check for existing README, then generate). For a single-task skill this is acceptable but could be clearer about the process. | 2 / 3 |
Progressive Disclosure | This is a simple, single-purpose skill under 50 lines with no need for external references. The content is organized into clear sections (When to Use, Instructions, Output Format, Notes), which is appropriate for its scope. | 3 / 3 |
Total | 7 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- ucdavis/ai-skills-registry
- Commit
c0b2e4b
- 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.