Discoverability Audit — Making Work Findable by Agents

When to Use

After creating new MCP tools, skills, endpoints, or workflows — before closing a session. The question: "Will a future agent working on a related problem actually find what I just built?" If the answer is no, the work is invisible and will be duplicated or missed.

The Discovery Surfaces

Future agents find tools through some subset of these surfaces, depending on what you have set up. Only the first two need nothing beyond what a fresh install already has:

#	Surface	How It Works	Needs setup?
1	MCP list_tools	Auto-listed if the agent has that MCP server attached	No — automatic
2	Skill file triggers:	Matched against user input keywords in the skill's frontmatter	No
3	Institutional-memory / semantic search	Search across your own past sessions and notes for what you built	Optional — see /alignment-harness:harness-setup (memory search checkpoint)
4	A tool registry	A database or index of your tools/skills/endpoints, searchable by slug/tag/category, with an approval workflow	Optional — most people won't have one; see below

If you don't have a tool registry (surface 4) or memory search (surface 3) configured, that's expected on a fresh install — run the surfaces that don't need them (1 and 2), and say plainly which surfaces you skipped and why, rather than reporting them as passed.

Audit Procedure

Step 1: Check MCP auto-listing

If your tool is registered in an MCP server's tool list, any agent with that server attached will see it.

Gap: Agents WITHOUT the MCP server attached will never find it.

Step 2: Check skill file triggers

Find where the skill actually lives — for Claude Code this is typically ~/.claude/skills/<name>/SKILL.md (personal, all projects) or <project>/.claude/skills/<name>/SKILL.md (project-scoped), or, if it ships as part of a plugin, <plugin>/skills/<name>/SKILL.md. Check whichever of these is where you actually put it:

cat ~/.claude/skills/{skill-name}/SKILL.md | head -20
# or, for a project-scoped skill:
cat <project>/.claude/skills/{skill-name}/SKILL.md | head -20

Look for the triggers: array in YAML frontmatter. If missing, agents won't match on keyword input.

Step 3: Check a tool registry, if you have one

Some setups keep a small database or index of tools/skills/endpoints with an approval workflow (proposed → approved) so a human can audit what agents have registered. If you have one:

# Shape of the check, generalized — replace with your registry's real path
curl -s "http://<your-api-server>/<your-registry-path>/slug/{tool-slug}" \
  -H "x-api-key: $YOUR_API_KEY" | node -e \
  "const j=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')); \
   console.log('Status:', j.data?.status, '| Certainty:', j.data?.certaintyScore)"

If it returns 404, the tool is missing from the registry. If it returns a "proposed"/unapproved status, it exists but hasn't been reviewed yet.

If you don't have a registry like this, skip this step and say so in your report — don't invent a pass.

Step 4: Check the registry's semantic search, if it has one

curl -s "http://<your-api-server>/<your-registry-search-path>?q=segment+compare" \
  -H "x-api-key: $YOUR_API_KEY" | node -e \
  "const j=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')); \
   console.log('Count:', j.count); \
   console.log('Top slug:', j.results?.[0]?.slug)"

Step 5: Check institutional-memory / semantic search, if it's set up

If this project's memory search is configured (see /alignment-harness:harness-setup), run it with a natural description of the tool's purpose and confirm it surfaces the tool or its documentation. If it isn't configured, search the repo's own docs and notes and git log for the tool's name instead, and say plainly that semantic memory search wasn't available.

Fix Patterns

Fix: Endpoint exists but is not discoverable

If your project has a script that syncs API routes into a tool registry, run it (dry-run first if one exists) and re-check the registry. If you don't have such a script, describe the endpoint's purpose in a skill file with triggers: frontmatter instead — that's the fallback path that needs nothing extra.

Fix: Tool missing from a tool registry (manual)

If you have a registry API, register the tool and mark it approved through whatever calls it exposes for that (shape below, generalized — use your registry's real paths):

curl -s -X POST "http://<your-api-server>/<your-registry-path>" \
  -H "x-api-key: $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "example-tool",
    "name": "Example Tool",
    "description": "What it does. Scope: workflow. When to use.",
    "toolType": "endpoint",
    "category": "analytics",
    "tags": ["endpoint", "example"],
    "signature": "GET /path/to/endpoint",
    "repo": "your-repo"
  }'

Without a registry, the equivalent fix is: write a skill file for it with clear triggers:, and mention it in whatever related skills would need to know it exists (see Step 6).

Fix: Skill file missing triggers

Add YAML frontmatter with trigger keywords:

---
name: your-skill-name
description: One sentence describing when an agent should use this.
triggers:
  - "keyword phrase 1"
  - "keyword phrase 2"
---

Validation Checklist

After fixes, verify each surface you actually have:

