readme-generator
Readme Generator - Auto-activating skill for Technical Documentation. Triggers on: readme generator, readme generator Part of the Technical Documentation skill category.
36
3%
Does it follow best practices?
Impact
98%
1.02xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./planned-skills/generated/17-technical-docs/readme-generator/SKILL.mdQuality
Discovery
7%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 description is extremely minimal and template-like, providing almost no useful information beyond the skill's name. It lacks concrete actions, meaningful trigger terms, and explicit usage guidance. The duplicate trigger term ('readme generator' listed twice) suggests auto-generated content with no human refinement.
Suggestions
Add specific concrete actions the skill performs, e.g., 'Generates README.md files with project overview, installation instructions, usage examples, API documentation, and badges from project source code.'
Add a 'Use when...' clause with natural trigger terms like 'Use when the user asks to create a README, write project documentation, generate a README.md, or set up a new repository's documentation.'
Include varied natural keywords users might say: 'README', 'README.md', 'project docs', 'repo documentation', 'create readme', 'write readme'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description only says 'Readme Generator' and 'Technical Documentation' without listing any concrete actions like 'generate README files from project structure, create badges, add installation instructions'. It is extremely vague about what the skill actually does. | 1 / 3 |
Completeness | The description fails to clearly answer 'what does this do' beyond the name itself, and the 'when' clause is essentially just restating the skill name as a trigger. There is no explicit 'Use when...' guidance with meaningful triggers. | 1 / 3 |
Trigger Term Quality | The trigger terms listed are just 'readme generator' repeated twice. It misses natural user phrases like 'create a README', 'README.md', 'project documentation', 'write a readme', or 'generate docs'. | 1 / 3 |
Distinctiveness Conflict Risk | While 'readme generator' is somewhat specific to README files, the mention of 'Technical Documentation' as a category is broad enough to overlap with other documentation skills. The lack of specific actions makes it harder to distinguish from general documentation tools. | 2 / 3 |
Total | 5 / 12 Passed |
Implementation
0%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is an empty shell—a meta-description of what a README generator skill would do, without any actual content to accomplish the task. It contains no templates, no examples, no concrete instructions, and no code. It would provide zero value to Claude when attempting to generate a README.
Suggestions
Add a concrete README template (e.g., a markdown skeleton with sections like Title, Description, Installation, Usage, Contributing, License) that Claude can fill in based on project context.
Include executable steps for generating a README, such as: 1) Inspect project structure, 2) Read package.json/pyproject.toml for metadata, 3) Generate sections based on discovered information, 4) Validate all links and code blocks.
Provide at least one complete input/output example showing a project directory structure and the resulting generated README.
Remove all self-referential meta-content (e.g., 'This skill activates automatically when you...', 'Example Triggers') and replace with actionable guidance.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is entirely filler and meta-description. It explains what the skill does in abstract terms without providing any actual instructions, code, or concrete guidance. Every line describes rather than instructs. | 1 / 3 |
Actionability | There is zero actionable content—no code, no commands, no templates, no concrete steps for generating a README. The entire skill is a self-referential description of itself with no executable guidance. | 1 / 3 |
Workflow Clarity | No workflow is defined. There are no steps, no sequence, and no validation checkpoints. The skill merely claims it 'provides step-by-step guidance' without actually containing any. | 1 / 3 |
Progressive Disclosure | The content is a flat, monolithic block of vague descriptions with no references to detailed files, no structured navigation, and no meaningful content organization beyond generic headings. | 1 / 3 |
Total | 4 / 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 |
|---|---|---|
allowed_tools_field | 'allowed-tools' contains unusual tool name(s) | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 9 / 11 Passed | |
- Commit
c8a915c
- 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.