CtrlK
BlogDocsLog inGet started
Tessl Logo
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
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./plugins/AI-Agents-Safe-Coding-Skills-claude/skills/readme/SKILL.md

The canonical home for this skill is readme in administrakt0r/AI-Agents-Safe-Coding-Skills

SKILL.md
Quality
Evals
Security

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.

DimensionReasoningScore

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.

DimensionReasoningScore

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%

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

CriteriaDescriptionResult

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

plugins/AI-Agents-Safe-Coding-Skills-claude/skills/readme/SKILL.md

Revision

64adc55

Reviewed

Table of Contents

DiscoveryImplementationValidation

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.

Claim skill