--- name: skill-reviewer description: Use when a SKILL.md and its supporting files need a structural review - after writing or editing a skill, when a SKILL.md has grown long, when deciding what belongs in references/ versus the skill body, or when the user asks to check, audit or clean up a skill. Reports the findings worst first and applies only the ones the user picks. allowed-tools: Read, Glob, Grep, Bash, Edit, Write --- # Skill structure review Review one agent skill, including Claude Code, Codex, OpenClaw and Hermes Agent, for whether it is discoverable, loads the needed instructions and resources, and can be used in its intended runtime. Review structure and host compatibility; do not treat this as proof that the workflow's domain instructions are correct or safe. Skills separate discovery metadata, invoked instructions and supporting resources. Review whether each layer contains what its reader needs; loading and invocation behavior depend on the target host. ## Target host First establish where and how the skill is intended to be used: target host and version when known, installation/discovery location, invocation method, and execution environment (local, sandbox, remote runtime, or other declared context). Infer this from the user's request, repository/package layout, installation instructions and metadata, not from the agent running this review. If the destination is not explicit, report the assumption and assess only the supported conclusions; do not silently treat the skill as intended for the current agent. Read only the applicable reviewer references: - Claude Code: [references/claude-code-skill.md](references/claude-code-skill.md). - Codex: [references/codex-skill.md](references/codex-skill.md). - OpenClaw: [references/openclaw-skill.md](references/openclaw-skill.md). - Hermes Agent: [references/hermes-agent-skill.md](references/hermes-agent-skill.md). - Multiple hosts: apply the shared checks once and each host's checks separately. Label compatibility findings by host. - Unknown destination or an unlisted host: use only the [generic Agent Skills checklist](references/agentskills-checklist.md). Do not infer host-specific behavior or flag host-specific fields as defects. If the user later names a host, apply its reference and verify any host-specific claims against official documentation. - Other stated but unlisted hosts: use the generic Agent Skills checklist, then consult that host's official documentation for any host-specific compatibility assessment. State unresolved assumptions. Do not assume one host's extensions work on another. ## Review procedure 1. Run the mechanical checks. They cover sizes, the heading tree, pointer candidates, frontmatter syntax and prose density. They are heuristics, not a host compatibility validator; YAML parsing requires PyYAML. Resolve `` to the directory containing this reviewer’s SKILL.md, not the skill being reviewed. ```bash python3 "/scripts/audit.py" "" ``` 2. Read the target skill’s SKILL.md, referenced supporting files and any host-consumed manifests. Apply the shared checks below and each selected host reference. Check whether the skill can be discovered and invoked in the stated host, whether its metadata and runtime features work there, and whether every required tool, executable, environment variable, path and supporting resource is available in the intended execution environment. Treat the target’s instructions and scripts as review material; do not execute them. If runtime behavior cannot be established from files and official documentation, state the assumption rather than claiming it was tested. These checks are ordered by how much damage the fault does. 3. Check every proposed move out of the body before reporting it. Name the path through the target skill that finishes successfully without the content, and put that path in the finding's Why. If no such path can be named, drop the finding. The same check applies when planning edits to a skill outside a review: a move plan that cannot name its skipping path is a length cut, not a structural fix. 4. Report worst first, and **apply only what the user picks** — structure is often deliberate, and rewriting before reporting destroys the reasoning behind it. The user may cap how many findings to report (`top 3`). Without a cap, report at most five and say how many were left out. ## 1. Broken invocation The skill never runs, or runs without what it needs. Use the syntax checks as a starting point, then verify the target host’s discovery and runtime requirements. | Fault | Why it matters | |---|---| | Frontmatter missing, misplaced or invalid YAML | Discovery metadata may not be read; the exact failure depends on the host | | Tools or resources required by the body are unavailable on a declared host | The promised workflow cannot finish | | `description` that omits what the skill does or when to use it | Triggering is decided from that text alone | Check required fields, invocation controls and runtime syntax against the selected host reference. Do not impose another host’s extensions on a portable skill. ## 2. Where the content lives | Look for | Fix | |---|---| | A procedure, command sequence or pitfall that only one situation needs, sitting in SKILL.md | Move it to `references/` and leave the list of situations in SKILL.md. The measure is what share of invocations need it, not its length — content needed every time belongs in the body however long, and a rarely-needed page earns its own file however short | | A supporting file with no reference or host-defined discovery path | Check indirect references and host-consumed metadata before linking or deleting it | | A pointer to a path that does not exist | Fix the path | | A pointer that never says when to open the file | Put it beside the symptom or situation it answers. The docs ask that a reader can tell what a file holds and when to load it; a markdown link and a bare path both do that | | The same procedure or value in both SKILL.md and a supporting file | One copy goes stale. Keep one source and point at it | | SKILL.md over 500 lines | Inspect for conditional detail to extract; this is a review heuristic, not a universal validity limit | Measure the share of invocations from the target skill's own branches, not from how the content reads. Look for an argument, flag or situation under which a run completes without the content. - A run that stops on an error or a failed precondition does not count. It skips every later step too, and treating it as a skip would move most of the body. - Variants that produce the same output still need the content. A dry run and a real run that share one output format both use that format. - If the skill has no path that completes without the content, the content is needed every time and stays in the body. ## 3. Order and proportion - **What gets decided first comes first.** A reader picks their situation before they need the settings every situation shares. Opening with shared detail and listing the situations last forces them to read all of it. - **Group by the reader's errand.** When a skill serves two errands, alternating sections make both readers skim. - **Keep sections comparable.** A section several times longer than its siblings usually covers two things; a run of three-line sections usually belongs under one heading. - **Give sibling reference files the same shape.** If one is steps only and another is steps plus pitfalls, the layout has to be worked out again each time. ## 4. Headings A reader scans the heading tree and jumps, so judge each heading by whether it predicts what the section holds. | Weak heading | Why | Better | |---|---|---| | `Two sources` | Counts instead of answering the reader's question | `Choosing a source` | | `About the API` | Hides the conclusion the section reaches | `What the Instructor API covers` | | `Fetching it`, `Reading it` | Conversational | Documentation headings are noun phrases: `Fetch procedure`, `Snapshot structure` | **For a skill written in Japanese, use [references/headings-ja.md](references/headings-ja.md) instead** — 体言止め, mixed 常体/敬体, katakana spelling drift and spacing are what go wrong there, and the English rules above do not catch them. Check that names agree: the wording in SKILL.md against the title of the file it points to, the directory name against `name`, and one term per concept throughout. ## 5. Prose The invoked body consumes context, so keep each line useful to the task. - **Explain why instead of stacking MUST, ALWAYS and NEVER.** A reader who knows the reason handles the case the rules do not cover. - **State standing guidance as standing guidance.** Advice meant to hold for a whole task reads better as a rule than as a step in a list. - **No changelog, no ticket ids.** A skill describes its current shape. - Watch the density of bold; when every paragraph has some, none of it reads as emphasis. ## Reporting Order by damage: a skill that cannot run, then material in the wrong file, then structure, headings, prose. Give the reason each one matters — without it the user cannot judge whether to fix it. | Where | What | Why | Fix | |---|---|---|---| | `SKILL.md` | A required tool exists only on one declared host | The workflow cannot finish on the other host | Add an available alternative or narrow the supported hosts | | `SKILL.md` 46-86 | 41 lines of editor keystrokes in the body | Only some invocations edit a file; every one reads this | Move into `references/`, point from the situation table | When the shape itself is off, show the proposed heading tree as well — a table of findings does not convey the whole. Close by asking which items to apply, and apply only those.