file-handler

file-handler

本仓库中所有 skill 统一使用一种磁盘存储约定：

.skillz/
└── <type>/
    └── <slug>

<type> 按用途对文件进行分组（note、plan、draft、log 等）。<slug> 是文件名。两者都会经过校验——不允许路径分隔符、.. 或以点开头，因此 skill 可以直接使用用户提供的 slug，无需清理。

如何使用此 skill

当另一个 skill 需要保存或加载工作文件时，通过 shell 调用 scripts/skillz.sh。三个子命令涵盖所有操作：

# write content to .skillz/<type>/<slug>
scripts/skillz.sh save_file note todo "things to do"

# write stdin (preferred for multi-line content)
some_command | scripts/skillz.sh save_file plan release-cut

# read it back
scripts/skillz.sh get_file note todo

# search by title and body, optionally narrowed to a type
scripts/skillz.sh search_files todo
scripts/skillz.sh search_files release --type plan

save_file 成功时会输出解析后的路径，调用方可以将其原样提供给用户。若目标文件或匹配项不存在，get_file 和 search_files 会以状态码 1 退出，因此 skill 可以通过 || 进行分支处理。

存储根目录

默认情况下，目录树位于 $PWD/.skillz。若要使用会话级或仓库级位置，可通过 SKILLZ_DIR 覆盖：

SKILLZ_DIR="$HOME/.local/share/skillz" scripts/skillz.sh save_file note hello "hi"

如果不应将这些文件提交到仓库，请将 .skillz/ 添加到仓库的 .gitignore。

调用方约定

• 选定一种类型后，重复使用。 不要为每个文件都创建新的 <type>——类型是分类目录（note、plan、draft、log、transcript）。slug 才是区分文件的部分。
• Slug 必须是适用于文件名的 ASCII 字符。 允许使用：[A-Za-z0-9._-]（字母、数字、点、下划线、连字符——推荐使用 kebab-case，但也接受扩展名中的点和大写字母）。其他字符会被拒绝，退出状态码为 2。
• 不要求使用扩展名，但添加扩展名（.md、.txt、.json）有助于用户直接打开文件。
• 多行内容优先通过 stdin 传入，而非内联内容参数——引用内容很快就会变得容易出错。
• 不要通过此 skill 写入受版本控制的源文件。 它用于 skill 临时文件，不用于项目目录。

子命令参考

save_file <type> <slug> [content]

写入 .skillz/<type>/<slug>。如果省略 content，则从 stdin 读取。按需创建父目录。输出解析后的路径。参数错误时以状态码 2 退出。

get_file <type> <slug>

将 .skillz/<type>/<slug> 输出到 stdout。文件不存在时以状态码 1 退出，参数错误时以状态码 2 退出。

search_files <query> [--type <type>]

分两轮搜索：

1. 标题——在存储根目录（或 --type 指定的单个类型目录）下，通过 find -iname "*<query>*" 进行不区分大小写的搜索。
2. 正文——在相同范围内，通过 grep -rIn 搜索相同查询。跳过二进制文件。

输出按部分分组（先是 ## titles，再是 ## bodies）；正文匹配项采用标准的 <path>:<line>:<text> 格式，编辑器可据此跳转到对应位置。两轮搜索都没有结果时以状态码 1 退出。

为什么使用单一 skill

如果没有统一约定，每个需要保存工作状态的 skill 都会自行发明存储方式（~/.cache/<skill>/、/tmp/<skill>-*、$PWD 下的隐藏文件等）。这会让用户需要四处寻找文件，也会使跨 skill 工作流更难衔接（“我们上一轮起草的计划”）。统一使用 .skillz/<type>/<slug> 和三个动词，就能让工具包的其余部分保持精简。

不要使用此 skill 的情况

• 应用代码、配置或任何受 git 追踪的内容。 请直接编辑这些文件——此 skill 用于 skill 临时文件。
• 机密信息。 .skillz/ 中的内容以明文存储在本地磁盘上。请改用密码管理器（1Password、Bitwarden、age）。
• 跨设备同步。 文件仅存储在本地文件系统中。如果需要在其他设备上使用，请手动复制，或有意提交到仓库。
• 大型二进制文件。 正文搜索会跳过二进制文件，但此存储布局并未针对大型文件进行优化。

注意事项

• SKILLZ_DIR 在每次调用时读取，而不是只导出一次。 每次 调用 shell 都会重新解析它，因此两次调用之间更改环境变量会改变 存储根目录。
• Slug 验证不允许空格。 请传入 release-cut，而不是 release cut。上文已说明正则表达式。
• 正文 grep 使用固定字符串匹配（grep -F）。 特殊 字符（.、*、[）会按字面匹配。这是有意为之 — 用户搜索 v1.2.3 时，得到的结果会与输入完全一致，而不是 正则表达式。
• 不加锁。 两个技能同时写入同一个 <type>/<slug> 时会发生竞争；最后写入者胜出。并行工作时请使用不同的 slug。