skill-reviewer

Deep review of an AI skill directory. Critically evaluates structure, clarity, completeness, and consistency of SKILL.md, skills/*.md, commands/*.md, and guidelines.md. Use when reviewing, auditing, or validating an AI workflow skill. Activated by commands: /review.

Quality

77%

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

The canonical home for this skill is skill-reviewer in flightctl/ai-workflows

Quality

Content

71%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 a well-structured, mostly executable workflow with explicit validation and error handling. Its chief weakness is progressive disclosure: the SKILL.md promises a multi-file bundle but most referenced files are missing from the directory, breaking navigation.

Suggestions

Add the referenced bundle files (commands/review.md, skills/review.md, guidelines.md, README.md, prompts/analyze-skill.md) or remove their references so every cited path resolves.

Consolidate the two separate numbered lists (Quick Start vs. the 1-6 process) into one coherent sequence, or label them distinctly as 'Routing' and 'Review process' to avoid ambiguity.

Tighten the inline report template to the essential fields, moving the full schema into guidelines.md once that file exists.

Dimension	Reasoning	Score
Conciseness	The body is efficient and assumes Claude's competence, avoiding explanations of concepts Claude already knows; minor instances (the full report template and some framing prose) could be trimmed.	4 / 5
Actionability	Gives an executable command ("python3 {skill-reviewer-dir}/scripts/pre-review-checks.py {target-dir}"), concrete file-read targets, and a copy-ready output template with a findings table, though heavy delegation to files not present in the bundle leaves minor gaps.	4 / 5
Workflow Clarity	A clear numbered 1-6 sequence includes an explicit validation step (step 5: verify each finding cites a specific file and drop unsubstantiated ones) and an error-stop checkpoint, but the two separate numbered lists (Quick Start 1-2 then process 1-6) and reliance on missing referenced files create minor gaps.	4 / 5
Progressive Disclosure	References are clearly signaled and one level deep with a documented File Layout, but scored against the actual bundle only scripts/pre-review-checks.py exists while commands/review.md, skills/review.md, guidelines.md, README.md, and prompts/analyze-skill.md are all absent, so most referenced paths do not resolve — a non-minor organization gap.	3 / 5
	Total	15 / 20 Passed

Description

83%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 is strong: it states a clear purpose, names concrete file targets and evaluation dimensions, and gives explicit when-to-use guidance with a command trigger. The main gaps are generic verbs and a few missing trigger synonyms.

Dimension	Reasoning	Score
Specificity	Enumerates concrete evaluation targets ("structure, clarity, completeness, and consistency of SKILL.md, skills/.md, commands/.md, and guidelines.md") rather than vague language, though the verbs ("Critically evaluates") stay generic, leaving minor coverage gaps.	4 / 5
Completeness	Explicitly answers both what ("Deep review of an AI skill directory ... Critically evaluates ...") and when ("Use when reviewing, auditing, or validating ... Activated by commands: /review") with concrete trigger phrases.	5 / 5
Trigger Term Quality	Provides natural terms a user would say ("reviewing, auditing, or validating an AI workflow skill" plus the "/review" command), but omits common synonyms like check, lint, or inspect.	4 / 5
Distinctiveness Conflict Risk	The "AI skill directory" / "AI workflow skill" niche plus the dedicated "/review" command make it mostly distinct with minimal conflict risk, though it could overlap with general code-review or audit skills.	4 / 5
	Total	17 / 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: amir-yogev-gh/ai-workflows
Path: skill-reviewer/SKILL.md
Commit: 2bd6607

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