plugins/meta
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(skills): 新增技能盤點頁與共用部署驗證流程，並把技能驗證移到新行程

Browse Source 
技能盤點以前只回到對話裡，換一台機器就得重跑才知道裝了什麼。
現在新增技能盤點這個 wiki 頁類型，雜湊取「主機、工具名稱、登入帳號」三段。
每支 CLI 各有自己的 plugin 集合，也各有自己的 hook 接線，那是互相獨立的事實。
少了工具名稱那一段，同一台機器上五支 CLI 會算出同一個雜湊，五份盤點互相覆蓋，
讀的人還看不出被蓋掉。技能盤點新增寫入這兩頁的步驟，整步規定必須開 sub agent。
兩份樣板刻意分開：內容頁每次盤點覆寫整頁，目錄頁只更新自己那一列，
兩者的寫入語意剛好相反，合成一份遲早有人把別台機器的紀錄刪掉。

四支異動技能原本在部署完的同一個工作階段，就叫用剛做好的技能。
部署收尾自己立起重啟閘門，那支技能必被擋下，驗證做不完。
解法不是把它加進豁免清單。豁免擋得住閘門，擋不住「行程還載著舊版」這件事，
硬過關驗到的是舊版行為，等於假通過。所以把判路線、部署、驗證、失敗分流
抽成一份共用說明，驗證一律另開 CLI 行程執行，四支技能只留一行指標指過去。

新增腳本檢查工具，一次做完語法、執行權限與結束碼宣告三項檢查，
只被 source 的函式庫豁免後兩項，而且逐支記在錯誤輸出，不靜默略過。
新增部署路線判定工具，判定改動有沒有進存取庫的預設分支，
取代四支技能各抄一段、各自漂移的散文；判不出來就回報停下，不自己挑路線走。

同時把四支技能裡的中文段落抽到共用說明、指標改回英文，
修正六處相對路徑，把技能盤點的模糊描述改成查得出來的條件，
並讓 manifest 同步的每一個呼叫端逐碼分流。

