Skills 仓库管理约定

这是跨 agent 的个人全局 skills 和全局指令主仓库。项目专用技能与指令在各自项目中管理和备份；本仓库不设 projects/global 分类目录。用户通过自然语言请求 agent 完成管理，不要求开发专用 CLI。适用于 Codex、Claude Code、OpenCode、pi 及后续接入的其他 agent。

全局指令

• 根目录 AGENTS.md 管理本仓库；agent-instructions/AGENTS.md 保存供各 agent 的 user level 加载的个人全局指令。不要将根目录文件链接为全局指令。
• agent-instructions 是指令目录，不是 skill；不添加 SKILL.md，也不登记到 SOURCES.md 的技能订阅中。技能目录继续在根目录平铺。
• 全局指令共享一份正文。接入时核实目标产品的指令文件名、加载位置和优先级；必要的产品差异在 README 中说明，不假定各 agent 的加载行为相同。
• 全局指令使用文件链接，不能使用目录 junction。链接在每台设备分别建立；已有目标文件时先检查内容和链接目标，保留备份并处理差异，不能直接覆盖。修改后核实链接目标与实际加载结果。

内容与记录

• 每个 skill 是根目录下的独立文件夹，包含 SKILL.md 以及所需脚本、模板、参考资料。保持平铺结构，默认将全局加载目录链接到仓库根目录。
• SOURCES.md 按自建、第三方和自行维护的 fork 精简记录来源、订阅选择及实际导入版本；同一来源合并记录，不重复填写空字段或“不适用”。不要凭名称猜测作者、来源或 commit；影响后续更新的未知信息集中注明“待确认”。
• Git 保存实际文件，不仅保存下载地址。第三方内容保留原始许可证；本仓库 MIT 不覆盖第三方许可证。
• 各 agent 的发现规则在实际接入时核实。各设备的仓库位置和加载路径可以不同，接入或修复时检查本机实际路径、产品配置及链接目标，不维护本机安装记录文件。共享文档使用相对路径或占位符，不依赖某台设备的绝对路径。凭据不得入库；不要记录不允许备份的 skill 的内容。
• 仅提交用户明确收录的 skills。不需要同步的普通技能，默认按具体根目录路径加入 .gitignore，让排除规则随仓库同步；只有明确属于单台设备的例外才写入 .git/info/exclude。不要仅凭“本机专用”就默认使用 exclude，也不要将文档示例自动加入实际忽略规则。
• 修改忽略规则前检查目标是否已被 Git 跟踪，修改后用 git check-ignore 核实。忽略不影响 agent 加载，也不会停止跟踪已有文件或清除历史；发现已跟踪内容时说明现状，不擅自删除文件或改写历史，不得强制添加已排除内容。明确不能进入个人仓库的内容保存在仓库外。未收录的私有或安装器管理内容不自动上传或清理。
• 不为不同 agent 复制维护多套相同 skill。共享正文使用标准 name、description 和相对路径；工具名、专用元数据、MCP、CLI 和运行平台差异必须记录，发现成功不代表行为兼容。

导入：用户说“从这个仓库添加这些 skills”

1. 检查 Git 状态、已有订阅及目录/name 冲突。仅第一次且选择不明确时展示候选项；已明确的选择直接执行，以后不反复询问。
2. 将来源解析到具体 commit，在临时目录检查所选完整内容及共享依赖，然后导入。不要为了查看内容执行第三方安装脚本。
3. 在 SOURCES.md 按来源记录 URL、跟踪分支或 tag、选中的 skills 及实际导入 commit；非 Git 下载记录地址和内容校验值。默认以目录/name 作为稳定本地标识，仅在上游路径或名称不同时补充映射。许可证、依赖及 agent 兼容性只记必要差异和已知限制，不重复技能正文，也不记录安装流水账。
4. 本地标识用于记住订阅；实际目录和 SKILL.md 的 name 尽量一致。不能只改目录而忽略内部引用和触发名称。
5. 更新 README 索引并检查引用。初次盘点不清楚来源的内容仍可备份，但不能假装已能自动跟踪更新。

检查与更新

