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-check/SKILL.md
+28 -22
View File
@@ -1,6 +1,6 @@
---
name: skill-check
description: Routine compliance, script, hook, flow-efficiency, and cost-efficiency audit of the whole jsc skill set with no change request in hand. Sync every domain repo from the Gitea canonical marketplace, validate scripts and hook smoke, audit every skill against guidelines.md, then review parallelism, tool extraction, repeated interaction, redundant checks, misplaced gates, and avoidable token, sub-agent, API, scan, or interaction cost. Confirm compliance fixes and optimization suggestions before applying them, re-check until accepted fixes pass, then open a PR per affected repo via jsc-git pr. Use for periodic or on-demand skill-set checks; not for applying a change request (use skillset-update) or editing one skill (use skill-update).
description: Routine compliance, script, hook, flow-efficiency, and cost-efficiency audit of the whole jsc skill set with no change request in hand. Sync every domain repo from the Gitea canonical marketplace, then run three parallel groups - lint-scripts.sh plus hook smoke, the guidelines.md checklist audit, and a review of parallelism, tool extraction, repeated interaction, redundant checks, misplaced gates, and avoidable token, sub-agent, API, scan, or interaction cost. Confirm compliance fixes and optimization suggestions before applying them, re-check until accepted fixes pass, then open a PR per affected repo via jsc-git pr. Use for periodic or on-demand skill-set checks; not for applying a change request (use skillset-update) or editing one skill (use skill-update).
---
# skill-check — audit compliance, flow efficiency, and cost efficiency
@@ -9,22 +9,26 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
## 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. Validate scripts and hooks before reading skill text:
1. For every synced domain repo, run `find {domain-path}/tools {domain-path}/hooks -type f -name '*.sh' -exec sh -n {} \;` for directories that exist. Report each script that fails with path and parser output. Missing `tools/` or `hooks/` directories are not failures.
2. For every shell script directly named by a touched or audited SKILL.md, confirm the script exists, is executable when it is meant to be called directly, and documents or implements every exit code the skill routes. Report evidence as `skill file:line -> script path`.
3. When the `jsc-hooks` domain is present, run `jsc-hooks/tools/wire-cli.sh smoke {cli}` for every CLI reported by `jsc-cli/tools/detect-clis.sh`. When no CLI is detected, run `jsc-hooks/tools/wire-cli.sh smoke codex` as the minimum hook behavior check and label it 「預設 hook smoke」 in the report. Use `smoke`, not `purge` or rewiring actions.
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.
The three review groups of step 2 all read this synced tree, so the sync finishes first.
2. Run the three review groups over the synced repos. They are independent — every one only reads, none writes a file — so **launch all three in parallel** and merge their results in step 3.
**Group 1 — validate scripts and hooks.**
1. For every synced domain repo, run `tools/lint-scripts.sh {domain-path}`. One run per domain, and the runs go **in parallel** — no domain's verdict depends on another's. The tool covers three checks in one pass: `sh -n` syntax, executable bit, and an exit-code declaration in the file header. Route each exit code: 0 — the domain's scripts pass all three; 1 — the failing items are printed as `{file}:{check}:{detail}`, so report each one; 2 — usage error, the tool takes exactly one argument; 3 — nothing was scanned, because the path is missing or the domain has neither `tools/` nor `hooks/`. Record exit 3 as 「無腳本可掃」; a domain with no script directory is not a failure, but exit 3 is **never** a pass.
2. For every shell script directly named by a SKILL.md, confirm the skill routes every exit code the script's header declares. `lint-scripts.sh` proves the script exists and declares its codes; this check is the other half — that the caller branches on each of them. Report evidence as `skill file:line -> script path`.
3. When the `jsc-hooks` domain is present, run `jsc-hooks/tools/wire-cli.sh smoke {cli}` for every CLI reported by `jsc-cli/tools/detect-clis.sh`; the per-CLI smokes run **in parallel**. When no CLI is detected, run `jsc-hooks/tools/wire-cli.sh smoke codex` as the minimum hook behavior check and label it 「預設 hook smoke」 in the report. Use `smoke`, not `purge` or rewiring actions, and set `JSC_READONLY=1` for the whole audit so a mistyped sub-command is refused in code (exit 6) instead of rewiring the machine; `status` and `smoke` are unaffected by that variable. Route each `smoke` exit code: 0 — the run passed its own assertions; 2 — usage error, so fix the CLI code and rerun; 4 — the smoke failed, which includes the script's own result-line count not matching what it expected. **Read the count from the script's `lines<TAB>{數量}` output line; never write the number into this skill.** The script counts its own result lines and asserts them, so a hardcoded number here goes stale the moment a hook or a decision path is added — an out-of-date count in a SKILL.md is exactly what misled the previous audit.
4. When a hook or script smoke fails, route it as a compliance failure with script name, exit code, output summary, and proposed fix. Do not continue to report the affected hook as compliant.
Completion condition: every domain has a script syntax verdict, every named script has an existence and exit-code-routing verdict, and the `jsc-hooks` domain has a hook smoke verdict.
3. Audit every skill of every domain against the guidelines.md audit checklist — this step MUST run as a sub agent, one sub agent per domain repo. Each sub agent reports its findings: skill, failed checklist item, evidence (file:line), proposed fix. Cover the checklist's four flow checks by name, not only the naming and language items:
1. Every step number, file path and section title the skill references — inside itself and in other files — really exists (the pointer points at something).
2. Every step ends in a checkable completion condition, with no vague wording.
3. Every external call (script, API, other skill) states what to do on failure and routes every exit code.
4. No gate the skill installs blocks the only path that lifts that gate.
**Group 2 — audit every skill of every domain against the guidelines.md audit checklist.** This group MUST run as a sub agent, one sub agent per domain repo, and those sub agents run **in parallel**. Each sub agent reports its findings: skill, failed checklist item, evidence (file:line), proposed fix. Cover the checklist's four flow checks by name, not only the naming and language items:
- Every step number, file path and section title the skill references — inside itself and in other files — really exists (the pointer points at something).
- Every step ends in a checkable completion condition, with no vague wording.
- Every external call (script, API, other skill) states what to do on failure and routes every exit code.
- No gate the skill installs blocks the only path that lifts that gate.
Completion condition: every domain has an audit result that names a verdict for all checklist items, the four flow checks included.
4. Run a separate flow and cost optimization review after the compliance audit. Each aspect **MUST run as a sub agent**, and the six aspects may run in parallel:
Three checklist items are **already decided by group 1** and must not be re-run here: `sh -n` on every `tools/` and `hooks/` script, script existence with the executable bit, and the hook smoke. Tell each sub agent to skip those three and leave them blank; the main agent fills them in from the group 1 verdicts when merging in step 3. Re-scanning the same files in every domain sub agent buys nothing — group 1 already scanned them all, with the same tool, on the same synced tree.
**Group 3 — a flow and cost optimization review**, kept separate from the compliance audit. Each aspect **MUST run as a sub agent**, and the six aspects run in parallel with each other and with groups 1 and 2:
| Aspect | Scope |
| --- | --- |
@@ -35,19 +39,21 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
| 5 Gate timing | Gates that run too early or too late, causing wasted work before a block or blocking the only path that clears the gate |
| 6 Cost efficiency | Avoidable token, sub-agent, API, file-scan, full-repo audit, or user-interaction cost that can be reduced without weakening correctness |
Each optimization finding reports skill, aspect, evidence (file:line), current flow step count, proposed flow step count, what time or interaction it saves, what cost it saves, current cost driver, proposed cost driver, whether correctness decreases, and which protection would be weakened if any. Cost savings may be token volume, sub-agent count, API calls, file scans, full-repo audits, or user prompts. Keep optimization findings separate from compliance failures. Completion condition: every aspect has returned a verdict for every domain; aspects with no findings return 「無發現」.
5. Present compliance failures and optimization findings separately via the `jsc-ask:ask` decision tree:
Each optimization finding reports skill, aspect, evidence (file:line), current flow step count, proposed flow step count, what time or interaction it saves, what cost it saves, current cost driver, proposed cost driver, whether correctness decreases, and which protection would be weakened if any. Cost savings may be token volume, sub-agent count, API calls, file scans, full-repo audits, or user prompts. Keep optimization findings separate from compliance failures.
Completion condition for all three groups: every domain has a `lint-scripts.sh` verdict, every script named by a SKILL.md has an exit-code-routing verdict, and every smoked CLI has a `smoke` exit code plus the `lines` value the script printed for it; every domain has a group 2 audit result that names a verdict for all checklist items — the four flow checks included, and the three group 1 items left blank for the step 3 merge rather than re-scanned; and every one of the six aspects has returned a verdict for every domain, 「無發現」 where an aspect found nothing.
3. Merge the three groups, then present compliance failures and optimization findings separately via the `jsc-ask:ask` decision tree. Merging means one thing in code: fill the three skipped checklist items of every group 2 sub agent report from the matching group 1 verdicts, so each domain ends with one complete checklist and no item counted twice.
- Compliance failure options: apply the proposed fix / skip / custom fix. Every option states its impact scope, for example skipping leaves the skill non-compliant until the next audit.
- Optimization options: apply / defer / custom. Any suggestion that weakens a protection must name the protection it removes and must not be applied unless the user explicitly accepts that tradeoff. Cost optimization may move, merge, cache, or narrow checks; it must not delete a compliance check only because it is expensive.
Completion condition: every compliance failure and every optimization finding has a recorded decision.
6. Apply the confirmed fixes and accepted optimizations — the file-change part MUST run as a sub agent, one sub agent per affected domain repo: modify the files per the recorded decision. Then run `tools/sync-skill-manifest.sh {domain-path}` directly (no sub agent needed) for each affected domain repo to refresh that domain README's 「Skills 目錄」 section and bump the version in all three manifests. Completion condition: every affected repo carries the changes and the manifest bump.
7. Sync the canonical marketplace — a **required** step, never optional. The canonical pair lives in `plugins/meta` and every domain repo carries a byte-identical copy, so a fix that leaves the copies apart makes some repos register a stale plugin set. Run `tools/sync-marketplace.sh {domain} {repo-url} {description}` once with an existing entry's own current values (rewriting the same entry is idempotent); the script rewrites both canonical files and copies them into every domain repo. Route each exit code:
Completion condition: every domain's checklist is complete after the merge, and every compliance failure and every optimization finding has a recorded decision.
4. Apply the confirmed fixes and accepted optimizations — the file-change part 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. Then run `tools/sync-skill-manifest.sh {domain-path}` directly (no sub agent needed) for each affected domain repo to refresh that 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: every affected repo carries the changes and the manifest bump.
5. Sync the canonical marketplace — a **required** step, never optional. The canonical pair lives in `plugins/meta` and every domain repo carries a byte-identical copy, so a fix that leaves the copies apart makes some repos register a stale plugin set. Run `tools/sync-marketplace.sh {domain} {repo-url} {description}` once with an existing entry's own current values (rewriting the same entry is idempotent); the script rewrites both canonical files and copies them into every domain repo. 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: the script takes exactly three arguments. Fix them 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.
8. Re-run the script and hook validation from step 2, re-check the guidelines.md audit checklist for every touched skill, then re-run the optimization aspect that produced each accepted optimization. On any compliance failure, **return to step 5**: confirm and fix again, until all accepted compliance fixes pass. On an accepted optimization that does not produce the promised step reduction or cost reduction, or still weakens correctness beyond the recorded decision, return to step 5 for a new decision. Completion condition: all script and hook checks pass, all checklist items pass, and every accepted optimization has a matching verification result.
9. Call `jsc-git:pr` once per affected domain repo to open a Push Request. Completion condition: every affected repo has a PR URL, and all URLs are reported in one table with the format in `references/pr-report.md`.
6. Re-run the group 1 script and hook validation, re-check the guidelines.md audit checklist for every touched skill, then re-run the optimization aspect that produced each accepted optimization. These three re-runs are as independent as the first pass, so run them **in parallel** and merge them the same way step 3 did. On any compliance failure, **return to step 3**: confirm and fix again, until all accepted compliance fixes pass. On an accepted optimization that does not produce the promised step reduction or cost reduction, or still weakens correctness beyond the recorded decision, return to step 3 for a new decision. Completion condition: `tools/lint-scripts.sh` exits 0 or 3 for every domain, every hook smoke exits 0 with the `lines` count the script itself asserted, all checklist items pass, and every accepted optimization has a matching verification result.
7. Call `jsc-git:pr` once per affected domain repo to open a Push Request. Completion condition: every affected repo has a PR URL, and all URLs are reported in one table with the format in [`../../references/pr-report.md`](../../references/pr-report.md).