Tessl • The management layer for AI agent skills

SkillPublic

readme

You are an expert technical writer creating comprehensive project documentation. Your goal is to write a README.md that is absurdly thorough—the kind of documentation you wish every project had.

Quality

63%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/readme/SKILL.md

Quality

Content

63%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The skill is highly actionable with a clear three-phase workflow, but it is severely bloated: the bulk is an inlined full README template that duplicates Rails deployment and testing knowledge Claude already has instead of being split into reference files. Adding a verification checkpoint for generated commands would round out the workflow.

Suggestions

Move the ~650-line README template (Getting Started, Architecture, Deployment, Testing, Troubleshooting examples) into references/ (e.g. references/readme-template.md, references/deployment-platforms.md) and keep SKILL.md as a lean overview with one-level-deep links.

Add a post-writing validation step, e.g. verify every command and file path cited in the generated README exists in the repo before finishing.

Trim sections that restate common knowledge (Heroku/Kamal/Fly CLI basics, Minitest/RSpec syntax) down to the format expectations and project-specific checks Claude cannot infer.

Dimension	Reasoning	Score
Conciseness	Roughly 650 of the ~840 lines are an inlined worked README example (Kamal/Heroku/Fly/Docker deployment commands, Minitest/RSpec test samples, Rails env-var tables) that largely duplicates knowledge Claude already has, making the body noticeably padded.	2 / 5
Actionability	Guidance is fully concrete and executable: exact detection files for each deployment platform (fly.toml, render.yaml, railway.json), copy-pasteable commands, a complete ordered README section structure, and explicit output location (README.md in project root).	5 / 5
Workflow Clarity	The pre-writing sequence (deep codebase exploration, identify deployment target, ask only if critical, write, output to README.md) is explicit and well-ordered, but there is no validation step verifying that commands and paths in the generated README actually exist in the repo.	4 / 5
Progressive Disclosure	The body is well-sectioned and navigable, but it is a single monolithic file with no bundle files at all; hundreds of lines of platform-specific template content (deployment, testing, troubleshooting) clearly belong in separate reference files.	3 / 5
	Total	14 / 20 Passed

Description

48%Weight 40%Scale 1-5

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 states a clear goal (an absurdly thorough README.md) but is written in second person and completely lacks a 'Use when...' trigger clause, so it would rarely be selected at the right moment. It is distinct as a niche but under-specified for triggering.

Suggestions

Add an explicit trigger clause, e.g. 'Use when the user asks to create or update a README.md, says "write readme" or "document this project".'

Rewrite in third person describing concrete actions (e.g. 'Explores the codebase, detects the deployment platform, and writes a comprehensive README.md covering local setup, architecture, and deployment').

Drop the aspirational padding ('the kind of documentation you wish every project had') in favor of the concrete deliverable and its trigger terms.

Dimension	Reasoning	Score
Specificity	Only one concrete action is stated ('write a README.md that is absurdly thorough') with the domain named but actions minimal, and the description is written in second person ('You are an expert technical writer', 'Your goal is to write'), which the rubric penalizes by one point.	2 / 5
Completeness	The 'what' is clear (write a thorough README.md) but the 'when' is entirely absent, capping completeness at 3 per the rubric guideline.	3 / 5
Trigger Term Quality	'README.md' and 'project documentation' are relevant keywords users would naturally say, but common variations and trigger phrasings ('write readme', 'document this project') are missing.	3 / 5
Distinctiveness Conflict Risk	README generation is a clear niche with minimal overlap risk, though the generic 'project documentation' wording without distinct triggers leaves minor overlap with broader docs skills.	4 / 5
	Total	12 / 20 Passed

Validation

87%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (844 lines); consider splitting into references/ and linking	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	14 / 16 Passed

Repository: administrakt0r/AI-Agents-Safe-Coding-Skills
Path: skills/readme/SKILL.md
Revision: 64adc55

Reviewed: 15 days ago

Discovery Implementation Validation

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.

readme

Table of Contents

Is this your skill?