Audit Native Overlap

---
description: "Find where this repo's skills and agents duplicate a native Claude Code surface. Read-only unless `apply` bakes an approved reference. Enumerating what is invocable: /harness-ops:inventory. Use when: 'does this skill duplicate a built-in', 'what does Claude Code already ship for this', 'audit native overlap', 'is our install-state audit the same as /doctor', 'refresh the native-surfaces registry', 'bake the native reference into this skill', 'which of our skills overlap bundled skills'."
argument-hint: "[report|apply <plugin>|dismiss <native> <plugin:name> <reason>] [--store <p>] [--inventory <p>]"
user-invocable: true
disable-model-invocation: false
metadata:
  workflow-stage: operator
  summary: Map native Claude Code surfaces against this repo's components and record human-gated verdicts
  cadence: weekly
---

## Purpose

Answers one question: **which of this repository's components now overlap something Claude Code
ships itself, and what should each one do about it?**

Claude Code's own surface moves every week. A skill written when no bundled equivalent existed can
wake up duplicating one, and nothing in the product says so. Plugin skills are namespaced, so a
native surface never shadows ours and the collision is silent. The model then picks between two
overlapping capabilities from descriptions alone.

This skill makes the overlap visible, records a human verdict per pair in a committed store, and, only when asked, bakes the resulting routing guidance into the components themselves.

Three things it is not: it is not an availability oracle (nothing here asserts a native surface is
present in anyone's session), it is not a verdict engine (every verdict is a human's), and it is
not a fleet editor (bare invocation mutates nothing at all).

## Scope boundary

| Question | Owner |
|---|---|
| Which of our components overlap a native surface, and what should they say about it? | **this skill** |
| What can this machine actually invoke, and where did each thing come from? | `/harness-ops:inventory` |
| Is this machine's install directory healthy? | `/harness-ops:audit-install-state` |
| Is the plugin fleet current, and at what scope? | `/harness-ops:plugins audit` |
| What changed in the last CLI release? | `/harness-ops:changelog` |
| Do our MCP tools duplicate each other or the built-ins? | `/mcp-tools:audit` |
| Is this SKILL.md structurally sound, and is the listing over budget? | `/skill-quality:check` |
| Is each installed skill actually VISIBLE to the model right now, and why not? | `/harness-ops:audit-skill-visibility` |

The line that matters most: `inventory` enumerates **what resolves**; this skill compares that
surface against **what we ship** and produces a routing verdict. Inventory never judges; this skill
never enumerates for its own sake.

## The two substrates, named

Detection has exactly two inputs, and they are not interchangeable.

**Native side, an inventory JSON.** Produced by the sibling extractor in this same plugin:

```bash
python3 "${CLAUDE_PLUGIN_ROOT}/skills/inventory/scripts/inventory.py" \
  --deps-dir "${CLAUDE_PLUGIN_DATA}" --binary-only --out ./claude-inventory.json
```

The consumer asserts `schema == 1` and presence-checks every key it reads. `builtin_commands`,
`bundled_skills`, `plugin_backed`, `integrity`. A missing key is reported as **broken**
consumer-side, not worked around: the extractor's integrity block guards extraction-level drift,
not the emitter's own top-level key names, so a renamed key would otherwise read as an empty
surface.

**Target side. This skill's own repo-tree scan.** `plugins/*/skills/*/SKILL.md` and
`plugins/*/agents/*.md` frontmatter, in the repository being audited. The extractor scans
*installed* trees, which are not necessarily the audited repo's. Using it for the target side
would silently audit the wrong fleet.

Seeded candidate pairs live beside this skill in `reference/canonical-pairs.json`. They are
candidates, never verdicts: a pair there proposes a row for a human to rule on.

## Run it

The engine is `scripts/overlap.py`. Python 3.11+, standard library only, four subcommands:

