fix(skills): reclassify bump-skill as internal (#40) (#45)

## What

Reclassifies `bump-skill` as an internal skill (`user-invocable: false`)
and
drops it from the Claude Code plugin manifest, removing the
`/bump-skill`
menu entry from every consumer install via both distribution channels
(the skills CLI's flag-based menu visibility, and the plugin manifest).
Reconciles the skill-count docs that assumed the old user-facing
classification (`15 user-facing + 13 internal` → `14 user-facing + 14
internal`).

## Why

`bump-skill` is repo-maintenance for `agentic-workflow` itself — its own
description already says "Internal skill for the agentic-workflow repo"
—
yet it shipped `user-invocable: true`, so every `npx skills add
gtrabanco/agentic-workflow` consumer got a `/bump-skill` slash-menu
entry
that does nothing for them (they aren't authoring this pack's `SKILL.md`
files or maintaining its `CHANGELOG.md`/`README.md`). It's the one skill
whose menu surface was pure noise for ~99% of installs.

## Changes

- `skills/bump-skill/SKILL.md` — `user-invocable: true` → `false`;
version
bumped `2.0.0` → `2.1.0` (minor: metadata reclassification, no behavior
  change).
- `.claude-plugin/plugin.json` — `./skills/bump-skill` removed from the
  `skills` array (28 → 27 entries).
- `docs/workflow/SKILLS.md` — removed the `/bump-skill` invocation-forms
  row; count updated to `14 user-facing + 14 internal`.
- `README.md` / `README.es.md` — both skill-count occurrences updated
  (English and Spanish).
- `CLAUDE.md` — repo-maintenance note now states `bump-skill` is
  `user-invocable: false`, invoked via the Skill tool.
- `CHANGELOG.md` / `CHANGELOG.es.md` — `bump-skill`'s per-skill history
  moved from the "Repo maintenance" subsection into "Internal
(`user-invocable: false`)"; new `2.1.0` row added; release-log entry
added.
- `docs/fix/README.md` / `docs/fix/40-bump-skill-internal-only/SPEC.md`
—
  fix marked `done`.

**Out of scope** (see SPEC): physically excluding `bump-skill` from a
default `npx skills add` install (the CLI has no
`--exclude`/manifest-skip
mechanism — verified impossible); rewriting historical docs that mention
running `bump-skill`; removing `bump-skill`'s `## Turn contract`/`##
Portability` sections.

## Evidence

```
$ grep -n '^user-invocable:' skills/bump-skill/SKILL.md
3:user-invocable: false

$ python3 -c "import json;d=json.load(open('.claude-plugin/plugin.json'));assert './skills/bump-skill' not in d['skills'];assert len(d['skills'])==27;print('OK')"
OK

$ grep -rn '/bump-skill' docs/workflow/SKILLS.md
(no output)

$ grep -rn '15 user-facing\|13 internal\|15 de cara al usuario\|13 internas' README.md README.es.md docs/workflow/SKILLS.md
(no output)

$ npx skills add . --list
◇  Found 28 skills
```

Closes #40

Author: gtrabanco

.claude-plugin/plugin.json

@@ -20,7 +20,6 @@
   "skills": [
     "./skills/audit-docs",
     "./skills/audit-pr",
-    "./skills/bump-skill",
     "./skills/design-feature",
     "./skills/execute-phase",
     "./skills/generate-docs",

CHANGELOG.es.md

@@ -95,20 +95,6 @@ Cómo funciona el pinning realmente, **verificado** contra el CLI `skills`:
 | 1.0.1 | 2026-06-27 | parche | Cierre normalizado al bloque canónico `→ Next:` |
 | 1.0.0 | 2026-06-19 | — | Nueva skill de diario de sesión. Añade una entrada estructurada a `docs/LOGS.md` (resumen, archivos, decisiones + por qué, siguiente paso) bajo demanda; `model: sonnet` (barato por diseño). Incluye hooks gratuitos y opt-in en `template/.claude/`: captura mecánica en SessionEnd + marcador en SessionStart, y restauración de contexto opt-in en SessionStart — todos sin modelo |
 
-### Mantenimiento del repo
-
-#### `bump-skill`
-| Versión | Fecha | Tipo | Qué cambió |
-|---|---|---|---|
-| 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`. |
-| 1.3.1 | 2026-07-04 | parche | Sin cambio de comportamiento: el frontmatter `model:`/`effort:` de esta skill se trasladó a `docs/workflow/model-routing.yml` (usado solo para construir la rama `#claude`); la guía sobre modelos no-Claude en la descripción se sustituyó por un puntero a `#claude`. |
-| 1.3.0 | 2026-07-03 | menor | El lint comprueba también la nueva sección `## Turn contract` en las skills de cara al usuario. |
-| 1.2.1 | 2026-07-02 | parche | Nota de equivalencia de modelos en la descripción (edita model:/effort: para modelos no-Claude / de libre inferencia). |
-| 1.2.0 | 2026-07-02 | minor | El lint ahora comprueba también que las skills de cara al usuario llevan la sección `## Portability`; añadida su propia nota de Portability. |
-| 1.1.0 | 2026-06-27 | menor | Paso de lint que marca las skills editadas sin bloque `→ Next:` o con etiquetas de fase `S1`/"Step" (avisa, nunca corrige solo) |
-| 1.0.0 | 2026-06-19 | — | Nueva skill de mantenimiento del repo. Tras editar un SKILL.md, sube la `version:`, añade filas en CHANGELOG.md + CHANGELOG.es.md y actualiza las tablas de skills y modelos en README.md + README.es.md |
-
 ### De cara al usuario
 
 #### `generate-docs`
@@ -338,6 +324,15 @@ Cómo funciona el pinning realmente, **verificado** contra el CLI `skills`:
 
 | Skill | Versión | Fecha | Tipo | Qué cambió |
 |---|---|---|---|---|
+| `bump-skill` | 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`. |
+| | 1.3.1 | 2026-07-04 | parche | Sin cambio de comportamiento: el frontmatter `model:`/`effort:` de esta skill se trasladó a `docs/workflow/model-routing.yml` (usado solo para construir la rama `#claude`); la guía sobre modelos no-Claude en la descripción se sustituyó por un puntero a `#claude`. |
+| | 1.3.0 | 2026-07-03 | menor | El lint comprueba también la nueva sección `## Turn contract` en las skills de cara al usuario. |
+| | 1.2.1 | 2026-07-02 | parche | Nota de equivalencia de modelos en la descripción (edita model:/effort: para modelos no-Claude / de libre inferencia). |
+| | 1.2.0 | 2026-07-02 | minor | El lint ahora comprueba también que las skills de cara al usuario llevan la sección `## Portability`; añadida su propia nota de Portability. |
+| | 1.1.0 | 2026-06-27 | menor | Paso de lint que marca las skills editadas sin bloque `→ Next:` o con etiquetas de fase `S1`/"Step" (avisa, nunca corrige solo) |
+| | 1.0.0 | 2026-06-19 | — | Nueva skill de mantenimiento del repo. Tras editar un SKILL.md, sube la `version:`, añade filas en CHANGELOG.md + CHANGELOG.es.md y actualiza las tablas de skills y modelos en README.md + README.es.md |
 | `orchestration-envelope` | 1.1.1 | 2026-07-10 | parche | Fix #33: la descripción del frontmatter y la sección de apertura aún enunciaban el contrato previo a la feature 10 ("toda skill de cara al usuario imprime el envelope") POR ENCIMA de la corrección de la feature 10 — reescritas de cabeza al contrato vigente (esquema + regla de parseo último-json-cercado como núcleo; emisión = `workflow-status` siempre, el resto de skills solo bajo el snippet inyectado por el driver, nada en sesiones interactivas). La misma frase obsoleta corregida en `packages/agentic-workflow-schema/README.md`, `package.json`, `src/index.ts` y `envelope.schema.json` (solo texto de descripción/comentario/metadatos, sin cambio de forma del esquema ni de comportamiento, sin release del paquete). |
 | | 1.1.0 | 2026-07-10 | menor | Nueva sección `## Driver system-prompt snippet + repair loop`: el snippet canónico de system-prompt inyectado por el driver (verbatim, cercado) y el protocolo de bucle de reparación (fallo de parseo → reinvocar con "Emit only the machine envelope for the turn above.", un reintento, luego FAILED del driver) — el requisito del envelope se traslada aquí desde los contratos de turno por skill de las 14 skills de cara al usuario. |
 | | 1.0.0 | 2026-07-05 | — | Nuevo contrato interno: el esquema JSON del envelope máquina (11 estados, claves fijas, regla de parseo último-json-cercado) que toda skill de cara al usuario emite como su salida final absoluta. |
@@ -392,6 +387,15 @@ Cómo funciona el pinning realmente, **verificado** contra el CLI `skills`:
 
 ## Registro cronológico (más reciente primero)
 
+- **2026-07-11 — bump-skill reclasificada como interna (fix #40).** Bump
+  MENOR para `bump-skill` (2.1.0): `user-invocable: false` y eliminada del
+  array `skills` de `.claude-plugin/plugin.json` — la skill es mantenimiento
+  del propio repo `agentic-workflow`, así que su entrada de menú
+  `/bump-skill` era ruido para el ~99% de quienes solo consumen el paquete.
+  Sin cambio de comportamiento; se sigue ejecutando vía la herramienta Skill.
+  Conteos de skills reconciliados en `README.md`, `README.es.md` y
+  `docs/workflow/SKILLS.md` (15 de cara al usuario + 13 internas → 14 + 14).
+  Cierra #40.
 - **2026-07-11 — cierre por fases para unidades de pase único (fix #35).**
   Bumps MENORES de `plan-fix` (2.1.0), `plan-feature-scaffold` (1.8.0) y
   `execute-phase` (2.1.0): todo SPEC de fix y de feature XS/S lleva ahora un

CHANGELOG.md

@@ -93,20 +93,6 @@ How pinning actually works, verified against the `skills` CLI:
 | 1.0.1 | 2026-06-27 | patch | Closing normalized to the canonical `→ Next:` recommendation block |
 | 1.0.0 | 2026-06-19 | — | New session-journal skill. Appends a structured entry to `docs/LOGS.md` (summary, files, decisions + why, next step) on demand; `model: sonnet` (cheap by design). Ships with free, opt-in `template/.claude/` hooks: SessionEnd mechanical capture + SessionStart marker, and an opt-in SessionStart context-restore — all model-free |
 
-### Repo maintenance
-
-#### `bump-skill`
-| Version | Date | Type | What changed |
-|---|---|---|---|
-| 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. |
-| 1.3.1 | 2026-07-04 | patch | No behavior change: this skill's `model:`/`effort:` frontmatter moved to `docs/workflow/model-routing.yml` (used only to build the `#claude` branch); the description's non-Claude guidance was replaced with a pointer to `#claude`. |
-| 1.3.0 | 2026-07-03 | minor | Lint also checks the new `## Turn contract` section on user-facing skills. |
-| 1.2.1 | 2026-07-02 | patch | Model-equivalence note in the description (edit model:/effort: for non-Claude / free-inference models). |
-| 1.2.0 | 2026-07-02 | minor | Lint now also checks that user-facing skills carry the `## Portability` section; added its own Portability note. |
-| 1.1.0 | 2026-06-27 | minor | Lint step flags edited skills missing a `→ Next:` block or using `S1`/"Step" phase labels (warns, never auto-fixes) |
-| 1.0.0 | 2026-06-19 | — | New repo-maintenance skill. After editing a SKILL.md, bumps `version:`, adds rows to CHANGELOG.md + CHANGELOG.es.md, and updates the skills and model tables in README.md + README.es.md |
-
 ### User-facing
 
 #### `generate-docs`
@@ -336,6 +322,15 @@ How pinning actually works, verified against the `skills` CLI:
 
 | Skill | Version | Date | Type | What changed |
 |---|---|---|---|---|
+| `bump-skill` | 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. |
+| | 1.3.1 | 2026-07-04 | patch | No behavior change: this skill's `model:`/`effort:` frontmatter moved to `docs/workflow/model-routing.yml` (used only to build the `#claude` branch); the description's non-Claude guidance was replaced with a pointer to `#claude`. |
+| | 1.3.0 | 2026-07-03 | minor | Lint also checks the new `## Turn contract` section on user-facing skills. |
+| | 1.2.1 | 2026-07-02 | patch | Model-equivalence note in the description (edit model:/effort: for non-Claude / free-inference models). |
+| | 1.2.0 | 2026-07-02 | minor | Lint now also checks that user-facing skills carry the `## Portability` section; added its own Portability note. |
+| | 1.1.0 | 2026-06-27 | minor | Lint step flags edited skills missing a `→ Next:` block or using `S1`/"Step" phase labels (warns, never auto-fixes) |
+| | 1.0.0 | 2026-06-19 | — | New repo-maintenance skill. After editing a SKILL.md, bumps `version:`, adds rows to CHANGELOG.md + CHANGELOG.es.md, and updates the skills and model tables in README.md + README.es.md |
 | `orchestration-envelope` | 1.1.1 | 2026-07-10 | patch | Fix #33: the frontmatter description and opening section still stated the pre-feature-10 contract ("every user-facing skill prints the envelope") ABOVE the feature-10 correction — rewritten head-first to the current contract (schema + last-fenced-json parse rule as the core; emission = `workflow-status` always, other skills only under the driver-injected snippet, nothing in interactive sessions). Same stale sentence fixed in `packages/agentic-workflow-schema/README.md`, `package.json`, `src/index.ts`, and `envelope.schema.json` (description/comment/metadata text only, no schema-shape or code-behavior change, no package release needed). |
 | | 1.1.0 | 2026-07-10 | minor | New `## Driver system-prompt snippet + repair loop` section: the canonical driver-injected system-prompt snippet (verbatim, fenced) and the repair-loop protocol (parse-fail → re-invoke with "Emit only the machine envelope for the turn above.", one retry, then driver-level FAILED) — the envelope requirement moved here from the 14 user-facing skills' per-skill turn contracts. |
 | | 1.0.0 | 2026-07-05 | — | New internal contract: the machine-envelope JSON schema (11 states, fixed keys, last-fenced-json parse rule) every user-facing skill emits as its absolute last output. |
@@ -390,6 +385,15 @@ How pinning actually works, verified against the `skills` CLI:
 
 ## Release log (chronological, newest first)
 
+- **2026-07-11 — bump-skill reclassified internal (fix #40).** MINOR bump for
+  `bump-skill` (2.1.0): `user-invocable: false` and dropped from
+  `.claude-plugin/plugin.json`'s `skills` array — the skill is
+  repo-maintenance for `agentic-workflow` itself, so its `/bump-skill` menu
+  entry was noise for the ~99% of consumers who don't author this pack's
+  `SKILL.md` files. No behavior change; still run via the Skill tool. Skill
+  counts reconciled across `README.md`, `README.es.md`, and
+  `docs/workflow/SKILLS.md` (15 user-facing + 13 internal → 14 + 14). Closes
+  #40.
 - **2026-07-11 — phased close-out for single-pass units (fix #35).** MINOR
   bumps for `plan-fix` (2.1.0), `plan-feature-scaffold` (1.8.0), and
   `execute-phase` (2.1.0): every fix SPEC and XS/S feature SPEC now carries a

CLAUDE.md

@@ -238,3 +238,5 @@ reusable operational knowledge as a skill under `skills/`.
   It bumps `version:`, adds changelog rows to `CHANGELOG.md` and
   `CHANGELOG.es.md`, and updates the skills and model tables in both READMEs.
   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.

README.es.md

@@ -54,7 +54,7 @@ agente** que lea skills — Claude Code, Cursor, Codex, OpenCode, Cline y
 ## Qué incluye
 
 ```
-skills/                  las 28 skills (15 de cara al usuario + 13 internas) — la fuente instalable
+skills/                  las 28 skills (14 de cara al usuario + 14 internas) — la fuente instalable
 .claude/skills           symlink → ../skills, para que este repo las use en Claude Code
 template/                 el scaffold de documentación exportable (el sustrato que leen las skills)
 docs/workflow/           el tutorial completo (flujo de feature, de issue, referencia, replicación)
@@ -71,11 +71,12 @@ plantillas de GitHub). Genera la forma de trabajo de un proyecto nuevo con
 
 ## Las skills
 
-**15 skills de cara al usuario** (una entrada de menú cada una) + **13 internas**
+**14 skills de cara al usuario** (una entrada de menú cada una) + **14 internas**
 que se componen por ti: los dos pasos de planificación del router `plan-feature`,
-el motor de `review-change`, el contrato `orchestration-envelope`, y el **pack de revisión interno propio de 9 skills**
+el motor de `review-change`, el contrato `orchestration-envelope`, el **pack de revisión interno propio de 9 skills**
 (`review-code`, `review-security`, `review-verify`, `review-debt`,
-`review-design`, `review-a11y`, `review-brand`, `review-perf`, `review-seo`) —
+`review-design`, `review-a11y`, `review-brand`, `review-perf`, `review-seo`), y
+el ayudante de mantenimiento interno `bump-skill` —
 así que **nunca se requiere una skill de revisión externa**, en ningún agente y
 con ningún modelo. Un único camino disciplinado:
 **design → plan → execute → review → audit → merge.**

README.md

@@ -53,7 +53,7 @@ reads skills — Claude Code, Cursor, Codex, OpenCode, Cline, and
 ## What's inside
 
 ```
-skills/                  the 28 skills (15 user-facing + 13 internal) — the installable source
+skills/                  the 28 skills (14 user-facing + 14 internal) — the installable source
 .claude/skills           symlink → ../skills, so this repo dogfoods them in Claude Code
 template/                 the exportable documentation scaffold (the substrate the skills read)
 docs/workflow/           the full tutorial (feature flow, issue flow, reference, replication)
@@ -70,13 +70,14 @@ templates). Scaffold a new project's way of working with
 
 ## The skills
 
-**15 user-facing skills** (one menu entry each) + **13 internal** ones composed
+**14 user-facing skills** (one menu entry each) + **14 internal** ones composed
 for you: the `plan-feature` router's two planning steps, the `review-change`
-engine, the `orchestration-envelope` contract, and the workflow's **own 9-skill internal review pack** (`review-code`,
+engine, the `orchestration-envelope` contract, the workflow's **own 9-skill internal review pack** (`review-code`,
 `review-security`, `review-verify`, `review-debt`, `review-design`,
-`review-a11y`, `review-brand`, `review-perf`, `review-seo`) — so **no external
-review skill is ever required**, on any agent, with any model. One disciplined
-path: **design → plan → execute → review → audit → merge.**
+`review-a11y`, `review-brand`, `review-perf`, `review-seo`), and the repo-only
+`bump-skill` maintenance helper — so **no external review skill is ever
+required**, on any agent, with any model. One disciplined path: **design →
+plan → execute → review → audit → merge.**
 
 > Every skill's invocation forms and flags (`--fix`, `--force`,
 > `--adversarial N`, `--next`, `--fullauto`, …) are catalogued in the