meta/skills/skill-delete/SKILL.md

name, description

name

description

skill-delete

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 in parallel sub agents until guideline checks pass, delete the skill, open a PR via jsc-git pr, then deploy per references/deploy-verify.md and verify from a fresh CLI process that no on-disk leftover remains, 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.

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 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 0 means hits were printed; exit 1 means a clean zero-hit scan; exit 2 means a usage error, so fix the two arguments and rerun; exit 3 means the scan never ran — the root could not be derived, the domain list was unreadable, no domain repo is on this machine, or grep failed. Read stderr and fix the named cause; when it names the root, set JSC_PLUGINS_ROOT to the directory that holds the domain repos, because under a plugin install the script sits in the CLI's plugin cache and its built-in guess lands there. Never read exit 3 as zero hits — a failed scan taken as "no references" makes this skill skip files it must fix. 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, and those sub agents run in parallel: each repo's files are independent, so serialising them only adds waiting. Each sub agent reports 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.

   jsc-meta/tools/delegate-spec.tsv appears in that inventory as the row naming the skill. Mark it as handled in step 6 and edit it nowhere else: the row goes out there, together with the skill directory, and splitting the edit over two steps risks one of them removing a row the other still expects to be there.

   Completion condition: every file in the step 4 inventory is marked either fixed-with-a-clean-checklist, explicitly no-fix-needed with a reason, or deferred to step 6 as the delegation list is — no file is left without a verdict.

6. Delete the skill directory skills/{name}/ and remove that skill's ## {name} section from references/behaviors.md — the whole section, its table included, leaving every other section untouched. Both deletions ship in this same PR: a behavior list still carrying a deleted skill fails the domain's next audit, and the extra section is exactly what check-behaviors.sh reports. 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. 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 remaining 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.

   Delete that skill's row from jsc-meta/tools/delegate-spec.tsv in the same pass — that one row, every other row left byte for byte as it was. A list still carrying a deleted skill makes the background assistant trigger a skill that cannot be called, and a failing trigger does not pause itself: it retries every round, for good. Then repoint every remaining row whose next column named the deleted skill; those rows now name something that cannot be called either, and they are the second half of the same defect. The file lives in plugins/meta whichever domain lost the skill, so deleting a skill outside meta changes two repos and step 7 opens the second Push Request for this one.

   The task-book half is not wired yet. ../../references/delegate-criteria.md also asks this skill to drop the assistant task-book entries that name the deleted skill. That task book does not exist yet, so there is nothing to remove from and this skill does not go looking for it. When the task book ships, add that removal here as a step of its own. Until then, carry 「待辦簿引用尚未接線」 into the step 8.3 wiki section, so a later reader does not take this deletion as having cleaned a place it never touched.

   Then run tools/check-behaviors.sh {domain-path} and route each exit code: 0 — the remaining sections match the remaining skills; 1 — every mismatch is printed on stderr as {檔案}:{技能名}:{說明}, so fix each one and rerun, the deleted skill's leftover section included; 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 fix the named cause and rerun. Exit 3 is never a pass.

   Then run tools/check-delegate.sh. 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; the deleted skill has no row left, and no surviving row points at it. 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, which every skill of the domain this deletion just bumped will now show. Report them as hints and fix nothing for them; a deletion held open over a version-behind line would never close.
   • 1 — a row remains for a skill this machine no longer has, or a surviving row's next points at the deleted skill. Both are printed on stderr as {清單路徑}:{domain}/{技能名}:{說明} — the first is the row this step was supposed to remove, the second is a next this step was supposed to repoint. Fix each and rerun.
   • 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 — a check that looked nowhere reports no leftover row either.

   Completion condition: the directory is gone, references/behaviors.md holds no ## {name} section for the deleted skill, tools/delegate-spec.tsv holds no row for it and no next naming it, tools/check-behaviors.sh {domain-path} and tools/check-delegate.sh both exit 0, the README's 「Skills 目錄」 no longer lists the skill, and all three manifests show the same new version.

7. Call jsc-git:pr to open a Push Request. When the deleted skill lived in a domain other than meta, the tools/delegate-spec.tsv removal 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 was removed there, and each is reported with the table format in ../../references/pr-report.md.

8. Deploy the deletion, verify it took, then report:

   1. Follow ../../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 set, so verifying inside it either gets blocked or passes on stale behavior. On the worktree route, add that the skill stays installed and stays callable until the outstanding release PR merges. Completion condition: every completion condition in deploy-verify.md sections 1 to 5 holds for this domain repo.

   2. Verify the deletion concretely, on top of the deploy-verify.md items:

      • tools/list-skills.sh prints no row carrying the deleted {domain}/{name}.
      • Deep-delete verification. Run tools/verify-skill-removed.sh {domain} {name}; it detects the installed CLIs and greps each one's skill cache and hook config. Route each exit code: exit 0 — no leftover in the locations listed on stderr; exit 1 — leftovers printed as {file}:{line}:{content}, so remove every one by hand and rerun; exit 2 — usage error, fix the two arguments and rerun; exit 3 — nothing was checkable, because the root could not be derived, detect-clis.sh was not found, no CLI was detected, or no config location exists. The script printed no leftover because it looked nowhere, so exit 3 is never clean: report「無處可查」with the reason from stderr, and carry that sentence into step 8.3's wiki section and the final report, so nobody later reads the deletion as verified on disk. This is the only place the deep-delete check runs — running it before the PR only scanned a deletion that had not been deployed yet, so it always came back clean and proved nothing.
      • Every tool and skill that step 5 fixed still finishes with its documented exit code — a fix that broke a caller shows up here, not earlier.
      • One minimal prompt per checkable CLI, each in its own fresh process and all in parallel, confirming /jsc-{domain}:{name} is gone or that the replacement path still works.

      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 8.1. Completion condition: the skill is absent from the list, the verification script exits 0 or its exit 3 is reported as「無處可查」and carried into step 8.3, every fixed caller ran, every checkable CLI completed the prompt with the expected result, and every untestable CLI has a stated reason.

   3. 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 domain repo that lost the skill, used at the full 40 characters it prints. Write it through jsc-gitea:wiki following ../../templates/skillset-page.md: append a section for this change — date, 「刪除」, skill name, changed files (the step 5 inventory verdicts included), PR URL, the step 8.1 route verdict and the step 8.2 verification result per item, the deep-delete verdict「無處可查」included when it applies, and the step 6 note 「待辦簿引用尚未接線」 — 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, 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-delete {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 directory, its behavior-list section and its delegate-spec.tsv row are gone, every PR this run needed is open, deploy-verify.md sections 1 to 5 hold, verify-skill-removed.sh and check-delegate.sh both exited 0, 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 — a leftover from verify-skill-removed.sh exit 1 could not be removed, or a wiki write failed again after its one retry
   degraded	the deletion landed with a part missing — the deep-delete check came back 「無處可查」, the skill's PR is open while the delegate-spec.tsv PR is not, or the content page was written while its SKILLSET_CONTENTS block was not
   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 deletion 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.