scrolls-update

更新 docs/.scrolls/

只有当 docs/.scrolls/ 如实反映实际情况时，它才有用。本技能会遵循 STARTER.md 已为每个文件规定的更新规则，不会另行制定新约定。重点不是每次都修改所有文件，而是只修改实际发生变化的文件，并遵循该文件自身约定的更新方式（覆盖、追加，或同步增删）。

本技能还会幂等地为在 SCROLLS.md、CLAUDE.md 和 AGENTS.md 尚不存在时就已设置好的项目补齐这些文件——这是每个会话都会运行的命令，因此它会自动弥补这一缺口，而不只是一次性的 /scrolls-setup。请参阅步骤 2。

跨平台

随附的唯一脚本（步骤 4）有两种形式：session_diff.sh（bash——适用于 macOS、Linux，或安装了 Git Bash/WSL 的 Windows）和 session_diff.ps1（PowerShell 7+——适用于 Windows，或安装了 pwsh 的 macOS/Linux）。本技能中的其他内容——标志、BASE_DIR 解析、定位 scrolls 文件夹——都是直接遵循的纯文本说明；它只会调用 git，无论运行在哪种 shell 中，行为都相同，因此无需为不同 shell 提供变体。根据实际可用的环境选择脚本：先运行 bash --version；如果成功，就使用 .sh 脚本；否则通过 pwsh 使用 .ps1 脚本（首选——如果缺少 pwsh，请从 https://aka.ms/powershell 安装），或者仅在确实没有 pwsh 时，使用 Windows 自带的 Windows PowerShell powershell.exe（尚未针对该旧版本测试；本脚本是针对 pwsh 编写并验证的）。

选项

按任意顺序读取这些选项的调用文本——这里没有真正的 argv 解析器，因此请自行从纯文本中提取：

• -p <path> / --path=<path> / --path <path> — 查找指定的自定义 docs 文件夹；除非给出绝对路径，否则路径相对于当前工作目录。
• -t / --reporoot — 在 git 仓库的顶层目录（$(git rev-parse --show-toplevel)）下查找，无论实际从哪个子目录调用。若当前目录不在 git 仓库中，则会显示明确的错误消息并失败。
• -l / --local — 明确在当前工作目录下查找。默认情况下也会如此，即未提供 -p/-t/-l 中任何选项时；此标志用于明确表达这一意图，例如跳过下文的路径不匹配检查。
• -r / --recurse — 如果 scrolls 文件夹不在显而易见的精确位置（BASE_DIR/docs/.scrolls 或 BASE_DIR/docs/scrolls），则在 BASE_DIR 下递归搜索，而不是直接放弃。默认关闭——符合 grep/cp/rm 等工具中 -r 的通常含义。

这里没有 -u/--unhide 选项——本技能会定位现有的 scrolls 文件夹，而不是在两个文件夹之间进行选择（见步骤 1）。-p、-t 和 -l 是回答同一个问题（“docs 文件夹在哪里？”）的三种不同方式——最多只传入一个；如果给出了多个，请询问用户原本想指定哪一个。-r 相互独立，可以与其中任意选项组合使用，也可以单独使用。

步骤

1. 确定 BASE_DIR，然后尝试使用两个名称查找 scrolls

计算 BASE_DIR：

• 给出了 -t/--reporoot：BASE_DIR = $(git rev-parse --show-toplevel)。如果失败（不在 git 仓库内），请停止并告知用户——建议改用 --path。
• 给出了 -l/--local：BASE_DIR = $(pwd)。
• 未给出任何选项（常见情况）：BASE_DIR = $(pwd)。不过，首先检查当前目录是否位于 git 仓库内；如果是，则运行 git rev-parse --show-toplevel 并将其与 $(pwd) 比较。如果两者相同，或者当前目录不在 git 仓库内，就照常使用当前工作目录继续。如果两者不同，请在搜索前说明这一点——从此处运行只会在 $(pwd)/docs 下查找，而位于仓库根目录（<repo-root>）的 scrolls 文件夹会被完全漏掉（不只是被跳过——看起来会像项目从未设置过）。询问用户这是否符合预期；如果用户没有明确偏好，默认继续使用当前工作目录（此技能文档规定的默认行为）。

然后，将 DOCS_BASE 设为 -p 已给出时的 --path 值，否则设为 ${BASE_DIR}/docs。其下的 scrolls 文件夹可能名为 .scrolls（隐藏，/scrolls-setup 的默认名称），也可能名为 scrolls（在运行 /scrolls-unhide 后，或设置时使用 --unhide 后）——先检查 DOCS_BASE/.scrolls，再检查 DOCS_BASE/scrolls。无论哪个存在，后续都将其设为 SCROLLS_PATH。

如果这两个确切位置都不存在：

