Skill Review

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