Menu
Hierarchical skill 撰寫格式。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
當要把一筆需求對齊進 plan package 時觸發，這筆需求可以是對既有規格的變更或缺陷，也可以是要落到既有或全新 plan package 的全新需求。把這筆需求追加進 spec.md 並校準 impact matrix。
跨 skill 共用資源庫，本身不會被執行，只存放供其他 skill 載入的共用資源（reference／asset／script）。
Turn a legal Red handoff for target feature files green by verifying drift, editing product code only, detecting failure oscillation, and emitting a Green handoff. TRIGGER when Green execute is requested after aibdd-red-execute. SKIP when no legal Red handoff exists or the request is test, DSL, runtime, or architecture repair.
當 reconcile 校準 impact matrix 後、本 owner 名下有 pending impact 待落成 persistent data schema 時觸發。以 `read --owner aibdd-data-plan --impact-status pending` 為 worklist，依 Discovery 真相（spec.md／feature truth）把須穩定保存的系統狀態推論成 state schema、在草稿上收斂後委派 boundary profile 宣告之 state_specifier 落地至 `${DATA_DIR}`，最後回寫 impact matrix。
Build the entity-to-table mapping (`entity_to_table_mapping.yml`) from a boundary's physical schema specs (DBML / SQL DDL), preserving existing entity names and naming new tables from the plan spec.
Create legal AIBDD red for target feature files by loading project config, mapping every Scenario step to DSL and core preset assets, rendering runtime-visible step definitions, and emitting a Red handoff. TRIGGER when Red execute is requested or delegated by implementation/debug flow. SKIP when the feature package or BDD stack config is absent.
| name | hierarchical-skill-creator |
| description | Hierarchical skill 撰寫格式。 |
| metadata | {"user-invocable":true,"source":"project-level"} |
每條規則以 bullet + 強情態定義 + 行內 ✗／✓ 對照呈現；先把規則本身定義清楚再貼具象正反例，避免脫錨。
頂層 SKILL.md 只負責 PRINCIPLE 宣告 + Phase 路由；實際步驟一律下放到 NN-<slug>/SOP.md。
頂層 SKILL.md 的允許內容（且僅這些）：
# <skill-title> ← H1 一個
<一句話開場> ← optional
## PRINCIPLE: <name1> ← H2，name 必為命名式
- <bullet>
## PRINCIPLE: <name2>
- <bullet>
...
# SOP ← H1 一個
<延遲控制 boilerplate 兩條> ← 見 §6
0. <參數綁定步驟> ← optional，唯一允許在頂層的 non-EXECUTE 步驟
1. EXECUTE the sub-sop: `NN-<slug>/SOP.md`
2. EXECUTE the sub-sop: `NN-<slug>/SOP.md`
...
N. <告知使用者語句> ← optional，single-line
頂層 SOP 步驟動詞限制：除 phase 0 之 parameter binding（grep / READ arguments.yml）外，禁止業務動詞（READ / WRITE / CREATE / DERIVE / THINK / FAITHFUL REASONING 等）直接出現於頂層 SOP 編號步驟。落盤動作一律下放至 sub-SOP。
1. READ ${PLAN_SPEC} 拆解每段話為 $P …（落盤動詞洩漏到頂層）1. EXECUTE the sub-sop: 01-sourcing-and-packaging/SOP.md一對一綁定：頂層 EXECUTE 必須一步對一個 NN-<slug>/SOP.md；禁止一步同時對應多個 sub-SOP 或多個 sub-SOP 對應同一步。
1. EXECUTE 01-xxx/SOP.md 與 02-yyy/SOP.md1. EXECUTE 01-xxx/SOP.md + 另起一行 2. EXECUTE 02-yyy/SOP.md頂層膨脹禁區：頂層 SOP 不得內嵌 30+ 步細節流程，必須透過 sub-SOP 分散。違反時 lazy load 失效，首回應 latency 拉高、context 浪費。
READ / WRITE / THINK 30 步細項EXECUTE 路由，每個 sub-SOP 自己長到 8–12 步## PRINCIPLE: <名稱> 前置區 + # SOP 主體區的硬切分全域不變式只放在 SKILL.md 的 PRINCIPLE 區；# SOP 區只列流程步驟，不重述 principle。
# <skill-title>
[<開場一句>]
## PRINCIPLE: <命名式 name 1>
- <atomic rule bullet>
## PRINCIPLE: <命名式 name 2>
- …
# SOP
< SOP 步驟 >
位置強制：## PRINCIPLE: block 必須全部出現在 # SOP heading 之前；禁止在 # SOP 區下再開 ## PRINCIPLE: 子節。
# SOP\n## PRINCIPLE: 後置補充 …## PRINCIPLE: 集中在 # SOP 之前命名強制：每個 PRINCIPLE 必須有命名（PRINCIPLE: CWD 為產出錨點），禁止裸 ## PRINCIPLE 或泛稱（如 PRINCIPLE: 一些重要原則）。
## PRINCIPLE 或 ## PRINCIPLE: 注意事項## PRINCIPLE: STRICT SOPAtomic 強制：PRINCIPLE 區內條文須是 atomic rule（一句話一條），不講脈絡敘事、不夾雜歷史決策。
因為之前發生過 X 問題，所以我們現在會 Y …（脈絡敘事）產出物一律落在 CWD 內，禁止寫到 CWD 外的絕對路徑。不重述強制：同一 invariant 禁止在 SOP 個別步驟以括號提示反覆出現。
1. EXECUTE 01-xxx/SOP.md （提醒：路徑不要寫到 CWD 外面喔）## PRINCIPLE: CWD 為產出錨點，SOP 步驟保持乾淨必備內建 PRINCIPLE（任一 hierarchical skill 都必須含這三條，逐字或語意等價）：
PRINCIPLE: STRICT SOP — 鎖死「依序不漏步 + 明示步號 + 限縮延長推理」；完整 boilerplate 見 Appendix A。PRINCIPLE: 長流程待辦（兩層） — 跨對話 compact 後可還原進度；完整 boilerplate 見 Appendix B。PRINCIPLE: Artifact output contract — Deny-by-default 的 side-effect 契約，唯 CREATE/WRITE/UPDATE 明標的 artifact 才能落盤；完整 boilerplate 見 Appendix C。三條皆逐字 / 語意等價複製到頂層 SKILL.md PRINCIPLE 區；缺一即視為非合規 hierarchical skill。這三條是「條款化」的版本，分別對應 §6（延遲控制）／§7（編號鏡像 + Todo 實體化）／§4（授權白名單）的形式約束 — §4/§6/§7 是約定，這三條 PRINCIPLE 是寫入產物。
其他常見但 optional 的 PRINCIPLE：
PRINCIPLE: CWD 為產出錨點 — 凡有 filesystem 產出物必備。每個 SOP 步驟以封閉動詞集合內的 ALL-CAPS 動詞鎖頭，同一語意永遠用同一動詞。
動詞表（封閉集合）：
READ / SEARCH / PARSEWRITE / UPDATE / CREATE / CREATE DIR / CREATE DIRS ONLYDERIVE / ASSERTTHINK / FAITHFUL REASONINGEXECUTE / DELEGATE / LOOP / FOR EACH / IF / END步驟句型：<整數編號>. <ALL-CAPS 動詞> [<目標物 = 路徑/變數/集合>][：補充描述]
動詞位置強制：動詞必須出現於步驟編號 N. 與一個空格之後，緊接步驟句首；禁止動詞嵌在描述中段。
1. 先看一下 layout 規則檔，了解一下路徑怎麼解析。1. READ rules/specs-root-layout.md 作為路徑解析 SSOT。同義 lock：同一動作必須永遠用同一動詞 — 「讀取／閱讀／查看」一律寫成 READ，「想／看／了解／補充／記得」禁止出現於 SOP。
2. 想想看命名語系該選哪個，可以對齊既有的 package 命名。2. DERIVE $package_naming_language：對齊既有 plan package 命名慣例。單一主動詞：一個步驟禁止混兩個主動詞；「READ X 並 WRITE Y」必須拆成兩步。
3. READ template 並 WRITE 報告。3. READ templates/foo.template.md。 + 4. WRITE ${PLAN_REPORTS_DIR}/foo.md（依模板）。目標物單一明確：動詞之後若有目標物，必為單一明確 entity（檔案路徑／$var／${VAR}／集合名）；禁止目標物模糊（「相關檔案」「對應位置」）。
5. UPDATE 相關檔案。5. UPDATE ${PLAN_SPEC}：追加 pointer 與摘要。任何會改變檔案系統的步驟必須夾白名單尾句，未列入名單者一律視為禁止。
凡步驟動詞 ∈ { WRITE, UPDATE, CREATE, CREATE DIR, CREATE DIRS ONLY } 必須符合以下兩條件：
目標路徑明指：用 ${VAR} placeholder 鎖定，禁止裸路徑、禁止模糊量詞（「相關檔案」「需要的話」「順便」「適當地」「合理範圍內」）。
把 sourcing 報告寫好，順便更新 spec.md 和相關檔案。WRITE ${PLAN_REPORTS_DIR}/function-packaging.md（章節以 template 為準）。句末白名單聲明：三種句型擇一，不得省略：
5. CREATE function package 目錄結構，需要的話一起把 dsl / feature / activity 骨架補起來。5. CREATE DIRS ONLY：於 ${TRUTH_BOUNDARY_PACKAGES_DIR} 建立各 ${TRUTH_FUNCTION_PACKAGE}，僅建 ${ACTIVITIES_DIR}、${FEATURE_SPECS_DIR} 骨架。禁止建立 dsl.yml、.feature、.activity、${CONTRACTS_DIR} / ${DATA_DIR} 內容或其它規格檔。READ/SEARCH/THINK/DERIVE 純觀察：搭配頂層 PRINCIPLE「READ/SEARCH/THINK/DERIVE 觀察到的路徑只可作為分析依據，不得被順手建立、寫入、更新或補骨架」，杜絕「LLM 看到就建」。
READ contracts/foo.openapi.yml；如不存在則自動建立空骨架。READ contracts/foo.openapi.yml。若不存在則 DELEGATE /clarify 詢問是否新建。多 artifact 必逐項授權：一步若輸出 ≥ 2 個 artifact，必須列舉每個都允許；禁止只給概述。
WRITE 報告與相關檔案。WRITE ${PLAN_REPORTS_DIR}/foo.md 與 UPDATE ${PLAN_SPEC}。本步僅允許 WRITE 該報告與 UPDATE ${PLAN_SPEC}。${UPPER_VAR} 外綁路徑 vs $lower_var 內推變數兩套變數命名必須各司其職：${UPPER_SNAKE} ＝外部綁定；$lower_snake ＝ SOP 內 DERIVE。
${...}（UPPER_SNAKE）＝外部綁定
arguments.yml / rules/*-layout.md${PLAN_SPEC}、${ACTIVITIES_DIR}$...（lower_snake 或 MixedCase）＝ SOP 內 DERIVE
DERIVE$package_naming_language、$UAT_FLOWS、$Actions路徑錨定強制：任何路徑必須以 ${...} 開頭錨定；禁止裸路徑（./specs/、specs/plans/、絕對路徑）。
1. READ specs/plans/001-foo/spec.md。1. READ ${PLAN_SPEC}。${...} 不可 DERIVE：${...} 必為「外部已綁定」的鍵；SOP 內不得 DERIVE 出新的 ${...}。新中間值一律用 $lower_var。
2. DERIVE ${NEW_SLUG}：對齊既有命名。（不該創造新 ${...}）2. DERIVE $plan_package_slug：形式 NNN-<slug>。大小寫 lock：${...} 與 $... 前綴與大小寫必須綁定；禁止 ${lower_case} 或 $UPPER_CASE。
${naming_lang} 或 $NEW_SLUG${PLAN_PACKAGES_DIR} + $package_naming_language單一寫法：同一個值在不同步驟禁止同時用 ${X} 與 $x 兩種寫法。
${PLAN_SPEC}、Step 5 寫 $plan_spec${PLAN_SPEC}SKILL.md # SOP heading 之後、第一個步驟之前，必須出現兩條延遲控制 boilerplate。
位置：緊接 # SOP heading 下方、Step 0. 或 1. 之前。
Boilerplate（語意鎖死，可改文字）：
# SOP
請執行到哪讀到哪，千萬不要提早閱讀後續文件，這會讓用戶起始體驗到的延遲度
很久，SOP 寫啥就做啥，沒叫你 [THINK/REASONING] 就絕對不准啟用 EXTENDED THINKING。
0. <parameter binding>
1. EXECUTE …
條款 1：lazy-load 強制：禁止提早讀後續檔案（後續 sub-SOP / rules / templates）；只在當步授權範圍內 READ。
# SOP\n開始前請先：讀完所有 sub-SOP 與 rules 目錄下全部規則檔 …# SOP\n請執行到哪讀到哪，千萬不要提早閱讀後續文件 …條款 2：限縮延長推理：未標 THINK / FAITHFUL REASONING 的步驟禁止啟用 extended thinking；該步以最直接可做之 READ／PARSE／DERIVE／WRITE／UPDATE／工具呼叫達成。
1. EXECUTE 01-xxx/SOP.md（先對整個流程做一次完整推演，列出所有可能 edge case 再開始）1. EXECUTE 01-xxx/SOP.md（直接執行，不額外深思）sub-SOP THINK 步驟自帶停損：sub-SOP 內 THINK 必為明文標頭，且必須附「本步只產出判斷，不寫檔」之類短句呼應。
4. 想一下 function package 數量該怎麼拆 …4. THINK：拆解 function package 數量（1..*）；bottom-up 規則見 rules/function-package.md。本步只產出判斷，不寫檔。預讀禁區詞：以下開場語全部禁止 — 「開始前請先讀完所有 sub-SOP / rules」「對整體流程做一次完整推演」「列出所有可能 edge case」「心中先有藍圖再開始第 1 步」。
三件事必須保持鏡像並且強制以工具實體化 Tier 0 Todo。
資料夾命名 regex：^[0-9]{2}[a-z]?-[a-z0-9-]+$
例：01-sourcing-and-packaging、02-activity-analyze、02b-feature-file-list-analyze、03-atomic-rules-analyze。（02b 表 phase 2 之內的補丁式分流，仍排在 03 之前。）
鏡像關係：
SKILL.md # SOP step N → 指向第 N 個（按 NN 前綴排序的）sub-folder
NN-<slug>/ → filesystem 上的第 N 個資料夾
Todo Tier 0 (N) → 「(N) 展開並執行至完成：<NN-<slug>>/SOP.md」
資料夾編號強制：sub-SOP 資料夾必須以 NN 前綴開頭（可帶 lowercase 字母如 02b）；禁止無編號名（sourcing/、activities/）。
sourcing/SOP.md、activities/SOP.md01-sourcing-and-packaging/SOP.md、02-activity-analyze/SOP.mdEXECUTE 順序對齊：SKILL.md 第 N 個 EXECUTE 步驟必須指向第 N 個 NN-* 資料夾（按字典序）；禁止順序倒置或跳號。
1. EXECUTE 02-... + 2. EXECUTE 01-...（順序倒置）1. EXECUTE 01-... + 2. EXECUTE 02-...Todo Tier 0 工具實體化：進入 sub-SOP 之前必須用 TodoWrite / TODOCREATE / TASKCREATE 建立 Tier 0 清單；禁止只在 chat 內口頭列點。
我接下來會做這四步：sourcing、activity、feature、atomic-rules（不開 Todo）(1)..(4) 四條 Tier 0 entry，並隨進度勾選Tier 1 lazy expand：Tier 1（phase 內細項）只在「進入該 phase」當下展開；不得為後續 phase 預開細項，避免 Todo 與 SOP 脫節。
每個 sub-SOP 資料夾必須按固定 mini-tree 分層，只允許自內相對引用。
NN-<slug>/
SOP.md ← 必，流程主文
rules/ ← optional：規則檔（雙段式，見 §9）
<topic>.md ← 任何規則主題（命名規則、邊界規則、欄位規則 …）
templates/ ← optional：結構骨架（fenced block 逐字複製對象）
<name>.template.md
assets/ ← optional：非規範性附件
templates/<name>.example.md ← 語感對照範例
reasoning/ ← optional：被 SOP THINK 步驟 READ 的延伸推理
<topic>.md
檔案分層強制：規則類檔放 rules/；模板類檔放 templates/；範例放 assets/templates/*.example.md；推理腳本放 reasoning/。禁止不同類檔平鋪在同一層。
02-x/actor.md + 02-x/initial-feature.md + 02-x/control-flow.md（規則／模板／推理混平鋪）02-x/rules/activity-actor.md + 02-x/templates/initial-feature-file.template.md + 02-x/reasoning/activity-control-flow.md自內相對引用強制：sub-SOP 內所有 link 必為自資料夾根的相對路徑（例：rules/foo.md、templates/bar.template.md）。
READ /Users/foo/notes/actor-tips.md（絕對路徑破壞 CWD 錨點）READ rules/activity-actor.md跨 phase 反向引用禁區：引用同 skill 內其他 phase 須透過 SKILL.md 路由或 sibling skill 的 references/；禁止 ../NN-other/... 直連，會造成 phase 之間循環依賴。
READ ../01-sourcing-and-packaging/rules/shared-naming.mdaibdd-core::FILENAME.md），各 phase 各自 LOAD跨 skill 直連禁區：禁止 ../../other-skill/... 直連；跨 skill 必須用 sibling skill 的 reference hub 慣例（e.g. aibdd-core::FILENAME.md 載入）。
READ ../../aibdd-core/references/ssot/spec-package-paths.mdaibdd-core::ssot/spec-package-paths.md（由 host 解析）# <規則主題> + ## Good + ## Bad 三段式所有 rules/*.md 必須用固定三段骨架：H1 寫規則主題與正向條款、H2 ## Good 與 H2 ## Bad 給具象正反例。
# <規則主題>
- <強情態 bullet 1>
- <強情態 bullet 2>
...
## Good
- <具象正例 1>
- <具象正例 2>
...
## Bad
- <具象違例情境 1>
- <具象違例情境 2>
...
H 階層強制：規則主題用 # (H1)、Good 與 Bad 必為 ## (H2) 子節；禁止 Good/Bad 用 # (H1) 與主題同階，兩者必須從屬於主題之下。
# Actor 命名規則 之後再開 # Good 或 # Bad（H1 同階）# Actor 命名規則 之後接 ## Good 與 ## Bad（H2 子節）強情態詞強制：H1 body 每條 bullet 必須含強情態詞之一作為條款主動詞 —「得 / 不得 / 禁止 / 僅當…才 / 必須 / 不准」；禁止 hedging 詞（「通常」「一般來說」「有時候」「建議」「最好」「可以」「應該」）。
Actor 通常是使用者，也可以是其他系統。一般來說建議畫人類角色 …不得將產品內建系統、自有後端、排程、worker、資料庫列為獨立 Actor。Atomic 強制：H1 body 一條 bullet 必為一條 atomic rule，禁止混合多條件；多條件必須拆成多條 bullet。
Actor 是 UI-facing 人類，且第三方系統若入口為 Webhook 也可以是 Actor，並且名稱要唯一 …（一條塞三條規則）Good/Bad 具象強制：## Good 與 ## Bad 區每 bullet 必為「具象情境」；禁止抽象陳述（「要寫清楚」「不要亂寫」），LLM 無法反向偵測。Bad bullet 尤須是「會被誤判為合規但實際違例」之具象情境。
Bad：不要把不適合的東西畫成 Actor。Bad：使用者在 UI 按下付款後，另立金流閘道、寄信服務為 Actor，把非入口的下游互動當成圖上獨立身分。三段完整性：禁止缺任一段（規則主題 / ## Good / ## Bad）；## Bad 條數 ≥ H1 body 條款的關鍵 case 數，讓 LLM 能反向偵測自己輸出。
# Actor 命名規則 + ## Bad，無 ## Good「Phase router + 授權白名單 + 強情態動詞 + 外綁變數 + 編號鏡像 Todo」 — 形式上把 LLM agent 當成嚴格受限狀態機在寫：每一步授權什麼動詞、寫什麼路徑、寫到哪裡，全部在文本層硬編；自由發揮的空間只留在被明確標 THINK / FAITHFUL REASONING 的格子裡。
下列三條 PRINCIPLE 為任一 hierarchical skill 之必備內建條款（見 §2 必備內建 PRINCIPLE 清單）。Boilerplate 已外移至 templates/ 下對應檔案，作為逐字複製對象；建立新 skill 時請從這三個檔逐字 / 語意等價貼進目標 SKILL.md 的 PRINCIPLE 區，缺一即視為非合規 hierarchical skill。
PRINCIPLE: STRICT SOPTemplate 檔：templates/principle-strict-sop.template.md
這條條款做兩件事：
使用方式：
## PRINCIPLE: STRICT SOP 起到第 2 點末）## PRINCIPLE: … 區PRINCIPLE: 長流程待辦（兩層）Template 檔：templates/principle-long-process-todo.template.md
這條條款做兩件事：
使用方式：
## PRINCIPLE: … 區PRINCIPLE: Artifact output contractTemplate 檔：templates/principle-artifact-output-contract.template.md
這條條款做兩件事：
使用方式：
## PRINCIPLE: … 區本 skill 的當前 mini-tree（呼應 §8 慣例）：
hierarchical-skill-creator/
SKILL.md # 本檔；九大特徵 + Appendix
rules/
writing-style-principles.md # skill 撰寫排版原則
templates/
principle-strict-sop.template.md # Appendix A 逐字複製對象
principle-long-process-todo.template.md # Appendix B 逐字複製對象
principle-artifact-output-contract.template.md # Appendix C 逐字複製對象