---

name: skill-evaluator description: > Evaluate a Claude skill's design quality against Anthropic's official skill-building guidance and Building Effective Agents principles. Produces a scored markdown report (7 dimensions, weighted rubric, severity-ranked issues, before/after improvement suggestions) saved as a file. Use when the user asks to evaluate, assess, audit, grade, rate, or review a skill, or wants a skill scorecard or quality report. Also trigger when the user says "how good is my skill", "skill assessment", or "skill report". Can be used alongside skill-creator to evaluate a skill mid-development. Do NOT use for general code review, plugin validation, or runtime testing of skill behavior. argument-hint: "<skill-path-or-name>" user-invocable: true

Skill Evaluator

Produce a comprehensive, formatted markdown assessment of a target skill, grounded in Anthropic's official skill-building guidance and effective-agents principles.

Instructions

Tone: Be constructive, not punitive — the goal is to help the skill author improve. Always find positive aspects even in weak skills. Ground every criticism in a specific principle from Anthropic's guidance. Do NOT inflate scores; a score of 3 means "functional but room to improve" and is perfectly acceptable. If the skill is already excellent, say so and suggest only minor refinements.

Step 1: Determine Target Platform and Locate the Skill

Platform gate: Infer the target platform from the skill's frontmatter rather than asking by default:

• If the user has already stated the platform in their message, use that.
• If frontmatter contains Claude Code-specific fields (allowed-tools, argument-hint, user-invocable, compatibility) → Claude Code.
• If frontmatter contains only name and description → Claude Desktop / claude.ai.
• If ambiguous (e.g., only name + description but the skill references CLI tools), ask the user.

State the inferred platform at the start of the report. If the user corrects you, re-evaluate with the corrected platform. Record the answer as the target platform — it affects frontmatter validation throughout the evaluation.

After determining the platform, proceed through Steps 2-6 autonomously. The remaining workflow creates a new markdown file (non-destructive) and does not require further user input.

Platform differences:

• Claude Code supports allowed-tools, user-invocable, argument-hint, and other extended frontmatter fields.
• Claude Desktop / claude.ai uses stricter YAML validation: only name and description are recognized. Fields like allowed-tools will cause import failures. Descriptions with unescaped quotes in unquoted YAML strings may also fail validation.
• Both — the skill must satisfy the stricter Desktop/Web rules while noting any Claude Code-specific features that would need to be added in a Code-only variant.

Locate the skill. The user may provide:

• A path to a SKILL.md file
• A skill name (search under ~/.claude/skills/, ~/.claude/plugins/, and the current working directory)
• A skill folder

Read the SKILL.md file and all top-level files in supporting directories (references/, scripts/, assets/, examples/). Only traverse subdirectories if SKILL.md explicitly references files within them.

If the skill cannot be found, report the paths searched and ask the user for the full path. If SKILL.md is missing from the folder, score Frontmatter Quality as 1/5, note it as a Critical issue, and evaluate any other files present. If frontmatter YAML is malformed (missing --- delimiters, invalid syntax), score Frontmatter Quality as 1/5 and include the parse error in the report. If SKILL.md has no body content beyond frontmatter, produce the full report — empty sections will naturally reflect the gaps.

Step 2: Gather Metrics

