mindbox-cloud/agent-skills / plugins/skill-review/skills/skill-review
skill-review
VerifiedQuick and accessible AI reviewer for Agent Skills — for non-specialists. Checks structure, workflow, references, and links. Produces a clear report without technical jargon. Summary from Exhausted Vitaly. Use when user says "quick review", "basic skill check", "review my skill", "review for product owner", "light review", "quick check", "check my skill", "evaluate skill quality", "what's wrong with my skill", "review this skill". Don't use when: user asks for a deep/nightmare review (use skill-review-nightmare), user asks to create a new skill, to review code, user asks to review a prompt that is not a skill.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 22.0 KB |
| references/antipattern-bingo.md | markdown | 6.7 KB |
| references/checklist-lifecycle.md | markdown | 2.6 KB |
| references/checklist-links.md | markdown | 2.6 KB |
| references/checklist-references.md | markdown | 6.2 KB |
| references/checklist-structure.md | markdown | 5.8 KB |
| references/checklist-workflow.md | markdown | 14.1 KB |
| references/instruction-singlepass.md | markdown | 35.5 KB |
| references/maturity-diagnostic.md | markdown | 1.7 KB |
| references/report-template.md | markdown | 6.1 KB |
| references/subagent-base-rules.md | markdown | 2.4 KB |
references/checklist-structure.md
View on GitHub# Checklist: Structure
> Sub-agent Structure. Checks folder structure, frontmatter, file size, basic form antipatterns, and whether the skill is justified as an artifact.
>
> Result of each check: `PASS` / `FAIL` / `WARNING` / `N/A`.
---
## ST01–ST04. Structure and Validity
> **Stage: 2** | Axis: personal use
**ST01** Is the folder named in `kebab-case`? (only lowercase a–z, digits 0–9, and hyphens; no spaces, underscores, or CamelCase)
*Context:* The Agent Skills Specification requires kebab-case for the folder name. Other formats (`Notion Project Setup`, `notion_setup`, `NotionSetup`) are not picked up by many clients or cause validation errors.
**ST02** Is the file named **exactly** `SKILL.md`? (not `skill.md`, not `SKILL.MD`, not `Skill.md`)
*Context:* The name is case-sensitive. Agents scan directories for exactly `SKILL.md` — other variants will not be discovered.
**ST03** No `README.md` inside the skill folder?
*Context:* This is a structural folder-hygiene check for an isolated skill: there should be no extra human-facing markdown inside the folder that creates noise during discovery or overrides the role of `SKILL.md`. See also `LC05`: that check covers the repository-level boundary — that a README as a human artifact lives at the repository level, not inside the skill folder.
**ST04** If `references/`, `scripts/`, `assets/` exist — are they used correctly? (references = documentation, scripts = executable code, assets = templates and resources)
*Context:* Correct distribution across directories is the foundation of progressive disclosure. The agent loads files from these directories only when needed, saving up to 85–95% of tokens compared to flat loading.
---
## ST05–ST08. YAML Frontmatter
> **Stage: 2** | Axis: personal use
**ST05** Is there a `name` field in kebab-case that matches the folder name?
*Context:* The specification requires: name = 1–64 characters, lowercase alphanumeric + hyphens, matches the parent directory. A mismatch causes validation errors.
**ST06** Is there a `description` field that follows the formula: **WHAT it does** + **WHEN to use** (trigger phrases)?
*Context:* The description is the most critical part of a skill. The router uses it to decide whether to activate the skill. A vague description (`Helps with projects`) means the skill never fires or fires incorrectly.
**ST07** Does the description contain **concrete trigger phrases**, not abstractions?
*Context:* Good: `Use when user says "plan sprint", "create tasks", "set up project"`. Bad: `Creates sophisticated multi-page documentation systems`. Concrete phrases allow the router to accurately match user requests to the description.
**ST08** No XML tags (`<`, `>`) anywhere in the YAML?
*Context:* XML tags in YAML frontmatter create a prompt injection risk. The specification explicitly prohibits their use.
---
## ST09. `SKILL.md` Size
> **Stage: 2** | Axis: personal use
**ST09** Is `SKILL.md` **< 5000 words / 500 lines**?
*Context:* The specification recommends keeping `SKILL.md` under 500 lines and 5000 tokens. If exceeded — immediate decomposition: details to `references/`, scripts to `scripts/`. A bloated `SKILL.md` causes context overload and quality degradation.
---
## ST10–ST13. Basic Antipatterns
> **Stage: 2** | Axis: personal use
**ST10 Skill-prompt.** Is the skill simply a long prompt without a clear (1) role, (2) constraints, and (3) output format?
*Context:* Skill = role + constraints + output format. Without these three components — it is just a prompt with a name. Early skill users copied long prompts into `SKILL.md` and got `maybe slightly better than before`.
**ST11 Self-generated / unvalidated skill.** Does the artifact appear to have been generated by a single command like "write me a skill" with no traces of human verification, curation, or domain adaptation?
*Context:* Self-generated skills provide ~0 pp improvement per SkillsBench data. The problem is not the writing style — it is the absence of verified human expertise: the model paraphrases what it already "knows".
**ST12 Vibe-coded knowledge core.** Is the methodology written "from model memory" (generic phrases, abstract best practices) rather than describing a concrete, verifiable procedure?
*Context:* Knowledge in a skill should be a procedure for obtaining and verifying data, not an "encyclopedia from model memory". Even an expertly written skill degrades if the knowledge core remains vague and unverifiable.
**ST13 Monolith.** Is everything dumped into a single `SKILL.md`: workflow, references, examples, API schemas, long tables?
*Context:* Everything that is not the core workflow should live in `references/` or `scripts/`. Otherwise — context overload: the agent drowns in details and loses focus on the main process.
---
## ST14–ST16. Skill Justification as an Artifact
> **Stage: 2** | Axis: personal use
**ST14** Is this one coherent workflow, not a set of unrelated commands?
*Context:* One skill = one coherent action. If `SKILL.md` describes 3 independent operations — those are 3 skills, not 1. Atomicity simplifies triggering, testing, and composability.
**ST15** Is the instruction **> 300 tokens**? (If less — it is a line in a system prompt, not a skill.)
*Context:* Very short instructions (< 300 tokens) that are needed in every conversation are better placed in `CLAUDE.md` or a system prompt — the overhead of creating a skill will not pay off.
**ST16** Does the artifact appear to be justified as a skill? (3+ steps, a domain procedure, a repeatable workflow, or non-trivial decision points.)
*Context:* Not every artifact should become a skill. If there is no multi-step process, domain methodology, or repeatable routine inside, this may be overengineering. An extra skill increases routing overhead and context noise with no real benefit.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |