# Better Skill Review

> Review an agent skill by combining automated linting with structured semantic analysis. Runs hard-rule validation, evaluates contextual findings, then performs deep review against best practices (description quality, workflow design, runtime robustness, script conventions, UX patterns). Produces actionable improvement suggestions with before/after examples. This skill should be used when reviewin…

- **Type:** Skill
- **Install:** `agentstack add skill-psylch-better-skills-better-skill-review`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [psylch](https://agentstack.voostack.com/s/psylch)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [psylch](https://github.com/psylch)
- **Source:** https://github.com/psylch/better-skills/tree/main/skills/better-skill-review

## Install

```sh
agentstack add skill-psylch-better-skills-better-skill-review
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:**

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

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

**2b. Profile extraction:**

```bash
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](https://github.com/psylch)
- **Source:** [psylch/better-skills](https://github.com/psylch/better-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-psylch-better-skills-better-skill-review
- Seller: https://agentstack.voostack.com/s/psylch
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.