七支技能改為併行執行：例行稽核從九步併成七步，技能盤點併成六步。
技能盤點不再重跑盤點腳本內部已經跑過的三支腳本，
而那三支原本兼作獨立交叉檢查，拿掉就少一層保護，
所以把少掉的是什麼、風險由誰擋住，明白寫進 Notes，不當作沒發生。
This commit is contained in:
jiantw83
2026-08-31 11:11:12 +08:00
parent 7dc5c32de3
commit 5aa4a3da57
12 changed files with 571 additions and 128 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/skill-new/SKILL.md
+19 -16
View File
@@ -1,6 +1,6 @@
---
name: skill-new
description: Create a new skill in the jsc skill set. Ask skill details via decision tree, generate the skill under the right jsc-{domain} per guidelines.md (create the domain from the template repo if missing), open a PR via jsc-git pr, then deploy the skill into the current session, verify it runs, and append the change report to wiki SKILLSET_{HASH}. Use when the user wants to add a skill; not for editing an existing one (use skill-update).
description: Create a new skill in the jsc skill set. Prefetch the skill list and the domain list in parallel, ask skill details via decision tree, generate the skill under the right jsc-{domain} per guidelines.md (create the domain from the template repo if missing), 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 when the user wants to add a skill; not for editing an existing one (use skill-update).
---
# skill-new — create a skill
@@ -9,13 +9,19 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
## Flow
1. Ask for skill details via the `jsc-ask:ask` decision tree until no doubt remains:
- Goal (single and not duplicating an existing skill; run `tools/list-skills.sh` first and show the similar skills for comparison — options must state the impact scope of "reuse existing" versus "create new")
- Trigger (when to use, when not to, trigger keywords)
- Input and output (can a standard input/output flow move down to `tools/`; does it need Gitea operations — if so, make the skill use `jsc-gitea/tools/gitea.sh` + token)
- Owning domain (run `tools/sync-domains.sh` and offer its domain list — the domains registered in the canonical marketplace)
1. Collect the decision tree's inputs first, then ask:
1. Prefetch both inputs — run `tools/list-skills.sh` and `tools/sync-domains.sh` **in parallel**. They share no data, and both answers are needed before the first question, so running them after the questions only makes the user wait. Route each exit code:
- `list-skills.sh` exit 0 — keep the `domain<TAB>name<TAB>description` rows. Exit 1 — the root could not be derived, the domain list was unreadable, or no skill was found; read stderr and fix the named cause. When stderr says the root could not be derived, set `JSC_PLUGINS_ROOT` to the directory that holds the domain repos and rerun: under a plugin install the script sits in the CLI's plugin cache, so its built-in guess lands in that cache instead of the domain workspace.
- `sync-domains.sh` exit 0 — the only code that means every repo is present and current; keep the `domain<TAB>path` rows. Exit 3 — 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. Exit 2 — a domain could not be cloned. Exit 1 — the root could not be derived, `gitea.sh` was not found, or the canonical marketplace was unreadable; for the root case set `JSC_PLUGINS_ROOT` as above and rerun. Resolve 2 and 1 before continuing.
Completion condition: goal, trigger, input/output and owning domain each have a recorded answer.
Completion condition: the skill rows and the `domain<TAB>path` rows are both in hand.
2. Ask for skill details via the `jsc-ask:ask` decision tree until no doubt remains:
- Goal (single and not duplicating an existing skill; show the similar skills from the step 1.1 rows for comparison — options must state the impact scope of "reuse existing" versus "create new")
- Trigger (when to use, when not to, trigger keywords)
- Input and output (can a standard input/output flow move down to `tools/`; does it need Gitea operations — if so, make the skill use `jsc-gitea/tools/gitea.sh` + token)
- Owning domain (offer the domain list from the step 1.1 `domain<TAB>path` rows — the domains registered in the canonical marketplace)
Completion condition: goal, trigger, input/output and owning domain each have a recorded answer.
2. If the domain does not exist (`tools/sync-domains.sh` clones every domain **registered in the marketplace**, so a missing directory means the domain is unregistered — the repository itself may already exist on Gitea):
1. Propose one short English word for the new domain (a single word preferred) and confirm it with the user. Completion condition: the user confirms the domain word.
2. Check before creating: run `jsc-gitea/tools/gitea.sh clone-url plugins/{domain}`. A URL comes back when the repository already exists — clone it, skip creation, and go on to step 2.3 to fill in whatever content is missing. Only when no URL comes back create the repository through the tool, never by hand: `gitea.sh api POST /orgs/plugins/repos` when `plugins` is an organization, `POST /user/repos` when `plugins` is the token's own account (`tea repo create` does the same job). Only when the call is refused (403 — the token has write but not admin rights on the owner) ask the user to create `plugins/{domain}` by hand, then continue. Completion condition: `gitea.sh clone-url plugins/{domain}` prints a URL and cloning it succeeds.
@@ -23,7 +29,7 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
4. Register the plugin: run `tools/sync-marketplace.sh {domain} {repo-url} {description}`. It needs `python3` on PATH — it edits the marketplace JSON with the json module. It writes the entry into both canonical marketplace files in `plugins/meta` and copies both into every domain repo, so any repo works as the registration entry point. Route each exit code:
- Exit 3 — written, but some domain repo is not present locally. Run `tools/sync-domains.sh`, then rerun this step.
- Exit 2 — usage error. Fix the three arguments and rerun.
- Exit 1 — missing python3, an unreadable canonical file, or a byte mismatch between copies. Read stderr, fix the named cause (install python3 for the first), then rerun.
- Exit 1 — the root could not be derived, python3 is missing, a canonical file was unreadable, or copies differ byte for byte. Read stderr and fix the named cause: install python3 for the second; for the root case 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. Then rerun.
- Exit 0 — every copy holds identical bytes; the script verifies that itself.
Completion condition: the script exits 0 and prints the touched paths.
@@ -31,12 +37,9 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
- `skills/{name}/SKILL.md`: entirely in English (description within either cap — ≤ 5 sentences or ≤ 5 steps — and stating when to use and when not to; body in STE100-style English)
- Rules enforceable by hooks go to `jsc-hooks` (never scattered in this domain); standard input/output flows go to `tools/`
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: `skills/{name}/SKILL.md` exists, the README lists the skill, and all three manifests show the same new version.
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: `skills/{name}/SKILL.md` exists, the README lists the skill, and all three manifests show the same new version.
4. Self-check every item of the guidelines.md audit checklist; fix anything that fails. Completion condition: every checklist item passes.
5. 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`.
6. Apply the new skill 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 step 6.2 against `/root/plugins/{domain}` rather than the installed copy, mark the report in 6.3 as 「工作樹驗證、尚未部署」, and say plainly which release PR still has to merge before the change reaches any CLI. Completion condition: step 6.2 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 `{domain}<TAB>{name}` row for the new skill, then run every tool the skill added with real arguments and compare each exit code against its documented meaning. Invoke `/jsc-{domain}:{name}` once and confirm the CLI loads the SKILL.md body instead of reporting an unknown command. 用 `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 missing row, an exit code the tool's own documentation does not describe, an unknown command, a prompt failure, or unexpected stderr — fix the cause and rerun this step from 6.1. Completion condition: the row is printed, every added 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 domain repo that gained 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, PR URL, the step 6.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.
5. 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`](../../references/pr-report.md).
6. Deploy the new skill, 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 added skill's row in `tools/list-skills.sh`, every tool the skill added, 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 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 gained 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, PR URL, the step 6.1 route verdict and 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.