• Skill file has triggers: array with 3-5 keyword phrases
• If a tool registry exists: a lookup by slug returns the tool, and a natural-language search surfaces it
• If institutional-memory search is set up: a natural description of the tool's purpose returns it
• Any surface you don't have is reported as "not checked — not configured," never silently marked passed

Step 6: Cross-reference into related skill files

After ensuring a tool is findable via the surfaces you have, check whether it should be referenced in OTHER skill files that represent related workflows. For example, a new testing tool should be cited in all testing-adjacent skills.

Procedure:

1. grep -rl "keyword1\|keyword2" ~/.claude/skills/*/SKILL.md (and any project-scoped .claude/skills/*/SKILL.md, and this plugin's own skills/*/SKILL.md if relevant) to find related skills
2. For each related skill, add a short section at the end: tool name, when to use it in that workflow, the call or command to reach it
3. Keep it to 3-5 lines — enough for an agent to know the tool exists and how to call it

Why: Agents load one skill at a time. If a testing skill doesn't mention a tool that answers exactly what it needs, the agent will never look for it. Cross-references close this gap.

Step 7: Will a Human See This?

Agents finding tools is one layer. A person seeing what needs their attention — without having to remember to go looking — is the other. If a backlog of proposed tools, intents, or findings sits unreviewed somewhere, the work is invisible to the person who'd act on it.

Questions to ask yourself:

1. What data source now holds signal that needs human review? — every place your work populated a queue, a "proposed" status, or an unreviewed list.
2. Does the person have to remember to check that page, or will something surface it? — if the answer is "they have to remember," the signal will rot, especially once there are many such pages.
3. Can priority be computed from the data itself? — most such data has a timestamp (staleness), a status (pending/proposed/overdue), and sometimes a leverage or impact score. Priority is roughly urgency(staleness) × impact × decay_rate — if you can compute it, you can rank it.
4. What's the cost of the person not seeing this signal? — state it plainly (stale proposals nobody approves, silent regressions, work that ships without review).
5. What form factor reaches the person without them pulling? — a page they must remember to visit is pull-based and gets forgotten; a status view, digest, or badge that's already part of their routine is more likely to be seen.
6. Is this signal already surfaced somewhere? — check whatever status or dashboard surface you already have (this harness ships alignment-harness status / alignment-harness doctor as one example) before assuming nothing covers it.

What to do with the answers:

• If nothing surfaces the signal: propose a small view that lists the top items ranked by computed priority — even a markdown file regenerated on demand under alignment-harness records <kind> is enough to start.
• If it's surfaced but buried: propose a count or priority indicator on whatever index the person already checks.
• If it's time-sensitive: propose a way to be notified when a threshold is crossed, using whatever notification path the person already has (chat, email, a CI check) rather than inventing a new channel.

Principle:

Agent discoverability is about machines finding tools. Human discoverability is about people seeing signal. Both layers must work or the work is invisible to someone.

Audit Registry — Preventing Duplicate Work

Before auditing any artifact, check audit-registry.json (same directory as this skill file) to see if it's already been audited. After auditing, add an entry.

# Read the registry — adjust the path to wherever you keep this skill
cat <skill-folder>/audit-registry.json | node -e "const j=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')); j.audited.forEach(a => console.log(a.slug, '|', a.status, '|', a.auditDate))"

Registry fields per artifact: slug, type (skill|endpoint|mcp-tool|admin-ui|utility|mcp-server), auditDate, surfaces (status per discovery surface you actually have), status (complete|gaps-found|needs-reaudit), notes.

After auditing: update the registry JSON with your findings, and recompute its own _meta.updated and _meta.totalAudited from the audited array itself (its length and the latest auditDate) rather than typing a number by hand — a registry whose own summary drifts from its entries is exactly the kind of staleness this skill exists to catch. Future agents read this first to skip already-audited work.

Known Gaps

1. A tool registry and a memory/semantic-search index are usually separate systems — registering a tool in a registry does not automatically make it findable via semantic search over your history, and vice versa. If the concept matters beyond one artifact, make sure it's captured in both.
2. If your registry uses a closed category enum, use the closest match rather than inventing a new one, and note the mismatch in your audit entry.
3. If you rely on an MCP-based memory search and its transport closes mid-session, that pipe is usually not repairable without restarting the session — use whatever local/CLI fallback you have for that session, then restart later.
4. A "surface signal to a human automatically" feed is rarely built by default — most setups require a person to manually check several places. See Step 7 above for how to close that gap incrementally rather than assuming it already exists.

Related Skills (Admin/Agent Tooling Cluster)

• how-to-bulk-register-atomic-tools — bulk-register endpoints, skills, and utilities, if this plugin's copy of that skill is installed
• run-discoverability-audit — a fuller, repo-wide sweep across everything, rather than the per-artifact check this skill does right after building something
• If your project has its own tool-registry skill, agent-tooling-registry skill, or canonical-function scanner, use those the same way — this skill's job is the audit logic, not any one registry's specific API.