此檔案是為技能消費者準備的，而非貢獻者。開發背景資訊請參閱 AGENTS.md —— 此技能的建立、迭代與測試方式。
文件工作區引導
此技能教導 AI 代理程式如何從頭開始，在一個空（或近乎空）的目錄中引導建立一個文件工作區。其結果是一個版本化、基於檔案系統、完全自給自足的知識庫——由使用者擁有、免費、無供應商鎖定，且結構化設計，讓在其中工作的代理程式無需考慮組織、格式或工具問題。
核心概念
一個已引導的工作區包含其專屬的 AGENTS.md —— 一個針對特定主題的「凍結的迷你技能」（per-workspace, topic-specific "frozen mini-skill"），代理程式在進入工作區時會讀取它。AGENTS.md 是根據此技能提供的範本建立的。一旦工作區存在，代理程式就遵循 AGENTS.md，而不是此技能。這就是全部的重點：預先決定規則一次，之後永遠不需要再耗費 token 重新推導。
何時使用此技能
請僅在以下情況使用此技能：
- 使用者明確想要建立/設置/初始化/建立一個文件工作區、docs 資料夾或知識庫。
- 目標目錄是空的或近乎空的（或者使用者儘管有現有檔案，仍明確選擇使用）。
- 目標目錄尚未包含
AGENTS.md（這表示它已經被引導）。
如果目標目錄已存在 AGENTS.md：不要執行此技能。請讀取現有的 AGENTS.md 並遵循它。使用者已經在一個已引導的工作區中。
何時不要使用此技能
- 使用者想要在現有工作區內新增文件、編輯文件、連結文件或重新組織——由工作區自己的
AGENTS.md來管理。 - 使用者想要推送到 GitHub、在瀏覽器中渲染工作區或設定託管——這些是不同的需求，需要不同的技能。
- 使用者提出關於文件、寫作或筆記的一般性問題——則不需要技能。
此技能產生的內容
當執行時，此技能會建立一個包含以下內容的工作區：
| 檔案 / 目錄 | 用途 |
|---|---|
AGENTS.md | 每個工作區專屬的「凍結的迷你技能」。95% 是規則，5% 是主題摘要。代理程式在進入時讀取此檔案。 |
README.md | 工作區層級的概覽。更豐富的介紹、自動生成的索引、指向 AGENTS.md 的指標。 |
index.yaml | 根目錄的文件排序。預設為空。 |
.gitignore | 合理的預設值：備份、作業系統垃圾檔案、編輯器檔案、Node。 |
package.json | 開發依賴項：prettier、markdownlint-cli、js-yaml。用於工具的 npm 腳本。 |
.prettierrc | Prettier 設定：120 字元行長、proseWrap preserve。 |
.markdownlint.json | markdownlint 設定，停用 nitpick 規則。 |
scripts/ | 輔助腳本：format.js、validate.js、hash.js、reindex.js。 |
assets/ | 空的共享資產目錄。建立在工作區根目錄。 |
如果系統中有 git，則在工作區中初始化一個 Git 儲存庫。如果系統中有 Node 和 npm，則安裝開發依賴項。
引導工作流程
請依序執行以下步驟。在每個標示的步驟中，都需與使用者確認。 切勿自行假設。
步驟 1 —— 確認目標位置
詢問使用者：「我將在 <cwd> 中引導建立文件工作區。是否正確？（是 / 否 / 指定路徑）」
- 如果回答「是」：則將 cwd 設為目標並繼續。
- 如果回答「否」：請使用者提供正確的路徑，確認後再繼續。
- 如果使用者說「在這個資料夾」或類似意思：則假定為 cwd，但仍需確認。
步驟 2 —— 確認目標為空（或取得使用者同意）
列出目標目錄的內容（排除像是 .git 的隱藏檔案）。
如果為空：則前往步驟 3。
如果不為空：
- 向使用者顯示目錄中的內容。
- 解釋：「此目錄並非空目錄。根據預設，此技能拒絕在非空目錄中進行引導。您可以選擇 (a) 中止，(b) 確認您仍希望我繼續，我將保留現有檔案不動，或 (c) 指定一個子目錄來建立工作區。」
- 等待使用者明確確認。如果使用者沒有給予嚴格的正面肯定，則中止。
- 如果使用者說「請繼續」或「是，請繼續」——則記錄為使用者同意並繼續。
如果目標目錄已存在 AGENTS.md：停止。工作區已經被引導。告知使用者，並提供讀取現有 AGENTS.md 的選項。
如果目標目錄已初始化 git：跳過後續的 git init 步驟，但繼續進行。
步驟 3 —— 收集主題摘要
詢問使用者：「這個文件工作區的主題是什麼？請用 1-2 段短文描述這個主題。這將成為 AGENTS.md 中的主題摘要和 README.md 中的介紹。」
主題摘要規則：
- 1 段（較佳），最多 2 段
- 純文字敘述，無格式，無列表
- 清楚說明工作區要記錄的文件內容
如果使用者只給了一句話：沒問題，直接使用。 如果使用者給出較長的描述：將其濃縮（需經使用者確認）或最多使用 2 段。 如果使用者說「你來決定」或「我還不知道」：請使用者至少提供一句話——主題摘要是 AGENTS.md 中唯一與主題相關的部分，工作區需要某種錨點。
步驟 4 —— 執行引導腳本
當你確認以下資訊都已取得：
- 目標路徑
- 確認該目錄合適
- 主題摘要
...接著執行引導腳本：
node /assets/skill-scripts/bootstrap.js --target --topic ""
腳本會：
- 確認 Node.js 是否可用（如否，則跳過 Node 相關的產物並發出警告）
- 確認 git 是否可用（如否，則跳過
git init） - 建立目錄結構
- 從
<skill-dir>/assets/templates/實例化所有範本，並替換{{TOPIC_SUMMARY}}和{{CREATED}}佔位符 - 複製工作區附帶的腳本（
format.js、validate.js、hash.js、reindex.js）到<target>/scripts/ - 執行
npm install（如果 Node + npm 可用） - 執行
git init（如果 git 可用） - 列印一份已建立內容的摘要
如果腳本執行失敗（例如權限問題、缺少工具），則退而使用 <skill-dir>/assets/templates/ 中的範本手動建立檔案。手動將每個範本複製到目標目錄，替換佔位符，並從 <skill-dir>/assets/workspace-scripts/ 複製腳本來建立 scripts 目錄。
步驟 5 —— 告知使用者已建立的內容
腳本完成後，總結：
- 建立了哪些檔案和目錄
- 是否已執行
git init（或已跳過，並附上提醒） - 是否已執行
npm install（或已跳過，並附上提醒） AGENTS.md現在是此工作區的管理文件- 工作區已備妥，可供使用
接著詢問：「您要開始撰寫文件，還是想先檢視一下結構？」
範本
所有範本檔案都位於 <skill-dir>/assets/templates/。引導腳本會複製並替換它們。
| 範本 | 產生的檔案 |
|---|---|
AGENTS.md.template | AGENTS.md |
README.md.template | README.md |
index.yaml.template | index.yaml |
_gitignore_.template | .gitignore（底線包覆會轉換為點前綴） |
package.json.template | package.json |
_prettierrc_.template | .prettierrc |
_markdownlint.json_.template | .markdownlint.json |
使用的佔位符：
{{TOPIC_SUMMARY}}—— 取代為使用者的主題描述{{CREATED}}—— 取代為今天的日期（YYYY-MM-DD）
引導腳本會自動處理底線包覆的慣例（名為 _foo_.template 的檔案在輸出中會變成 .foo）。
工作區附帶的腳本
引導完成後，工作區的 scripts/ 目錄中會有這些輔助腳本：
| 腳本 | 用途 |
|---|---|
scripts/format.js | 對所有 .md/.html/.json/.yaml 檔案執行 Prettier |
scripts/validate.js | 對所有 .md 檔案執行 markdownlint |
scripts/hash.js | 計算檔案的 SHA-256 雜湊值，可選擇寫入到 assets/ 並更新 manifest |
scripts/reindex.js | 重新生成 README.md 中的自動索引區段 |
所有腳本皆可透過 npm 呼叫：
npm run formatnpm run validatenpm run hashnpm run reindex
參考資料
如需特定主題的更深入背景資訊，請參閱 references/ 目錄：
references/asset-management.md—— 如何新增、連結和遷移資產（內容定址儲存、manifest、每個文件 vs 共享）references/document-promotion.md—— 當單一文件文件獲得子文件時，如何將其升級為資料夾
這些檔案僅在相關時才會載入到上下文中。主要的 AGENTS.md 涵蓋常見情況；參考資料則用於較不常見的情況。
給代理程式的提醒（在引導期間）
- 主題摘要是使用者提供的唯一與主題相關的內容。其他所有內容都是範本化的。請勿詢問關於檔案命名、連結樣式、frontmatter 欄位、提交訊息樣式或任何其他規則——這些都已內建在範本中。
- 如果使用者要求範本不支援的功能，請提出來。請勿默默地發明新的慣例。正確的做法是 (a) 記錄下來供未來範本修訂時參考，或 (b) 在獲得使用者明確確認後，將其作為例外情況實作。
- 引導完成後，此技能的工作就結束了。 下次使用者想要在工作區內執行任何操作時，代理程式會讀取
AGENTS.md並遵循它。除非使用者明確要求引導另一個工作區或重新引導現有的工作區，否則此技能不會再次執行。