• 给出了 -r/--recurse：改为在 BASE_DIR 下递归搜索——搜索深度限制在一定范围内，并跳过 /scrolls-hide//scrolls-unhide 同样会跳过的大型或供应商目录（node_modules、.git、vendor、dist、build、.venv、venv、__pycache__、target、.next、.cache），查找包含 STARTER.md 的 .scrolls 或 scrolls 目录。如果只找到一个，它就是 SCROLLS_PATH。如果找到多个（即此 BASE_DIR 下的 monorepo 中有多个独立的 scrolls 设置），请列出这些目录，并询问用户本次会话的更新实际针对哪一个——不要猜测，也不要更新多个目录，因为会话叙述属于特定项目，而不是它恰好嵌套在附近的每个项目。
• 未给出 -r，或上述递归搜索也未找到任何结果：不要在此处创建目录。告知用户此项目（或路径）尚未设置，并指引其使用 /scrolls-setup——如果 BASE_DIR 解析为当前工作目录（默认情况或使用了 -l），而不是仓库根目录，请提及可以尝试 -t/--reporoot；如果尚未使用过 -r/--recurse，也请提及该选项，以防 scrolls 位于预期确切位置之外。

如果 DOCS_BASE 下 .scrolls 和 scrolls 两者同时存在，请停止并询问用户当前使用的是哪一个——这是不一致的状态，此技能不应在未说明的情况下自行处理。

2. 如果项目早于这些文件，补齐 SCROLLS.md、CLAUDE.md 和 AGENTS.md

由早于 2.0.0 的 /scrolls-setup 设置的项目可能没有 SCROLLS.md、没有 AGENTS.md，而且其中的 CLAUDE.md（如果存在）可能直接嵌入了 scrolls 路径，而不是指向 SCROLLS.md。由于 /scrolls-update 才是人们每个会话实际运行的命令——而不是只运行一次的 /scrolls-setup——因此项目会在这里自动补齐，每次运行都会如此。

这是一次性、按文件执行的幂等补齐：可以安全地在每次调用 /scrolls-update 时运行，因为下方三个文件都会采用 /scrolls-setup 第 4 步使用的相同处理方式：不存在则创建／未引用则插入／已正确则保持不变——**绝不覆盖或调整这些文件中已有内容的顺序。**它只会触及本次解析出的 SCROLLS_PATH 对应的一个位置（即使使用了 -r 也是如此）——遵循上文第 1 步的“不要猜测，不要触及多个位置”规则。

按照 /scrolls-hide／/scrolls-unhide 已有的方式，计算这三个文件应位于何处（CLAUDE.md 按构造始终是 docs 文件夹的直接同级文件）：

PTR_DIR    = dirname(DOCS_BASE)                          # e.g. "packages/api" for DOCS_BASE "packages/api/docs"
DOCS_NAME  = basename(DOCS_BASE)                          # normally "docs"
SCROLLS_DIR_NAME = basename(SCROLLS_PATH)                 # ".scrolls" or "scrolls", whichever was found
SHORT_SCROLLS_PATH = "${DOCS_NAME}/${SCROLLS_DIR_NAME}"    # e.g. "docs/.scrolls" — always correct relative to PTR_DIR

三个共用指针模板只存放在一个位置——/scrolls-setup 自身的 assets/templates/ 中——并从那里读取，而不是在此处重复存放，这样今后更改模板内容时就不需要在两个技能中同步编辑：

• SCROLLS.md：读取 <scrolls-setup-skill-dir>/assets/templates/SCROLLS_MD_BLOCK.md，并将 {{SCROLLS_PATH}} 替换为 SHORT_SCROLLS_PATH。如果 ${PTR_DIR}/SCROLLS.md 不存在，则创建它。如果它存在但尚未引用 SCROLLS_PATH/STARTER.md（简写或完整形式均可），则在文件顶部附近插入该区块，并以空行分隔——如果文件开头已有一级标题，则使区块的标题级别与文件自身结构相符。如果已经引用，则保持不变。
• CLAUDE.md：原样读取 <scrolls-setup-skill-dir>/assets/templates/CLAUDE_MD_BLOCK.md——这是固定的两行指针，无需替换内容。如果 ${PTR_DIR}/CLAUDE.md 不存在，则创建该文件，并使其内容恰好为该区块。如果文件存在但尚未引用 SCROLLS.md，则在文件顶部附近插入该区块（放在其他指示之前，因为只有先读到“先读此处”才有用），并用空行与周围内容分隔——即使文件已经直接指向 SCROLLS_PATH/STARTER.md 也一样，因为在这两个文件拆分之前就可能已经如此。这是一个真实且常见的情况（项目由早于 1.2.0 的 /scrolls-setup 版本设置），也正是这项补齐要解决的问题：仍然插入这个占位内容，让 CLAUDE.md 最终无论原先写了什么都指向 SCROLLS.md。这项操作只会添加内容——绝不删除或改写已有内容，即使这导致同一文件中同时存在旧的直接引用和新的占位内容。如果已经引用 SCROLLS.md，则保持不变。
• AGENTS.md：原样读取 <scrolls-setup-skill-dir>/assets/templates/AGENTS_MD_BLOCK.md。采用相同的三种处理方式，并引用 CLAUDE.md。

