Skills
每個 OpenSpec 技能：引數、它建立的內容，以及它回應的內容。
技能分為兩組：
- 核心：預設安裝，主要的規劃迴路。
- 選用：僅在你透過 Profiles 新增時安裝。
每個技能都預期專案已經使用 OpenSpec。在其寫入任何內容的第一個步驟之前，技能會檢查是否有已解析的根目錄。當沒有根目錄時，會發生什麼事取決於技能被觸發的方式：
- 自動選取：你的代理自行選取了該技能，而你並未提及 OpenSpec。它會放棄 OpenSpec 並正常回答你的要求，就像未安裝 OpenSpec 時一樣。
- 明確 OpenSpec 要求：你提及了 OpenSpec、指定了技能，或執行了它的命令。它會在寫入前停止並詢問如何繼續：在此執行
openspec init、以--store <id>指定存放區，或在沒有 OpenSpec 的情況下繼續。它會等待你的回答。
命令永遠屬於第二種情況。若專案的 openspec/config.yaml 指定的存放區這部機器無法解析（未註冊，或 store: 行格式錯誤），不會被視為未初始化：技能會停止並顯示存放區錯誤及其修正方式。在這兩種情況下，沒有技能會自行建立 openspec/ 目錄。以下條目說明每個技能在根目錄就緒後的行為。
| 技能 | 工作 | 類型 |
|---|---|---|
| openspec-explore | 在構想成為變更提案之前先仔細思考 | 核心 |
| openspec-propose | 以一個步驟建立變更提案及其所有規劃產物 | 核心 |
| openspec-apply-change | 實作變更提案的任務 | 核心 |
| openspec-update-change | 修訂變更提案的計畫 | 核心 |
| openspec-sync-specs | 將變更提案的規格更新合併至 specs/ | 核心 |
| openspec-archive-change | 將已完成的變更提案移至封存區 | 核心 |
| openspec-new-change | 以空腳手架開始變更提案 | 選用 |
| openspec-continue-change | 一次建立一個下一個規劃產物 | 選用 |
| openspec-ff-change | 一次建立包含實作所需全部產物的變更提案 | 選用 |
| openspec-verify-change | 檢查實作是否符合計畫 | 選用 |
| openspec-bulk-archive-change | 一次封存多個變更提案 | 選用 |
| openspec-onboard | 透過端到端完成一個真實的變更提案來學習工作流程 | 選用 |
以下每個條目都指明負責下一步的技能。當你的 profile 未包含該技能時，已安裝的檔案絕不會提及它：交接會改為對等的 openspec 命令，或改為直接對你的要求，而僅為指向遺失技能而存在的那一行根本不會被寫入。因此你擁有的技能永遠會交接給你所擁有的技能。你要使用哪一組取決於 Profiles。
openspec-explore
在想法成為變更提案之前，先對其進行思考。
| 合約 | 描述 |
|---|---|
| 參數 | 一個主題：一個想法、一個問題、一個比較，或一個現有變更提案的名稱，以便在上下文中探索。若未提供任何內容，則進入探索模式。 |
| 建立 | 預設不建立任何內容。它僅進行閱讀與調查。依需求捕捉洞察：在 openspec/changes/<name>/ 下建立新的變更提案，或更新現有提案的 proposal、design、specs 或 tasks。絕不建立程式碼。 |
| 回應 | 一個開放式對話，沒有必需的輸出。當思考具體化時，它會總結問題、方法、開放問題和後續步驟，並提供捕捉這些內容的選項。由你決定。實作絕不從這裡開始。 |
openspec-propose
建立變更提案，並在一次步驟中產生其所有規劃工件。
| 合約 | 描述 |
|---|---|
| 參數 | 一個 kebab-case 名稱（add-dark-mode）或一個純文字描述。若兩者皆未提供，則會詢問。 |
| 建立 | 在 openspec/changes/<name>/ 中建立 schema 定義的所有工件，依相依順序（spec 驅動：proposal、spec deltas、design、tasks）。絕不建立程式碼。 |
| 回應 | 已建立的工件，可供審查，以及下一步。到此為止；實作等待 openspec-apply-change。 |
openspec-apply-change
實作變更提案的任務，依序處理清單直到完成或受阻。
| 合約 | 描述 |
|---|---|
| 參數 | 變更提案名稱（add-auth），可選。若目標不明確，它會列出作用中的變更提案並請你選擇。 |
| 建立 | 程式碼：每個任務所需的最小變更，寫入你的專案檔案。在變更提案中，它會在由 sourcePath 和以 1 為起始的 line 所識別的追蹤檔案中，將每個已完成的任務標記為完成（- [ ] 改為 - [x]）。schema 可能跨多個檔案追蹤任務。 |
| 回應 | 每個任務的進度，然後是整體計數（N/M 個任務完成）。全部完成：建議 openspec-archive-change。因缺少工件而受阻：指向 openspec-continue-change，或當該技能未安裝時指向 openspec status 和 openspec instructions（核心設定檔不包含它）。任務不明確或發生錯誤：暫停並詢問。 |
openspec-update-change
修訂變更提案的現有規劃工件，並保持它們彼此一致。
| 合約 | 描述 |
|---|---|
| 參數 | 變更提案名稱，可選，加上你想要的修訂版本。若未指定修訂版本，它會執行一致性審查：檢查工件之間是否有矛盾、遺漏和重複。 |
| 建立 | 編輯已存在的工件檔案。一個例外：對於以 glob 形式撰寫的工件，例如 specs/**/*.md，且已至少有一個檔案，它可以在你確認路徑後新增缺少的配套檔案。尚無任何檔案的工件是 openspec-continue-change 的職責。若沒有該技能（核心設定檔不包含它），則改為指向 openspec status 和 openspec instructions。絕不建立程式碼。 |
| 回應 | 顯示每個提議的修訂，並僅在你確認後才寫入，一次一個工件。最後總結已修訂的內容和下一步；實作等待 openspec-apply-change。 |
openspec-sync-specs
將變更提案的 spec 更新合併到 specs/，而不封存它。
| 合約 | 描述 |
|---|---|
| 參數 | 變更提案名稱，可選。你也可以指定其 delta specs 的子集，僅同步那些。 |
| 建立 | 為每個 delta spec 編輯或建立 openspec/specs/<capability-path>/spec.md，將新增、修改、移除和重新命名的需求合併到主 spec。絕不建立程式碼。 |
| 回應 | 在更新後的 specs 驗證通過後，提供每個能力的需求新增、修改、移除或重新命名摘要。變更提案維持作用中；封存等待 openspec-archive-change。 |
openspec-archive-change
將已完成的變更提案移至封存區。
| 合約 | 描述 |
|---|---|
| 參數 | 變更提案名稱，可選。 |
| 建立 | 將變更提案資料夾移至 openspec/changes/archive/YYYY-MM-DD-<name>/（若名稱已以日期開頭則不另加日期）。經你核准後，它會先同步未處理的 delta specs。當 openspec-sync-specs 已安裝時，它會執行該工作流程。否則，它會自行將 delta specs 合併到主 specs。絕不建立程式碼。 |
| 回應 | 在封存前若工件或任務不完整，會警告並詢問，且當 delta specs 存在時會詢問是否同步。最後總結：名稱、schema、封存位置、spec 同步狀態，以及任何警告。 |
openspec-new-change
以空脚手架開始一個變更提案。
| 合約 | 描述 |
|---|---|
| 參數 | 一個 kebab-case 名稱（add-user-auth）或一個純文字描述，加上僅用於非預設工作流程的 schema 名稱。若兩者皆未提供，則會詢問你想建立什麼。 |
| 建立 | 在 openspec/changes/<name>/ 建立空的 scaffold：尚無任何工件，絕不建立程式碼。 |
| 回應 | 脚手架的名稱和位置、工作流程的工件順序、狀態（0/N 完成），以及第一個工件的範本。撰寫工件等待 openspec-continue-change。 |
openspec-continue-change
一次建立變更提案中的下一個規劃工件。
| 合約 | 描述 |
|---|---|
| 參數 | 變更提案名稱，可選。若仍不明確，它會請你從最近修改的項目中選擇。 |
| 建立 | 在 schema 的順序中，下一個就緒的單一工件，寫入變更提案資料夾。每次執行一個工件，絕不建立程式碼。 |
| 回應 | 已建立的工件、進度（N / M 完成），以及該工件解鎖了哪些工件。當規劃完成時會明確說明；實作移至 openspec-apply-change。 |
openspec-ff-change
一次建立變更提案及實作所需的所有規劃工件。
| 合約 | 描述 |
|---|---|
| 參數 | 一個 kebab-case 名稱或一個純文字描述。若兩者皆未提供，則會詢問。若指定的變更提案已存在，它會建議改為繼續該提案。 |
| 建立 | 在 openspec/changes/<name>/ 中建立實作所需的所有規劃工件，依相依順序（spec 驅動：proposal、specs、design、tasks），僅略過標記為 skipped 或 conditional 的工件。絕不建立程式碼。 |
| 回應 | 變更提案的名稱和位置、每個已建立的工件，以及任何被略過的條件式工件及其原因。到此為止；實作等待 openspec-apply-change。 |
openspec-verify-change
檢查實作是否符合變更提案的工件。
| 合約 | 描述 |
|---|---|
| 參數 | 變更提案名稱，可選。當不明確時，它會列出具有 tasks 工件的變更提案並詢問。 |
| 建立 | 不建立任何內容。它會閱讀變更提案的工件和程式碼庫。驗證僅產生報告。 |
| 回應 | 一份報告：完整性、正確性和一致性的計分卡，然後是 CRITICAL、WARNING 和 SUGGESTION 等級的問題與建議，以及最終的封存準備度評估。它不改變任何內容，也不封存。 |
openspec-bulk-archive-change
一次封存多個變更提案。
| 合約 | 描述 |
|---|---|
| 參數 | 無。它會列出作用中的變更提案，並請你選擇任意數量，並提供全選選項。若沒有作用中的提案，它會說明並停止。 |
| 建立 | 每個封存的變更提案會建立 openspec/changes/archive/YYYY-MM-DD-<name>/（已含日期的名稱保留其前綴）。每個提案的 spec deltas 會先透過 openspec-sync-specs 同步。絕不建立程式碼。 |
| 回應 | 每個變更提案的狀態表格，以及整個批次的一次確認，然後是封存、略過和失敗的摘要，加上 spec 同步結果。當兩個變更提案觸及同一個 spec 時，它會檢查程式碼庫，並依最舊到最新同步已實作的 deltas。 |
openspec-onboard
透過實際執行一個真實的變更提案來學習工作流程。
| 合約 | 描述 |
|---|---|
| 參數 | 無。它會掃描你的程式碼庫，尋找小型入門任務，並請你選擇一個或描述你自己的任務。 |
| 建立 | 為所選任務建立一個真實的變更提案，一次一個工件，然後在你確認實作後建立真實程式碼。最後封存該變更提案。 |
| 回應 | 完整週期的逐步導覽，並在需要你的輸入時暫停：探索、建立、建構每個工件、實作、封存。最後以回顧和指向 openspec-propose 的提示作結。約需 15 到 20 分鐘。 |