Skill Quality ReviewerSAFE

Semi-automated research assistant for academic research and software development. Supports Claude Code, Codex CLI, Kimi Code CLI, and OpenCode across ideation, coding, experiments, writing, and publication.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: skill-quality-reviewer
description: This skill should be used when the user asks to "analyze skill quality", "evaluate this skill", "review skill quality", "check my skill", or "generate quality report". Evaluates local skills across description quality, content organization, writing style, and structural integrity.
version: 0.1.0
---

# Skill Quality Reviewer

## Overview

A meta-skill for evaluating the quality of Claude Skills. Perform comprehensive analysis across four key dimensions—description quality (25%), content organization (30%), writing style (20%), and structural integrity (25%)—to generate weighted scores, letter grades, and actionable improvement plans.

Use this skill to validate skills before sharing, identify improvement opportunities, or ensure compliance with skill development best practices.

## When to Use This Skill

**Invoke this skill when:**
- Analyzing a skill's quality before distribution
- Reviewing skill documentation for best practices
- Evaluating adherence to skill development standards
- Generating improvement recommendations for existing skills
- Validating skill structure and completeness

**Trigger phrases:**
- "Analyze skill quality for ./my-skill"
- "Evaluate this skill: ~/.claude/skills/api-helper"
- "Review skill quality of git-workflow"
- "Check my skill for best practices"
- "Generate quality report for this skill"

## Review Modes

Use one of three review modes depending on the task:

1. **score-only**
   - fast first-pass grading for one skill.
2. **remediation-backlog**
   - convert findings into P0 / P1 / P2 fix queues with concrete evidence.
3. **batch-portfolio**
   - review multiple skills together, cluster repeated issues, and produce a prioritized shortlist.

Prefer `remediation-backlog` when the user asks what to fix next.
Prefer `batch-portfolio` when auditing many skills at once.

## Analysis Workflow

### Step 1: Load the Skill

Accept skill path as input. Verify the path exists and contains `SKILL.md`. Read the complete skill directory structure.

```bash
# Example invocation
ls -la ~/.claude/skills/target-skill/
```

**Validate:**
- SKILL.md exists
- Directory is readable
- Path points to a valid skill

### Step 2: Parse YAML Frontmatter

Extract and validate the YAML frontmatter from SKILL.md.

**Required fields:**
- `name` - Skill identifier
- `description` - Trigger description with phrases

**Check for:**
- Valid YAML syntax
- No prohibited fields
- Proper formatting

### Step 3: Evaluate Description Quality (25%)

Assess the quality and effectiveness of the frontmatter description.

**Scoring breakdown:**

| Criterion | Points | Evaluation |
|-----------|--------|------------|
| Trigger phrases clarity | 25 | 3-5 specific user phrases present |
| Third-person format | 25 | Uses "This skill should be used when..." |
| Description length | 25 | 100-300 characters optimal |
| Specific scenarios | 25 | Concrete use cases, not vague |

**Red flags:**
- Vague triggers like "helps with tasks"
- Second-person descriptions ("Use this when you...")
- Missing or generic descriptions
- No actionable trigger phrases

**Reference:** `references/examples-good.md` for exemplary descriptions

### Step 4: Evaluate Content Organization (30%)

Assess adherence to progressive disclosure principles.

**Scoring breakdown:**

| Criterion | Points | Evaluation |
|-----------|--------|------------|
| Progressive disclosure | 30 | SKILL.md lean, details in references/ |
| SKILL.md length | 25 | Under 5,000 words (1,500-2,000 ideal) |
| References/ usage | 25 | Detailed content properly moved |
| Logical organization | 20 | Clear sections, good flow |

**Check:**
- SKILL.md body is concise and focused
- Detailed content moved to `references/`
- Examples and templates in appropriate directories
- No information duplication across files

**Reference:** `references/scoring-criteria.md` for detailed rubrics

### Step 5: Evaluate Writing Style (20%)

Verify adherence to skill writing conventions.

**Scoring breakdown:**

| Criterion | Points | Evaluation |
|-----------|--------|------------|
| Imperative form | 40 | Verb-first instructions throughout |
| No second person in body | 30 | Avoids conversational second person in the main workflow body |
| Objective language | 30 | Factual, instructional tone |

**Check for:**
- Imperative verbs: "Create the file", "Validate input", "Check structure"
- Absence of: "You should", "You can", "You need to"
- Objective, instructional language
- Consistent style throughout

**Good examples:**
```
Create the skill directory structure.
Validate the YAML frontmatter.
Check for required fields.
```

**Bad examples:**
```
You should create the directory.
You need to validate the frontmatter.
Check if the fields are there.
```

### Step 6: Evaluate Structural Integrity (25%)

Verify the skill's physical structure and completeness.

**Scoring breakdown:**

| Criterion | Points | Evaluation |
|-----------|--------|------------|
| YAML frontmatter | 30 | All required fields present |
| Directory structure | 30 | Proper organization |
| Resource references | 40 | All referenced files exist |

**Validate:**
- YAML frontmatter contains `name` and `description`
- Directory structure follows conventions:
  ```
  skill-name/
  ├── SKILL.md
  ├── references/ (optional)
  ├── examples/ (optional)
  └── scripts/ (optional)
  ```
- All files referenced in SKILL.md actually exist
- Examples are complete and working
- Scripts are executable

### Step 7: Calculate Weighted Score

Compute the overall quality score using weighted dimensions.

**Formula:**
```
Overall Score = (Description × 0.25) + (Organization × 0.30) +
                (Style × 0.20) + (Structure × 0.25)
```

**Letter grade mapping:**

| Score Range | Grade | Meaning |
|-------------|-------|---------|
| 97-100 | A+ | Exemplary |
| 93-96 | A | Excellent |
| 90-92 | A- | Very Good |
| 87-89 | B+ | Good |
| 83-86 | B | Above Average |
| 80-82 | B- | Solid |
| 77-79 |

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.