prose-review

Check that added comments, docstrings, and changelog entries document the code rather than narrate the change that produced it

Quality

75%

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 ./.claude/skills/prose-review/SKILL.md

Quality

Content

100%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 body is an exemplar of a focused, single-purpose skill: lean, fully actionable, with a clear sequenced workflow, calibration checkpoints against false positives, and concrete remediation commands, all well-organized into labeled sections.

Dimension	Reasoning	Score
Conciseness	The body is lean and assumes Claude's competence throughout — it never explains what comments or changelogs are, and every sentence (scope table, the test, calibration examples, remediation table) earns its place, matching the lean-and-efficient anchor.	5 / 5
Actionability	It gives fully executable, copy-paste-ready guidance: exact git diff commands per scope, a concrete list of rewrite/delete triggers, before/after example fixes, and a remediation table with exact commands (git commit --amend --no-edit, gh pr edit <pr_number> --body), matching the fully-executable anchor.	5 / 5
Workflow Clarity	The process is clearly sequenced with explicit validation and feedback loops: scope selection -> review added lines only -> apply the test -> rewrite or delete -> remediate via the situation table -> report, with a calibration section that acts as an error-correction checkpoint against false positives, matching the explicit-validation anchor.	5 / 5
Progressive Disclosure	Content is appropriately organized into well-labeled one-level sections (Scope, The Test, Calibration, Changelog Exception, Remediation, Report) with no nested external references; for an under-50-line single-purpose skill with no bundle files this clear sectioning meets the simple-skill exception for a top score.	5 / 5
	Total	20 / 20 Passed

Description

50%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 and specific 'what' with a memorable distinguishing angle, but it omits any explicit 'when' trigger guidance and offers only thin natural-keyword coverage, which caps both completeness and trigger quality.

Suggestions

Add an explicit 'when' clause, e.g. 'Use when reviewing staged or branch diffs that add comments, docstrings, or changelog entries.'

Include natural trigger phrases users would actually say, such as 'review my comments', 'clean up docstrings', or 'check the changelog'.

Briefly enumerate the concrete actions (e.g. 'rewrites or deletes prose that narrates the change') to lift specificity toward comprehensive coverage.

Dimension	Reasoning	Score
Specificity	Names the domain (comments, docstrings, changelog entries) and concrete actions (check, document the code) but 'check' is a single generic action and there is no enumerated list of operations, so it sits above a 3 but not at comprehensive 5.	4 / 5
Completeness	The description states a clear 'what' (check that added prose documents the code) but contains no 'when/Use when...' trigger clause and no explicit invocation guidance, so it falls between the clear-what-only anchor (3) and the vague-what-no-when anchor (2), capped here because the cap on missing trigger guidance limits completeness to 3 and there is genuinely no 'when'.	2 / 5
Trigger Term Quality	It uses domain terms like 'comments', 'docstrings', and 'changelog entries' that a user might say, but it lacks common natural variations and synonyms a user would actually invoke ('review my comments', 'clean up prose', 'check changelog'), placing it at the some-keywords anchor.	3 / 5
Distinctiveness Conflict Risk	The niche ('document the code rather than narrate the change') is specific and unlikely to collide with unrelated skills, with only minor overlap risk against a general code-review skill, matching the mostly-distinct anchor.	4 / 5
	Total	13 / 20 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: pipecat-ai/pipecat
Path: .claude/skills/prose-review/SKILL.md
Commit: baf1f16

Reviewed: 3 days ago

Table of Contents

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.