changelog-audit

Audit Warp CHANGELOG.md before a release: recover lost entries, sort by user impact, refine entry language, line-wrap, and (release-branch mode) bump compare refs.

Quality

76%

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/changelog-audit/SKILL.md

Quality

Content

85%Weight 40%Scale 1-3

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

The content is a well-structured, highly actionable, multi-phase workflow with strong validation feedback loops and clean progressive disclosure. Its only real weakness is length — some detailed enumerations could be tightened without losing clarity.

Suggestions

Tighten Phase 1.5 and the failure-modes section by collapsing near-duplicate edge cases into a single table or condensed list to reduce token load.

Consider extracting the large regex/parse-rules block (lines ~522-531) into a references file or compressing it, since it is reference material rather than workflow.

A few narrative paragraphs (e.g. the merge=union rationale in Phase 2 and the 'why' prose in Phase 3) could be trimmed to the essential rule, trusting Claude's understanding of git merge semantics.

Dimension	Reasoning	Score
Conciseness	The body is efficient in that its length comes from genuinely complex project-specific workflow, executable commands, and edge cases rather than explaining concepts Claude already knows; however, it is lengthy overall and some enumerations (Phase 1.5, the failure-mode list) could be tightened, so it sits between anchor 2 and 3.	2 / 3
Actionability	Fully executable guidance throughout — concrete git commands ('git tag --merged', 'git log -S', 'gh issue list'), exact regexes, branch-name formulas, and numeric thresholds (0.5, 0.7) — copy-paste ready with no pseudocode.	3 / 3
Workflow Clarity	A clearly sequenced Phase 1→1.5→2→…→7 pipeline with explicit validation checkpoints (Phase 3a code/build verification), confirmation gates, fix-and-revalidate feedback loops, and an exhaustive failure-mode section — matching the anchor-3 validate→fix→retry pattern.	3 / 3
Progressive Disclosure	SKILL.md is a concise overview pointing to two one-level-deep reference files (sorting-rubric.md, language-conventions.md), both present and clearly signaled with on-demand 'Read' cues and content descriptions.	3 / 3
	Total	11 / 12 Passed

Description

67%Weight 40%Scale 1-3

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 is concrete and clearly niche-scoped, but lacks an explicit 'Use when...' trigger clause and leans on project-specific terms that a user would not naturally say verbatim. It is strong on what and distinctiveness, weaker on when and trigger phrasing.

Suggestions

Add an explicit 'Use when...' clause, e.g. 'Use when preparing a Warp release or auditing CHANGELOG.md before tagging, sorting, or releasing.'

Broaden trigger terms toward natural user phrasing such as 'changelog', 'release prep', 'release notes', or 'sort changelog entries' rather than relying on 'Warp' and 'compare refs'.

Trim the parenthetical '(release-branch mode) bump compare refs' — it narrows the trigger to a mode the user may not name, slightly diluting the natural-keyword coverage.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — 'recover lost entries', 'sort by user impact', 'refine entry language', 'line-wrap', and 'bump compare refs' — each a distinct, specific operation rather than vague language.	3 / 3
Completeness	The 'what' is explicit (the action list), but the 'when' is only implied by the phrase 'before a release'; there is no 'Use when...' clause, which caps completeness at 2 per the guidelines.	2 / 3
Trigger Term Quality	Contains some natural terms a user might say ('CHANGELOG', 'before a release', 'refine entry language'), but they lean project-specific ('Warp', 'bump compare refs') and lack the common variations a user would naturally voice.	2 / 3
Distinctiveness Conflict Risk	Scoped to a single artifact ('Warp CHANGELOG.md') and a specific event ('before a release'), giving it a clear niche unlikely to trigger for any other skill.	3 / 3
	Total	10 / 12 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 (532 lines); consider splitting into references/ and linking	Warning
relative_links	Relative link issues: 2 missing, 2 suspicious	Warning

	Total	14 / 16 Passed

Repository: NVIDIA/warp
Path: .claude/skills/changelog-audit/SKILL.md
Commit: ee184d6

Reviewed: 10 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.