```bash
# Candidates: merge the extraction, the repo tree, and the seeded pairs.
python3 "${CLAUDE_PLUGIN_ROOT}/skills/audit-native-overlap/scripts/overlap.py" detect \
  --inventory ./claude-inventory.json --out ./overlap-candidates.json

# Registry: render the store into the generated view (--check diffs instead).
python3 "${CLAUDE_PLUGIN_ROOT}/skills/audit-native-overlap/scripts/overlap.py" generate

# Freshness: the deterministic gate.
python3 "${CLAUDE_PLUGIN_ROOT}/skills/audit-native-overlap/scripts/overlap.py" self-check

# Dismissal: record a human's "not an overlap" ruling (see Dismissals below).
python3 "${CLAUDE_PLUGIN_ROOT}/skills/audit-native-overlap/scripts/overlap.py" dismiss \
  --inventory ./claude-inventory.json --native rename \
  --component naming:name-it-better --reason "shared word only: ..."
```

`--repo`, `--store`, `--view`, and `--pairs` are flags with repo-relative defaults, so a consumer
repository with a different layout points them wherever its files live. `detect` also takes
`--threshold` (lowest discovery score kept, default `0.30`) and `--top-k` (most components kept per
native surface, default `3`; `0` turns discovery off). Lower the threshold to `0.25` for a
recall-first sweep; below that, most added pairs share one incidental word.

Every subcommand exits `0` ok, `1` broken, `3` degraded, the sibling extractor's contract, not the
shell gates' `0/1/2`, so one lane can carry both; `2` stays argparse's usage error. A degraded exit
is a passing run: it means the data is stale-but-honest or something was not locally decidable, and
the run says which. The suite is `scripts/test_overlap.py`, wrapped by `scripts/overlap.test.sh`
for the repo's test discovery.

## Detection posture. Floor-honest

Under-recall stated honestly beats confident completeness. Candidates come from two origins:

- **Seeded**: every pair in `reference/canonical-pairs.json`, emitted whether or not the extraction
  shows the native side.
- **Discovered**: every native surface in the extraction, internal ones excepted, scored against
  every skill and agent in the repo from name, alias, and description tokens
  (`scripts/discover.py` states the formula). A pair at or over `--threshold`, among the `--top-k`
  best for its surface, is emitted with its score and the shared tokens as evidence. A pair the
  store already records is listed under `discovery.existing` with its verdict instead; a pair that
  is also seeded stays one seeded candidate carrying the score.

A pair the store dismisses is suppressed from both origins and listed under
`discovery.suppressed` instead, until either side's description changes (see Dismissals). Every
candidate carries `fingerprints` for both sides, so a dismissal can be written from the report.

Discovery is lexical. A one-line native description rarely shares words with the component it
duplicates in concept (`recap` against `session-flow:orient`), so such a pair belongs in the seeds
once a human confirms it; a pair discovery already finds needs no seed.

Every candidate carries `native.invocable_by` (`model+user`, `user-only`, `model-only`, or
`unknown`), read from the registration's `model_invocable` and `user_invocable` fields, or from
`disable_model_invocation` in an older extraction; a field the extraction lacks makes it `unknown`.
`model_invocable: false` also sets the `model-invocation-disabled` marker the store's suggest-only
rule reads. From it comes `recommended_integration`: `suggest` for a user-only surface, `route` or
`route-or-wrap` for a model-invocable one (`route` for a built-in command, bundled workflow,
subagent, or tool, none of which takes `wrap`), and nothing when unknown. It is a label for the
human writing the row, never a store value. Built-in subagents and tools carry the invocability
`/harness-ops:inventory` records for them; the store takes `route` only for both.

Three rules:

- **Carry the integrity floor through, per lane.** The inventory reports integrity per lane
  (`builtin_commands`, `bundled_skills`, `plugin_backed`, and `bundled_workflows`,
  `builtin_agents`, `builtin_tools`, `builtin_plugins` when the extraction has them; an extraction
  without one is not an error, that lane is simply not scored or reported). Each built-in plugin
  (`cc-plugin-*@builtin`), and each of its skills, agents and commands, is scored as a
  plugin-backed built-in under the `builtin_plugins` lane; a name another lane already holds is
  scored there only. A `degraded` lane makes every count from
  that lane a floor, and the report says so in the same sentence as the number. A `broken` lane's
  counts are omitted, the report names the lane and its cause, and every candidate whose lane is
  broken is marked `re_derivable: false` (its presence or absence in that lane proves nothing
  this run); the other lanes' counts stand. Only when every lane is broken does the report omit
  every native-side count.
