Rework skill validator script

.github/workflows/validate-skills.yml

@@ -2,17 +2,12 @@ name: Validate Skills
 
 on:
   pull_request:
-    paths:
-      - "skills/**"
 
 jobs:
   validate:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
-        with:
-          # Full history is needed so git diff can compare against the base branch
-          fetch-depth: 0
 
       - name: Set up Go
         uses: actions/setup-go@v6
@@ -23,5 +18,5 @@ jobs:
       - name: Install skill-validator
         run: go install github.com/agent-ecosystem/skill-validator/cmd/skill-validator@latest
 
-      - name: Validate changed skills
-        run: bash .github/scripts/validate-skills.sh "${{ github.base_ref }}"
+      - name: Validate all skills
+        run: bash tools/validate-skills.sh

CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# Contributing
+
+## Adding a new skill
+
+To add a new skill, create a new directory in the `skills` directory with the name of the skill. The directory should contain a `SKILL.md` file with the skill's metadata and instructions. You may find the [`skill-creator`](https://github.com/anthropics/skills/tree/main/skills/skill-creator) skill by Anthropic helpful for creating the initial draft. To install in Claude Code, add the `skill-creator` plugin.
+
+## Testing new skills
+
+### Structural testing
+
+Use the `tools/validate-skills.sh` script to test the structural validity of the skill. This script uses the [`skill-validator`](https://github.com/agent-ecosystem/skill-validator) tool to check the skill's metadata and instructions.
+
+### LLM testing
+
+Use the `tools/review-skill` skill to have an agent review the skill and interpret the results. On top of the structural validation offered by the `validate-skills.sh` script, it can also perform LLM scoring and provide a summary of the results.
+
+Exact installation instructions depend on the client, but should be something similar to:
+
+```bash
+mkdir -p ~/.claude/skills && ln -s <path-to-agent-skills>/tools/review-skill ~/.claude/skills/review-skill
+```
+
+This creates a symlink to the `review-skill` tool in the `~/.claude/skills` directory so that it can be used in Claude Code.

tools/validate-skills.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+# Validates all skill directories.
+#
+# Exit codes:
+#   0  All validated skills passed.
+#   1  One or more skills failed validation.
+
+# -e is intentionally omitted: all error paths are handled explicitly,
+# so abort-on-error would conflict with the || FAILED=1 accumulator pattern.
+set -uo pipefail
+
+# Find repository root (script is at tools/validate-skills.sh)
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+
+# Check if skill-validator is available
+if ! command -v skill-validator &> /dev/null; then
+  echo "❌ skill-validator is not installed."
+  echo ""
+  echo "To install it, run:"
+  echo "  brew tap agent-ecosystem/tap"
+  echo "  brew install skill-validator"
+  echo "--- or ---"
+  echo "  go install github.com/agent-ecosystem/skill-validator/cmd/skill-validator@latest"
+  echo ""
+  exit 1
+fi
+
+FAILED=0
+
+# Find and validate all skill directories
+for skill_dir in "$REPO_ROOT"/skills/*/; do
+  # Check if the glob matched anything
+  [ -d "$skill_dir" ] || continue
+
+  if [ -n "${GITHUB_ACTIONS:-}" ]; then
+    # In CI: use markdown output with annotations, filter annotations from summary
+    skill-validator check --strict --emit-annotations -o markdown "$skill_dir" \
+      | tee >(grep -v '^::' >> "$GITHUB_STEP_SUMMARY") || FAILED=1
+  else
+    # Local: simple output
+    skill-validator check --strict "$skill_dir" || FAILED=1
+  fi
+done
+
+echo ""
+if [ $FAILED -ne 0 ]; then
+  echo "❌ Skill validation failed!"
+  if [ -n "${GITHUB_ACTIONS:-}" ]; then
+    echo ""
+    echo "📋 See the Job Summary for detailed validation results:"
+    echo "   https://github.com/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
+  fi
+else
+  echo "✅ Skill validation passed!"
+fi
+
+echo ""
+
+exit $FAILED
+