在第 7 步的报告中，除了 scroll 文件本身，还要说明这三个文件中是否有任何文件以这种方式创建或更新。

3. 将 STARTER.md 作为权威指南

不要假设 /scrolls-setup 中的六个最精简文件仍是全部内容——STARTER.md 明确指出，项目会随着时间推移增加其他 scrolls 文件（架构决策、安全审查、子系统深入分析），并为每个文件列出了各自的读取／更新规则。完整阅读当前的 STARTER.md，并以其中的编号列表和“When to update”部分为准，确定有哪些文件以及各文件的更新方式。如果某个文件的更新约定与以下通用规则不同（例如只能追加、带日期的日志，绝不能直接编辑，就像本仓库自己的 SECURITY_ANALYSIS.md），请遵循该文件的特定约定，而非通用规则。

4. 确认本次会话实际发生了什么

对话上下文是首要信息来源——你亲历了整个过程。但不要只依赖它，尤其是在上下文已压缩、会话已恢复，或有人要求你更新本次对话开始前所做工作的 scrolls 文件时。运行随附脚本，与 git 交叉核对——根据当前环境，从 <skill-dir>/scripts/ 中选择适用的脚本（见下方“跨平台”部分）：

bash <skill-dir>/scripts/session_diff.sh SCROLLS_PATH
pwsh <skill-dir>/scripts/session_diff.ps1 -ScrollsDir SCROLLS_PATH

脚本会显示未提交的更改、docs/.scrolls/ 最近一次变更之后的提交，以及文件变更统计摘要——足以发现对话记忆遗漏的内容，同时又不会把完整 diff 倾倒进上下文。如需了解某项具体变更的更多细节，请自行查看相应的 git diff／git log -p 片段。

5. 按各文件自身的规则更新所有需要更新的文件

STARTER.md 中对核心六个文件规定的通用规则：

• HANDOFF.md — 覆盖写入，不要追加。它是一份快照：当前状态、刚刚发生的事情、已知问题／未完事项。如果本次会话没有实质性变化，可以保持原样，不必为了凑内容而添加无事发生的记录。
• SPEC.md — 仅为确实已经交付的功能（可正常工作，而不只是开始着手）追加一节。描述它为用户实现的功能，而不是实现方式。
• GAP_ANALYSIS.md + GAP_CONTEXT.md — 两者必须保持同步。解决了某个缺口 → 从 GAP_ANALYSIS.md 中删除对应行（不要标记为已完成，而是直接删除），并删除 GAP_CONTEXT.md 中对应的条目。发现新缺口 → 在 GAP_ANALYSIS.md 中添加简短条目，并在 GAP_CONTEXT.md 中说明原因（有意搁置／疏忽／阻碍）。
• PLAN.md — 已完成的任务将 [ ] 改为 [x]；如果新请求改变了优先级，则重新排序；发现新工作时，添加新任务。
• WISDOM.md — 仅当确实学到了新知识时，才在相应章节（Constraints／Traps／Ditches／Wisdom）下添加条目，例如遇到的 bug、值得复用的模式或发现的硬性限制。如果本次会话没有带来新收获，不要硬凑条目。

对于核心集合以外的项目专属 scrolls 文件，请遵循 STARTER.md 为该文件规定的约定——如果文件明确采用不同的方式，就不要套用上述通用规则。

6. 不要捏造或夸大

如果无法确定某项工作是已交付还是仅仅开始着手，就视为尚未交付——将其记在 HANDOFF.md 的“已知问题／未完事项”或 PLAN.md 中，而不是作为已完成内容写入 SPEC.md。如果存在真正的歧义（例如无法确定某个缺口是已解决，还是仅被绕过），请先询问，不要猜测——这些文件对未来的每次会话都至关重要。

7. 报告更改内容

列出修改过的 scrolls 文件，并为每个文件说明一行修改原因。如果某个文件因会话活动而被有意保留原样（例如没有功能交付，因此 SPEC.md 无需添加条目），可以不提，不必逐一列出所有未修改的文件。只有第 2 步确实创建或更新了 SCROLLS.md／CLAUDE.md／AGENTS.md 时，才将它们列出；如果三者原本都正确，就像其他未修改的文件一样，无需提及。

开发

有关目录结构、运行 tests/ 回归测试套件和版本管理说明，请参阅 meta/MAINTAINERS.md。处理用户的 /scrolls-update 请求时，不会读取这两者——回答此类请求时，请勿操作 meta/MAINTAINERS.md 或 tests/。