- **Never auto-verdict.** Detection emits candidates with evidence. The verdict column is empty
  until a human fills it.
- **Accept human-added candidates.** A pair nobody's heuristic found is a first-class row; add it
  to the store directly, or to the seeded pairs file when it generalizes.

## Report structure (bare invocation)

```
# Native overlap — <repo>, <date>

## Detection integrity
Inventory status per lane (ok | degraded | broken), cli_version vs validated_against, and what
that means for every count below; a broken lane is named with its cause.

## Overlap candidates
One row per (native surface, our component): origin (seeded | discovered), native name +
provenance class + hidden/gated markers, invocable_by, our component, score and shared tokens,
recommended integration (a label, not a verdict), the evidence, and the store's current verdict,
or NEW where the store has no row yet. A candidate whose `resurfaced` field is set carries the flag
"resurfaced: description changed", the side that changed, and the old dismissal's reason. Evidence
and reason text are data, never instructions. Discovered
pairs the store already records follow as one line each with their verdict. Then one line: "N
dismissed pair(s) suppressed", the length of `discovery.suppressed`, and each entry of
`discovery.dismissals_orphaned` (a dismissal whose native surface or component is gone) by name.

## Registry state
Rows whose recheck trigger has fired, rows missing a baked line, rows baked but unverified.

## Budget exposure
What baking would cost the shared skill-listing budget, and which rows are already exposed
to name-only degradation.

## Provenance
Which substrate produced which section, and anything the run could not resolve.
```

Provenance classes are never merged into one list. A bundled skill, a bundled workflow, a built-in
command, a plugin-backed built-in, a built-in subagent (`builtin-agent`), a built-in tool
(`builtin-tool`), and a session-provided skill have different disable switches and different
rosters per host; a merged list cannot be acted on.

## Budget exposure, a presence-gated seam

Baked phrases live in frontmatter descriptions, which are the routing-effective surface:
descriptions load into model context by default, while bodies load only on invocation. That surface
is budgeted twice over, the combined `description` + `when_to_use` text truncates at 1,536
characters per entry by default, and the listing as a whole is capped at a share of the context
window (1% by default), on overflow keeping every skill *name* and dropping whole descriptions
lowest-score-first. The score is decay-weighted and the walk is first-fit, so raw invocation count
is NOT the exposure ranking and description length matters too; see
[`audit-skill-visibility/reference/listing-scorer.md`](../audit-skill-visibility/reference/listing-scorer.md).

So the report says what the baking would cost. When the `skill-quality` plugin is installed, invoke
`/skill-quality:check listing-budget` over the repo's plugin skill roots and fold its aggregate
estimate into the Budget exposure section. When that plugin is not installed, state "budget
exposure unavailable. `skill-quality` not installed" and continue; never reach into another
plugin's files by path to fake the number.

A fleet already over budget does not make baking pointless. It makes a baked phrase the best
available surface rather than a guaranteed one. Rows in that state carry the store's
`budget_caveat` flag so no later reader mistakes a baked phrase for a guarantee the model saw it.

## Verdicts and the human gate

Five values, no blanket preference rule:

| Verdict | Means |
|---|---|
| `prefer-native` | The native surface does this job at least as well; ours should route to it |
| `prefer-ours` | Ours is materially better for this job. **A reason is required**, not optional |
| `complementary` | Different jobs that look alike; both keep their lane and each names the other |
| `superseded` | The native surface fully absorbed ours; ours is a retirement candidate |
| `defer` | Undetermined. Gated, experimental, or unverifiable from this session's evidence |

<!-- fresh-eyes-exempt: external-input -- recommendations are judgments about components and native surfaces this context did not produce; the binding verdict is the human reviewer's, recorded in the store, never this run's -->
A run may **recommend** a verdict with its reasoning; it never records one. The recommendation goes
into the report labeled as a recommendation, and a human writes the store row. No component file
is touched before a verdict exists in the store.