• “检查更新”只报告；“更新”授权应用能够明确判断的普通更新。沿用已记录的选择，同一来源集中检查，不自动订阅新出现的 skills。
• 从已导入 commit 比较到候选 commit；实际内容和已导入版本记录一起更新。失败项保留原有内容和版本，分别报告。
• 移动或改名：根据 Git 变更、内容、元数据识别明确的一对一映射，更新路径记录并验证引用，保留稳定本地标识。
• 不明确的改名、合并或拆分：保留当前版本，集中展示迁移选项，只询问必要选择，随后保存决定。
• 上游删除：保留最后可用文件，标记“上游已删除”；不自动删除或卸载。
• 先检查本地自定义改动，必要时做三方合并；不能直接覆盖冲突。大幅改造记为自行维护的 fork，保留基于的 commit、许可证及是否继续跟踪上游。
• 验证元数据、重名、引用、依赖和受影响的可执行行为。不要自动执行导入内容中的安装或外部写入指令。

自建

• 按适用的技能创作指导，在根目录创建独立 skill 文件夹并登记来源为自建。
• 从其他项目对话提炼的通用技能可直接写入已链接的全局加载目录，文件会落在本仓库中，无需搬运或补建链接；同时读取本仓库管理约定并登记来源。仅适用于当前项目的技能留在该项目。
• 目录链接不会让其他项目中的对话自动读取本 AGENTS.md；需要用户在对话中说明保存位置，或另行授权配置各 agent 的全局创建约定。
• 通用流程不依赖特定 agent 的专用工具名；不可避免的专用能力要声明兼容范围和替代方式。

换机安装与多设备同步

1. 确认用户实际使用的产品、版本、加载路径及原生 Windows/WSL 等运行环境。不要把所有 agent 当成 Codex，不要假定所有产品自动读取 AGENTS.md。
2. 仓库 clone 到本机选定的位置，各设备无需保持相同目录。默认让各 agent 的全局 skills 加载目录指向本机仓库根目录，链接在各设备分别建立，不随 Git 同步。多个 agent 可复用已支持的共享加载目录，无需逐 skill 建链接。
3. Windows 本地目录可考虑 junction，macOS/Linux 使用目录符号链接；核实整目录接入的实际发现结果。已指向正确目标的链接跳过。
4. 加载目录已经存在时先盘点并处理重名，不能覆盖。仅迁入用户允许收录或允许按忽略规则本机保留的内容；不可收录的内容留在仓库外。保留原目录备份后再建立链接，未解决的冲突不得强行迁移。
5. 产品不支持整目录接入，或必须保留独立安装器目录时，可用额外搜索路径或批量逐项链接作为兼容方案。核实实际规则，不假定所有产品相同。
6. 不删除插件或其他安装器管理的内容。整目录接入后安装器可能直接写入仓库，新增内容在提交前必须核实来源和是否应同步。移除链接前确认归属与目标，仅移除链接本身，不递归删除目标。
7. 各 agent 复用同一加载目录时避免重复接入。检查重名、发现结果及实际技能调用；无法验证时说明，不宣称已成功。经链接编辑会直接修改仓库文件；本机独有改动不能靠忽略规则隐藏已跟踪文件的修改。Git 忽略和 SOURCES.md 均不是技能启停配置，需要限制启用范围时使用目标产品支持的配置或兼容方案。
8. 同步仓库先检查工作区。干净工作区可 git pull --ff-only；有改动或分叉时先检查并保留，不强制 reset。同步不会顺便升级第三方。 整目录接入下，新增和更新的 skill 无需补建链接；按目标产品要求刷新或重启并验证。拉取前检查未跟踪或被忽略的本机目录是否与新增内容冲突，保留本机文件，不强制覆盖或清理。
9. 多设备修改前先同步，完成后按用户授权提交并推送，另一台再拉取。未提交、未推送的改动不构成远程备份；Git 不会自动同步。
10. 系统自带/插件附带 skills 通过原安装渠道恢复，记录渠道即可；不要复制插件缓存冒充独立 skill。CLI、MCP、凭据和平台依赖另行恢复。

完成标准

• 报告变更项、版本、待处理异常、兼容范围、验证结果及提交/推送状态。
• 用户只要求设计或检查时，不执行本机安装、迁移或上游升级。
• 不自行提交、推送或改写历史，除非用户已经授权。