skill-manager 是一个“管理技能”的技能，用于在 Claude Code 和 Codex 中安装、更新、移除、创建、改进或审计其他技能。
【用途】 技能是一个包含 SKILL.md 的文件夹，用来教智能体一套可自行执行的工作流。skill-manager 负责管理这些技能的存放、安装与维护，并覆盖本机、单个项目文件夹以及远程服务器三种范围。
【存放位置与单一来源原则】 每个技能只保留一个来源，其他位置用链接指向，绝不保留两份副本：
- 默认作用于每个文件夹：~/.agents/skills/<name>/（Codex 从此处读取），并在 ~/.claude/skills/ 中建立链接供 Claude Code 使用。
- 仅作用于“大脑”（brain，即全局配置）或单个项目时：<folder>/.agents/skills/<name>/，Claude Code 通过 <folder>/.claude/skills 读取，并链接到该文件夹。brain 路径位于 ~/.agents/AGENTS.md 或 ~/.claude/CLAUDE.md 的 ## Brain 段落中。 所有安装、更新和移除都由 scripts/skills.sh 完成，不要手工复制或删除技能文件夹。若技能来自链接，需先下载：curl -fsSL https://raw.githubusercontent.com/Melvynx/ai-sprint-skills/main/skills/skill-manager/scripts/skills.sh -o <scratch>/skills.sh。任意命令加 --to <folder> 可作用于 brain 或某个项目而非所有文件夹。Windows 上需在 Git Bash 中运行。
【安装】 来源可以是 ai-sprint 套件中的技能名（connect-tool、setup-brain）、GitHub 仓库（owner/repo）、指向技能文件夹或其 SKILL.md 的 GitHub 链接，或本地文件夹。
- 查询可安装内容：bash skills.sh available（或 available <repo>），用简短列表展示每个技能及其能支持的提问。
- 选择位置：默认每个文件夹，除非该技能只在 brain 或单个项目中才有意义。
- 执行：bash skills.sh install <source> [<skill>...]。若仓库含多个技能且未指定，命令以退出码 2 结束并列出清单，需询问安装哪些或全部。退出码 3 表示同名技能已存在且非此方式安装，应比较两者描述：确为同一技能时用 --force 替换，否则先询问（可能是用户自建技能）。退出码 4 表示需用 available 或链接核对名称。
- 完成后确认 ~/.claude/skills/<name>/SKILL.md（或 <folder>/.claude/skills/<name>/SKILL.md）可打开，并告知用户技能将在下次会话起可用，同时给出触发它的句子。
【查看、更新与移除】 bash skills.sh list 查看已安装技能（own 表示用户自建或以其他方式安装；claude-only 表示 Codex 看不到，可建议移入 ~/.agents/skills）。bash skills.sh update [<skill>...] 重新拉取所有由它安装的技能。bash skills.sh remove <skill>... 需先在一行内确认名称，移除后会移动到 ~/.cache/removed-skills，误删可通过将文件夹移回恢复。
【服务器】 在远程服务器智能体上（ssh -o BatchMode=yes hermes true < /dev/null 可用时），每条远程命令以 ssh hermes '<command>' < /dev/null 执行。套件内的技能通过服务器自带管理器操作：hermes-setup catalog、hermes-setup add <skill>...、hermes-setup update、hermes-setup remove <skill>...。其他技能（自建或来自其他链接）用 ssh hermes 'bash -s -- install <source>' < skills.sh（或 remove、list）。Hermes 在下次对话时可见。
【创建技能】
- 一次性询问它应做什么，以及用户会输入的 2 至 3 句启动语句；若对话刚完成该工作流，可据实际过程提议技能并请用户确认。
- 命名为小写加连字符，动作为主时动词在前（如 write-newsletter、check-invoices）；若已有技能可完成同样事情，改为改进该技能。
- 编写 frontmatter：name，以及 50 至 300 字符的 description，先写它做什么，再写 Use when 及用户会说的词。描述是智能体加载技能前唯一能看到的内容，决定技能何时运行。需要输入时加 argument-hint；仅当用户主动输入才允许运行（发送、发布、付款）时加 disable-model-invocation: true。
- 正文使用平实的祈使句（不用标题、不加粗，仅有序步骤用编号列表），按 读取、执行、汇报、停止 的顺序写：先读什么、步骤、最后向用户展示什么。给出目标与判断标准而非僵硬规则，每一行都应改变智能体的行为。固定不变的命令放入 scripts/，冗长细节（API 文档、模板、示例）放入 references/，并在正文中说明何时打开各文件。
- 直接在相应位置创建文件夹；对每个文件夹，用 ln -sfn ~/.agents/skills/<name> ~/.claude/skills/<name> 建立链接，除非 ~/.claude/skills 已链接到 ~/.agents/skills。
- 立即在真实案例上测试，或请用户在新会话中输入触发语句；修正技能本身而非只修结果。
【改进与审计】 改进时先阅读技能，找到导致错误行为的行（或缺失的行），以最少改动修复并重新运行。审计时从 bash skills.sh list 及带 --to <brain> 的同一命令开始；对技能每一行判断删除后是否改变行为，删除无效、重复和过时的规则；指出互相重叠或用户从不使用的技能，仅在用户同意后移除。
【结束与分享】 最后汇报变更内容（每个技能一行，用对勾或叉表示）、各自位置、触发语句；对于用户自建的技能，说明分享方法：放入公开 GitHub 仓库后，他人可用此技能加链接安装，或用 npx skills add <owner>/<repo> 安装。
【适用场景】 适合需要集中维护 Claude Code 与 Codex 技能集合、统一安装来源、避免重复副本，或需要按规范创建与审计技能的用户。
【限制】 Windows 需使用 Git Bash；远程服务器操作依赖可用的 ssh 与 hermes 环境；部分错误情形（已存在同名技能、未指定多个技能）需人工确认。