# Skill Review

Critically review a workspace skill and suggest improvements.

- Repository: https://github.com/stencila/stencila (914 stars)
- Category: AI and agents
- License: Apache-2.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add stencila/stencila --skill skill-review -g -a claude-code -y`
Codex: `npx skills add stencila/stencila --skill skill-review -g -a codex -y`
Cursor: `npx skills add stencila/stencila --skill skill-review -g -a cursor -y`
Gemini CLI: `npx skills add stencila/stencila --skill skill-review -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add stencila/stencila`

## Description

Critically review a workspace skill and suggest improvements. Use when asked to review, audit, critique, evaluate, or improve a SKILL.md file or skill directory. Covers frontmatter validation, instruction clarity, completeness, and adherence to the Agent Skills Specification.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

## Overview

Review an existing workspace skill for quality, correctness, completeness, and self-containment. Produce a structured report with specific, actionable suggestions for improvement. The review covers frontmatter fields, instruction clarity, step structure, examples, edge cases, adherence to the Agent Skills Specification, and whether the skill avoids depending on files outside its own directory.

## Steps

1. Identify the skill to review from the user's request, accept a skill name, a directory path, or a `SKILL.md` file path
2. Resolve the skill file: if given a name, look for `.stencila/skills/<name>/SKILL.md` walking up from the current directory; if given a path, use it directly
3. Read the full `SKILL.md` file and any supporting files in the skill directory (`scripts/`, `references/`, `assets/`)
4. Check whether the skill refers to documentation, specifications, or other content outside the skill directory; if it does, assess whether that material should be copied, summarized, or excerpted into local `references/` files instead
5. Evaluate the skill against each criterion in the Review Checklist below
6. Produce a structured review report with a summary, per-criterion findings, and a prioritized list of suggestions
7. If the user asks you to apply the improvements, make the changes and validate the result with `stencila skills validate <skill-name>`

## Review Checklist

### Frontmatter

- **name**: present, matches directory name, valid kebab-case (`^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$`)
- **description**: present, under 1,024 characters, specific (not vague), includes keywords that help agents match the skill to user requests
- **Optional fields**: `license`, `compatibility`, `allowed-tools`, `metadata`, check for correctness if present (e.g., valid SPDX identifier, `compatibility` under 500 characters, `allowed-tools` is space-delimited)

### Tooling and `allowed-tools`

The rest: https://github.com/stencila/stencila/blob/HEAD/.stencila/skills/skill-review/SKILL.md