| name | awesome-novel |
| description | 和 AI 协作写小说的工作流系统。7 个 agent 协作完成从设定到归档的完整写作流程。入口检测 → 初始化/迁移 → 交 novel-agent 调度。适用场景:从零写新小说、导入已有小说。 |
Novel — 小说创作工作流
和 AI 一起写小说。本 skill 负责项目状态检测、新项目初始化、旧版项目自动迁移,完成后将控制权交给 novel-agent。
检测流程 — 严格按此执行,禁止跳过
检测项目状态
├─ story.yaml 存在 → 旧版 2.x → 执行自动迁移(见下文)
├─ story.md 不存在 → 询问作者是否初始化 → 是则执行 init.py
│ └─ python tools/init.py [project-path] [--genre <编号>] → 完成后 @novel-agent
└─ story.md 存在 → 已有项目 → @novel-agent 继续写作
强制规则:
story.md 不存在时,先询问作者是否要在此目录创建小说项目,确认后再运行 init.py
- 禁止未经确认直接执行
init.py
- 确认后必须运行
init.py,禁止手动创建目录结构替代
- 禁止在 skill 安装目录(含
skills/awesome-novel 路径)内运行 init.py — 此目录是技能仓库,不是小说项目
- 如果当前目录是 skill 安装目录,应提示作者切换到目标目录后再执行
init.py 执行完毕后,确认 .agent/status.md 和 .claude/agents/ 已生成,方可进入 @novel-agent
- 如果
init.py 报错,必须先修复问题重新执行,不允许绕过
初始化 — 先询问,确认后执行,不可跳过
全新项目先询问作者是否初始化,确认后运行 init.py(项目路径可选,默认当前目录):
python tools/init.py [project-path] [--genre <编号>]
禁止以任何理由跳过 init.py: 手动创建目录、复制模板、直接调用 agent 都属于违规行为。init.py 是初始化入口,必须执行且完整运行。
init.py 会:
- 选题材
- 创建项目骨架(settings/、volumes/、chapters/、prompts/、archives/)
- 部署 agent 定义到
.claude/agents/
- 按题材继承反 AI 规则和文风偏好到
.claude/knowledge/
- 按题材继承格式规范、题材案例到
.claude/knowledge/
- 创建空白的写作记忆文件(
.claude/memory/*.md)
- 创建永久记忆占位文件(
.claude/knowledge/permanent-memory.md)
- 生成 CLAUDE.md
- 初始化状态文件
.agent/status.md
以上 9 步全部由 init.py 自动完成,AI 无需也不应手动干预。
检查: 运行后确认 .agent/status.md 存在且内容正确,方可进入 @novel-agent。
设定讨论 — novel-agent 与作者讨论后,由 updater 写入
init.py 完成后进入 @novel-agent,此时 phase=setup,按以下流程:
- novel-agent 检测到 setup 阶段,与作者逐项讨论设定(世界观/角色/风格/题材)
- 讨论完毕后,novel-agent 写 order 文件
.agent/task/setting-update-order.md
- novel-agent 通过 Agent 工具调用 updater
- updater 读取 order,写入
settings/world-setting.md、settings/genre-setting.md、settings/character-setting/*.md 等设定文件
- updater 清理 order 文件并结束
- novel-agent 确认 order 已清理,推进 phase → outline,进入卷纲规划
权限规则: novel-agent 不得直接写 settings/ 下的文件,设定写入必须通过 updater 的 setting-update 模式完成。
自动迁移(2.x → 3.0)
检测到 story.yaml 存在时,按以下流程自动迁移:
Step 1: 展示迁移计划
扫描项目目录,给作者看三张清单:
文件清单:
- 设定文件:story.yaml + settings/ 下所有文件
- 角色文件:settings/character-setting/ 下所有文件
- 卷纲:volumes/ 下所有文件
- 正文:archives/ 下
.md 文件数量
- 章纲(已归档):chapters/ 下
status: archived 的章节数量
- 章纲(跳过):chapters/ 下
status != archived 的章节列表
- 提示词:prompts/ 下文件数量
废弃清理(直接丢弃):
author-intent.md、current-focus.md
drafts/、drifts/、tmp/、temp-*.txt
manuscripts/、.vscode/
作者确认后继续。
Step 2: 备份旧文件
mkdir -p old
mv story.yaml settings/ volumes/ chapters/ archives/ prompts/ old/
rm -rf drafts/ drifts/ tmp/ manuscripts/ .vscode/ author-intent.md current-focus.md
Step 3: 初始化新骨架
python tools/init.py [project-path] [--genre <编号>]
init.py 创建目录结构 + 空模板 + agent 定义 + 记忆/知识库。后续迁移步骤负责填数据。
Step 4: 迁移设定(逐文件按 templates/migration/ 映射)
对照 templates/migration/migration-spec.md 的字段映射表,按优先级逐文件转换:
| 优先级 | 旧文件 → 新文件 | 参考模板 |
|---|
| P0 | old/settings/character-setting/*.yaml → settings/character-setting/*.md | templates/migration/character.md.template |
| P1 | old/story.yaml + old/volumes/*.yaml → story.md | templates/migration/story.md.template |
| P2 | old/volumes/*.yaml → volumes/volume-{N}.md | templates/migration/volume.md.template |
| P3 | old/chapters/*.yaml(archived)→ chapters/vol-{N}-ch-{M}.md | templates/migration/chapter.md.template |
| P4 | old/settings/world-setting.yaml → settings/world-setting.md | templates/migration/world-setting.md.template |
| P5 | old/settings/writing-style.yaml → settings/writing-style.md | templates/migration/writing-style.md.template |
| P6 | old/settings/anti-ai.yaml → settings/anti-ai.md | templates/migration/anti-ai.md.template |
| P7 | old/settings/hooks.yaml → settings/foreshadowing.md | templates/migration/foreshadowing.md.template |
| P8 | 无旧源 → settings/genre-setting.md | templates/migration/genre-setting.md.template |
字段映射细节在 templates/migration/migration-spec.md 中有完整定义。
Step 5: 拷贝已归档正文 + 提示词
只拷贝已定稿的正文(非 .draft.md),提示词全部复制:
for f in old/archives/*.md; do
[ -f "$f" ] || continue
case "$f" in *.draft.md) ;; *) cp "$f" archives/ ;; esac
done
cp old/prompts/*.md prompts/ 2>/dev/null
cp old/prompts/*.txt prompts/ 2>/dev/null
正文不做任何修改。
Step 6: 验收
Step 7: 交接 novel-agent 评估补充
迁移完成后,调度 @novel-agent,由其执行:
- 项目空间评估 — 扫描全部迁移后的文件,对照验收清单识别缺失项
- 补充决策 — 判断缺失项该由哪个 agent 处理:
- 设定缺失(世界观/角色/风格/题材等)→ 调度 updater(setting-update 模式)
- 其他 → 直接向作者提问
- 逐项引导补充 — 每次调度一个 agent 完成补充后,再评估下一项,直到项目就绪
- 汇报就绪 — 全部就绪后向作者展示迁移+补充结果,进入写作循环。确认无误后,作者可手动删除
old/ 目录。
边界条件
| 场景 | 处理 |
|---|
story.yaml 存在 → story.md 不存在 | 旧版 2.x → 执行自动迁移流程 |
story.md 存在但 skill_version < 4.0 | 待升级 → 执行自动迁移流程 |
story.md 存在且版本匹配 | 已有项目 → @novel-agent |
| 两者都不存在 | 全新项目 → init.py → @novel-agent |
init.py 不可用 | 手动创建目录结构 + 复制 templates/ 文件 |
| 检测到未提交的 git 变更 | 提示作者先提交/stash |
项目目录结构
{project-name}/
├── story.md # ★ 项目索引
├── settings/
│ ├── world-setting.md # 世界观
│ ├── writing-style.md # 写作风格
│ ├── genre-setting.md # 题材设定
│ └── character-setting/
│ └── <id>.md # 每角色一个文件
├── volumes/
│ └── volume-{N}.md # 卷纲
├── chapters/
│ └── vol-{N}-ch-{M}.md # ★ 章纲(status: outline → draft → archived)
├── prompts/
│ └── vol-{N}-ch-{M}-prompt.md # 提示词
├── archives/
│ ├── *.draft.md # 草稿
│ └── *.md # 定稿
├── .agent/
│ ├── status.md # 进度追踪
│ └── task/ # agent 间 order 文件
└── .claude/
├── agents/ # Agent 定义
├── knowledge/ # 反 AI 规则、文风偏好、永久记忆、格式规范
└── memory/ # 写作动态记忆
Agent 协作架构
novel-agent(总指挥)
├─ 新项目 → 调度 volume-planner(规划卷纲)
├─ 卷纲就绪 → 调度 chapter-planner(生成章纲)
├─ 章纲就绪 → 调度 prompt-crafter(组装提示词)
├─ 提示词就绪 → 调度 writer(写正文)
├─ 正文就绪 → 可选调度 reader(深度评审)
└─ 作者确认 → 调度 updater(归档 + lore-keeping)
各 agent 定义在 agents/,skill SOP 在 skills/。agent 间通过 .agent/task/*-order.md 文件通信。
调度规则: novel-agent 是唯一调度者,只写 order 文件 + 调用子 agent。所有内容创作(卷纲/章纲/提示词/正文)、设定维护、归档更新均由子 agent 完成,novel-agent 不得越权代劳。子 agent 完成任务后清理 order 文件,novel-agent 检测到清理即确认完成。
重要:novel-agent 是顶层入口,通过 @novel-agent 加载进主 agent,禁止通过 Agent 工具将 novel-agent 作为 subagent 调度。 主 agent 加载 novel-agent 定义后即扮演总指挥角色,拥有完整的 Agent 工具权限来调度子 agent。如果 novel-agent 被作为 subagent 派出,它将失去 Agent 工具调用能力,导致调度链断裂。
工具契约
| 工具 | 用途 | 谁用 |
|---|
| Bash | 执行 init.py;迁移备份/拷贝命令;版本检测 | skill 入口(非 agent) |
| Read | 检测项目文件、读取设定/状态 | 所有 agent |
| Write | 写 order 文件(novel-agent);写设定/记忆/知识(子 agent) | 各 agent 按权限 |
| Agent | novel-agent 调用子 agent | novel-agent 专用 |
| Edit | 写 settings/、.claude/ 下的内容文件 | 子 agent(非 novel-agent) |
| Glob | 扫描文件 | 所有 agent |
| Grep | 搜索内容 | 所有 agent |