# agents-skills-mirror-nudge

Claude Code `Stop` hook that fires when the session edited a `.claude/skills/` source but the derived `.agents/skills/` cross-tool mirror is stale.

## Why

`.agents/skills/` is a generated FLAT mirror of the segmented `.claude/skills/{fleet,repo}/<name>/` skills, so Codex and OpenCode (which discover skills only one level deep) find every fleet/repo skill. The mirror is regenerated by `scripts/fleet/gen-agents-skills-mirror.mts`, and the `agents-skills-mirror-is-current` CI check reds when the committed mirror drifts from its source.

A cascade regenerates the mirror in the same wave that copies a skill source (sync-scaffolding's `fix-agents-mirror.mts`), so the cascade path can't strand it. This hook is the backstop for a hand-edited skill outside a cascade — especially a repo-tier `.claude/skills/repo/<name>/` skill, which has no `template/` twin and so never trips `dogfood-cascade-nudge`.

## What it catches

A session that touched any `.claude/skills/**` file (committed vs `origin/HEAD` or dirty in the working tree) AND left `.agents/skills/` drifted from the source (per the generator's `--check` mode).

## When it's a no-op

- No `.claude/skills/**` file changed this session.
- The mirror is already in sync.
- The repo doesn't ship `scripts/fleet/gen-agents-skills-mirror.mts`.

## The fix it points to

```sh
node scripts/fleet/gen-agents-skills-mirror.mts
```

Then commit the regenerated `.agents/skills/` alongside the skill edit.

## Test

```sh
node --test test/*.test.mts
```
