fix(bump-skill): exclude from npx skills discovery via metadata.internal (#96)

## What

`bump-skill` is repo-maintenance for `agentic-workflow` itself, yet
`npx skills add . --list` still discovered and offered it to every
consumer
— listed under `General` and installable. Fix #40 already made it
`user-invocable: false` and dropped it from `plugin.json`, but neither
lever
gates *discovery*: the CLI scans `skills/*/SKILL.md` directly and the
manifest is additive, not an allowlist.

This fix adds `metadata.internal: true` to `bump-skill`'s frontmatter —
the
`skills` CLI's own supported exclusion mechanism — so `npx skills add .
--list` no longer discovers it, while it keeps working in this repo
(Claude
Code reads the symlinked SKILL.md directly via `.claude/skills →
../skills`,
never through the CLI's discovery path).

## Why

Issue #74's first acceptance criterion required establishing the
`skills`
CLI's actual exclusion capabilities from primary sources before scoping
—
fix #40 had assumed no such mechanism existed, based only on `npx skills
add
--help`. That assumption was wrong.

## Evidence

Read directly from the `skills` npm package's `dist/cli.mjs`, verified
in
both version 1.5.16 (resolved from this machine's npx cache) and 1.5.19
(latest published):

```js
if (data.metadata?.internal === true && !shouldInstallInternalSkills()
    && !options?.includeInternal) return null;
```

```js
function shouldInstallInternalSkills() {
  const envValue = process.env.INSTALL_INTERNAL_SKILLS;
  return envValue === "1" || envValue === "true";
}
```

`.claude-plugin/plugin.json`'s `skills` array is confirmed **additive,
not
an allowlist** — the discovery routine always also pushes `skills/` onto
its
search list regardless of the manifest. There is no `.skillsignore` and
no
other exclusion field.

Before the fix: `npx skills add . --list` → "Found 29 skills",
`bump-skill`
listed under `General`.
After the fix: → "Found 28 skills", `bump-skill` absent;
`INSTALL_INTERNAL_SKILLS=1 npx skills add . --list` → "Found 29 skills",
`bump-skill` present (proves the mechanism, not breakage).

Full write-up:
`docs/fix/74-bump-skill-discovery-exclusion/decisions.md`.

## Scope precision

14 skills in this repo are `user-invocable: false`, but 13 of them
(`orchestration-envelope`, the `review-*` pack, `plan-feature-scaffold`,
`plan-feature-from-issue`) are still listed in `plugin.json` because
orchestrators compose them in target projects — they must stay
discoverable.
Only `bump-skill` satisfies both `user-invocable: false` **and** absence
from `plugin.json`, so it is the only skill marked `metadata.internal:
true`. The new `bump-skill` lint rule (§2b, rule 7) keys on that exact
conjunction to avoid ever flagging the 13 shipped sub-skills.

## Changes

- `skills/bump-skill/SKILL.md` — `metadata.internal: true`; new §2b lint
  rule 7 (internal-skill discovery exclusion); version 2.2.0 → 2.3.0.
- `CLAUDE.md` — one-line note on the repo-internal-skill convention.
- `docs/fix/74-bump-skill-discovery-exclusion/{SPEC.md,decisions.md}` —
this
  unit's SPEC and its recorded architect decision (option 2 chosen over
relocating `bump-skill` out of `skills/` or converting it to a hook —
both
  rejected, rationale in `decisions.md`).
- `CHANGELOG.md` / `CHANGELOG.es.md` / `README.md` / `README.es.md` —
  `bump-skill`'s self-bump documentation trail.
- `docs/fix/README.md` — index row, `done`.

## Options considered (recorded in decisions.md)

1. **Relocate `bump-skill` out of `skills/`** — rejected: breaks the
   `.claude/skills → ../skills` symlink and the uniform layout; kept as
   documented fallback if the CLI mechanism is ever removed upstream.
2. **Use the CLI's own exclusion mechanism** — **chosen**, per the
evidence
   above.
3. **Convert to a hook** (the issue's own alternative) — rejected:
picking a
semver bump and writing changelog/README prose is judgement work a shell
hook cannot do, and it does nothing about discovery, the actual defect.

Closes #74

Author: gtrabanco

CHANGELOG.es.md

@@ -364,7 +364,9 @@ Cómo funciona el pinning realmente, **verificado** contra el CLI `skills`:
 
 | Skill | Versión | Fecha | Tipo | Qué cambió |
 |---|---|---|---|---|
-| `bump-skill` | 2.2.0 | 2026-07-18 | menor | Fix #71/#72/#73: el lint de §2b gana dos comprobaciones de superficies máquina — paridad con `plugin.json` (toda skill `user-invocable: true` tiene su entrada en el array) y orden alfabético de las superficies máquina (array `skills` de `plugin.json` + claves de `model-routing.yml`) — la misma clase de deriva que dejó a `fold-findings` instalarse sin registrar. |
+| `bump-skill` | 2.3.1 | 2026-07-18 | patch | Seguimiento de `review-change` sobre #74/PR #96: se corrigieron las referencias al conteo de reglas del lint §2b ("dos" → "siete" invariantes de autoría de `CLAUDE.md`, en consonancia con "las 7 reglas de autoría" del Turn contract) y se ancló el grep de la regla 7 (exclusión de descubrimiento) al bloque de frontmatter únicamente (región extraída con `awk` entre las dos primeras líneas `---`), de modo que ya no puede satisfacerse con la propia prosa de la regla que menciona `metadata.internal: true` en vez de una clave real de frontmatter. |
+| `bump-skill` | 2.3.0 | 2026-07-18 | menor | Fix #74: `bump-skill` lleva ahora `metadata.internal: true` — el mecanismo propio de la CLI `skills` (verificado en `dist/cli.mjs` 1.5.16/1.5.19) que impide que `npx skills add . --list` descubra u ofrezca skills internas del repo, a diferencia de `user-invocable`/`plugin.json`, que solo rigen el menú posinstalación. El lint de §2b gana una 7ª regla que exige lo mismo para cualquier futura skill interna del repo (conjunción: `user-invocable: false` Y ausente de `plugin.json`). |
+| | 2.2.0 | 2026-07-18 | menor | Fix #71/#72/#73: el lint de §2b gana dos comprobaciones de superficies máquina — paridad con `plugin.json` (toda skill `user-invocable: true` tiene su entrada en el array) y orden alfabético de las superficies máquina (array `skills` de `plugin.json` + claves de `model-routing.yml`) — la misma clase de deriva que dejó a `fold-findings` instalarse sin registrar. |
 | | 2.1.0 | 2026-07-11 | menor | Fix #40: reclasificada como `user-invocable: false` — la skill es mantenimiento del propio repo `agentic-workflow` y su entrada de menú `/bump-skill` era ruido para el ~99% de quienes consumen el paquete sin autorar sus `SKILL.md`. Sin cambio de comportamiento; se sigue ejecutando vía la herramienta Skill o siguiendo `SKILL.md` directamente. Su tabla por skill se traslada de "Mantenimiento del repo" a esta sección Interna. |
 | | 2.0.0 | 2026-07-10 | mayor | **Cambio incompatible:** se elimina la sección `## Machine envelope` y su cláusula de emisión en el contrato de turno — el contrato del envelope se traslada a la capa de orquestación; `workflow-status` sigue siendo el único emisor en línea. Además se retira la regla de lint "Machine envelope", ya obsoleta (exigía que toda skill de cara al usuario llevara la sección — ya no es cierto). Ver `docs/workflow/MIGRATION.md`. |
 | | 1.5.0 | 2026-07-05 | menor | Envelope máquina: cada invocación termina ahora con un bloque JSON fijo (state, unit, phase, pr, findings, blockers, dependencies, next + pista de tier de modelo) para orquestación programática — esquema en la skill interna `orchestration-envelope`, protocolo en `docs/workflow/ORCHESTRATION.md`. El lint gana una 5ª regla: las skills de cara al usuario deben llevar la sección `## Machine envelope`. |
@@ -431,6 +433,24 @@ Cómo funciona el pinning realmente, **verificado** contra el CLI `skills`:
 
 ## Registro cronológico (más reciente primero)
 
+- **2026-07-18 — exclusión de bump-skill del descubrimiento (fix 74).**
+  `bump-skill` es mantenimiento del propio repo `agentic-workflow`, pero
+  `npx skills add . --list` seguía descubriéndola y ofreciéndola a cada
+  consumidor — el fix #40 (`user-invocable: false` + retirada de
+  `plugin.json`) solo rige el menú posinstalación, no el descubrimiento. Se
+  estableció, a partir del código fuente de la propia CLI `skills`
+  (`dist/cli.mjs`, verificado en 1.5.16 y 1.5.19), que `metadata.internal: true`
+  es el mecanismo real de exclusión del descubrimiento — lo que deja sin
+  efecto las opciones de reubicar o convertir en hook que el issue había
+  dejado abiertas. Bump MENOR para `bump-skill` (2.3.0): se añade
+  `metadata.internal: true` a su propio frontmatter, más una 7ª regla de lint
+  en §2b que exige lo mismo para cualquier futura skill interna del repo.
+  Seguimiento del mismo día vía `review-change`: bump PATCH (2.3.1) que
+  corrigió la referencia de conteo obsoleta ("dos" → "siete" invariantes de
+  autoría) y ancló el grep de la regla al bloque de frontmatter únicamente,
+  de modo que ya no puede satisfacerse con la propia prosa descriptiva de la
+  regla.
+
 - **2026-07-18 — paridad de registro de skills (fix 71+72+73).** Se registra
   `fold-findings` en `.claude-plugin/plugin.json` (se instalaba bajo `General`
   en vez de `Agentic Workflow`); se restaura el orden alfabético completo de

