/update-skill

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:

  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 s