meta/skills/skill-update/SKILL.md

name, description

name

description

skill-update

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 the change into the current session, verify it runs, 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.

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 and exit 1 means the canonical marketplace was unreadable — resolve either 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. Completion condition: 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.
5. Update the skill — the modification part MUST run as a sub agent: modify SKILL.md and related files. 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. Completion condition: the skill files carry the change and all three manifests show the same new version.
6. Check every item of the guidelines.md audit checklist. On any failure, return to step 4: ask again and fix, until all items pass. Completion condition: every checklist item passes.
7. Call jsc-git:pr to open a Push Request. Completion condition: a PR URL comes back and is reported with the table format in references/pr-report.md.
8. Apply the update to the current working session, verify it works, then report:
   1. Force the change into the session — which of the two routes applies depends on where the change has reached, because the marketplace and version-guard.sh both read the repository's default branch (master), so jsc-cli:deploy cannot see anything that stopped at develop:
      • The PR is merged all the way to master: call jsc-cli:deploy in update mode so every installed CLI loads the new version, and restart the CLI when it asks (the deploy writes $JSC_HOME/restart-required; see guidelines.md「部署後重啟閘門」). When the deploy cannot update a CLI, record which CLIs did load the new version and carry on with one of those; when none did, stop and report the change as unverified. Completion condition: claude plugin list (or the equivalent command of another installed CLI) prints jsc-{domain} at the version the three manifests now carry.
      • The PR is still short of master (waiting on review, or merged only into develop): deploying is pointless and its completion condition is unreachable, so verify against the worktree instead — run the next sub-step against /root/plugins/{domain} rather than the installed copy, mark the report as 「工作樹驗證、尚未部署」, and say plainly which release PR still has to merge before the change reaches any CLI. Completion condition: the verification sub-step passed against the worktree and the outstanding release PR is named in the report.
   2. Verify the function concretely: run tools/list-skills.sh and see the updated description in the skill's row, then run every tool this change touched with real arguments and compare each exit code against its documented meaning. Invoke /jsc-{domain}:{name} once and confirm the CLI loads the changed SKILL.md body. 用 jsc-cli/tools/detect-clis.sh 偵測已安裝的測試環境 CLI；每個支援非互動 Prompt 的 CLI 都要實際送出一個最小 Prompt，呼叫 /jsc-{domain}:{name}，並記錄 CLI 結束碼與 stderr。Prompt 若因 CLI 工具、plugin 安裝、hook 接線、模型標籤表或設定而失敗，先跑 jsc-cli:doctor，再用 jsc-cli:setup 修復待修項目，然後重跑同一個 Prompt。hook 冒煙測試若失敗，交給 jsc-hooks:hooks-install，由它把 hook 接線或執行期錯誤轉給 jsc-hooks:repair。若根因是技能組本身的規格、工具或 hook 實作，修正對應 domain，跑 manifest 同步與驗證，然後用 jsc-git:pr develop 開 PR；PR 送出後回到本步驟重跑同一個 Prompt。只有每個可測 CLI Prompt 都沒有非預期 stderr，或該 CLI 以明確原因列為不可測，才能停止。On any mismatch — a stale row, an exit code the tool's own documentation does not describe, an unchanged body, a prompt failure, or unexpected stderr — fix the cause and rerun this step from 8.1. Completion condition: the row shows the new description, every touched tool ran with an expected exit code, the command loaded, every checkable test-environment CLI completed the prompt without unexpected stderr, and every untestable CLI has a stated reason.
   3. Write the change report to wiki page SKILLSET_{HASH} — this part MUST run as a sub agent. Call jsc-gitea:wiki; {HASH} comes from the {owner}/{repo} of the changed domain repo, and the wiki repo resolves through JSC_WIKI_REPO_SKILLSET first, then JSC_WIKI_REPO. Append a section for this change — date, 「更新」, skill name, changed files, PR URL, the step 8.2 verification result per item — and keep every earlier section. Add the page to SKILLSET_CONTENTS when it is new. When the write fails — no {owner}/{repo} resolves, or jsc-gitea:wiki reports an API error — 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: the page holds the new section plus all earlier sections, and SKILLSET_CONTENTS links it.