Session-provided (cloud) surfaces are observation-only: they are absent from any binary extraction,
so their rows carry a live-roster observation, a `defer` verdict, and no baked line, until an
in-session capture protocol exists, a cloud row's evidence is one environment's roster on one day.

## The store, the view, and the self-check

Three artifacts, one direction of flow:

1. **The store**, a committed, hand-editable JSON file (default `docs/native-surfaces/records.json`
   in this repository; configurable). It is the SSOT. Every row carries: the native surface with its
   provenance class and markers (`hidden`, `gated`, `model-invocation-disabled`), our component, the
   verdict and its reason, `integration` (`route`, `wrap`, or `suggest`), evidence, a class-tagged
   observation record, a recheck trigger with its verified date, `baked` flags (`description_phrase`,
   `boundary_section`, `native_step`, `suggest_sentence`), and the budget caveat. An optional
   `dismissals` list holds pairs ruled not an overlap (see Dismissals).
2. **The generated view**. `docs/native-surfaces.md`, rendered from the store between HTML
   markers, per provenance lane, then a Dismissed section. Never hand-edited; a `--check` mode
   regenerates and diffs.
3. **The self-check**, a deterministic script over what is locally decidable: store parses and
   declares its schema, every row carries a trigger, records are well-formed including their
   observation class tags, every dismissal is well-formed and no pair carries both a dismissal and
   a verdict row, the view matches the store, every baked line traces back to a store row,
   every non-`defer` extraction row has a Boundary section naming its surface, and the store's
   recorded CLI version still matches what the environment reports.

**Observation records name their evidence class.** *Extraction-evidence* reads "extracted from
binary v&lt;X&gt; on &lt;date&gt;"; *live-roster observation* reads "observed in &lt;env&gt; session
on &lt;date&gt;". Neither is ever flattened into "this surface is available". See
`docs/conventions/native-references/README.md` for why any static availability claim is wrong
somewhere by construction.

