fix(tools): make every agent_skills pointer resolve

[bbudaedu]

The defect

AGENT_GUIDE.md makes Layer 3 mandatory:

Every generation tool has an agent_skills field listing its Layer 3 skills. These skills contain provider-specific prompt engineering, parameter tuning, and quality techniques. Read them before writing prompts. Layer 3 is not optional.

Four of the 137 pointers the registry advertises name skills that do not exist under .agents/skills/, so the mandated read silently cannot happen. tts_selector makes it worse by republishing its list to callers as required_agent_skills, propagating a dead name downstream.

hyperframes_compose      -> website-to-hyperframes
openai_tts               -> openai-docs
tts_selector             -> openai-docs
screen_capture_selector  -> screen-demo

The repair

Each pointer was repaired according to what the evidence showed it to be — repoint where a correct skill exists, drop where none does, rather than aiming at something merely adjacent.

website-to-hyperframes → website-to-video (stale name)

Not a missing file. .agents/skills/hyperframes/PROVENANCE.md:20 records the rename:

| website-to-video | Renamed upstream from website-to-hyperframes. |

The tool never followed it. The other five entries in that same list already resolve.

openai-docs → dropped (never vendored)

Nothing in .agents/skills/ covers the OpenAI speech API. The nearest candidate, text-to-speech, documents HeyGen's Starfish endpoints and declares allowed-tools: mcp__heygen__* — pointing there would actively send the agent at the wrong provider. tts_selector keeps its two entries that do resolve (text-to-speech, elevenlabs); openai_tts is left with the default empty list and a comment saying why.

screen-demo → dropped (category error)

That names the Layer 2 pipeline directory (skills/pipelines/screen-demo/), not a Layer 3 skill. No Layer 3 skill covers OS screen capture, and this selector routes only between screen_recorder (FFmpeg) and cap_recorder — neither playwright-recording nor synthetic-screen-recording describes what it does. The capture guidance it was reaching for is already reachable through the manifest's per-stage skill: entries, so nothing is lost.

An empty agent_skills is the BaseTool default and already the case for 18 of 102 tools, so the two removals need no further wiring.

Coverage

tests/contracts/test_agent_skill_pointers.py iterates the registry rather than naming tools, so a newly added tool is checked the moment it is discovered. It also guards against covering nothing, since a parametrized test over an empty list passes silently.

Verification

• The 4 pointers fail on the unfixed tree; all 139 cases pass after.
• Full suite: 964 → 1103 passed, 10 skipped, no regressions.
• make lint: passed.

Related to #233 (".claude/skills out of sync with .agents/skills?") but deliberately narrower: this only makes existing pointers resolve and does not touch the two skill trees' relationship.

Independent of #468, #469 and #472 — no overlapping files.

🤖 Generated with Claude Code