# Changelog

All notable changes to this skill will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/2.0.0/),
and this skill adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [0.8.4] - 2026-09-09

### Removed
- Removed `disable-model-invocation`, so the skill can be invoked by the model as well as by `/name`.

## [0.8.3] - 2026-09-09

### Changed
- Description condensed to fit the repo's 250-character limit.

## [0.8.2] - 2026-08-21

### Changed

- Declared ClawHub browse categories (`agents, automation`) and topics in `metadata`, so the release pipeline publishes them instead of leaving the skill in the `other` category.

### Removed

- `skill-card.md`. The ClawHub CLI strips a root `skill-card.md` from every publish and the registry generates its own card, so the authored file never reached ClawHub.

## [0.8.1] - 2026-07-22

### Added

- skill-card.md release record following NVIDIA's skill-card format
- metadata.openclaw block (emoji, homepage) for ClawHub display

## [0.8.0] - 2026-07-10

### Added
- Worktree lifecycle hardening from real runs: keep the worktree until the PR merges (follow-up rounds reuse it), remove the worktree before deleting its branch, `git worktree prune` for stale entries, and regenerate (never hand-merge) generated-file conflicts like README.md on rebase.
- Phase 3 line-budget planning: report the projected SKILL.md size when additive rows land and plan a references/ split when it would exceed the repo's cap.
- Phase 5 failure-attribution step: when the validation gate fails in a way unrelated to the edits, stash and re-run on a clean tree before debugging.
- Phase 3 public-vs-private scope call on usage-derived findings: private-infra learnings go to user memory/CLAUDE.md, never the public skill.
- Phase 2 research inputs: ground-truth CLI-wrapping skills against the live installed CLI, and accept user-supplied seed findings as explicit leads.
- Operating rule for duplicate/scheduled triggers firing mid-run: hold at the emitted gate, never redo research.
- Phase 4 authoring caution: never let a `!` at line start or after whitespace directly touch a backticked command in SKILL.md bodies (Claude Code executes it at load, even in code fences).
- Phase 1 pre-flight now verifies LICENSE.txt presence; Done phase reminds to propagate published updates to installed copies; Phase 7 batches multi-skill updates into one push when CI republishes per push.
- `metadata.upstream` now tracks `keep-a-changelog@2.0.0` - the spec the skill embeds a template of, whose releases invalidate content (proven this run).

### Changed
- Keep a Changelog citations and the bootstrap header template moved from 1.1.0 to 2.0.0 (six change types and dates unchanged; adds the `**Breaking:**` marker convention and version-pinned format links).
- Phase 2 notes subagents run in the background by default (Claude Code v2.1.198+): collect all completions before Phase 3.
- Phase 7 feature-branch flow now follows through merge: watch the default-branch publish CI after the PR merges (some repos have no PR CI at all), then clean up branch and worktree.

### Fixed
- Bootstrap upstream proposal no longer promotes incidentally-mentioned tools: candidates must be things whose releases would invalidate the skill's content.
- Phase 6 leak scan explicitly covers untracked new files, which `git diff` misses.

Verified against: keep-a-changelog@2.0.0

## [0.7.0] - 2026-06-16

### Added
- Phase 0 worktree choice: the run now asks once whether to operate in a dedicated git worktree (`git worktree add ... -b chore/update-<name>`), enabling parallel updates of multiple skills without README/index/diff contention. All phases operate against a new `<workdir>` variable (the worktree if chosen, else `${CLAUDE_PROJECT_DIR}`); the existing Phase 7 branch guard handles the resulting feature-branch PR flow, and the worktree is removed after the run.

## [0.6.0] - 2026-06-05

