Better Skill Review

Skill Review

Language

Match user's language: Respond in the same language the user uses.

Overview

Review an agent skill through three layers: automated linting (hard rules), contextual finding evaluation (agent judges with context), and structured semantic review (deep analysis against best practices). Optionally fix issues and verify fixes through independent subagent validation.

Workflow

Progress:

• [ ] Step 1: Identify the skill
• [ ] Step 2: Review (linting + profile + findings + semantic)
• [ ] Step 3: Present findings
• [ ] Step 4: Fix gate
• [ ] Step 5: Verify & iterate

Step 1: Identify the Skill

Accept the skill location as a directory path containing SKILL.md. Auto-detect if the current working directory contains one.

Step 2: Review

Run both tools, then evaluate.

2a. Automated linting:

python3 {SKILL_DIR}/scripts/validate.py run --path 

Output: checks (hard-rule verdicts → linter grade) + findings (soft detections needing judgment).

2b. Profile extraction:

bash {SKILL_DIR}/scripts/analyze.sh analyze 

Note skill level (l0/l0plus/l1) and feature flags.

2c. Contextual findings review:

Judge each finding using its context_hint. See references/semantic_dimensions.md § Finding Judgment Table for decision criteria. Promote real issues to warnings; dismiss the rest with a brief note.

2d. Semantic review:

Read the skill's SKILL.md fully, then score each dimension (0-3). Read references/semantic_dimensions.md for the full checklist per dimension:

| Dimension | What it evaluates | |-----------|------------------| | 5.1 Description Quality | Trigger phrases, length, voice, specificity | | 5.2 Workflow Design | Steps, decision points, SKILL.md length | | 5.3 Runtime Robustness | Preflight, degradation, troubleshooting (L0+/L1 only) | | 5.4 Script Quality | JSON output, error handling, exit codes (scripts only) | | 5.5 UX Practices | Language, checklist, completion report (applicability matrix) | | 5.6 Setup Flow Integrity | Bootstrap safety, live validation, credential security |

Step 3: Present Findings

Format the report:

[Skill Review] 

═══ Linter ═══
Grade:  (/ passed,  warnings,  failures)

Failures:
  ✗ :  → Fix: 

Warnings:
  ⚠ : 

Findings (agent-reviewed):
  ✓ : dismissed — 
  ⚠ : promoted to warning — 

═══ Semantic Review ═══
5.1 Description Quality:   /3  
5.2 Workflow Design:        /3  
5.3 Runtime Robustness:     /3  
5.4 Script Quality:         /3  
5.5 UX Practices:           /3  
5.6 Setup Flow Integrity:   /3  
                            ─────────
Semantic Score:             /18

═══ Improvement Suggestions ═══
For each dimension scoring )

Use the prompt template from references/semantic_dimensions.md § Verification Subagent Prompt Template. The verification subagent must:

1. Run validate.py and analyze.sh fresh (never trust cached results)
2. Read references/semantic_dimensions.md for scoring criteria
3. Score all 6 dimensions independently, citing file:line evidence
4. Return linter grade + per-dimension scores + specific FAIL items

5b. Process verification result:

• All pass → Report success, done
• Has failures → Fix ONLY the specific FAIL items from the verification report, then dispatch a NEW subagent to verify again
• Max 3 rounds — if issues persist after 3 fix-verify cycles, report remaining issues and let the user decide

Anti-patterns (never do these):

| Anti-pattern | Why it's wrong | Correct approach | |---|---|---| | Self-evaluate after fixing | Blind to own mistakes | Always dispatch subagent | | Reuse same subagent for re-verify | Already biased by prior assessment | New subagent each round | | Fix without running tools first | Subjective judgment misses issues | Tools produce objective data | | Ignore verification report | Discards independent evidence | Fix only reported FAIL items |

Linter Reference

Grading (hard-rule checks only):

• A — All pass, zero warnings
• B — All pass, some warnings
• C — 1–2 failures
• D — 3+ failures
• F — SKILL.md missing or no valid frontmatter

Check categories:

| Category | Checks | |----------|--------| | structure | SKILL.md exists, frontmatter, required fields, directory layout | | naming | Kebab-case, length, no consecutive hyphens, matches directory | | content | Description length, body length, heading structure | | paths | Referenced files exist, scripts executable | | security | No secrets, no template placeholders |

References

• references/semantic_dimensions.md — Full checklist for each review dimension + finding judgment table + verification prompt template
• references/validation_rules.md — Rationale for each linter check
• references/improvement_patterns.md — Knowledge base of improvement patterns with examples
• references/best_practices.md — Skill design conventions and quick reference

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: psylch
• Source: psylch/better-skills
• License: MIT

Install and usage instructions live in the source repository linked above.