meta/skills/skill-update/SKILL.md

---
name: skill-update
description: Update one existing skill in the jsc skill set. List all skills from the Gitea canonical marketplace (cloning any missing domain repo) and let the user pick one, ask update details via decision tree, apply the change, re-check against the guidelines checklist until it passes, open a PR via jsc-git pr, then deploy and verify per references/deploy-verify.md from a fresh CLI process, and append the change report to wiki SKILLSET_{HASH}. Use for modifying a single skill; not for creating (skill-new), not for removing (skill-delete), and not for a change spanning several skills or domains (skillset-update).
---

# skill-update — update a skill

Single source of guidelines: [`../../references/guidelines.md`](../../references/guidelines.md).

## Flow

1. Run `tools/sync-domains.sh` to sync every domain repo of the Gitea canonical marketplace. Completion condition: the script exits 0 and prints one `domain<TAB>path` line per marketplace domain — exit 0 is the only code that means every repo is present and current. Exit 3 means some repos were not updated: reconcile every path named on stderr (commit or stash the dirty tree, or fix the failing pull) and rerun; when the user confirms a dirty tree is intentional local work, record that decision and continue on the local version — never read exit 3 as current. Exit 2 means a domain could not be cloned. Exit 1 means the root could not be derived, `gitea.sh` was not found, or the canonical marketplace was unreadable; when stderr says the root could not be derived, set `JSC_PLUGINS_ROOT` to the directory that holds the domain repos and rerun, because under a plugin install the script sits in the CLI's plugin cache and its built-in guess lands there instead of the domain workspace. Resolve 2 and 1 before continuing.
2. Run `tools/list-skills.sh` and present its `domain / name / description` rows to the user. The tool prints skills, not domains, so read the domain column to prove coverage. Exit 1 means the root could not be derived, the domain list was unreadable, or no skill was found — read stderr, fix the named cause (`JSC_PLUGINS_ROOT` for the root case, as in step 1) and rerun; never read it as an empty skill set. Completion condition: the script exits 0 and every domain printed by step 1 appears in at least one row; a domain with no row means its repo is missing or holds no skill — return to step 1 for that domain.
3. Let the user pick the skill to update. Completion condition: one `{domain}/{name}` pair is confirmed.
4. Ask for update details via the `jsc-ask:ask` decision tree (change the goal? the trigger? the flow? move rules down to a hook or a tool?). Every option states its impact scope (example: renaming breaks the existing invocation command). Completion condition: every question has a recorded answer.

   Settle the delegation verdict in the same tree, before any file is touched. A change that touches the **flow** or the **`description`** re-runs the whole decision tree of [`../../references/delegate-criteria.md`](../../references/delegate-criteria.md) — all five questions, the `next` question and the `probe` question — and produces a fresh verdict. The `probe` question is re-asked even when the verdict itself comes back unchanged: a skill that switched which script it calls, or that gained a read-only flag it did not have, leaves that column naming something the assistant can no longer run, and the reference file's three points settle it — which script, whether it takes a read-only flag, how a failure is reported — each verified in the owning repo rather than copied from the old value. Skipping that leaves a skill that just turned from read-only into file-writing sitting on its old verdict, and the background assistant keeps triggering it on a description of behavior it no longer has. A change that only rewrites wording and touches no behavior may keep the recorded verdict; then step 5 moves the row's `version` alone and the reuse is stated in the report, never left silent. Every option states its impact scope, this one included: reusing a verdict wrongly is the one failure this flow cannot detect later, because the row still looks complete. Completion condition: the run holds either a fresh verdict with a value in every column `delegate-criteria.md` marks mandatory for it, or a recorded decision to reuse the existing verdict together with the reason it changed no behavior.
