npx skills 命令行指南

npx skills 是 Vercel Labs 的开源 Skill 管理工具，用于搜索、安装、列出和更新 Skill。它负责把文件放到工具能发现的位置；脚本依赖、账号登录和实际任务结果仍需要分别检查。

先查看，再安装

从项目目录运行，先查看仓库提供了哪些技能：

npx skills add vercel-labs/agent-skills --list

--skill 匹配 SKILL.md 中的 name，不要把 GitHub 文件夹名称直接当成技能名。例如 React 最佳实践的文件夹叫 react-best-practices，安装名是 vercel-react-best-practices。

npx skills add vercel-labs/agent-skills --skill vercel-react-best-practices

不指定 --skill 时，多技能仓库通常会让你选择。-y 会跳过交互，并可能安装多项；--all 会同时扩大技能和目标工具范围。初次安装保留交互，选当前任务需要的那一个。

指定工具与范围

# 当前项目，指定 Claude Code
npx skills add makerjackie/skills --skill mj-writer --agent claude-code

# 全局，供多个项目使用
npx skills add makerjackie/skills --skill mj-writer --agent claude-code -g

范围	适合什么	管理方式
项目级	产品知识、框架规范、团队流程	随项目审阅和维护
全局级	跨项目反复使用的能力	只保留确实常用的技能

CLI 可通过共享目录、符号链接或复制安装。--copy 使用复制；最终路径以安装摘要为准。手动安装的目录和 CLI 的共享目录不一定相同。

查看与搜索

npx skills list
npx skills list -g
npx skills list --json
npx skills find pdf

list --json 列出已安装技能，不是全部兼容工具的清单。搜索结果和排行榜可用来发现候选，再回到源码检查使用条件。

更新与删除

更新会从来源重新获取文件。自己改过的内容先提交或备份，再明确选择范围：

npx skills update -p
npx skills update -g
npx skills update mj-writer -p

不带范围参数时，行为会受环境和交互选择影响，不要把它理解成“只更新当前项目”。当前实现中 check 是 update 的别名，也可能修改文件；不要拿它当只读检查命令。

# 按名称删除当前项目的技能
npx skills remove mj-writer

删前检查是否有本地修改。团队更新后，查看文件差异，再用一份实际输入验证输出。

私有仓库与本地目录

私有仓库可以用同样的安装命令，但当前环境必须有访问权限，例如已经配置好 Git/SSH 或 GitHub CLI 认证。不要把 token 写进 Skill、安装命令示例或提交记录。

npx skills add your-account/private-skills --skill your-skill
npx skills add ./local-skills --skill your-skill

下载失败时先区分网络问题、仓库权限和技能名错误。安装器无法替代仓库认证。

Lock 文件

项目根目录的 skills-lock.json 记录来源、技能路径和内容哈希。全局记录通常在 ~/.agents/.skill-lock.json，也可能受环境配置影响。

它们有助于追踪安装来源，但不要把内容哈希当成固定版本恢复保证：更新或重新安装可能读取来源的当前内容。需要稳定交付时，把经过审阅的 Skill 文件和依赖版本随项目保存，并检查差异。

experimental_install、experimental_sync 属于实验性命令。先阅读当前 CLI 文档，验证恢复结果后再用于团队初始化，不要直接套用 npm 锁文件的语义。

实战：维护自己的 Skill 仓库

每项能力放在独立目录，入口为 SKILL.md：

skills/
├── article-adapter/
│   ├── SKILL.md
│   └── references/
└── release-checklist/
    ├── SKILL.md
    └── scripts/

在一份真实任务上跑通流程，写清输入、输出和依赖。
审阅修改后推到仓库。
在需要的项目安装指定技能。
更新后检查差异与产物，再推广给团队。

可以用 npx skills init article-adapter 生成模板。格式和写法见创建 Skill。

它支持的 AI 工具

安装器适配多种 Agent，但“能放入目录”和“能在当前客户端完整执行”是两件事。目录发现、调用入口、扩展字段、脚本权限取决于客户端版本。

当前 CLI 对 Codex、Cursor 使用共享的 .agents/skills/ 路径；Claude Code 等工具还可能有自己的链接目录。手动安装与调用说明见快速入门，完整安装目标以 CLI 官方文档为准。

安装后没有生效

先查当前项目和全局列表，再检查 SKILL.md 的名称、描述和目标工具。明确点名调用一次；如果客户端没有发现新文件，按该工具的刷新说明处理。路径和加载问题见 FAQ。

本页命令与行为依据 2026-09-30 的上游文档和源码核对；CLI 升级后以当前帮助和安装摘要为准。

npx skills 命令行指南

On this page