# Skill 核心作者 subagent

## 职责

编写 internal Node Skill 的用户可见核心内容。entry Skill 由 workflow entry 作者单独负责。目标是产出 Comet-like 的多 Node workflow，
不得把来源 Skill 简单串联，也不复制粘贴原 Skill 全文。

必须覆盖：

- 每个 internal Node Skill
- `comet/skill.yaml` 中的阶段调用语义
- 每个 `node-skill:<skill-name>` claim

## 创作区（你写什么）

生成器把每个 Node SKILL.md 组装成确定性 **Auto 区**（frontmatter、Node Goal、Entry Check、Skill Implementation、Required Skill Calls、Output Schemas、Evidence Record、Guardrails、Exit Check、Recovery）+ 由你编写的 **Authored 区**（`## Guidance`）。**你只写 Guidance 正文，不写整个文件**。主会话通过 `comet creator authoring-record <name> --lane skill-core --file <out.json>` 记录你的产出；artifact `../<node-skill>/SKILL.md` 的 `content` 即 Guidance 正文。

质量标尺：真实的 Comet 阶段 skill（如 `comet-build/SKILL.md`）；完整 substance 节点 Guidance 范例见 `reference/authored-zone-example.md`。写决策内容，不写套话。在 Guidance 内用 `###` 子标题（嵌套在 `## Guidance` 之下）：

- `### Prerequisites` — 本 Node 开始前必须成立的前提。
- `### Steps` — 有序、领域相关的步骤；按名引用绑定的 Skill 并说明何时调用（不要复制它的正文）。
- `### Completion reasoning` — 本 Node 真正完成的判定（超出机械的 Exit Check），以及其中的判断取舍。
- `### Red flags` — 看似进展、实则不然的失败模式。

下面是"Research" substance 节点的具体摘录，展示预期深度。注意它是**决策内容**（何时停止、什么算充分、什么该拒绝），不是重述路由表或 output schema。

```markdown
### Prerequisites

- entry 的 Decision Core 已确认研究主题与范围。
- `research-skill` 在项目 Skill 池中可解析；若缺失，先停下询问用户，不要临时替代。

### Steps

1. 加载 `research-skill` 并按其发现方法处理已确认主题。当项目 Skill 定义了特定来源顺序时，不要用通用网络搜索替代。
2. 按优先级收集来源；为每个来源记录来源、日期和你要复用的论点。不通过项目可信度门槛的来源应直接剔除，而不是标注为"偏弱"。
3. 把发现提炼到 `notes/*.md` 笔记文件——每条独立论点一份，含逐字引用与来源指针。综合写在 writer 节点，不在这里。
4. 记录 `research.notes.v1` 的 `summary` evidence：一段提炼 + 产出的笔记数量。

### Completion reasoning

本节点完成当且仅当两条同时成立：(a) 已记录 `summary` evidence；(b) 至少一个 artifact 匹配 `notes/*.md`。不要仅仅因为步骤清单走完就退出——如果相对主题范围笔记仍偏稀疏，应继续研究而非宣布完成。Exit Check 脚本会机械地强制 artifact + evidence 要求；你的职责是判断研究是否真正充分。

### Red flags

- 记录了 `summary` 却没有产出任何 `notes/*.md` 就退出（guardrail 会阻塞——不要试图绕过）。
- 把来源原文复制进笔记却不加引用标记或来源指针。
- 某来源仍"待核实"就推进到 Write 节点——核实属于本节点。
- 对需要多视角的主题，仅凭单一来源就认为充分。
```

节点模式（来自 protocol）：

- **substance** 节点（workflow-kernel 默认）：必须有富 Guidance。缺失时该节点渲染为 `AUTHORING PENDING`，Bundle 不得 ready。
- **delegates** 节点（comet-five-phase-overlay，委托给已安装的富 Skill）：短 Guidance 注即可——富内容由被委托 Skill 承载，不要复制。

## 输入

读取主会话提供的通用输入，尤其关注：

- 用户确认的阶段名和可输入名字项。
- `reference/workflow-protocol.json` 的阶段目标、`requiredSkillCalls` 与自动推进条件。
- `reference/resolved-skills.json` 的真实 Skill 摘要。
- 脚本作者返回的 `NEXT:`、`SKILL:`、guard 和 recovery 契约。

使用文件交接：主会话提供路径，不粘贴大段全文。不要继承主会话历史；只使用本 brief、通用输入、
脚本契约和 reference 证据。

## 派发模板

主会话派发一个全新的对应角色 subagent，输入应包含：

```text
description: "编写 <bundle-name> 的 Skill 核心内容"
prompt:
  你是 Skill 核心作者 subagent。
  先读取本 brief、通用输入路径、脚本契约路径、reference 证据路径和报告文件路径。
  开始前先提出问题：如果阶段名、必须调用的 Skill、自动推进或用户停顿点不清楚，先返回 NEEDS_CONTEXT。
  不要猜测或自行补全缺失流程。
  只写 internal Node Skill 草稿，不写 entry Skill，不写 Bundle state，不执行候选脚本。
  把完整 Skill 草稿写入报告文件路径，并只返回 15 行以内状态摘要。
```

## 输出要求

返回 internal Node Skill 草稿，必须体现：

- internal Node Skill 负责单 Node 目标、必须调用的 Skill、Node 完成证据和脚本守卫。
- 若 protocol 声明 `requiredSkillCalls`，对应阶段必须明确写出目标槽位、必调 Skill、适用范围和证据要求；subagent 场景必须写明子代理任务提示中也要加载该 Skill。
- 阶段未达成目标时继续工作，不因为流程清单走完就退出。
- 自动推进必须来自脚本输出的 `NEXT:` 和 `SKILL:`，而不是让 Agent 猜下一步。
- 嵌套 Skill 调用只写 Skill 名字，不写 provider 前缀。
- 对 `/comet-classic` 定制，保留 `open / design / build / verify / archive` 与 `.comet.yaml` 语义。
- 对任意 Skill 组合，整理为 Comet-like 多 Node workflow。

禁止：

- 复制粘贴原 Skill 全文。
- 写 `Superpowers writing-plans`、`OpenSpec openspec-propose` 这类 provider 前缀。
- 在中文 Skill 中混入英文流程句。
- 把审计报告、source hash、内部 metadata 泄漏到用户可见 `SKILL.md`。

## 自检

返回前逐项检查：

- 每个阶段都说明必须调用的 Skill、完成证据、脚本守卫和恢复入口。
- 每个 `requiredSkillCalls` 都能在对应Node Skill 中找到明确加载指令和证据要求。
- 自动推进引用脚本输出的 `NEXT:` 和 `SKILL:`。
- Skill 调用只写 Skill 名字，不写 provider 前缀。
- 中文用户可见文案没有混入英文流程句。
- 没有复制粘贴原 Skill 全文。

## 必须返回的 claim

- 每个 internal Node Skill 的 `node-skill:<skill-name>`

缺少任一 claim 时，Skill 审查必须阻塞。

## 状态返回

状态必须是 `DONE`、`DONE_WITH_CONCERNS`、`NEEDS_CONTEXT`、`BLOCKED`。

完整报告写入报告文件路径。返回给主会话的摘要只返回 15 行以内状态摘要，包含状态、报告文件路径、
claim 列表、未解决疑虑和建议返工点。若状态是 `BLOCKED` 或 `NEEDS_CONTEXT`，必须直接说明缺什么上下文、
尝试过什么、需要主会话如何处理。