Run the bundled collector first — do not count by hand. Resolve the script path relative to the directory containing this SKILL.md (not the current working directory, which is the user's cwd), then execute it with the target skill directory as the argument: python3 <this-skill-dir>/scripts/gather_metrics.py <target-skill-dir>. It emits a single JSON object with the body word count, the rendered description character count (computed after YAML block-scalar folding, so no manual folding is required), supporting-directory inventories with per-directory text word counts, frontmatter field presence, and kebab-case/reserved-word/XML checks. Use these values verbatim throughout the report. The script's preflight object also satisfies the verification gate below.

The collector handles the mechanical counts only. You must still apply judgment for the semantic checks the script cannot make: whether the description contains both WHAT and WHEN, how many distinct trigger phrases it has, and (Desktop/Web target) whether the description is properly quoted and whether any unsupported frontmatter fields are present. The script reports fields_present and description_has_xml_brackets to inform those judgments but does not make them for you.

Expected output: a JSON object whose errors array is empty for a healthy skill. If the script reports errors (e.g., "CRITICAL: missing closing '---' frontmatter delimiter"), carry those into Step 4 at the indicated severity.

Only if the script is unavailable or exits non-zero, fall back to counting the data points below by hand and note the fallback as a Minor issue. If any metric still cannot be obtained (file unreadable, binary content, empty directory), record "N/A" for that metric and note it as a Minor issue in Step 4.

Structural metrics:

• SKILL.md word count (body only — count words after the closing --- frontmatter delimiter)
• Number of supporting directories present (references/, scripts/, assets/, examples/)
• Number of files in each supporting directory (skip hidden files like .DS_Store)
• Total reference material word count (sum word counts of all text files in references/; skip binary files)

Frontmatter metrics:

• All fields present — which fields to check depends on the target platform:
  • Claude Code: name, description, and optionally allowed-tools, license, metadata, compatibility, user-invocable, argument-hint
  • Claude Desktop / claude.ai: name and description only. Flag any other fields (e.g., allowed-tools) as a Major issue — they will cause YAML validation failures on import.
  • Both: only name and description should be in frontmatter (Desktop constraint). Note Claude Code-specific fields that could be added for a Code-only variant.
• Description character count (count the rendered single-line string after YAML block scalar folding, excluding trailing whitespace)
• Whether name uses kebab-case
• Whether description contains both WHAT and WHEN components
• Whether description contains XML angle brackets (forbidden)
• Whether name contains "claude" or "anthropic" (forbidden)
• Desktop/Web only: Whether description is properly quoted (double-quoted with escaped inner quotes, or using YAML block scalar >) — unquoted strings with embedded quotes may fail strict YAML parsers

Verification gate: Before proceeding, confirm: SKILL.md word count > 0, description character count > 0, and at least the name field is present. If any check fails, do not abandon the evaluation — proceed with the following adjustments:

• If SKILL.md body is empty (word count = 0), score Instruction Clarity as 1/5.
• If description character count is 0, score Frontmatter Quality as 1/5.
• If name field is missing, score Frontmatter Quality as 1/5 and note as a Critical issue.

Step 3: Evaluate Against Rubric

Self-dependency check: Before scoring, verify that references/evaluation-rubric.md and references/output-template.md (relative to the directory containing this SKILL.md file, not the target skill's directory) are readable. If either file is missing or unreadable:

• Use the dimension names, weights, and verdict thresholds listed below as a fallback rubric.
• Use the section structure from the Examples section of this file as a fallback output template.
• Note in the report header: "Generated with embedded fallback rubric (reference files unavailable)."

Read references/evaluation-rubric.md (relative to this SKILL.md's directory) for detailed scoring criteria. Score each dimension on a 1-5 scale using its criteria.

The seven evaluation dimensions are:

1. Frontmatter Quality -- name format, description effectiveness, trigger coverage
2. Instruction Clarity & ACI Design -- specificity, actionability, imperative form, tool format design, poka-yoke, self-documenting parameters
3. Progressive Disclosure -- appropriate use of the three-level system
4. Composability -- works alongside other skills, no assumption of exclusivity
5. Error Handling & Verification -- troubleshooting guidance, edge cases, failure modes, ground-truth verification checkpoints, stopping conditions for iterative behavior
6. Examples & Documentation -- concrete scenarios, before/after, expected outputs
7. Agentic Design Alignment -- simplicity, transparency, workflow pattern fitness, complexity justification, human-in-the-loop checkpoints

Step 4: Identify Issues

Review the scores from Step 3. For any dimension scored 3 or below, identify the specific gaps that caused the deduction. Also note any Minor issues observed in higher-scoring dimensions. Categorize each finding by severity:

• Critical -- Prevents the skill from functioning (missing SKILL.md, broken frontmatter, no description)
• Major -- Significantly reduces effectiveness (vague description, no trigger phrases, excessive SKILL.md length, missing error handling)
• Minor -- Opportunities for polish (missing metadata, no examples, style inconsistencies)

Format each issue with a file location, description, and fix suggestion, following the Issues section structure in references/output-template.md.

Step 5: Generate Improvement Suggestions

For up to 3 issues, prioritized by severity (Critical > Major > Minor), provide:

• The specific problem
• Why it matters (citing the relevant principle)
• A concrete fix with before/after examples

If fewer than 3 issues exist, cover all of them.

Step 6: Write the Assessment File

Write the assessment to a markdown file. Save to the current working directory as skill-evaluation-{skill-name}.md. If a file with that name already exists, append a date suffix: skill-evaluation-{skill-name}-{YYYYMMDD}.md.

Read references/output-template.md (relative to this SKILL.md's directory) for the exact assessment file structure. Follow it precisely. (If the template was unavailable and you're using the embedded fallback from Step 3, use the structure shown in the examples below.)

For complete examples of finished evaluation reports across different verdict levels, see the examples/ directory (relative to this SKILL.md's directory):

| Example | Verdict | File | |---------|---------|------| | Strong skill | EXCELLENT | examples/sample-evaluation-excellent.md | | Average skill | NEEDS IMPROVEMENT | examples/sample-evaluation.md | | Weak skill | NEEDS MAJOR REVISION | examples/sample-evaluation-weak.md |

Verification gate: After writing, read back the first 20 lines of the output file to confirm it was written correctly. Verify that the Overall Score line is present and that the weighted score sum matches the verdict threshold (EXCELLENT: 4.5–5.0, GOOD: 3.5–4.4, NEEDS IMPROVEMENT: 2.5–3.4, NEEDS MAJOR REVISION: below 2.5). If the Overall Score line is missing, the weighted sum is incorrect, or the verdict doesn't match the threshold, recompute and rewrite the scorecard section once. If it still mismatches after that single rewrite, emit the report with an explicit "⚠ score-arithmetic discrepancy" note rather than rewriting again — do not loop.

Troubleshooting

See references/troubleshooting.md for common edge cases and how to handle them.

Examples

Evaluate by name

User: "evaluate the frontend-design skill" Actions: Search ~/.claude/skills/ and ~/.claude/plugins/ for frontend-design/SKILL.md → Read top-level files → Gather metrics → Score against rubric → Write skill-evaluation-frontend-design.md Result: Assessment file saved to current directory. Example excerpt:

## Overall Score: 3.65/5

| Dimension                        | Score | Weight | Weighted |
|----------------------------------|-------|--------|----------|
| Frontmatter Quality              | 4/5   | 25%    | 1.00     |
| Instruction Clarity & ACI Design | 3/5   | 20%    | 0.60     |
| Progressive Disclosure           | 4/5   | 15%    | 0.60     |
| ...                              |       |        |          |

**Verdict:** GOOD

Evaluate by path

User: "grade my skill at ./my-plugin/skills/data-viz/" Actions: Read ./my-plugin/skills/data-viz/SKILL.md and supporting files → Full evaluation workflow → Write skill-evaluation-data-viz.md Result: Assessment file with all 7 dimensions scored, issues categorized by severity, and top 3 improvement suggestions with before/after examples.

Evaluate a broken skill

User: "evaluate the skill at ./experiments/half-baked/" Actions: Search for SKILL.md → Found but frontmatter missing --- delimiters → Score Frontmatter Quality as 1/5, note Critical issue → Evaluate remaining content → Write skill-evaluation-half-baked.md Result: Assessment file with Critical issue flagged. Example excerpt:

## Overall Score: 1.95/5

### Critical (1)
1. **SKILL.md, line 1** — Frontmatter missing `---` delimiters. Claude cannot parse
   the name or description, so the skill will never be loaded.
   **Fix:** Add `---` before and after the YAML block.

**Verdict:** NEEDS MAJOR REVISION

Evaluate with platform auto-detection

User: "evaluate this skill" (provides a skill with argument-hint and allowed-tools in frontmatter) Actions: Read SKILL.md → Detect argument-hint and allowed-tools fields → Infer Claude Code platform → Full evaluation workflow using Claude Code frontmatter rules → Write skill-evaluation-{name}.md Result: Assessment file with inferred platform noted in header:

> Target platform: Claude Code (inferred — frontmatter contains argument-hint, allowed-tools)

If the user corrects the platform ("actually this targets Desktop too"), re-evaluate with the Both platform rules — apply the stricter Desktop/Web constraints and note Code-specific fields as recommendations for a Code-only variant.

Execution Priorities

• The suggested improved description is the single highest-value output — invest effort here.
• Provide concrete before/after examples for the top 3 suggestions.
• When scoring, differentiate between "works but could improve" (3) and "significantly reduces effectiveness" (2). Most functional skills land at 3–4; reserve 5 for genuinely exemplary work.

Scope Boundaries

This skill evaluates skill design — frontmatter, instructions, progressive disclosure, composability, error handling, examples, and agentic alignment. It works alongside skill-creator for iterative skill development — run skill-evaluator at any point during the create/iterate loop to get a quality checkpoint. It does NOT:

• Execute or test scripts bundled with the target skill
• Evaluate the runtime behavior or output quality of the target skill
• Assess asset files (images, templates) beyond noting their presence