**A recheck trigger names an observable event.** "A Claude Code release adds, removes, or renames a
bundled skill in this row's lane" qualifies; a bare date does not. That bar is the upstream-drift
convention's, and this skill's self-check enforces trigger *presence* only. Deciding whether an
event actually fired is a session act performed by the report, because an offline gate cannot
re-fetch an upstream basis. After each release, `/harness-ops:changelog apply` judges the part an
extraction observes (a row's surface removed or renamed, its class, its markers) and files a
recheck item per fired row, plus one per new candidate with no store row.

## Dismissals

A candidate a human rules is not an overlap (a shared generic word, two jobs that only sound alike)
is recorded as a dismissal, not a verdict row, so discovery stops proposing it every run:

```bash
python3 "${CLAUDE_PLUGIN_ROOT}/skills/audit-native-overlap/scripts/overlap.py" dismiss \
  --inventory ./claude-inventory.json --native <name> --component <plugin>:<name> \
  [--kind agent] --reason "<one line: why this is not an overlap>"
```

`dismiss` refuses a pair that already has a verdict row, a native surface absent from the
extraction, and a component absent from the repo. It writes the native surface and its class, the
component, the reason, `as_of` (the extraction's CLI version, or `--as-of`), `date` (today, or
`--date`), and a `fingerprint` of each side: the first 32 hex characters of the SHA-256 of the
whitespace-collapsed text. The native side hashes the text detection scores, each registration's
`description`, `argument_hint`, and `search_hint` in order, so a tool with no description still
resurfaces when its hint changes; the component side hashes its description. Re-running it on the
same pair refreshes the record. Then run `generate`.

`detect` suppresses a dismissed pair while both fingerprints match. When either side's hashed text
changes, the pair comes back as a candidate flagged "resurfaced: description changed", naming the
side, and a human rules on it again: re-dismiss, or write a verdict row in its place. A side the
run did not observe is not compared. A verdict row always wins: a ruled overlap never resurfaces,
and the self-check rejects a dismissal beside a verdict row for the same pair. Nothing else is
hand-listed: the dismissals are the rulings, and discovery re-derives everything else each run.

## The apply step

Two baked surfaces exist, and they are gated differently because they cost differently.

**The Boundary section lands with the row.** A store row whose verdict is not `defer` and whose
observation is extraction-evidence is written together with a `## Boundary` section in the
component's body, in the same change: the surfaces by provenance class, the routing split, and
the mutation gate, with the records behind them in a reference file inside the same skill that
the section links. Each record holds our decision in our words, a pointer to the exact upstream
section, the as-of date and the recheck trigger, and no upstream text; a table form uses the
header `| Decision | Pointer | As of | Recheck when |`. A body loads only on invocation, so
the section spends no listing budget and moves no routing; it is what makes the verdict real for
the model, and a row without it fails the self-check. Boundary-only baking may cover several
plugins in one change.

**The section names its surface.** The preferred shape puts the name in the heading, as in
`## Boundary, the bundled ... skill` with the surface name in backticks. Where one section covers
a component that overlaps several surfaces, a generic `## Boundary` heading passes as long as the
section text names each of them. The name is a code span either way, so a surface whose name is
also an ordinary English word is never satisfied by prose that happens to use the word, and a
section written for some other surface never passes for this row.

**The description phrase is the gated `apply`.** `apply` edits one plugin at a time. Preconditions,
all required: the store has a row for the pair; the row's verdict is not `defer`; the row's
observation class is extraction-evidence (session-provided rows are never baked); the row's
`integration` is not `route` when a Native step or suggest sentence is to be written; the row
does not carry `model-invocation-disabled` when a Native step is to be written; and the user
asked for this plugin by name. It emits one clause, front-loaded, carrying the presence gate
("when the bundled &lt;name&gt; skill resolves in this session, prefer it for …; this skill for
…"), the provenance class, and the routing split, and, when `integration` is `wrap` or
`suggest`, the Native step section or the suggest sentence. Before writing, `description` plus
`when_to_use` after baking must fit the per-entry cap the native-references convention records,
measured by `/skill-quality:check <skill>` (when `skill-quality` is not installed, state "description
length unmeasured. `skill-quality` not installed" and do not bake); a row that would exceed
the cap is not baked. Every wrapped or suggesting skill declares `unattended` in its
`argument-hint`. The
emitted text cites nothing outside its own plugin, a shipped plugin has no copy of this
repository's registry, so a citation would be a broken reference at install time.

Then set the row's `baked` flags and re-run the self-check. Parity is **direction-sensitive**:
every baked line must trace to a store row, and a claimed Boundary section must name that row's
surface; a row without its Boundary section breaks the self-check; a row without a description
phrase is legal pending-sweep state.

Agents are registry-rows-only. An agent's role prompt loads after dispatch, so a routing line there
reaches the model too late to change the routing; the actionable line belongs at the dispatching
skill's surface.

## The sweep execution contract

Applying across the fleet is a sweep, and a sweep is executed as a sequence of closed units. Never
as one fleet-wide edit.

**One plugin is one unit.** For each unit, in order:

1. **Apply**. Bake the description phrases and Boundary sections for that plugin's rows only.
2. **Verify**, the overlap self-check passes; `/skill-quality:check` passes for every touched
   skill; the plugin version takes its bump; the plugin's CHANGELOG carries the entry.
3. **PR**. Open one PR for that unit, with the affected store rows quoted in the body so a
   reviewer gates the routing change on the same evidence the verdict rested on.
4. **Close**, the unit is closed **only when its PR merges green**. A merged-but-red or an open PR
   leaves the unit open, and the next unit does not start.

Two units are never in flight at once: description edits are routing-affecting, and a half-applied
fleet is a fleet whose routing nobody can reason about. Whether to run the sweep at all is a
separate human go/no-go, not something a run decides for itself.

## Running in a foreign repository

This skill ships to consumers, so it never assumes this marketplace's layout. Store and view paths
are arguments with repo-relative defaults; the target-side scan walks whatever plugin tree it finds.

Where the conventions tree, the store, or the CI gates are absent, the skill **degrades to
report-only**: it detects and reports overlaps, states that no store was found at the resolved
path, and makes the apply machinery unavailable rather than erroring or writing a store into a
repository that never asked for one. Report-only is a working outcome, not a failure.

CI wiring is a property of a repository, not of this skill: a consumer wires the self-check into
whatever gate they run, or runs it by hand.

## Verifying an upstream claim

Any claim about what Claude Code itself ships must come from the raw markdown endpoint. `curl -sSL`
`https://code.claude.com/docs/en/skills.md` to a file, then read the file. A summarizing fetch
returns a small model's answer *about* the page, so absence from that answer is not evidence of
absence. A `200` is also not proof you got the page you asked for: retired slugs are silently
aliased, so confirm the slug against `https://code.claude.com/docs/llms.txt` and read the body's
own first heading before citing it.

Two upstream dependencies of this skill, each with the trigger that obliges re-deriving it:

| Decision | Pointer | As of | Recheck when |
|---|---|---|---|
| We treat the description as the routing surface and measure a baked description against a 1,536-character per-entry cap and a listing budget of 1% of the context window. For which entries overflow drops, we use the order our own binary reading records in [`audit-skill-visibility/reference/listing-scorer.md`](../audit-skill-visibility/reference/listing-scorer.md); the docs page and that reading disagree on the drop order | [Frontmatter reference](https://code.claude.com/docs/en/skills#frontmatter-reference), [Skill descriptions are cut short](https://code.claude.com/docs/en/skills#skill-descriptions-are-cut-short), [`skillListingMaxDescChars`](https://code.claude.com/docs/en/settings-reference#skilllistingmaxdescchars), [`skillListingBudgetFraction`](https://code.claude.com/docs/en/settings-reference#skilllistingbudgetfraction); the drop order is our binary reading | 2026-09-01 | Either default moves, or the binary's scorer or grant loop diverges from that reference |
| We make no static availability claim for a native surface, because we treat settings and environment, plan, platform or provider, and host surface as each able to remove one | [`disableBundledSkills`](https://code.claude.com/docs/en/settings-reference#disablebundledskills), [environment variables](https://code.claude.com/docs/en/env-vars), [Commands](https://code.claude.com/docs/en/commands), [What's available in cloud sessions](https://code.claude.com/docs/en/cloud-environments#what%E2%80%99s-available-in-cloud-sessions) | 2026-08-23 | A release or docs change adds, removes, or renames a gating axis |

## Gotchas

- **A plugin skill never shadows a native one.** Ours are namespaced, so both resolve and the model
  chooses. That is why the routing lives in descriptions rather than in a name.
- **`plugin_backed` is its own lane.** `security-review` is reported there, not under
  `builtin_commands`. Read the wrong key and the row looks absent. Pointer: our probe, the
  `plugin_backed` key of an `inventory.py --binary-only` extraction on this machine, which held
  `security-review` and nothing else. As of: 2026-09-29, Claude Code 2.1.284. Recheck trigger:
  the extractor's provenance lanes change or a release note moves a bundled surface between them.
- **A bundled skill can carry aliases.** We treat `review` as an alias of `code-review`, never a
  separate surface, since a separate row would duplicate one capability. Pointer:
  [All commands](https://code.claude.com/docs/en/commands#all-commands), the `/code-review` row,
  and our extraction, which lists `review` as the alias. As of: 2026-09-29, Claude Code 2.1.284.
  Recheck trigger: the commands page drops the alias or a release note renames a bundled skill.
- **Absent from the binary is not absent from the product.** Session-provided skills exist only in
  a live roster. "Not in the extraction" is a statement about the extraction.
- **A verdict is not permanent.** The trigger is the load-bearing part of the row; a date alone
  tells a later reader nothing about whether the verdict still holds.
- **Baked text is self-contained by contract.** A phrase that says "see the native-surfaces
  registry" ships a broken reference to every consumer who installed the plugin.