37 lines
9.8 KiB
Markdown
37 lines
9.8 KiB
Markdown
---
|
|
name: skill-delete
|
|
description: Remove a skill from the jsc skill set safely. Pick the skill from the Gitea canonical marketplace skill list, inventory every file referencing it, fix each affected file through decision-tree questions until guideline checks pass, delete the skill and verify no on-disk leftover in any CLI, open a PR via jsc-git pr, then deploy the deletion into the current session and append the change report to wiki SKILLSET_{HASH}. Use only for removal; not for renaming (use skill-update).
|
|
---
|
|
|
|
# skill-delete — delete 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 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 delete. Options state the impact scope: which skills reference it, and that its command stops working after deletion. Completion condition: one `{domain}/{name}` pair is confirmed for deletion.
|
|
4. Inventory every file related to the skill: run `tools/find-skill-refs.sh {domain} {name}` to list every file that references the skill name or its `/jsc-{domain}:{name}` command form, across every marketplace domain repo on this machine (covers other SKILL.md files, the domain README's 「Skills 目錄」 section, the two marketplace.json files in `plugins/meta` plus their synced copies in every domain repo, `tools/`, and the `jsc-hooks` wiring). The skill-name pattern is a bare substring match, so the list also carries other skills whose name starts with the same word plus plain prose — treat it as candidates to read, not as files that must change. Exit 1 means a clean zero-hit scan; exit 3 means the scan failed — fix the root path or the missing domain repos and rerun, never treat it as zero hits. Completion condition: the tool's file list is captured as the step 5 inventory.
|
|
5. Fix every file in the step 4 inventory. For each file:
|
|
1. Read the file and decide whether it needs a fix to keep its current behavior after the deletion. If no fix is needed, record it as no-fix-needed with the reason and **skip the rest of this loop**. Completion condition: the file carries a recorded verdict — needs-fix or no-fix-needed with a reason.
|
|
2. Ask for fix details via the `jsc-ask:ask` decision tree (call a replacement skill? move a deterministic input/output flow to `tools/`? run the detailed flow as a sub agent? drop the feature too?). If the fix touches wiki or Gitea access, confirm it reads inherited environment variables before asking the user. Every option states its impact scope. Completion condition: every question has a recorded answer.
|
|
3. Apply the confirmed fix, then check the guidelines.md audit checklist for the file — the per-file fix work MUST run as a sub agent, one sub agent per affected domain repo, each reporting one line per file: the path and either the applied fix or「無需修正」with the reason. On any checklist failure, return to step 5.2. Completion condition: the fix is in the file and every checklist item passes for it.
|
|
|
|
Completion condition: every file in the step 4 inventory is marked either fixed-with-a-clean-checklist or explicitly no-fix-needed with a reason — no file is left without a verdict.
|
|
6. Delete the skill directory `skills/{name}/`, then run `tools/sync-skill-manifest.sh {domain-path}` directly (no sub agent needed) to sync the domain README and bump the version in all three manifests. Completion condition: the directory is gone, the README's 「Skills 目錄」 no longer lists the skill, and all three manifests show the same new version.
|
|
7. Deep-delete verification: after removing the plugin through each CLI's native plugin commands, run `tools/verify-skill-removed.sh {domain} {name}`. It detects the installed CLIs and greps each one's skill cache and hook config for the skill. Route each exit code:
|
|
- Exit 1 — leftovers printed as `{file}:{line}:{content}`. Remove every one by hand, then rerun.
|
|
- Exit 2 — usage error. Fix the two arguments and rerun.
|
|
- Exit 3 — nothing was checkable: no CLI detected, or no config location exists. The script prints no leftover because it looked nowhere, so this is **never** clean. Report「無處可查」with the reason from stderr and stop the deep-delete verification here; state in the PR that on-disk verification did not run.
|
|
- Exit 0 — no leftover in the locations listed on stderr.
|
|
|
|
Completion condition: the script exits 0, or exit 3 is reported to the user and recorded in the PR.
|
|
8. 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`.
|
|
9. Apply the deletion to the current working session, verify it took, 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 version without the skill, 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 deletion 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 deletion reaches any CLI. Until it merges the skill is still installed and still callable, so say that too. 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 confirm no row carries the deleted `{domain}/{name}`, rerun `tools/verify-skill-removed.sh {domain} {name}` for exit 0, then run every tool and skill that step 5 fixed and confirm each still finishes with its documented exit code — a fix that broke a caller shows up here, not earlier. 用 `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 — the deleted skill still listed, a leftover from exit 1, a fixed caller that now fails, a prompt failure, or unexpected stderr — fix the cause and rerun this step from 9.1. Completion condition: the skill is absent from the list, the verification script exits 0 (or its exit 3 stays reported as「無處可查」), every fixed caller ran, every checkable test-environment CLI completed the prompt with the expected result, 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 domain repo that lost the skill, 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 (the step 5 inventory verdicts included), PR URL, the step 9.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.
|