5. Update the skill — the modification part MUST run as a sub agent: modify SKILL.md and related files. In the same pass, update this skill's `## {name}` section in `references/behaviors.md` so its five rows — 觸發時機、關鍵步驟、外部呼叫、完成條件、可驗證跡象 — describe the new behavior. A renamed skill gets its section renamed and moved back into dictionary order. In the same pass, update this skill's row in `jsc-meta/tools/delegate-spec.tsv` from the step 4 answer: a re-judged skill has every column rewritten from the fresh verdict with `origin` set to `judged`; a reused verdict keeps its columns and its `origin` untouched. Either way the `version` column moves to the version the manifests carry after the `sync-skill-manifest.sh` run below — a row left on the old version reads as never revisited, and the next audit reports it as pending re-judgement. The reuse itself is **not** recorded in the row: the twelve columns hold no note column and a thirteenth column fails the checker, so state it in the PR description and in the step 8.2 wiki section as 「沿用前一輪判定」 with the date that judgement was made. A reused verdict still gets its `probe` column re-checked against the files this run touched — a renamed or removed script leaves that column naming something the assistant cannot run, and the checker reports it as a missing script. A renamed skill also has its row's `name` column renamed, and every other row whose `next` named the old name is repointed in the same edit — those rows now name a skill that cannot be called, and the assistant retries such a name instead of pausing on it. The file lives in `plugins/meta` whichever domain owns the skill, so updating a skill outside `meta` changes two repos. The behavior list ships in this same PR: a behavior change that lands without its section makes the domain's list wrong from the merge onward, and the next audit reports drift this step created. Then run `tools/sync-skill-manifest.sh {domain-path}` directly (no sub agent needed) to sync the domain README's 「Skills 目錄」 section and bump the version in all three manifests. Route each exit code: 0 — the README block and all three manifests are synced; 1 — the domain path, `skills/`, `README.md`, the `JSC-SKILLS` markers, a `SKILL.md`, a manifest, or a manifest `version` field is missing, so fix the named cause on stderr and rerun; 2 — usage error, the script takes exactly one argument; any other code — the script runs under `set -e`, so treat it as an environment fault and stop, never as a successful sync. Completion condition: the skill files carry the change, the skill's `references/behaviors.md` section states the new behavior with all five rows filled, its `tools/delegate-spec.tsv` row carries the fresh verdict or the reused one with a moved `version`, and all three manifests show the same new version.
6. Check every item of the guidelines.md audit checklist. Run `tools/check-behaviors.sh {domain-path}` for the behavior-list item instead of comparing by eye, and route each exit code: 0 — the list matches `skills/` and all five rows are filled; 1 — every mismatch is printed on stderr as `{檔案}:{技能名}:{說明}`, so fix each one and rerun; 2 — usage error, the tool takes exactly one argument; 3 — nothing was checked, because `references/behaviors.md` is missing, `skills/` is missing, or no `SKILL.md` was found, so create the missing file and rerun. **Exit 3 is never a pass.**

   Then run `tools/check-delegate.sh` for the delegation-list item. It takes the plugins root, not a domain path, and the list is one file covering every domain, so it runs **once for the whole flow**. Route each exit code:
   - 0 — the list matches the skills on this machine and every mandatory column is filled. **A run that printed lines on stdout and exited 0 still passed.** Those lines are hints, not defects: `origin=seed` marks a row seeded from the earlier inventory and awaiting review, and a version-behind line marks a row whose `version` trails its domain's current one, a `probe=pending:` line marks a delegated slice whose read-only entry point is not wired yet, and a line saying a `probe` domain is not installed here marks a script this machine cannot check. The version number is per domain, so bumping one skill's domain marks every other skill in it — reading those lines as failures paints the whole domain red on every release until nobody reads them at all. Report the hints and treat this item as passed. The one hint worth acting on here is a version-behind line naming **the skill this run just changed**: that row's `version` was supposed to move in step 5, so go back and move it.
   - 1 — a missing row, a duplicate row, a row for a skill this machine does not have, an empty column, a column value outside its vocabulary, a `next` pointing at a skill that does not exist, or a `probe` in the wrong shape — a command on a row whose `way` holds `invoke`, a `-` on a row whose `way` holds only `patrol` or `remind`, a dollar sign or tilde, an unknown substitution point, or a script that does not exist. Every one is printed on stderr as `{清單路徑}:{domain}/{技能名}:{說明}`; fix each and rerun. A rename that left the old name behind lands here twice — once as a stale row, once as another row's dead `next`.
   - 2 — usage error: the script takes at most one argument. Fix the call and rerun.
   - 3 — nothing was checked, because `tools/delegate-spec.tsv` is missing, the root could not be derived, or `list-skills.sh` listed no skill. Read stderr and fix the named cause; set `JSC_PLUGINS_ROOT` to the directory holding the domain repos for the root case, as in step 1. **Exit 3 is never a pass.**

   On any failure, **return to step 4**: ask again and fix, until all items pass. Completion condition: every checklist item passes, `tools/check-behaviors.sh {domain-path}` exits 0, and `tools/check-delegate.sh` exits 0 with its hint lines reported as hints.
