scrolls-hide

隐藏 docs/scrolls/

有些项目会让其 scrolls 文件夹保持可见（scrolls，例如通过 /scrolls-setup --unhide 或之前运行 /scrolls-unhide），之后又想恢复为默认的点文件隐藏状态。此技能会将 scrolls 重命名为 .scrolls，并修复它能够确信找到的所有旧路径引用，不会擅自猜测并编辑其作用范围之外的文件。它与 /scrolls-unhide 方向相反，操作机制相同。

除非 -t/--reporoot 指定其他位置，否则所有操作都相对于当前工作目录进行，而不是相对于此技能自身所在的位置。

跨平台

随附脚本提供两种形式：hide.sh（bash，适用于 macOS、Linux，或安装了 Git Bash/WSL 的 Windows）和 hide.ps1（PowerShell 7+，适用于 Windows，或安装了 pwsh 的 macOS/Linux）。两者接受完全相同形式的相同标志（-p/--path、-t/--reporoot、-l/--local、-r/--recurse），并产生相同的输出；区别仅在于启动方式。请根据实际可用情况选择：尝试运行 bash --version；如果成功，使用 .sh；否则通过 pwsh 使用 .ps1（首选；如果缺少 pwsh，请从 https://aka.ms/powershell 安装），只有在确实无法使用 pwsh 时才使用 Windows 内置的 Windows PowerShell powershell.exe（尚未针对该旧版本测试；本脚本是按 pwsh 编写并验证的）。

选项

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

• -p <path> / --path=<path> / --path <path> ——要操作的基目录，而非当前目录。可重复指定，以便在一次运行中定位多个位置（例如，在单体仓库中使用 -p packages/api -p packages/web）。
• -t / --reporoot ——将 git 仓库的顶层目录（$(git rev-parse --show-toplevel)）用作基目录，无论你实际从哪个子目录调用。如果当前目录不在 git 仓库内，则会显示明确的错误消息。
• -l / --local ——明确使用当前工作目录作为基目录。未提供 -p/-t/-l 中任何一个时，默认行为本来就是如此；此标志用于明确表示这一意图。
• -r / --recurse ——在基目录下递归搜索 scrolls 文件夹，而不是仅检查其确切路径 docs/scrolls。其含义与 grep/cp/rm 等工具中的 -r 一致：默认关闭，需主动启用以扩大影响范围。可与上述任一选项组合使用，也可单独使用（从当前工作目录开始递归）。

-p、-t 和 -l 是选择基目录的三种不同方式；-t 和 -l 各自只会解析为一个目录，不能与 -p 或彼此组合；需要指定更具体的位置时，请使用 -p（可重复指定）。-r 独立生效，可与上述任一选项组合。如果未指定基目录，随附脚本会优先使用用户设置的 DEFAULT_SCROLLS_RELPATH 环境变量，否则使用当前目录；如果该默认位置未启用递归，且与仓库顶层不同（位于 git 仓库内时），脚本会提示可改用 -t/-r，因为否则仓库其他位置的 scrolls 文件夹会被忽略，而不会报错。

由于名称中不带点的 scrolls 目录比 .scrolls 更通用，因此这里出现误报的可能性高于 /scrolls-unhide。下文所述的 STARTER.md 存在性检查可确保递归操作始终安全。

步骤

1. 运行随附脚本

bash <skill-dir>/scripts/hide.sh [-p BASE ...] [-t] [-l] [-r]
pwsh <skill-dir>/scripts/hide.ps1 [-p BASE ...] [-t] [-l] [-r]

将用户提供的标志以相同形式传递给与环境匹配的脚本（参见上文“跨平台”）。若要使用默认设置，则完全不传递标志。对于每个解析出的基础目录，脚本会执行以下操作：

• 不带 -r（默认）：只检查一个位置——如果基础目录本身已经是 scrolls 文件夹（包含 STARTER.md），则检查该目录；否则检查 <base>/docs/scrolls。速度快，并且与 /scrolls-setup 和 /scrolls-update 默认使用的位置一致，因此直接运行时会优先检查最明显的位置。
• 带 -r/--recurse：在基础目录下的有限层级内搜索名称确切为 scrolls 且包含 STARTER.md 的目录——这一限制使得从较大的基础目录（甚至整个仓库）开始递归搜索也很安全：会忽略名称恰好相同但不含 STARTER.md 的目录，并且会跳过常见的大型目录或供应商目录（node_modules、.git、vendor、dist、build、.venv、venv、__pycache__、target、.next、.cache），不进入这些目录搜索。

对于找到的每个匹配项（无论使用哪种方式）：

1. 如果旁边已经存在 .scrolls 文件夹，则跳过该项（并说明原因）；否则，如果仓库和文件已由 git 跟踪，则使用 git mv 重命名（保留历史记录），否则使用普通的 mv。
2. 在已移动文件夹自身的文件中重写对旧路径的引用（这也会处理 STARTER.md，因为其中多处引用了自身路径）；如果存在与该文件夹的 docs 目录恰好相邻的唯一一个 SCROLLS.md 文件，也会在其中重写引用——绝不会广泛搜索 SCROLLS.md。不会改动 CLAUDE.md 本身：/scrolls-setup 会将其写成指向 SCROLLS.md 的固定指针，而不是直接引用 scrolls 路径，因此无需在其中重写任何内容。/scrolls-setup 会写入简短、可移植的引用（相对于 SCROLLS.md 所在位置的 docs/scrolls），因此在多位置扫描中，两个不同的 scrolls 文件夹可能会合法地共用完全相同的短字符串。若“好心地”广泛搜索匹配的 SCROLLS.md 文件，可能会误改不相关的相邻软件包文件。（对于按照旧约定使用自定义 --path 设置的 scrolls 文件夹，重写操作也会尝试使用发现时的完整路径。）
3. 输出附近仍提及旧路径的其他文件——这些文件只会报告，不会编辑；排除其他 scrolls 文件夹内部的文件（在共用短格式约定下，这是常见的误报来源），但偶尔仍可能包含误报的相邻 SCROLLS.md 文件——这是预期情况，见下文第 2 步。脚本有意不触碰 scrolls 文件夹及其自身 SCROLLS.md 以外的文件，因为不先阅读内容就重写任意文本（README、CI 配置、其他文档），可能会破坏不相关内容。

如果给定的基础目录中没有匹配的文件夹，脚本会报错退出——不带 -r 时，这表示应检查路径；如果预期的是仓库根目录，则尝试使用 -t；如果目标可能嵌套得更深，则添加 -r；否则请引导用户前往 /scrolls-setup。

2. 处理报告中剩余的引用

对于脚本在“Other references... left for manual review”下列出的每个文件，请阅读文件内容；如果确实存在过时路径引用（例如 README、CONTRIBUTING 文档或 CI 脚本），请运用正常的编辑判断自行更新，而不要盲目查找并替换。跳过与本项目的 scrolls 文件夹无关的内容（例如偶然匹配的字符串）。

3. 汇报结果

列出每个已隐藏的文件夹（旧路径 → 新路径）、每个文件夹中自动修复的内容（其自身文件、SCROLLS.md）、任何被跳过的文件夹及原因（目标已存在），以及你在第 2 步中手动修复的内容（如有）。

开发

请参阅 meta/MAINTAINERS.md，了解目录布局、运行 tests/ 回归测试套件以及版本管理说明。处理用户的 /scrolls-hide 请求时，不会读取这两者；回答此类请求时，请勿操作 meta/MAINTAINERS.md 或 tests/。