此文件面向技能消费者，而非贡献者。请参阅 AGENTS.md 获取开发上下文——本技能的构建、迭代和测试方式。
文档工作区引导
本技能教导 AI 代理如何从一个空（或近乎空）目录开始引导一个文档工作区。结果是一个版本化的、基于文件系统的、完全自包含的知识库——由用户拥有、免费、无供应商锁定，并且结构清晰，使得在其中工作的代理无需考虑组织、格式或工具。
核心概念
引导后的工作区包含其自己的 AGENTS.md——一个针对特定主题的“冻结迷你技能”，代理在进入时会读取它。AGENTS.md 是通过本技能附带的模板创建的。一旦工作区存在，代理将遵循 AGENTS.md，而不是本技能。这就是全部要点：一次性预先确定规则，然后永远不再花费令牌重新推导它们。
何时使用本技能
仅在以下情况下使用本技能：
- 用户明确想要创建/设置/初始化/搭建一个文档工作区、文档文件夹或知识库。
- 目标目录是空的或近乎空的（或者用户在存在文件的情况下明确选择了加入）。
- 目标目录尚未包含
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 配置，禁用挑剔规则。 |
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/ 复制来创建脚本目录。
步骤 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/ 并更新清单 |
scripts/reindex.js | 重新生成 README.md 中的自动索引部分 |
所有均可通过 npm 调用：
npm run formatnpm run validatenpm run hashnpm run reindex
参考资料
有关特定主题的深层上下文，请参阅 references/ 目录：
references/asset-management.md— 如何添加、链接和迁移资源（内容寻址存储、清单、每个文档 vs 共享）references/document-promotion.md— 如何将单文件文档提升为文件夹（当其获得子文档时）
这些仅在相关时加载到上下文中。主要的 AGENTS.md 涵盖常见情况；参考资料用于较少见的情况。
对代理的提醒（在引导过程中）
- 主题摘要是用户提供的唯一与主题相关的内容。所有其他内容都是模板化的。不要询问文件名、链接风格、前置元数据字段、提交消息风格或任何其他规则——这些都已嵌入模板中。
- 如果用户提出了模板不支持的要求，请提出来。不要悄悄地发明新的约定。正确的做法是 (a) 记录供未来模板修订使用，或 (b) 在获得明确确认后将其作为例外实现。
- 引导完成后，本技能就结束了。下次用户想要在工作区中执行任何操作时，代理将读取
AGENTS.md并遵循它。除非用户明确要求引导另一个工作区或重新引导现有工作区，否则本技能不再运行。