| name | an-init |
| description | 将现有工作区转换为 AI Native 上下文结构。当用户想要：1) 将现有工作内容纳入 AI Native 格式 2) 为已有材料生成 background/conventions/artifacts 文档 3) 执行 /an-init 命令 4) 让 AI 理解并接管现有工作区 5) 从空模板开始建立通用 AI Native 上下文时触发此技能。**始终使用中文与用户沟通。** |
AI Native 上下文初始化
调用此 skill 时若需要使用子代理则默认授权。
将现有工作区（或空工作区）转换为 AI Native 上下文结构。
支持将一个或多个工作单元放入 projects/ 目录，每个子目录视为一个独立工作单元。
前置检查
执行前检查：
-
检查 projects/ 目录内容
- 如果已有工作区材料：继续执行
- 如果为空（仅有
.gitkeep）或不存在：
- 询问用户是否从空模板开始
- 若用户确认，则创建一个最小通用上下文结构（不报错停止）
- 若用户希望先放入材料，提示用户复制材料后重新执行
/an-init
-
默认授权使用子代理并行处理独立扫描
我可以用两个子代理并行处理初始化中的独立扫描：
1. 动作探测子代理：探测验证、构建、生成、检查等可执行动作并生成 .agents/recipes.json
2. 背景扫描子代理：抽取工作区结构、能力/工具栈、对外边界、领域模型等线索
此 skill 默认授权使用子代理并行处理这两项；如果用户明确拒绝、跳过或当前环境不支持子代理，则主代理本地顺序执行同样脚本。
无需再次询问即可启动子代理；用户明确拒绝、跳过或当前环境不支持子代理时，主代理本地顺序执行同样脚本。
执行流程
阶段一：工作区分析（静默执行）
扫描 projects/ 目录下的每个子目录，提取客观信息。
子代理并行策略：
| 执行者 | 职责 | 输出 |
|---|
| 主代理 | 识别工作单元、提问、合并文档、最终报告 | AGENTS.md、background/、conventions/ |
| 动作探测子代理 | 探测验证、构建、检查、生成、导出等可执行动作 | .agents/recipes.json 和动作摘要 |
| 背景扫描子代理 | 抽取工作区结构、能力/工具栈、对外边界、领域模型等线索 | 背景扫描摘要 |
动作探测子代理任务：
在当前仓库中运行：
node skills/an-recipes/scripts/detect-recipes.mjs --root projects --write .agents/recipes.json
返回：
1. 识别到的工作单元和动作数量
2. 每个工作单元的验证、构建、生成、检查、导出等动作
3. 低置信度或缺失的动作
4. 非代码工作区时的处理结果
背景扫描子代理任务：
在当前仓库中运行：
node skills/an-refresh/scripts/scan-projects.mjs --root projects --artifacts artifacts --format markdown
返回：
1. 工作区结构、文件类型和工具链摘要
2. 对外入口和交互边界线索
3. 数据结构和领域模型线索
4. 已有验证或质量评价报告线索
5. 需要主代理人工判断的待确认项
工作单元列表识别：
- 扫描
projects/ 下的所有一级子目录
- 每个子目录视为一个独立工作单元
- 若
projects/ 为空，则记录为“空工作区”，不停止初始化
工作区类型识别（对每个工作单元分别执行以下检查）：
对每个工作单元子目录：
1. 进入 projects/{工作单元名}/
2. 检查是否存在能表明工作区类型的特征文件
3. 根据文件内容总结工作区类型与能力/工具栈
| 证据 | 输出 |
|---|
| 特征文件、依赖、脚本、配置 | 能力/工具栈摘要 |
| 目录结构和入口文件 | 工作单元职责摘要 |
| 构建、验证、检查配置 | 可执行动作线索 |
目录结构分析：
风格分析：
- 命名规范（camelCase/kebab-case/PascalCase）
- 文件组织方式
- 注释/标注风格
- 动作探测子代理和背景扫描子代理返回的结构化摘要
分析原则：
- 所有结论必须基于工作区中的客观事实（文件存在性、依赖列表、脚本名）。
- 禁止根据文件名、目录名推测业务功能、用户意图或未实现的需求。
- 无法确认的信息标记为"待确认"，不得编造。
阶段二：自主补全与待确认
分析完成后，AI 应先基于工作区事实、README、配置文件、包信息、注释、已有文档和子代理摘要自主生成背景草稿，不要默认暂停询问用户。
自主补全原则：
- 工作区类型、工具栈、入口、脚本、对外边界线索、交付线索等可由材料事实分析的信息，必须由 AI 自行提取和写入。
- 主题定位、目标用户、外部文档、设计稿等业务语义信息，应先检索仓库内 README、docs、注释、配置命名和已有文档。
- 能从证据中合理归纳的内容可以写为“基于工作区事实推断”，并标注来源；置信度不足时写入“待确认”，不得编造。
- 不要把可由 AI 根据材料事实和领域常识判断的问题转交给用户填表。
- 初始化流程不应因为缺少业务补充而阻塞；缺失信息写入文档的“待确认”项或留空。
仅当缺失信息会影响初始化产物的正确性，且无法通过材料、README、配置或已有文档推断时，才一次性向用户提出必要问题：
我已分析 projects/ 目录，识别到以下工作单元：
{遍历 projects/ 下的子目录，每个输出一行}
- {工作单元名}：{工作区类型} - {主要工具/能力摘要}
以下信息无法从仓库事实中确认，已在文档中标记为“待确认”。如果你愿意，可以补充：
1. 这个工作区整体是做什么的？（一句话描述）
2. 目标用户/读者是谁？
条件待确认项：
条件待确认项只能基于工作区中的可验证事实决定是否附加：
| 工作区事实 | 附加问题 |
|---|
| 检测到对外接口、服务入口或发布格式 | 是否有接口协议、集成文档或交付规范？ |
| 检测到用户界面、可视化或设计相关文件 | 是否有设计稿或交互规范？ |
- 禁止 AI 自行判断"是否有后台管理功能"等无法从材料客观验证的事项。
- 如果无法确定是否满足条件，默认写入待确认项而非跳过。
提问是例外路径，不是默认路径。默认路径是 AI 先完成初始化文档，把无法确认的业务信息标记为“待确认”。
阶段三：文档生成
根据分析、已有仓库文档和用户已提供的信息生成以下文档。
文档生成原则：文档中的每条信息只能来自两个来源——①用户明确输入 ②工作区客观分析。禁止编造、推测或填充未经验证的信息。无法确认的内容标记为"待确认"或留空。
已有文档处理：如果目标文件已存在（如重复执行 an-init），基于实际情况合并——保留有效内容，补充新增信息，删除过时内容。
AGENTS.md（更新工作区背景）
## 工作区背景
{AI 基于仓库事实归纳的主题描述；若无法确认则写“待确认”}
> **缩写说明**：对话中出现的 "AN" 一般指 AI Native 的缩写。
### 工作区列表
| 工作区 | 类型 | 描述 |
|--------|------|------|
| {projects下的子目录名} | {工作区类型} | {简要说明} |
### 必读文档
| 路径 | 描述 |
|------|------|
| background/ | 上下文背景知识 |
| conventions/ | 上下文约定规范、对话长期规则与优化记录 |
### 能力/工具栈
{从工作区分析得出的能力/工具栈概要}
### 关键链接
| 资源 | 链接 |
|------|------|
| 设计或交互文档 | {仓库内已发现的路径；若无法发现则留空或写“待确认”} |
| 对外契约/交付规范文档 | {仓库内已发现的路径；若无法发现则留空或写“待确认”} |
## 工作流阶段
| 阶段 | 说明 |
|------|------|
| raw-input | 原始输入，原模原样保存用户描述 |
| requirements | 基于 raw-input 生成的结构化需求与验收标准 |
| design | 方案设计，讨论采用什么方案 |
| tech-spec | 执行规范，输出可执行的变更清单 |
| implementation | 按变更清单执行并产出 |
| testing | 基于前面的规范生成验证用例并执行验证 |
| deployment | 交付/归档 |
## AI 行为约束
- 禁止自行脑补未提及的需求、功能或业务逻辑。
- 所有背景知识必须来自工作区材料或用户明确输入。
- 从工作区材料反推的信息要标注来源；无法确认的信息标记为"待确认"。
## 必读规范
| 规范 | 用途 |
|------|------|
| [rules](conventions/rules.md) | 对话过程中的长期记忆感知与沉淀 |
| [memories](conventions/memories/AGENTS.md) | 对话优化记录索引 |
## Skill 路由
当用户描述执行意图（如"我要做一个XXX"、"写XXX"、"分析XXX"、"设计XXX"、"添加XXX"、"修复XXX"、"重构XXX"等）时，
使用 `/an-task`。AI 根据 [flow-policy](conventions/flow-policy.md) 自主判断 L0/L1/L2/L3 流程等级、方案、验证动作和推进顺序。
- L0/L1：可直接实现和验证，完成后总结改动、理由和验证结果。
- L2/L3：创建并维护对应 artifacts，按所需阶段推进并记录决策。
- 不要要求用户在"完整流程 / 快速修复 / 自由对话"中选择。
- 只有需求目标不明确、业务语义必须由用户决定、涉及权限/数据/安全/部署等高风险边界、破坏性操作或外部授权时，才暂停请求确认。
background/product/overview.md
# 产品/主题概述
## 名称
{从工作单元名称或用户输入提取}
## 定位
{AI 基于仓库事实归纳；若无法确认则写“待确认”}
## 目标用户/读者
{AI 基于仓库事实归纳；若无法确认则写“待确认”}
## 工作区关系
{描述各工作区之间的关系}
background/tech/stack.md
# 能力/工具栈
{按工作单元分节}
{遍历 projects/ 下的子目录，为每个工作单元生成一节}
## {工作单元名}
| 工具/能力 | 版本 | 用途 |
|-----------|------|------|
| ... | ... | ... |
## 通用工具链
| 工具 | 用途 |
|------|------|
| ... | ... |
background/AGENTS.md
# background 目录说明
`background/` 存放工作区的稳定背景知识，包括主题定位、领域模型、能力/工具栈、结构决策和交付状态。
## AI 行为
- 需要理解业务或技术背景时，按需读取相关文档。
- 除 `/an-init`、`/an-refresh` 或用户明确要求外，不主动修改本目录。
- 更新时保持增量，不重写人工补充内容。
- 从工作区材料反推的信息要标注来源；无法确认的信息标记为“待确认”。
- 背景文档与 `projects/` 工作区内容冲突时，先以材料事实为准，并在更新摘要中说明冲突。
conventions/structure.md
# 工作区结构规范
## projects/ 目录结构
{扫描 projects/ 生成的目录树}
## 工作单元说明
| 目录 | 工作单元 | 职责 |
|------|----------|------|
| projects/{工作单元A} | {工作单元A名称} | {说明} |
| projects/{工作单元B} | {工作单元B名称} | {说明} |
conventions/style-guide.md
# 风格规范
## 命名规范
{从工作区推断}
## 文件组织
{从工作区推断}
## 标注/注释风格
{从工作区推断}
.agents/recipes.json
由 /an-recipes 或动作探测子代理探测生成，记录验证、构建、生成、检查、导出等可执行动作清单。
conventions/rules.md
# 对话长期记忆规则
## 目标
AI 在任意对话过程中持续感知用户是否正在“纠错、约束、提升”AI 的工作方式。若满足长期沉淀条件，应写入 `conventions/memories/` 中对应功能主题文件；若同名主题已存在，则追加到该文件。
## 写入规则
- `conventions/rules.md` 只保存长期记忆机制的指导规则，不作为具体记忆内容的回写目标。
- `conventions/memories/` 保存具体优化记录、来源、分类、判断依据和后续追加内容。
- memory 文件使用功能性名字，不带日期，例如 `dialog-memory.md`、`git-workflow.md`。
- 写入前先查找同名或同主题 memory 文件；找到则追加，找不到才创建新文件。
- 不要把对话流水直接追加到 `rules.md`；具体记录写入 `memories/`。
- 不写入密钥、凭据、隐私数据、临时路径或不可泛化的上下文。
conventions/memories/AGENTS.md
# memories
| Memory | 描述 |
|--------|------|
| - | - |
artifacts/AGENTS.md
# artifacts 目录说明
`artifacts/` 存放任务产出。每个任务使用独立目录，命名为 `YYYYMMDD__feature-name`。
## 约定结构
artifacts/{YYYYMMDD}__{feature-name}/
├── AGENTS.md
├── raw-input/
├── requirements/
├── design/
├── tech-spec/
├── implementation/
├── testing/
└── deployment/
## AI 行为
- 新任务优先创建独立产出目录，并在根 `AGENTS.md` 的活跃 Artifacts 表中登记。
- 产出目录只存过程文档、决策、报告和临时分析，不存放最终交付物本身（最终交付物应写入 `projects/` 或用户指定的交付位置）。
- 每个产出目录可包含自己的 `AGENTS.md` 作为任务索引。
- 任务完成后，可使用 `/an-archive` 移动到 `artifacts/archive/`。
- 恢复历史任务时先匹配目录名，再读取对应产出内容，避免无谓加载大量文档。
初始化完成后不保留 background/README.md 或 artifacts/README.md。目录级说明统一放入对应的 AGENTS.md，避免 README 与 Codex 双入口漂移。
输出格式
单工作区示例：
✅ AI Native 上下文初始化完成！
识别到 1 个工作单元：
- workspace-a：{工作区类型} - {主要能力/工具摘要}
生成文件：
...
多工作区示例：
✅ AI Native 上下文初始化完成！
识别到 2 个工作单元：
- workspace-a：{工作区类型} - {主要能力/工具摘要}
- workspace-b：{工作区类型} - {主要能力/工具摘要}
生成文件：
- AGENTS.md（更新工作区背景）
- background/product/overview.md
- background/tech/stack.md（按工作单元记录能力/工具栈）
- conventions/structure.md（包含各工作单元的目录结构）
- conventions/style-guide.md（包含风格约定）
- conventions/rules.md（对话长期记忆机制）
- conventions/memories/AGENTS.md（对话优化记录索引）
- .agents/recipes.json（可执行动作清单）
- background/AGENTS.md
- artifacts/AGENTS.md
下一步：
1. 在 artifacts/ 中创建你的第一个任务产出目录
2. 参考 background/ 了解上下文背景
3. 规范已写入 conventions/，编辑工作区、目录结构和对话长期记忆时自动生效
空工作区示例：
✅ AI Native 上下文初始化完成！
projects/ 目录为空，已创建最小通用上下文结构。
生成文件：
- AGENTS.md
- background/AGENTS.md
- artifacts/AGENTS.md
- conventions/rules.md
- conventions/memories/AGENTS.md
你可以在 projects/ 中放入工作区材料后重新执行 /an-init，也可以直接开始创建任务产出。
阶段四：安装运行期技能与清理
如果未使用动作探测子代理，生成文档后运行动作探测：
node skills/an-recipes/scripts/detect-recipes.mjs --root projects --write .agents/recipes.json
如果未使用背景扫描子代理，需要本地运行背景扫描并将结果纳入文档：
node skills/an-refresh/scripts/scan-projects.mjs --root projects --artifacts artifacts --format markdown
初始化完成后，将运行期技能安装到激活目录：
mkdir -p .agents/skills
mv skills/* .agents/skills/
rmdir skills
安装规则：
.agents/skills/an-init/ 在模板阶段保留，用于自动激活初始化能力。skills/ 暂存目录中的其他技能不在模板阶段激活；只在初始化完成后移动到 .agents/skills/。- 移动完成后删除空的
skills/ 目录，避免项目中保留模板暂存结构。
删除模板专用文件：
- 删除
./README.md（模板说明文档，仅供人类阅读）
- 删除
background/README.md 和 artifacts/README.md（如存在），目录级说明统一使用 AGENTS.md
- 删除
projects/.gitkeep（初始化占位文件，如存在）
错误处理
| 情况 | 处理 |
|---|
| projects/ 为空（仅有 .gitkeep） | 询问用户是否从空模板开始；若确认则创建最小上下文结构，不报错停止 |
| projects/ 下无子目录 | 提示用户创建工作单元子目录或选择从空模板开始 |
| 无法识别工作区类型 | 跳过自动识别，询问用户 |
| 用户取消 | 不生成任何文件 |
