check-skills.sh

#!/usr/bin/env bash
# check-skills.sh — consistency gate for skills/.
# Read-only: asserts, never edits. Auto-enrols every directory under skills/, so a
# new skill is covered the moment it exists — nothing to register by hand.
#
# Checks, per skill:
#   1. SKILL.md exists, with a delimited YAML frontmatter block.
#   2. frontmatter `name` matches the directory name (this is what installers key on).
#   3. `description` is substantial — it is the only thing an agent sees when deciding
#      whether to load the skill.
#   4. `license` is present.
#   5. No `version:` — these skills version against nothing (see CTA-6a); a stale
#      number is worse than none.
set -uo pipefail

ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
SKILLS="$ROOT/skills"
MIN_DESC=120
PASS=0; FAILED=0
ok()  { printf '  ok  %s\n' "$*"; PASS=$((PASS+1)); }
bad() { printf 'FAIL  %s\n' "$*"; FAILED=$((FAILED+1)); }

field() { # field <file> <key> — first frontmatter value, empty if absent
  awk -v k="$2" '
    NR==1 && $0=="---" { inside=1; next }
    inside && $0=="---" { exit }
    inside && index($0, k ": ")==1 { print substr($0, length(k)+3); exit }
  ' "$1"
}

[[ -d "$SKILLS" ]] || { echo "FAIL  no skills/ directory at $SKILLS"; exit 1; }

shopt -s nullglob
for dir in "$SKILLS"/*/; do
  name="$(basename "$dir")"
  file="$dir/SKILL.md"
  echo "== $name =="

  if [[ ! -f "$file" ]]; then
    bad "$name: no SKILL.md"
    continue
  fi
  if [[ "$(head -n1 "$file")" != "---" ]]; then
    bad "$name: SKILL.md does not open with a --- frontmatter block"
    continue
  fi

  fm_name="$(field "$file" name)"
  [[ "$fm_name" == "$name" ]] \
    && ok "name matches directory" \
    || bad "$name: frontmatter name is '${fm_name:-<missing>}', want '$name'"

  desc="$(field "$file" description)"
  if (( ${#desc} >= MIN_DESC )); then
    ok "description is ${#desc} chars"
  else
    bad "$name: description is ${#desc} chars, want >= $MIN_DESC (it is the trigger surface)"
  fi

  [[ -n "$(field "$file" license)" ]] \
    && ok "license present" \
    || bad "$name: no license in frontmatter"

  grep -q '^version:' "$file" \
    && bad "$name: has a version: field — these skills pin to nothing, drop it" \
    || ok "no stale version pin"
done

echo
echo "== $PASS passed, $FAILED failed =="
(( FAILED == 0 ))