Original skill document
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
custom-skills-dev
ai-dev 的 framework 與第一方 skills 分成兩個公開 repositories。開始前先確認目標，不要把內容改到錯的 repository。
Repository ownership
| Repository | 負責內容 |
|---|---|
ValorVie/custom-skills | ai-dev CLI、commands、agents、plugins、project-template、OpenSpec、upstream 設定與 upstream/npx-skills.yaml |
ValorVie/ai-dev-skills | npx skills 可安裝的第一方 skills/<canonical-id>/、skill 直接測試及 collection validator |
第一方 skill 內容不得複製回 framework repository。ai-dev baseline 是否採用某個 skill，由 framework 的 upstream/npx-skills.yaml 明確決定。
Runtime flow
text
ai-dev install
tools → repos → npx-skills → targets
ai-dev update
tools → repos → npx-skillsnpx-skills安裝或更新第一方與第三方 global skills。targets只分發仍由 framework 管理的 commands、agents、workflows、plugins，以及明確保留 clone ownership 的來源。- ECC 白名單 skills 與 custom repo skills 仍可由 clone 管理；不得與 npx-managed canonical ID 同名。
完整 ownership 與路徑見 copy-architecture.md。
修改 ai-dev framework
- 在
ValorVie/custom-skillscheckout 確認現有 dirty files 與 active OpenSpec change。 - 修改
script/、commands/、agents/、plugins/、project-template/或upstream/中的必要檔案。 - 為使用者可見行為更新 OpenSpec delta、測試與正式文件。
- 使用目前 checkout 執行測試，不使用可能過時的已安裝
ai-dev。 - framework release 只提交 framework 範圍，不夾帶另一個 repository 的 skill content。
新增 CLI command 的細節見 cli-development.md。
新增或修改第一方 skill
- 在
ValorVie/ai-dev-skills的skills/<canonical-id>/修改內容。 - 目錄名必須與
SKILL.mdfrontmattername相同。 - 主要流程需要的 scripts、references、assets、templates、evals 與直接測試必須留在 skill root 內。
- 執行 repository validator、skill 直接測試及 npx discovery：
bash
python tests/validate_skills.py
DISABLE_TELEMETRY=1 npx --yes skills@1.5.22 add . --list- 新 skill 只有在 ai-dev 維護者更新
upstream/npx-skills.yaml後，才會進入 baseline。不得用 wildcard 自動採用。
修改 npx baseline
在 ValorVie/custom-skills：
- 先用
npx skills add <repo> --list確認來源與 canonical IDs。 - 檢查同名來源、agent paths 與現有 local modifications。
- 在
upstream/npx-skills.yaml明確加入 repository 與 skill names。 - 更新 npx manifest、install/update、list、toggle 與 migration 測試。
- dry-run 不得執行 npx、寫 lock 或清理 ownership。
發布
兩個 repositories 分開發布、分開驗證、分開 commit。ai-dev-skills 應先有可讀取的 known-good revision，ai-dev 才能引用它。
任何 repository creation、release、tag 或 push 都要遵循當前專案授權；一般文件或程式修改不自動授權 remote mutation。
framework release 細節見 release-workflow.md。
Language
- 人類文件使用繁體中文，技術識別字保留原文。
- Commit message 使用 Conventional Commits 與繁體中文摘要。
- 公開內容不得包含內部品牌、repository、host、帳號、credential 位置、private path 或組織專用流程。
