Run Discoverability Audit

A broken safeguard is worse than none, because the person still trusts it. The failure mode this skill checks for is quieter than that: a skill or tool that works fine but that no agent can actually find — no trigger keywords, no cross-reference from a sibling skill, missing from a registry, invisible to search. This is a maintenance sweep, not something that runs inside a single task: it's what keeps the rest of your tools from becoming exactly that kind of quietly-broken safeguard.

The five things below don't need any particular script to check — each one is something an agent can do directly by reading files. If your project has its own automation for this already, use it; the steps here work with nothing but the Read/Grep tools.

When to Run

• After shipping new tools/endpoints/skills — before closing the session
• Periodically — catch drift from accumulated changes
• After MCP server changes — check cross-surface parity
• When an agent reports "couldn't find X" — diagnose and fix the gap

Run it by hand by default. If you want it on a schedule, that's a dial to add yourself — an automatic full-project scan on every session would be the kind of thing that gets in the way, so it isn't wired to run automatically here.

The Discovery Surfaces (check whichever of these you actually have)

#	Surface	How to check
1	MCP list_tools	If an MCP server is attached, its tools already show up automatically — nothing to fix here unless one is missing from the server's own list.
2	Skill triggers: frontmatter	Read each skill's frontmatter (see Phase 1)
3	A tool registry, if you keep one	See agentic-tooling-registry if shipped, or your own equivalent
4	Institutional-memory / semantic search, if you've set one up	/alignment-harness:harness-setup checkpoint "memory-search"
5	Registry semantic search, if you have your own API for it	Whatever search endpoint your own registry exposes

Surfaces 3-5 only apply if you've actually built them. If you haven't, say so and move on — there's nothing broken about not having a registry yet.

Phase 1: Triggers Audit

For every skill you have — this plugin's own skills/*/SKILL.md, anything under ~/.claude/skills/, and any project-scoped .claude/skills/ — read the YAML frontmatter and check for a triggers: list. List which ones are missing it.

Fix missing triggers: for each skill missing triggers:, read the SKILL.md and add 3-5 keyword phrases a person might actually say, to the frontmatter:

triggers:
  - "keyword phrase 1"
  - "keyword phrase 2"
  - "keyword phrase 3"

Phase 2: Cross-Reference Audit

An "orphaned" skill is one that does something useful but that no sibling skill ever points to — so an agent working nearby never learns it exists.

How to find candidate clusters: group your skills by shared subject matter — read each skill's frontmatter description and any triggers:, and cluster the ones that clearly belong together (they'll usually share obvious keywords: "billing", "auth", "testing", "deploy", and so on). For a small project this is quick to do by eye; for a large one, look for skills whose descriptions share 2+ distinct keywords.

Example, illustrative only (your actual clusters will be whatever your own skills group into):

Cluster	What belongs together
testing	any UX/browser-verification skills you have (chrome/playwright automation, "did this actually work" checks)
auth	login flow, security checklist, auth-specific debugging
tooling registry	whatever manages your own tool/skill registry, bulk-registration helpers, this audit itself

Fix orphaned skills: append a "Related Skills ({Cluster} Cluster)" section at the end of each orphaned skill file, listing 3-6 sibling skills with a one-line description each.

Phase 3: Registry Gaps (only if you keep a tool registry)

If you maintain a registry of your own tools/endpoints (a local file per agentic-tooling-registry if shipped, or your own database), check that every tool an agent might reach for is actually registered in it — cross-reference your skills' descriptions against what the registry lists, and note anything missing.

Fix missing entries: add the missing tool to your registry in whatever form it takes (a local JSON/file entry, or a row via your own API) — name, description, type, category, tags, and how to call it.

If you don't keep a registry, skip this phase — there's nothing to check yet.

Phase 4: MCP Cross-Surface Parity (only if you have both an MCP server and a registry)

If you have an MCP server exposing tools AND a separate tool registry, check that everything in one shows up in the other — an agent shouldn't get a different answer depending on which surface it happens to search. If you only have one of the two, this phase doesn't apply.

Phase 5: Endpoint Sync (only if your project auto-discovers routes)

If your project has its own script for discovering API routes and diffing them against a registry, run it. If it doesn't, this is optional scaffolding to build later, not something to do by hand here.

Phase 6: "Is anything waiting for review that nobody's told about?" (optional, generalize to your own setup)

The general pattern worth checking, whether or not you build any specific tooling for it: if any page, queue, or file holds items in a "proposed", "pending", "unscored", or "backlog" state that needs a person's decision, is that surfaced anywhere the person will actually see it — a dashboard, a digest, a notification — or does someone have to remember to go look? A queue nobody is told about is functionally invisible.

This doesn't ship as an automated check here because the concrete form (a dashboard config file, a specific admin route) depends entirely on what your project has. If you build one, this is the question it should answer.

Phase 7: Keep a Record So Re-Runs Don't Redo Work

After fixing gaps, write down what you found and fixed so a future run doesn't re-audit the same ground from scratch. Local default: a JSON file under the folder alignment-harness records discoverability-audits prints, dated, listing what was checked and what was fixed. If you have your own compaction/records system, use that instead.

Doing This Without a Helper Script

Nothing here requires a dedicated script — each phase is a Read/Grep pass an agent can do directly, as described above. If you find yourself running this often enough to want automation, a reasonable shape to write your own script around is: a checkTriggers() that scans your skills folder for missing frontmatter, a checkCrossRefs(cluster?) that audits sibling references, and a checkRegistryGaps() that diffs your skills against your registry (if you have one) — each callable standalone or together as a full report.

Related Skills

• discoverability-audit-learnings-findable-by-agents (if shipped) — deeper reference on the five-surface method
• agentic-tooling-registry (if shipped) — query and manage a local tool registry
• how-to-bulk-register-atomic-tools (if shipped) — bulk registration patterns
• if you have your own registry-sync automation, keep it in sync with whatever this audit finds