skill-audit

Audit codebases for quality, consistency, and broken patterns — use for pre-release or tech debt review

Quality

61%

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

Quality

Content

56%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 delivers a genuinely systematic, well-sequenced audit process with concrete tool guidance and thorough output templates — actionability and workflow clarity are solid. Its main costs are token bloat from sections that restate the obvious and a monolithic structure with no real bundle files behind its external references.

Suggestions

Delete or compress the 'Be Systematic, Not Random' and 'Make Findings Actionable' good/poor pairs, the 'Red Flags' table, and 'The Bottom Line' — they restate knowledge Claude already has and account for substantial token cost.

Move the three audit templates (functional, code pattern, UI consistency) and the worked pattern walkthroughs into a references/ file, keeping SKILL.md as a lean overview of the five phases with one-level-deep pointers.

Replace placeholder verification methods ('[how to test - code review, runtime check, etc.]') with concrete guidance per audit type (matching the Quick Reference table) and add an explicit coverage-validation step before reporting findings.

Dimension	Reasoning	Score
Conciseness	At 587 lines the body contains several padded sections that teach Claude what it already knows: the 'Be Systematic, Not Random' good/poor pair, the 'Make Findings Actionable' good/poor pair, the 'Red Flags' table, and 'The Bottom Line'. This matches anchor 2 ('noticeably verbose; several unnecessary explanations or padded sections') rather than anchor 3, where unnecessary explanation would be isolated rather than recurring sections.	2 / 5
Actionability	The guidance names concrete tools ('Use Glob and Grep to find all relevant code', 'Use TodoWrite to track audit progress', 'Use AskUserQuestion if needed') and provides fully specified per-phase output templates. It is not anchor 5 because verification methods are placeholders ('[how to test - code review, runtime check, etc.]') and no worked example with real content is given.	4 / 5
Workflow Clarity	Five phases are clearly sequenced (Scope → Discovery → Execution → Analysis/Reporting → Remediation) with per-item checkpoints specifying Expected/Method/Result/Evidence and explicit severity categorization. It falls short of anchor 5 because there is no explicit feedback loop such as verifying checklist coverage is complete or re-testing findings before reporting.	4 / 5
Progressive Disclosure	In-file structure is good (clear section headers, a quick-reference table), but the skill is a single ~590-line monolith where the three audit templates, pattern walkthroughs, and example blocks could live in reference files. The references it does make ('skills/blocks/engineering-method-selection.md', 'skills/blocks/architecture-simplification.md') are external plugin paths not present in this bundle and are not clearly signaled as navigation. This matches anchor 3 ('content that should be separate is inline').	3 / 5
	Total	13 / 20 Passed

Description

66%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.

A compact, grammatical description that clearly states what the skill does and gives two explicit usage contexts with natural trigger terms. Its weaknesses are abstraction in the action list, missing natural trigger variants, and no in-description disambiguation from code-review or security-audit skills.

Suggestions

Enumerate concrete actions instead of abstract focuses, e.g. 'Audit codebases by building a checklist of features/patterns, testing each systematically, and producing a severity-categorized findings report with a prioritized fix plan'.

Add natural trigger phrases to the description itself, e.g. 'use when the user asks to audit the app, find all instances of a pattern, or check for broken features'.

State the boundary in the description (e.g. 'for functional quality audits — not security audits or code review') to reduce conflict risk with adjacent skills.

Dimension	Reasoning	Score
Specificity	The description names the domain ('Audit codebases') and three audit focuses ('quality, consistency, and broken patterns'), but 'quality' is abstract, it is a single verb applied to targets rather than several distinct actions, and it omits the discovery, reporting, and fix-prioritization work the skill actually performs. It sits above anchor 3's '1-2 concrete actions' in focus areas but below anchor 4's 'several specific actions' (e.g. 'extracts, fills, converts').	3 / 5
Completeness	It answers both 'what' ('Audit codebases for quality, consistency, and broken patterns') and 'when' ('use for pre-release or tech debt review') explicitly. Not a 5 because the 'when' gives two usage scenarios rather than the concrete trigger phrases anchor 5 requires (e.g. 'when the user mentions X or asks for Y').	4 / 5
Trigger Term Quality	'audit codebases', 'pre-release', and 'tech debt review' are phrases users would naturally say when they need this skill. It falls short of anchor 5 because common natural variants such as 'check for broken features', 'find all instances of', or 'scan for issues' are absent (they exist only in the frontmatter trigger, not the description).	4 / 5
Distinctiveness Conflict Risk	'Audit codebases for quality' overlaps heavily with code review and linting skills, and the description itself provides no exclusion of adjacent skills (only the frontmatter trigger block does). It is somewhat specific to auditing, matching anchor 3 ('could still overlap with similar skills') rather than anchor 4's 'minor overlap risk with closely related skills'.	3 / 5
	Total	14 / 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 (587 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: nyldn/claude-octopus
Path: .claude/skills/skill-audit/SKILL.md
Commit: 0093dab

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