/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.10.0"
  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 Phase 0 worktree. Use absolute paths under `<workdir>`; do not mix in the main checkout.
• **Scratch directory for toolchains.** Pick one scratch directory outside every checkout (the session scratchpad if the harness provides one, else `mktemp -d`) and name it in every subagent brief. Every build or toolchain command - `swift`, `xcodebuild`, `npm`, `cargo`, `uv`, `go` and the like, including `--help` probes and scratch packages - runs with that directory as its working directory. Subagents start in the main checkout, so a bare `swift build --help` leaves a `.build/` there.
• **No backticks in shell arguments.** Single-quote search patterns (`rg -n 'pattern' path`). In zsh and bash a backtick inside a double-quoted argument is command substitution, and one such `rg` pattern has printed the whole environment, secrets included, into a transcript.

Phase 0 - Separate worktree

Run the whole update in a separate worktree on a new branch `chore/update-<name>`, so several skills can be updated in parallel. `<workdir>` is that worktree's absolute path. Keep it until the PR merges, then remove it and delete the branch.

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)
• `git status --porcelain` snapshot of `<workdir>` and of `${CLAUDE_PROJECT_DIR}` - the baseline for the Phase 6 hygiene check, so pre-existing user files are never flagged or removed
• A per-skill license file, only if the repo's linter or publish pipeline requires one (ClawHub does not - it licenses every skill MIT-0); if required and 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 the research subagents in a single message: one each for upstream and docs, plus the usage lanes. 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 is available, dispatch three usage lanes alongside the upstream and docs agents. Tell each to use the pond MCP tools and read their descriptions first, and paste in the interim notes below:
• **Summaries** - the agent's own end-of-task conclusions about the tool: causes, fixe