chore(claude): add hooks, skills, and agents for Claude Code (#496)

* chore(claude): add hooks, skills, and agents for Claude Code

Add auto-formatting hooks (ruff, shfmt, prettier, actionlint),
rules.yml edit blocker, 5 skills (/release, /test-action,
/new-action, /validate, /check-pins), and 2 subagents
(action-validator, test-coverage-reviewer). Update CLAUDE.md
with hook documentation.

* fix(claude): add tool availability guards and fix skill docs

Add jq availability checks to hook scripts (block-rules-yml.sh,
post-edit-write.sh) and wrap actionlint call in command -v guard,
consistent with project rules #2 and #10. Fix validate skill to
reflect actual make all pipeline order and note that make test
runs separately.

* fix(claude): correct skill docs per PR review feedback

Fix validate skill description to say "precommit" instead of "test",
and fix check-pins SHA guidance to use origin/main instead of HEAD.

* feat(tools): add SHA-pinning enforcement to check-version-refs

The check-version-refs script previously only displayed existing
SHA-pinned refs but silently skipped non-SHA references. Add a
validation pass that detects and reports any ivuorinen/actions/*
references not using a 40-char hex SHA, exiting 1 on violations.

* fix(tools): fix temp file leak in check-version-refs.sh

Write find output directly to $violations_file instead of
$violations_file.all so the EXIT trap covers cleanup on all
exit paths, not just the happy path.

.claude/skills/check-pins/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: check-pins
+description: Verify all action references are properly SHA-pinned
+disable-model-invocation: true
+---
+
+# Check SHA-Pinned Action References
+
+## 1. Check version references
+
+```bash
+make check-version-refs
+```
+
+This verifies that all `ivuorinen/actions/*` references in `action.yml` files use SHA-pinned commits.
+
+## 2. Check local references
+
+```bash
+make check-local-refs
+```
+
+This verifies that test workflows use `./action-name` format (local references are allowed in tests).
+
+## 3. Interpret results
+
+**Violations to fix:**
+
+- `@main` or `@v*` references in `action.yml` files must be replaced with full SHA commits
+- `./action-name` in `action.yml` (non-test) files must use `ivuorinen/actions/action-name@<SHA>`
+- External actions must be pinned to SHA commits, not version tags
+
+**How to get the SHA for pinning:**
+
+```bash
+# After pushing, get the SHA of the latest commit on the remote
+git rev-parse origin/main
+```
+
+Use a SHA that exists on the remote. Local-only commits won't resolve when the action is used externally.

.claude/skills/new-action/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: new-action
+description: Scaffold a new GitHub Action with all required files
+disable-model-invocation: true
+---
+
+# Scaffold a New GitHub Action
+
+## 1. Gather information
+
+Ask the user for:
+
+- **Action name** (kebab-case, e.g. `my-new-action`)
+- **Description** (one line)
+- **Category** (setup, linting, testing, build, publishing, repository, utility)
+- **Inputs** (name, description, required, default for each)
+- **What it does** (shell commands, composite steps, etc.)
+
+## 2. Create directory and action.yml
+
+Create `<action-name>/action.yml` following the existing action patterns:
+
+- Use `composite` runs type
+- Include `set -eu` in shell scripts (POSIX sh, not bash)
+- Use `${{ github.token }}` for token defaults
+- Pin all external action references to SHA commits
+- Pin internal action references using `ivuorinen/actions/action-name@<SHA>`
+- Add `id:` to steps whose outputs are referenced
+
+## 3. Generate validation rules
+
+```bash
+make update-validators
+```
+
+This generates `<action-name>/rules.yml` from the action's inputs.
+
+## 4. Generate test scaffolding
+
+```bash
+make generate-tests
+```
+
+## 5. Generate README
+
+```bash
+make docs
+```
+
+## 6. Run validation
+
+```bash
+make all
+```
+
+Fix any issues before considering the action complete.
+
+## 7. Update repository overview
+
+Remind the user to update the Serena memory `repository_overview` if they use Serena.

.claude/skills/release/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: release
+description: Create a new CalVer release with validation checks
+disable-model-invocation: true
+---
+
+# Release Workflow
+
+Follow these steps to create a new CalVer release:
+
+## 1. Pre-flight checks
+
+Run the full validation pipeline:
+
+```bash
+make all
+```
+
+If any step fails, fix the issues before proceeding.
+
+## 2. Check version references
+
+Verify all action references are properly pinned:
+
+```bash
+make check-version-refs
+make check-local-refs
+```
+
+## 3. Prepare the release
+
+Run release preparation (updates version references):
+
+```bash
+make release-prep
+```
+
+Review the changes with `git diff`.
+
+## 4. Confirm with user
+
+Ask the user to confirm:
+
+- The version number (defaults to `vYYYY.MM.DD` based on today's date)
+- That all changes look correct
+
+## 5. Create the release
+
+```bash
+make release VERSION=vYYYY.MM.DD
+```
+
+Replace `vYYYY.MM.DD` with the confirmed version.
+
+## 6. Verify
+
+Show the user the created tag and any output from the release process.

.claude/skills/test-action/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: test-action
+description: Run tests for a specific GitHub Action by name
+disable-model-invocation: true
+---
+
+# Test a Specific Action
+
+## 1. Identify the action
+
+Ask the user which action to test if not already specified.
+List available actions if needed:
+
+```bash
+ls -d */action.yml | sed 's|/action.yml||'
+```
+
+## 2. Run tests
+
+```bash
+make test-action ACTION=<action-name>
+```
+
+## 3. Display results
+
+Show the test output. If tests fail, read the relevant test files in `_tests/unit/<action-name>/` and the action's `action.yml` to help diagnose the issue.
+
+## 4. Coverage (optional)
+
+If the user wants coverage information:
+
+```bash
+make test-coverage
+```

.claude/skills/validate/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: validate
+description: Run full validation pipeline (docs, format, lint, precommit)
+disable-model-invocation: true
+---
+
+# Full Validation Pipeline
+
+Run the complete validation pipeline:
+
+```bash
+make all
+```
+
+This runs in order: `install-tools` -> `update-validators` -> `docs` -> `update-catalog` -> `format` -> `lint` -> `precommit`
+
+**Note:** `make test` must be run separately.
+
+## If validation fails
+
+### Formatting issues
+
+```bash
+make format
+```
+
+Then re-run `make all`.
+
+### Linting issues
+
+- **actionlint**: Check action.yml syntax, step IDs, expression usage
+- **shellcheck**: POSIX compliance, quoting, variable usage
+- **ruff**: Python style and errors
+- **markdownlint**: Markdown formatting
+- **prettier**: YAML/JSON/MD formatting
+
+### Test failures
+
+```bash
+make test
+```
+
+Read the failing test output and fix the underlying action or test.
+
+### Documentation drift
+
+```bash
+make docs
+```
+
+Regenerates READMEs from action.yml files.