CHANGELOG.md

@@ -363,7 +363,9 @@ How pinning actually works, verified against the `skills` CLI:
 
 | Skill | Version | Date | Type | What changed |
 |---|---|---|---|---|
-| `bump-skill` | 2.2.0 | 2026-07-18 | minor | Fix #71/#72/#73: §2b lint gains two machine-surface checks — `plugin.json` parity (every `user-invocable: true` skill has a matching array entry) and machine-surface alphabetical order (`plugin.json` `skills` array + `model-routing.yml` keys) — the exact drift class that let `fold-findings` ship unregistered. |
+| `bump-skill` | 2.3.1 | 2026-07-18 | patch | Review-change follow-up on #74/PR #96: fixed the §2b lint's rule count references ("two" → "seven" `CLAUDE.md` authoring invariants, matching the Turn contract's "all 7 authoring rules") and anchored rule 7's discovery-exclusion check to the frontmatter block only (`awk`-extracted region between the first two `---` lines), so it can no longer be satisfied by the rule's own prose mentioning `metadata.internal: true` instead of an actual frontmatter key. |
+| `bump-skill` | 2.3.0 | 2026-07-18 | minor | Fix #74: `bump-skill` itself now carries `metadata.internal: true` — the `skills` CLI's own gate (verified in `dist/cli.mjs` 1.5.16/1.5.19) that keeps `npx skills add . --list` from discovering/offering repo-internal skills, unlike `user-invocable`/`plugin.json` which only govern the post-install menu. §2b lint gains a 7th rule enforcing the same for any future repo-internal skill (conjunction: `user-invocable: false` AND absent from `plugin.json`). |
+| | 2.2.0 | 2026-07-18 | minor | Fix #71/#72/#73: §2b lint gains two machine-surface checks — `plugin.json` parity (every `user-invocable: true` skill has a matching array entry) and machine-surface alphabetical order (`plugin.json` `skills` array + `model-routing.yml` keys) — the exact drift class that let `fold-findings` ship unregistered. |
 | | 2.1.0 | 2026-07-11 | minor | Fix #40: reclassified `user-invocable: false` — the skill is repo-maintenance for `agentic-workflow` itself and its `/bump-skill` menu entry was pure noise for the ~99% of consumers who don't author this pack's `SKILL.md` files. Behavior unchanged; still run via the Skill tool or by following `SKILL.md` directly. Per-skill table moved from "Repo maintenance" (User-facing-adjacent) to this Internal section. |
 | | 2.0.0 | 2026-07-10 | major | **Breaking:** dropped the `## Machine envelope` section and its turn-contract emission clause — the envelope contract moved to the orchestration layer; `workflow-status` remains the sole inline emitter. Also retired the now-obsolete "Machine envelope" lint rule (it required every user-facing skill to carry the section — no longer true). See `docs/workflow/MIGRATION.md`. |
 | | 1.5.0 | 2026-07-05 | minor | Machine envelope: every invocation now ends with a fixed JSON block (state, unit, phase, pr, findings, blockers, dependencies, next + model-tier hint) for programmatic orchestration — schema in the internal `orchestration-envelope` skill, protocol in `docs/workflow/ORCHESTRATION.md`. Lint gains a 5th rule: user-facing skills must carry the `## Machine envelope` section. |
