fix: resolve skills across all three install roots, not ~/.claude/skills alone (1.4.0)

[wan-huiyan]

What this fixes

A skill installed as a plugin lives at ~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/, not at ~/.claude/skills/<name>/. Anything that reaches a skill through the ~/.claude/skills/ root alone misses on a plugin install, and the usual fallback is a log line plus "continue" — so the step silently does nothing while the summary still reads clean.

CLAUDE_PLUGIN_ROOT does not rescue this. It is frequently unset in the shell a step actually runs in, and it points at the running plugin's own root, so it can never reach a sibling plugin.

Same bug class as session-handoff v1.17.0 (wan-huiyan/session-handoff#13).

1. The executable lookup — overnight-insight-discovery (this one had teeth)

references/ccr_env_toolchain_preflight.md decided whether this skill was installed with a single line:

test -f ~/.claude/skills/overnight-insight-discovery/SKILL.md

On a plugin install that test fails. The documented failure path is not benign: the track writes env_preflight.json with "PASS": false, commits, and taps out with [ENV_BLOCKER] reporting no skill tree. A failed lookup gets reported as an install-state finding — exactly the misread that motivated the session-handoff fix.

It now probes all three roots in order and, on a miss, names the paths it tried:

S="${CLAUDE_PLUGIN_ROOT:+${CLAUDE_PLUGIN_ROOT}/SKILL.md}"
[ -f "$S" ] || S="$HOME/.claude/skills/overnight-insight-discovery/SKILL.md"
[ -f "$S" ] || S="$(find -L "$HOME/.claude/plugins/cache" -mindepth 4 -maxdepth 4 \
    -path '*/overnight-insight-discovery/*/SKILL.md' 2>/dev/null \
  | awk -F/ '{print $(NF-1)"\t"$0}' | sort -V -k1,1 | tail -1 | cut -f2-)"
if [ -f "$S" ]; then
  echo "overnight-insight-discovery SKILL.md: $S"
else
  echo "overnight-insight-discovery SKILL.md: not found — tried \$CLAUDE_PLUGIN_ROOT/, ~/.claude/skills/overnight-insight-discovery/, and ~/.claude/plugins/cache"
fi

Three details are not cosmetic:

• Ranks on the version segment alone ($(NF-1), depth 4 — the target here is <version>/SKILL.md, not <version>/scripts/<script>). The marketplace segment precedes the version in the path, so a plain sort -V over whole paths ranks by marketplace name and lets aaa-mkt/2.5.0 lose to zzz-mkt/1.0.0.
• find, not a shell glob. zsh's nomatch fails a non-matching glob at expansion time, before 2>/dev/null can apply, printing a raw shell error.
• "not found — tried <paths>", never a bare "not installed". A failed lookup is not evidence about install state.

Tested against a fake $HOME with two marketplaces (zzz-mkt/1.0.0 and aaa-mkt/1.10.0): picks aaa-mkt/1.10.0; silent and correct with no cache directory at all under zsh; CLAUDE_PLUGIN_ROOT wins when set.

Nothing here redirects to a file, so the guard-before-redirecting rule has no site to apply to in this change.

2. The dead documentation links — schedule-poll-orchestrator-pattern

Three see-also entries were markdown links of the form [name](~/.claude/skills/name/SKILL.md) — a file a reader on a plugin install cannot open. There is no local path that resolves under every install method, so they are now plain skill names, with a GitHub URL where the source repo is known:

• successor-handoff → https://github.com/wan-huiyan/context-baton/blob/main/plugins/successor-handoff/SKILL.md (verified via the contents API)
• claude-code-delayed-execution → name only. No repo of that name exists under this owner and a code search found no SKILL.md for it, so no URL was invented.
• overnight-insight-discovery → https://github.com/wan-huiyan/overnight-workflows/blob/main/plugins/overnight-insight-discovery/SKILL.md (verified)

Also removed one ~/.claude/skills/-rooted self-reference from overnight-insight-discovery's v1.3.2 changelog entry (it now says "this skill's own references/phase_b_review_loop.md").

Deliberately NOT changed

Every ~/.claude/skills/** mention in § "Autonomous-safe skill edits" and the Phase G summary above it — SKILL.md lines 570, 596, 606, 610 and 810. Those are the path patterns that fire a sensitive-file permission prompt in Claude Code. That is a fact about the prompt system, not about where this skill lives; broadening them to include the plugin cache would change what the contract forbids, and narrowing them would break it outright. Confirmed present at the remote tip after the push.

Also left alone, and worth a separate decision rather than a silent edit:

• README.md lines 96–98 (cp -R … ~/.claude/skills/) and plugins/observational-analysis-rigor/skills/data-provenance-verifier/README.md:33 (git clone … ~/.claude/skills/…) — install instructions that create that root. Correct as written.
• references/phase_c_consolidation.md:225, "Commit any skill changes under the user's ~/.claude/skills/ directory." This one does assume a single root, but it is plain guidance to a human about their own skills directory, and the Phase G autonomous-safe contract already overrides it for unattended runs. Rewriting it means deciding what "commit a skill change" even means on a plugin install (you would be editing a cache directory), which is a design question, not a path fix.

Versions

	before	after
bundle VERSION	1.3.1	1.4.0
overnight-insight-discovery — plugin.json + marketplace.json	1.1.1	1.2.0
overnight-insight-discovery — SKILL frontmatter	1.8.0	1.9.0
schedule-poll-orchestrator-pattern — plugin.json + marketplace.json	1.0.0	1.0.1
schedule-poll-orchestrator-pattern — SKILL frontmatter	1.0.0	1.0.1

Minor for overnight-insight-discovery because the pre-flight check's behaviour changes; patch for schedule-poll-orchestrator-pattern because it is links only.

Pre-existing drift, not introduced here and not reconciled here: overnight-insight-discovery's SKILL frontmatter (1.8.0) and its manifests (1.1.1) are on two different numbering lineages, and have been for several releases. I bumped each within its own lineage by the same increment rather than guess which is authoritative. overnight-review-panel-blocked-reviewer-reads-as-clean (frontmatter 1.0.0 / manifest 1.0.1) and subagent-review-tier-calibration-for-overnight-pr-chains (frontmatter 1.0.1 / manifest 1.0.0) have the same kind of drift and are untouched by this PR.

README Version history has an entry. Changelogs added to both SKILL.md files (schedule-poll-orchestrator-pattern had no version-history section before; it has one now).

Checks

All three CI gates were run locally before the change (all green) and again after (all green): validate_plugins.py, leak_scan.sh, check_skill_descriptions.py --triggers. Nothing was red before this change.

Do not auto-merge.