7. Call `jsc-git:pr` to open a Push Request. When the updated skill lives in a domain other than `meta`, the `tools/delegate-spec.tsv` row is a change to `plugins/meta` and needs its own Push Request against that repo — two repos changed, two PRs, neither waiting on the other. Completion condition: a PR URL comes back for every repo this run changed, `plugins/meta` included when the row landed there, and each is reported with the table format in [`../../references/pr-report.md`](../../references/pr-report.md).
8. Deploy the update, verify it runs, then report:
   1. Follow [`../../references/deploy-verify.md`](../../references/deploy-verify.md) from section 1 to section 5: `tools/deploy-route.sh {domain-path}` picks the route, the deploy route or the worktree route runs, and the verification then runs in a **fresh CLI process**, never in the session that ran the deploy. That session raised the restart gate itself and still holds the old skill body, so verifying inside it either gets blocked or passes on stale behavior. Verify the updated `description` in the skill's `tools/list-skills.sh` row, every tool this change touched, and one minimal prompt per checkable CLI — the per-CLI prompts run in parallel. Completion condition: every completion condition in `deploy-verify.md` sections 1 to 5 holds for this domain repo.
   2. Write the change report to the wiki — this part MUST run as a sub agent. It is two pages in two repos, and they must not be mixed up.
      - **Content page `SKILLSET_{HASH}`.** Resolve its repo with `jsc-gitea/tools/gitea.sh wiki-repo SKILLSET`, which reads `JSC_WIKI_REPO_SKILLSET` first, then `JSC_WIKI_REPO`. `{HASH}` is `gitea.sh hash-id "{owner}/{repo}"` of the changed domain repo, used at the full 40 characters it prints. Write it through `jsc-gitea:wiki` following [`../../templates/skillset-page.md`](../../templates/skillset-page.md): **append** a section for this change — date, 「更新」, skill name, changed files, PR URL, the step 8.1 route verdict and verification result per item, and the delegation verdict this run recorded: the fresh verdict with its columns, or 「沿用前一輪判定」 with the date of the judgement being reused. The row itself has no room for that note, so this section is the only place it is kept — and keep every earlier section.
      - **Directory page `SKILLSET_CONTENTS`.** It lives in the CONTENTS repo, never in the SKILLSET one. `wiki-contents.sh` resolves it itself with `gitea.sh wiki-repo CONTENTS`, whose chain is `JSC_WIKI_REPO_CONTENTS` then `JSC_WIKI_REPO` and never falls back to `JSC_WIKI_REPO_SKILLSET`. That page is a heading-plus-bullets list and holds no markdown table: one `## SKILLSET_{HASH}` block per domain repo, every field one `- {欄位名}：{值}` line under it. Build one file holding this domain's single block, following [`../../templates/skillset-contents.md`](../../templates/skillset-contents.md), with its 異動頁 bullet written as `[SKILLSET_{HASH}]({url})` from the **absolute** URL that `gitea.sh wiki-url {SKILLSET repo} SKILLSET_{HASH}` prints. The H2 heading itself carries no link, no URL, no affix and no date — only the content page name. Every link on both pages takes that `[{text}]({url})` form; the double-bracket wiki-link form resolves only inside one wiki, so it is never used. Then run:

        `jsc-gitea/tools/wiki-contents.sh upsert SKILLSET 2 "SKILLSET_{HASH}" {entry file} templates/skillset-contents.md`

        The key is the H2 heading `SKILLSET_{HASH}`, so one domain keeps exactly one block and no other domain's block moves. That page name depends only on `{owner}/{repo}`, which is why it is the key: a host rename or a changed `JSC_WIKI_REPO_SKILLSET` leaves it untouched, so the match still finds the existing block. The `2` is the key column: the index of the column that held the content-page link in the **old markdown table**, and it matters only when such an old table still has to be converted automatically — the conversion takes the last path segment of that column's link URL as the H2 heading. Count that index from the **live page's own column layout**, never from the template's: the live `SKILLSET_CONTENTS` reads `| 存放庫 | 異動報告 | 目前版本 | 最後更新 |`, so the link sits in column 2 while column 1 is plain text like `plugins/ask`. Passing `1` would make the heading `plugins/ask`, which never matches the key `SKILLSET_{HASH}`, so the existing entry is appended as a brand-new one — one domain ends up with two blocks and the older one is never updated again. The fourth argument is the whole block, not a table row. Never hand-edit the directory page. Write the content page first and fetch the URL only after it exists.
      - **Check the links before writing.** Hand every URL going onto the content page and into the directory block to `jsc-gitea/tools/link-check.sh`, and write only when it exits 0. It verifies through the Gitea API, never a web status code: a private repo answers 404 to an unauthenticated web request, so a status-code check would call a live page dead.
      - **Exit codes.** Route every one of them:

        | Call | Exit | Do |
        | --- | --- | --- |
        | `gitea.sh wiki-repo` | 2 | The page type was misspelled. Fix the argument and rerun |
        | | 3 | No wiki repo is configured for that type. Name the variable (`JSC_WIKI_REPO_SKILLSET` for the content page, `JSC_WIKI_REPO_CONTENTS` for the directory page) and `JSC_WIKI_REPO`, ask per the `jsc-ask:ask` rules, then rerun |
        | `gitea.sh hash-id` | 1 | No SHA-1 helper on this machine. Stop and report that `sha1sum` or `shasum` has to be installed, and never hand-compute the hash |
        | | 2 | Empty input, so the `{owner}/{repo}` was never resolved. Fix that first |
        | Content page read | 0 | Append into the sections already there |
        | | 4 | The page does not exist yet, so build it from `templates/skillset-page.md` |
        | | 7 or 8 | Stop and write nothing: a page rebuilt on top of an unread read loses every section already on it |
        | `gitea.sh wiki-url` | 4 | The content page is not there, so the write above did **not** succeed. Go back and write it, and add no directory block until the page exists |
        | | 5 | The API answered with no `html_url`. Stop and report it; never assemble the URL by hand from the host and the page name |
        | `link-check.sh` | 0 | Every link is reachable. Write the page |
        | | 1 | At least one link is dead. Write nothing, and report the `DEAD` lines it printed |
        | | 2 | No URL was passed, which is a defect here. Pass the links and rerun |
        | | 3 | `GITEA_HOST` is unset. Set it and rerun; never skip the check instead |
        | | 7 | Gitea authentication failed. Stop and report the key problem, and never read it as a dead link |
        | `wiki-contents.sh upsert` | 0 | The block is in place. Report the `updated` or `added` it printed |
        | | 1 | The page content could not be assembled, or the write failed. Report `SKILLSET_CONTENTS` as not written, together with the block content |
        | | 2 | An argument was rejected. Fix it and rerun; nothing was written |
        | | 3 | No CONTENTS wiki repo is configured. Report `JSC_WIKI_REPO_CONTENTS` and `JSC_WIKI_REPO` as the two variables to set; the new section is on `SKILLSET_{HASH}` and stays there |
        | | 4 | The directory page is absent and no template was passed. Rerun with `templates/skillset-contents.md` as the fifth argument |
        | | 7 | The token is invalid or lacks permission, so the other domains' blocks are unknown. Stop, report the token problem, and create no page |
        | | 8 | Some other API failure. Stop, report that status, and create no page |

      On any failure, hand the page name and the unwritten entry back to the user and leave this step open; never close the flow on an unwritten report. Completion condition: `SKILLSET_{HASH}` holds the new section plus all earlier sections, and `wiki-contents.sh upsert` exited 0 with this domain's `## SKILLSET_{HASH}` block on `SKILLSET_CONTENTS` linking that page by absolute URL.