@@ -430,6 +432,21 @@ How pinning actually works, verified against the `skills` CLI:
 
 ## Release log (chronological, newest first)
 
+- **2026-07-18 — bump-skill discovery exclusion (fix 74).** `bump-skill` is
+  repo-maintenance for `agentic-workflow` itself, yet `npx skills add . --list`
+  still discovered and offered it to every consumer — fix #40's
+  `user-invocable: false` + `plugin.json` removal only gate the post-install
+  menu, not discovery. Established from the `skills` CLI's own source
+  (`dist/cli.mjs`, verified in 1.5.16 and 1.5.19) that `metadata.internal: true`
+  is the CLI's actual discovery-exclusion mechanism, mooting the relocate/hook
+  options the issue had left open. MINOR bump for `bump-skill` (2.3.0):
+  `metadata.internal: true` added to its own frontmatter, plus a 7th §2b lint
+  rule enforcing the same for any future repo-internal skill. Same-day
+  `review-change` follow-up: PATCH bump (2.3.1) fixed the rule's stale count
+  reference ("two" → "seven" authoring invariants) and anchored its grep to
+  the frontmatter block only, so the check can no longer be satisfied by the
+  rule's own descriptive prose.
+
 - **2026-07-18 — skill-registration-parity (fix 71+72+73).** Registered
   `fold-findings` in `.claude-plugin/plugin.json` (it was installing under
   `General` instead of `Agentic Workflow`); restored `docs/workflow/model-routing.yml`