### Added
- Restored the `argument-hint: "[skill-name]"` frontmatter field removed in 0.5.0. It is a valid, functional Claude Code field for user-invoked skills (used in Anthropic's own `skills/<name>/SKILL.md` examples) and is documented in this repo's `skills-best-practices`; it is simply outside the open Agent Skills spec, which ignores unknown fields.

### Fixed
- Aligned the repo linter (`scripts/check_skills.py`) with the optional Claude Code skill/command fields documented in `skills-best-practices` (`argument-hint`, `when_to_use`, `arguments`, `model`, `effort`, `context`, `agent`, `hooks`). The previous allowlist rejected fields the repo's own guidance endorses.

## [0.5.0] - 2026-06-05

### Added
- Apache-2.0 `LICENSE.txt` (required for publishing).
- Upstreamless-by-nature escape hatch: skills that wrap no package/spec/doc (workflow or writing skills) cleanly omit `metadata.upstream` and skip the bootstrap upstream-candidate proposal instead of being nagged.

### Changed
- Generalized for use in any skills repository. The pond usage angle is now optional with an explicit skip-and-fallback when the pond MCP is absent (https://pond.cascade.fyi/). Phase 5 reframed as a repo-agnostic validation gate, and Phase 7 defers publish/slug/release-tag specifics to the repo's own pipeline (CLAUDE.md/AGENTS.md) instead of hardcoding this repo's ClawHub scripts and release-tag naming.

### Removed
- `argument-hint` frontmatter field to pass the repo's lint allowlist (restored in 0.6.0 once the allowlist was corrected; the body already handles the no-argument case regardless).

Apache License
Version 2.0, January 2004
https://www.apache.org/licenses/

TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

1. Definitions.

"License" shall mean the terms and conditions for use, reproduction, and
distribution as defined by Sections 1 through 9 of this document.

"Licensor" shall mean the copyright owner or entity authorized by the
copyright owner that is granting the License.

"Legal Entity" shall mean the union of the acting entity and all other
entities that control, are controlled by, or are under common control with
that entity. For the purposes of this definition, "control" means (i) the
power, direct or indirect, to cause the direction or management of such
entity, whether by contract or otherwise, or (ii) ownership of fifty percent
(50%) or more of the outstanding shares, or (iii) beneficial ownership of
such entity.

"You" (or "Your") shall mean an individual or Legal Entity exercising
permissions granted by this License.

"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation source, and
configuration files.

"Object" form shall mean any form resulting from mechanical transformation or
translation of a Source form, including but not limited to compiled object
code, generated documentation, and conversions to other media types.

"Work" shall mean the work of authorship, whether in Source or Object form,
made available under the License, as indicated by a copyright notice that is
included in or attached to the work (an example is provided in the Appendix
below).

"Derivative Works" shall mean any work, whether in Source or Object form,
that is based on (or derived from) the Work and for which the editorial
revisions, annotations, elaborations, or other modifications represent, as a
whole, an original work of authorship. For the purposes of this License,
Derivative Works shall not include works that remain separable from, or
merely link (or bind by name) to the interfaces of, the Work and Derivative
Works thereof.

"Contribution" shall mean any work of authorship, including the original
version of the Work and any modifications or additions to that Work or
Derivative Works thereof, that is intentionally submitted to Licensor for
inclusion in the Work by the copyright owner or by an individual or Legal
Entity authorized to submit on behalf of the copyright owner. For the
purposes of this definition, "submitted" means any form of electronic, verbal,
or written communication sent to the Licensor or its representatives,
including but not limited to communication on electronic mailing lists, source
code control systems, and issue tracking systems that are managed by, or on
behalf of, the Licensor for the purpose of discussing and improving the Work,
but excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."

"Contributor" shall mean Licensor and any individual or Legal Entity on
behalf of whom a Contribution has been received by Licensor and subsequently
incorporated within the Work.

2. Grant of Copyright License. Subject to the terms and conditions of this
License, each Contributor hereby grants to You a perpetual, worldwide,
non-exclusive, no-charge, royalty-free, irrevocable copyright license to
reproduce, prepare Derivative Works of, publicly display, publicly perform,
sublicense, and distribute the Work and such Derivative Works in Source or
Object form.

3. Grant of Patent License. Subject to the terms and conditions of this
License, each Contributor hereby grants to You a perpetual, worldwide,
non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this
section) patent license to make, have made, use, offer to sell, sell, import,
and otherwise transfer the Work, where such license applies only to those
patent claims licensable by such Contributor that are necessarily infringed by
their Contribution(s) alone or by combination of their Contribution(s) with
the Work to which such Contribution(s) was submitted. If You institute patent
litigation against any entity (including a cross-claim or counterclaim in a
lawsuit) alleging that the Work or a Contribution incorporated within the Work
constitutes direct or contributory patent infringement, then any patent
licenses granted to You under this License for that Work shall terminate as of
the date such litigation is filed.

4. Redistribution. You may reproduce and distribute copies of the Work or
Derivative Works thereof in any medium, with or without modifications, and in
Source or Object form, provided that You meet the following conditions:

(a) You must give any other recipients of the Work or Derivative Works a copy
of this License; and

(b) You must cause any modified files to carry prominent notices stating that
You changed the files; and

(c) You must retain, in the Source form of any Derivative Works that You
distribute, all copyright, patent, trademark, and attribution notices from
the Source form of the Work, excluding those notices that do not pertain to
any part of the Derivative Works; and

(d) If the Work includes a "NOTICE" text file as part of its distribution,
then any Derivative Works that You distribute must include a readable copy of
the attribution notices contained within such NOTICE file, excluding those
notices that do not pertain to any part of the Derivative Works, in at least
one of the following places: within a NOTICE text file distributed as part of
the Derivative Works; within the Source form or documentation, if provided
along with the Derivative Works; or, within a display generated by the
Derivative Works, if and wherever such third-party notices normally appear.
The contents of the NOTICE file are for informational purposes only and do not
modify the License. You may add Your own attribution notices within Derivative
Works that You distribute, alongside or as an addendum to the NOTICE text from
the Work, provided that such additional attribution notices cannot be
construed as modifying the License.

You may add Your own copyright statement to Your modifications and may provide
additional or different license terms and conditions for use, reproduction, or
distribution of Your modifications, or for any such Derivative Works as a
whole, provided Your use, reproduction, and distribution of the Work otherwise
complies with the conditions stated in this License.

5. Submission of Contributions. Unless You explicitly state otherwise, any
Contribution intentionally submitted for inclusion in the Work by You to the
Licensor shall be under the terms and conditions of this License, without any
additional terms or conditions. Notwithstanding the above, nothing herein
shall supersede or modify the terms of any separate license agreement you may
have executed with Licensor regarding such Contributions.

6. Trademarks. This License does not grant permission to use the trade names,
trademarks, service marks, or product names of the Licensor, except as
required for reasonable and customary use in describing the origin of the Work
and reproducing the content of the NOTICE file.

7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
writing, Licensor provides the Work (and each Contributor provides its
Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied, including, without limitation, any warranties
or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any risks
associated with Your exercise of permissions under this License.

8. Limitation of Liability. In no event and under no legal theory, whether in
tort (including negligence), contract, or otherwise, unless required by
applicable law (such as deliberate and grossly negligent acts) or agreed to in
writing, shall any Contributor be liable to You for damages, including any
direct, indirect, special, incidental, or consequential damages of any
character arising as a result of this License or out of the use or inability to
use the Work (including but not limited to damages for loss of goodwill, work
stoppage, computer failure or malfunction, or any and all other commercial
damages or losses), even if such Contributor has been advised of the
possibility of such damages.

9. Accepting Warranty or Additional Liability. While redistributing the Work
or Derivative Works thereof, You may choose to offer, and charge a fee for,
acceptance of support, warranty, indemnity, or other liability obligations
and/or rights consistent with this License. However, in accepting such
obligations, You may act only on Your own behalf and on Your sole
responsibility, not on behalf of any other Contributor, and only if You agree
to indemnify, defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason of your
accepting any such warranty or additional liability.

END OF TERMS AND CONDITIONS

---
name: update-skill
description: Thorough on-demand refresh of one skill in a skills repo - researches usage, upstream, and docs in parallel, gates twice for approval, bumps version, updates CHANGELOG, validates, commits, watches CI. Use to check a skill's freshness.
argument-hint: "[skill-name]"
metadata:
  version: "0.8.4"
  categories: "agents, automation"
  topics: "skill-maintenance, versioning, changelog, research, agent-skills"
  openclaw:
    homepage: https://github.com/tenequm/skills/tree/main/skills/update-skill
    emoji: "🔄"
  upstream: "keep-a-changelog@2.0.0"
---

# Update Skill

Run a thorough on-demand refresh of one skill in a skills repository. Two hard human-approval gates ensure no edits or commits happen without explicit confirmation.

The target skill is: $ARGUMENTS

If no argument was provided, run `ls ${CLAUDE_PROJECT_DIR}/skills/` and ask the user which to update. Stop until confirmed. Then verify `${CLAUDE_PROJECT_DIR}/skills/$ARGUMENTS/SKILL.md` exists; if not, list skills and ask again. Throughout this run, `<name>` refers to the resolved skill name.

## Operating rules

These rules apply across all phases:

- **GATE 1 stops before any edit.** Do NOT call Edit or Write until the user replies affirmatively to the GATE 1 banner.
- **GATE 2 stops before any commit or push.** Do NOT run `git commit` or `git push` until the user replies affirmatively to the GATE 2 banner.
- **Privacy scan is a hard blocker.** Skills in a public repo can publish on merge, so the run does not reach a commit while a Phase 6 leak finding is unresolved.
- **Sticky posture.** Once GATE 1 has been emitted, "report findings first" persists across follow-up rounds in the same session. If the user replies `changes` or asks for revisions, re-emit the gate after revising; never silently apply.
- **Non-resume.** If the session is interrupted between GATE 1 and GATE 2, re-run `/update-skill <name>` from scratch. There is no checkpoint or resume mechanism.
- **Duplicate triggers.** If a scheduled task or a repeated invocation fires while a run is holding at a gate, hold at the emitted gate and answer from the existing report - never redo research or re-apply edits.
- **No `--no-verify`, no `--amend`, no force-push** unless the user explicitly authorizes it for this run. Per the repo's CLAUDE.md or AGENTS.md.
- **Working directory.** Every path, every `just check`, and every working git command (`status`/`diff`/`add`/`commit`/`push`) in the phases below runs against `<workdir>` - the worktree created in Phase 0 if the user opted in, otherwise `${CLAUDE_PROJECT_DIR}`. Use absolute paths under `<workdir>`; do not mix in the main checkout once a worktree is chosen. The exception is Phase 0's own `git worktree add`/`remove`, which must run against `${CLAUDE_PROJECT_DIR}` (the main checkout).

## Phase 0 - Worktree choice (ask first)

After resolving `<name>`, ask exactly once: "Run this update in a dedicated git worktree, so you can update other skills in parallel? (yes / no)". Wait for the reply.

- **no** (default) -> set `<workdir>` = `${CLAUDE_PROJECT_DIR}` and proceed to Phase 1 in the current checkout.
- **yes** -> create an isolated worktree on a fresh branch and use it as `<workdir>` for the entire run:
  ```bash
  git -C "${CLAUDE_PROJECT_DIR}" worktree add "${CLAUDE_PROJECT_DIR}/../skills-<name>" -b chore/update-<name>
  ```
  Set `<workdir>` = `${CLAUDE_PROJECT_DIR}/../skills-<name>`. If that path or branch already exists, add the same numeric suffix (`-2`, `-3`, ...) to both the worktree path and the branch name until both are free, and carry that suffix into `<workdir>`. Every later phase - reads, edits, `just check`, diff review, commit, push - operates inside `<workdir>`. The Phase 7 branch guard will see `chore/update-<name>` and route to the push + PR flow automatically. Keep the worktree until the PR is **merged** - follow-up review rounds reuse it instead of recreating it. Then clean up in order: `git -C "${CLAUDE_PROJECT_DIR}" worktree remove "<workdir>"` first, then delete the branch (`git branch -d chore/update-<name>`) - a branch delete fails while a worktree still holds the branch. `git worktree remove` refuses if there are uncommitted changes (leave it in place and tell the user if so); `git worktree prune` clears stale entries left by interrupted runs. If a generated file (e.g. `README.md`) conflicts when the PR falls behind the default branch, rebase and re-run the generator - never hand-merge generated output. If the user aborts before a PR exists, remove the worktree and delete the branch the same way.

## Phase 1 - Pre-flight read

Read every file in `skills/<name>/` end-to-end, in parallel:
- `skills/<name>/SKILL.md`
- All files under `skills/<name>/references/` (use Glob first to enumerate)
- `skills/<name>/CHANGELOG.md` (if present)

Capture state for the rest of the run:
- `metadata.version` (current)
- `metadata.upstream` (current; parse to `{name: version}` map; empty if absent)
- Topmost CHANGELOG entry date (if `CHANGELOG.md` exists; this is the "last verified" signal)
- `git log -1 --format=%cs -- skills/<name>/` date (last touch)
- `LICENSE.txt` (or the repo's equivalent) present and non-empty - publish pipelines and repo linters commonly hard-fail without it; if missing, queue a fix row in the Phase 3 report
- `bootstrap_needed` flag = true if `metadata.upstream` is missing OR `CHANGELOG.md` is missing - **unless the skill is upstreamless by nature** (it wraps no package, spec, or living doc - e.g. a workflow or writing skill like `polish`). For those, omitting `metadata.upstream` is correct, not a gap: derive `bootstrap_needed` from the missing `CHANGELOG.md` alone and skip the upstream-candidate proposal.

## Phase 2 - Parallel research

Dispatch three research subagents in a single message, one per angle. Subagents run in the background by default (Claude Code v2.1.198+): collect every agent's completion before starting Phase 3. If the user supplied a seed finding (a bug they hit, a release they know about), pass it verbatim to the relevant agent - specific leads converge fastest. **Adapt each angle to the skill**: a skill wrapping a package researches that package's releases and source; a skill tracking living docs or a spec researches those docs and their source repos; a skill with no upstream at all still gets the usage angle.

- **Usage** (pond - optional): if the pond MCP (`mcp__pond__pond_search`) is available, mine it with NO `project` filter for footguns, scenario-specific breakage, inefficiencies, gaps, and recurring misunderstandings the skill could absorb. Keep the query semantic (concepts, not project names); scope with filters. These are **advisory leads, not facts** - never verified, ground-checked in Phase 3. **If pond is not installed, skip this angle entirely** - dispatch only the upstream and docs agents, and note "Usage angle skipped: pond MCP not available (https://pond.cascade.fyi/)" in the Phase 3 report.
- **Upstream**: releases, commits, and merged PRs since the last-verified date. Read real source - clone to a local scratch dir (e.g. `~/pjv/<owner>/<repo>`, lowercase) or use the GitHub MCP pinned to a concrete tag/SHA. For skills wrapping a CLI, also ground-truth against the live installed binary (`<cmd> --help`, real invocations) - docs and clones lag shipped behavior.
- **Docs**: the current canonical docs, read from source (raw `.md` or cloned repo), not model-summarized. Two distinct jobs, **both required**:
  - **(a) Drift check** - compare the docs against the skill's current `SKILL.md` and `references/`, flagging API changes, deprecated or removed symbols, and patterns the skill should adopt. This is anchored to what the skill already says.
  - **(b) Coverage sweep** - enumerate upstream's *current* feature/concept surface from the docs nav / table of contents, the API index, and the "what's new" / changelog. List every major capability, primitive, or concept the skill has **zero mention of**. Do NOT anchor this to existing skill content - the whole point is to find net-new surface the skill is silent about (`ADD` findings). This is the step a "verify what's there" pass structurally misses.

Every finding is one bulleted line: `[KIND]` (`ADD`/`CHANGE`/`DEPRECATE`/`REMOVE`/`FIX`/`SECURITY`), a one-line summary, an exact quote from the source (no paraphrase), and a citation. pond findings also carry `status: advisory`. Merge all returns into one list, deduped by `(KIND, citation)`.

## Phase 3 - Verify, report, GATE 1

### Ground-truth verification (before the report)

No row ships unverified. Before a finding becomes a row, confirm it against primary source read **today**:

- Verify the finding's claim **and the existing skill text it touches** - links, enumerated lists, pinned versions, version-coupled examples. Spot-check the skill's other upstream-coupled claims even where no finding landed; silent staleness is the common miss.
- A row asserting upstream state (a bug, API shape, version, behavior) cites the primary source checked - cloned `repo@SHA file:line`, a release, or a docs URL; a pond citation alone is insufficient, so re-ground it or drop it. A row that is purely experiential enrichment (a recurring gap or confusion) may keep its pond citation, but verify the wording you write is technically correct.
- Drop a pond-reported bug already fixed upstream; correct any finding whose pond framing the source contradicts.
- **Coverage-gap rows** (net-new concepts from the Phase 2(b) sweep) are verified two ways: confirm the concept exists in today's source (cite it), **and** confirm the skill genuinely omits it - grep the skill for the concept and any synonyms before claiming it's absent, so a renamed-but-present feature isn't reported as missing.
- Scope-check every usage-derived row: a learning about private infrastructure (internal hosts, personal tooling, machine-specific setups) belongs in the user's own CLAUDE.md or memory, not a public skill. Route it there and drop the row - the Phase 6 leak scan cannot make this judgment call.

### Report

Print a structured report, sections in order:

1. **Tracked packages diff** - `package | pinned | latest | delta`, or "no upstream packages tracked."
2. **Proposed `metadata.upstream`** - the new flat string. No floating tags (`@latest`/`@next`/`@beta`/`@canary`); pin to a concrete tag or SHA.
3. **Proposed CHANGELOG entry** - a Keep a Changelog block ready to commit.
4. **Proposed edits** - one row per smallest atomic change, each with a stable ID (`A1`/`C1`/`D1`/`R1`/`F1`/`S1`...): `<ID> | target file | one-line summary | citation`. Batch trivially-related changes into one row; past ~20 rows, consider whether the skill needs a rewrite rather than a patch. When ADD rows are numerous, include the projected post-apply `SKILL.md` line count; if it would cross the repo's size cap (500 lines in this repo), plan the `references/` split as part of the proposal, not as a surprise after apply.
5. **New-concept coverage** (**always present, never omitted**) - the result of the Phase 2(b) coverage sweep. Either a table of net-new upstream concepts the skill omits (each becoming an `ADD` row above), or the explicit statement that there are none. End this section with the verbatim attestation below. Coverage need not be complete to pass - but any gap in what you could enumerate (JS-gated docs, rate limits, unreachable pages) must be named here, not silently dropped:
   ```
   Coverage sweep: enumerated upstream's current surface from <sources>. Net-new concepts the skill omits: <list> / none since <last-verified date>. Not reachable this run: <areas, or "none">.
   ```
6. **Bootstrap proposal** (only when `bootstrap_needed`): candidate upstream packages greppable from the skill's content, each as `<package> (mentioned <N>x, first cite: <file>:<line>)` for the user to confirm or prune; plus a seed `CHANGELOG.md`. Propose only upstreams whose releases would invalidate the skill's content - the package, spec, or living doc the skill teaches. A tool mentioned incidentally (a validator run once, a CLI in one example) is not an upstream candidate. If the skill is **upstreamless by nature**, say so explicitly, propose no candidates, and leave `metadata.upstream` omitted - only seed the `CHANGELOG.md`.

### No-op short-circuit

If sections 1-4 yield zero rows AND the Phase 2(b) coverage sweep found no omitted concepts (section 5 attestation says "none") AND `bootstrap_needed` is false, print this verbatim and exit cleanly - no file changes, no commit. Never short-circuit without the section 5 attestation present:

```
All current as of <today>. Last verified per CHANGELOG.md on <date> against <metadata.upstream value>.
```

### CHANGELOG format

[Keep a Changelog](https://keepachangelog.com/en/2.0.0/) format. The dated entry uses only the sections it has content for (Added / Changed / Deprecated / Removed / Fixed / Security), plus a `Verified against: <pkg@version list>` trailer **only if** a tracked package version actually changed this run. Mark breaking changes inside Changed/Removed with a leading `**Breaking:**` marker, and pin the KaC link in preambles to the version followed (both per KaC 2.0.0).

When `bootstrap_needed`, create the full file with this header:

```markdown
# Changelog

All notable changes to this skill will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/2.0.0/),
and this skill adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [<current-version>] - <YYYY-MM-DD>
- Initial CHANGELOG; tracking established.
```

### GATE 1 banner (verbatim)

```
GATE 1 - APPROVE TO EDIT? (yes / yes <IDs> / drop <IDs> / changes <free-form> / no)
```

Reply parsing:
- `yes` / `yes all` -> apply every row
- `yes A1-A4 C1` -> apply only those rows (and the listed package version updates, if any)
- `drop D1,R2` -> apply everything except those
- `changes <text>` -> revise the report and re-emit GATE 1
- `no` -> abort, no changes

Do NOT call Edit or Write until you receive an affirmative. Every revision round re-emits GATE 1; never silently apply.

## Phase 4 - Apply

Apply each approved row with Edit/Write; batch independent edits in parallel. Then, in order:

1. Update `metadata.upstream` to the new comma-separated `<name>@<version>` list. Reject floating tags - stop with an error if one appears. Skip entirely if the skill is upstreamless by nature - leave `metadata.upstream` omitted.
2. Bump `metadata.version` (semver per the repo's CLAUDE.md or AGENTS.md: patch for fixes, minor for new content/sections, major for breaking removal).
3. Append the new dated entry to `CHANGELOG.md` directly under `[Unreleased]`, above the previous entry. Add the `Verified against:` trailer only if a tracked version changed this run.
4. If `bootstrap_needed`, write the full `CHANGELOG.md` from the bootstrap header plus the approved seed entry.
5. When pasting upstream doc examples into a `SKILL.md` body, never let a `!` at line start or after whitespace directly touch a backticked command - Claude Code executes it at skill load, even inside code fences, and repo linters may reject it. Keep such examples in `references/` or break the adjacency.
6. Check the post-apply `SKILL.md` line count against the repo's cap (500 here); if crossed, execute the `references/` split planned in Phase 3.

## Phase 5 - Repo validation gate

If the repo defines a validation command - check its CLAUDE.md/AGENTS.md or `Justfile`/`package.json` (e.g. `just check`, `npm run lint`, `make check`) - run it from `<workdir>` (the repo root, or the Phase 0 worktree). In this repo that is `just check`, which also regenerates `README.md` (the most common CI failure cause). On failure, surface the error verbatim, fix the root cause, and re-run until clean. If the failure looks unrelated to this run's edits, attribute before debugging: stash the changes (`git stash -u`) and re-run the gate on a clean tree. Failing identically means the breakage is pre-existing (an environment flake or repo issue) - unstash, report it to the user, and don't sink this run into debugging it. No `--no-verify`, no `--amend`, no hook-skipping. If the repo has no validation gate, skip this phase and note it.

## Phase 6 - Privacy scan + diff review + GATE 2

### Privacy / leak scan (hard blocker)

Skills in a public repo can publish on merge, and any research source can leak into the diff - especially pond, which draws on private cross-project conversations. This scan runs every time, whether or not pond was used. Before showing the diff, dispatch a dedicated agent (separate from the Phase 2 research agents) to scan the added/changed lines **and every new untracked file** under `skills/<name>/` and `README.md` (if the repo generates one). `git diff` alone misses brand-new files (e.g. a fresh `references/` doc) - enumerate them with `git status --porcelain` and give the agent their full content.

It flags anything unsafe for a public skill: secrets (keys, tokens, passwords, `.env` values, connection strings), personal data (real names, emails, handles), and the easy-to-miss ones - non-public project or repo names, internal hostnames or endpoints, ticket IDs, local machine paths, pond session IDs. Intentional public references are fine (the public repo owner, official upstream repos and docs, published package names, spec URLs). The agent returns `[LEAK] <file>:<line> - <what> - suggested redaction: <text>` per issue, or exactly `NO LEAKS FOUND`.

An unresolved `[LEAK]` is a hard blocker: redact each finding, re-run the scan, and repeat until clean before GATE 2. Hold the commit message to the same public-safe standard.

### Diff review

Print `git status`, `git diff --stat`, and per-file diffs for `SKILL.md`, every changed `references/` file, `CHANGELOG.md`, and `README.md`. Then print this recovery hint verbatim, immediately above the gate banner:

```
To discard everything: git restore . && git clean -fd skills/<name>/
```

```
GATE 2 - APPROVE COMMIT + PUSH? (yes / no)
```

Wait for explicit confirmation. Do not commit on ambiguous responses.

## Phase 7 - Commit, push, watch

**Branch guard first.** Run `git rev-parse --abbrev-ref HEAD`. If the result is not the repo's default branch, ask the user: push to the current branch and open a PR (recommended), push directly to the default branch (only on explicit instruction - if the repo auto-publishes on merge, this skips PR review and ships straight to the registry), or cancel.

Commit with a conventional-commit message (type per content, per the repo's CLAUDE.md or AGENTS.md) using the HEREDOC pattern:

```bash
git commit -m "$(cat <<'EOF'
<type>(<name>): <one-line summary>

<body if non-trivial>
EOF
)"
```

- **On the default branch**: `git push`, then, if the repo has CI, `gh run watch` the triggered run. On CI failure, surface logs verbatim; do not auto-retry.
- **On a feature branch**: `git push -u origin <branch>`, then `gh pr create` with a body summarizing the Phase 3 report. Skip `gh run watch` at this point - PR CI is typically non-publishing, and some publish-on-merge repos run no PR CI at all. The run is not done at PR creation: once the PR merges, watch the default-branch publish run (`gh run watch`), confirm the publish landed, then do the Phase 0 cleanup (worktree first, then branch).

Updating several skills in one session? Land them together: batch into one push, or merge the PRs back-to-back and watch only the final publish run - each push to the default branch typically triggers a full republish.

If the repo auto-publishes on merge (e.g. to a registry via CI), confirm the publish landed once CI is green. The published slug and release/tag naming follow the repo's own pipeline - check its CLAUDE.md/AGENTS.md (the published slug can differ from the folder name).

## Done

Report a one-line summary to the user: skill name, version delta, tracked packages updated, CI status. If the repo's skills are consumed through an installer (e.g. `npx skills`), remind the user to refresh installed copies (`npx skills update <name>`) once the publish lands.