skill-audit

skill-audit

Diagnose one skill. Report what is wrong, at what severity, with the edit that fixes it.

Overview

Measurement first, judgment second. Numbers settle the mechanical axes for free, which keeps the expensive reading focused on the axes a script cannot reach: whether the description encodes real trigger conditions, whether steps distinguish done from not-done, whether the body still describes where it used to live.

The rules being applied belong to docs:skill-forge and live in its bundled references. Read them there rather than restating them; this skill is the diagnostic pass over one target.

When to use

Audit one named skill: after writing it, after moving it between plugins, when it does not trigger, when it loads on one runtime and not another, or when its body outgrew its job.

Do not use it to write or rewrite a skill (docs:skill-forge), or to sweep the whole repository (docs:skill-fleet-review).

Procedure

1. Measure

Resolve the plugin root, then measure the tree that contains the target. Pass that tree explicitly: with no argument the script defaults to plugins/ when it exists, so auditing a skill under .claude/skills/ in a repository that also has plugins/ silently measures a different tree and the target never appears in the output.

Set TARGET_ROOT to the directory holding the target and its siblings: plugins/<plugin>/skills, .claude/skills, or whatever contains it. Siblings matter: the pointer axis is judged against them.

# Honor a caller-supplied PLUGIN_ROOT first — the abort message below tells the user to
# export it, and starting from CLAUDE_PLUGIN_ROOT would overwrite that escape hatch.
PLUGIN_ROOT="${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
[ -z "$PLUGIN_ROOT" ] && [ -d plugins/docs/skills ] && PLUGIN_ROOT=plugins/docs
if [ -z "$PLUGIN_ROOT" ]; then
  # Rank Codex cache candidates on the version basename, not the whole path: a plain
  # sort puts 0.9.0 above 0.10.0 and lets the marketplace directory outrank the version.
  cache_root="${CODEX_PLUGIN_CACHE:-$HOME/.codex/plugins/cache}"
  if sort -V </dev/null >/dev/null 2>&1; then vsort="sort -V"; else vsort="sort -t. -k1,1n -k2,2n -k3,3n"; fi
  PLUGIN_ROOT=$(ls -1d "$cache_root"/*/docs/* 2>/dev/null | awk -F/ '{print $NF "\t" $0}' | $vsort | tail -1 | cut -f2-)
fi
[ -d "$PLUGIN_ROOT/skills" ] || { echo "docs plugin root not found; export PLUGIN_ROOT" >&2; exit 1; }
TARGET_ROOT="${TARGET_ROOT:?set TARGET_ROOT to the directory containing the target skill}"
TARGET_SKILL="${TARGET_SKILL:?set TARGET_SKILL to the skill directory name being audited}"
out=$(node "$PLUGIN_ROOT/skills/skill-forge/scripts/measure-skills.mjs" "$TARGET_ROOT"); rc=$?
printf '%s\n' "$out"
[ "$rc" -eq 0 ] || { echo "measure-skills exited $rc — part of $TARGET_ROOT was unreadable, so this audit's scope is incomplete" >&2; exit 1; }
# Fail closed: a target that is not in the measurement means TARGET_ROOT points elsewhere.
# Continuing would judge the seven axes against rows belonging to other skills.
printf '%s\n' "$out" | grep -qE "(^|[[:space:]])${TARGET_SKILL}([[:space:]]|$)" \
  || { echo "no row for '$TARGET_SKILL' under $TARGET_ROOT — the root is wrong, not the skill" >&2; exit 1; }