CLAUDE.md

@@ -259,3 +259,6 @@ reusable operational knowledge as a skill under `skills/`.
   This is the mechanical enforcement of the "Version every change" rule above.
   `bump-skill` itself is `user-invocable: false` — invoke it via the Skill
   tool / by following its `SKILL.md` directly, not the slash-command menu.
+  It also carries `metadata.internal: true`, the `skills` CLI's own gate
+  that keeps `npx skills add` from discovering/offering repo-internal
+  skills to target projects (see `docs/fix/74-bump-skill-discovery-exclusion/`).

README.es.md

@@ -158,7 +158,7 @@ con ningún modelo. Un único camino disciplinado:
 
 | Skill        | Qué hace                                                                                                                                                                                                                                                                                                                                                                                                     |
 | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `bump-skill` | Tras editar una skill en este repo: sube la `version:` en el frontmatter del SKILL.md, añade filas en CHANGELOG.md + CHANGELOG.es.md y actualiza las tablas de skills y modelos en README.md + README.es.md. Además **lintea las reglas de autoría del repo** (toda skill cierra con un bloque `→ Next:`; las fases son `P1, P2, …`, nunca `S1`/"Steps") y las **reglas de registro en superficies máquina** (toda skill `user-invocable: true` tiene su entrada correspondiente en `.claude-plugin/plugin.json`; ese array y las claves de `model-routing.yml` se mantienen en orden alfabético). Ejecutar antes de cada commit que toque una skill. |
+| `bump-skill` | Tras editar una skill en este repo: sube la `version:` en el frontmatter del SKILL.md, añade filas en CHANGELOG.md + CHANGELOG.es.md y actualiza las tablas de skills y modelos en README.md + README.es.md. Además **lintea las reglas de autoría del repo** (toda skill cierra con un bloque `→ Next:`; las fases son `P1, P2, …`, nunca `S1`/"Steps") y las **reglas de registro en superficies máquina** (toda skill `user-invocable: true` tiene su entrada correspondiente en `.claude-plugin/plugin.json`; ese array y las claves de `model-routing.yml` se mantienen en orden alfabético; toda skill que sea a la vez `user-invocable: false` y esté ausente de `plugin.json` —interna del repo, sin sentido para un consumidor— lleva `metadata.internal: true`, el mecanismo propio de la CLI `skills` para no aparecer en el descubrimiento de `npx skills add`). Ejecutar antes de cada commit que toque una skill. |
 
 ### Autopilot — el flujo completo, de punta a punta
 

README.md

@@ -153,7 +153,7 @@ plan → execute → review → audit → merge.**
 
 | Skill        | What it does                                                                                                                                                                                                                                                                                                                                                                        |
 | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `bump-skill` | After editing a skill in this repo: bumps `version:` in the SKILL.md frontmatter, adds rows to CHANGELOG.md + CHANGELOG.es.md, and updates the skill and model tables in README.md + README.es.md. Also **lints the repo's authoring rules** (every skill closes with a `→ Next:` block; phases are `P1, P2, …`, never `S1`/"Steps") and the **machine-surface registration rules** (every `user-invocable: true` skill has a matching entry in `.claude-plugin/plugin.json`; that array and `model-routing.yml`'s keys stay alphabetical). Run before every commit that touches a skill. |
+| `bump-skill` | After editing a skill in this repo: bumps `version:` in the SKILL.md frontmatter, adds rows to CHANGELOG.md + CHANGELOG.es.md, and updates the skill and model tables in README.md + README.es.md. Also **lints the repo's authoring rules** (every skill closes with a `→ Next:` block; phases are `P1, P2, …`, never `S1`/"Steps") and the **machine-surface registration rules** (every `user-invocable: true` skill has a matching entry in `.claude-plugin/plugin.json`; that array and `model-routing.yml`'s keys stay alphabetical; any skill that's both `user-invocable: false` and absent from `plugin.json` — repo-internal, meaningless to a consumer — carries `metadata.internal: true`, the `skills` CLI's own mechanism for staying out of `npx skills add` discovery). Run before every commit that touches a skill. |
 
 ### Autopilot — the whole flow, end to end