openskills 怎么安装？Claude Code/Codex 技能包加载教程

不少人搜「openskills 怎么安装」，其实第一步先选对目录就行：如果只给 Claude Code 用，就放在 ./.claude/skills；要是还想给 Codex 共用，就换成 ./.agent/skills。装完之后还要把索引同步到 AGENTS.md 里。

动手前，安装目标怎么定？

准备工作其实就两样：Node.js 20.6 或更高版本，以及能正常运行的 Git。官方仓库地址是 numman-ali/openskills；要是需要核对源码，直接执行 git clone https://github.com/numman-ali/openskills.git 就行。从 README 里能看到，它支持四类技能来源：Anthropic 技能库、任意 GitHub 仓库、本地路径和私有 Git 仓库。

只给 Claude Code：用项目默认目录

npx openskills install anthropics/skills

这条命令默认会把技能装到当前项目的 ./.claude/skills 目录下。要是想跨项目通用，加个 --global 参数就行。

还要给 Codex：改用通用目录

npx openskills install anthropics/skills --universal

加了 --universal 参数之后，技能会装到 ./.agent/skills 目录，Claude Code、Codex 等工具就能共用同一份 AGENTS.md 索引了。

工具找技能的优先级是这样的：项目级 .agent、全局 .agent、项目级 .claude、全局 .claude；如果有同名技能，排在前面的先生效。

技能装好了，Codex 为什么还看不到？

安装命令只是把技能文件放好，得跑 sync 才会创建或者更新 AGENTS.md 里的 <available_skills> 索引。Codex 先读到这个索引，之后才会根据任务调用 read 拿完整的技能指令。你可以跑这几条命令做个最小验证：

npx openskills sync
npx openskills list
npx openskills read <skill-name>

正常情况下，list 会返回已装的技能名，read 会输出技能指令和资源基目录。要是没出结果，就按顺序检查：命令执行目录对不对、技能文件夹里有没有 SKILL.md、AGENTS.md 里有没有写入索引；同步的时候不想逐项勾选，直接用 npx openskills sync -y 就行。

FAQ：需要 API Key 或重启吗？

OpenSkills 本身不需要 API Key；私有仓库需要 Git 凭据，要是具体技能本身要调用外部服务，还得按各自说明配置依赖和环境变量。密钥最好放在系统环境变量或宿主配置中，除非技能官方说明明确要求，不然别写进项目根目录的 .env。不同宿主刷新旧会话的规则不一样，当前任务没读到新索引时，重新打开项目或者新建 Codex 任务就好了。

交付前查这五项

1. Node.js 版本在 20.6 及以上，Git 命令能正常运行。
2. 目标技能目录和 Claude Code、Codex 的使用范围匹配。
3. 技能文件夹内存在有效的 SKILL.md。
4. AGENTS.md 已生成技能索引，list 能列出对应名称。
5. read 能返回完整指令，新任务可按需加载。