9. Report this run's outcome to the local event stream — the last step of every run, the ones that stop early included. Run:

   `jsc-hooks/tools/report-status.sh skill-end jsc-meta:skill-update {status} {exit code} [detail]`

   Resolve `jsc-hooks` from the `domain<TAB>path` row step 1 printed for the `hooks` domain, the same way this skill resolves every other cross-plugin script. **When that script is not on this machine, skip this step in silence and close the run as normal.** A reporting path that is absent must never fail the run it reports on, and this call's own exit code never changes what this skill reports.

   Pick `{status}` from what the run actually did:

   | status | Use it when |
   | --- | --- |
   | `ok` | the skill files, the behavior-list section and the `delegate-spec.tsv` row carry the change, the checklist passes, every PR this run needed is open, `deploy-verify.md` sections 1 to 5 hold, and both wiki writes exited 0 |
   | `blocked` | a gate or a missing prerequisite stopped the run before any file changed — `sync-domains.sh` never reached exit 0, or no skill could be listed to pick from |
   | `failed` | the run broke mid-way — the step 6 checklist loop kept failing, or a wiki write failed again after its one retry |
   | `degraded` | the update landed with a part missing — the content page was written while its `SKILLSET_CONTENTS` block was not, the skill's PR is open while the `delegate-spec.tsv` PR is not, or a CLI could not be verified and the reason was recorded |
   | `aborted` | the user stopped the run, or a prerequisite turned out not to hold and this skill stopped on its own |

   `{exit code}` is this run's own result as a number: `0` for `ok`, non-zero otherwise. `detail` is optional, one line, at most 200 characters.

   The matching `skill-start` comes free from the hook, which fires when the skill loads. The update itself happens in the model turns after that, so no hook can see how the run ended — a `start` with no `end` reads as an abort, which is why writing the `end` is this skill's own job.

   Completion condition: one `skill-end` line for this run is appended to `$JSC_HOME/usage/events.jsonl`, or the script was absent and the final report says so.