npx skills 完全指南

一、npx skills 是什么

npx skills 是 Vercel 推出的 AI Agent 技能管理工具，让 AI 编程助手（Claude Code、Cursor、Windsurf 等）获得专业能力。它就像 AI 助手的"应用商店"，一次安装，多个助手共享。

• 技能市场：https://skills.sh/
• CLI 源码：https://github.com/vercel-labs/skills

---

二、核心概念

概念	说明	示例
技能包	GitHub 仓库，包含多个技能	obra/superpowers、vercel-labs/agent-skills
技能	具体的技能项，从技能包中选取安装	test-driven-development、frontend-design

结构关系（以 obra/superpowers 为例）：

obra/superpowers（技能包/仓库）
├── test-driven-development（技能 1）
├── systematic-debugging（技能 2）
├── verification-before-completion（技能 3）
└── ...

---

三、第一次使用 npx skills

第一次运行 npx skills 命令时，npx 会提示你是否下载 skills 工具包。输入 y 确认即可，之后 npx 会缓存这个包。

四、技能安装详解

来源格式

npx skills add <仓库来源>

格式	示例
GitHub 短名	vercel-labs/agent-skills
GitHub URL	https://github.com/vercel-labs/agent-skills
本地路径	./my-skills

（1）查看仓库有哪些技能

安装前先看看某个仓库里有哪些技能可选：

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

---

（2）安装技能

方式 A：安装整个技能包

安装某个仓库包含的所有技能：

# 安装 obra/superpowers 的所有技能
npx skills add obra/superpowers

# 安装 vercel-labs/agent-skills 的所有技能
npx skills add vercel-labs/agent-skills

方式 B：安装指定技能

从仓库中只安装特定的一个或多个技能：

# 安装单个技能
npx skills add vercel-labs/agent-skills -s frontend-design

# 安装多个指定技能
npx skills add vercel-labs/agent-skills -s frontend-design -s skill-creator

# 安装带空格的技能名（必须加引号）
npx skills add owner/repo --skill "Convex Best Practices"

# 安装所有技能到指定助手
npx skills add vercel-labs/agent-skills --skill '*' -a claude-code

方式 C：非交互式安装

建议先使用交互式安装熟悉流程后再使用此方式

使用 -y 跳过确认，-g 全局安装，-a 指定助手：

# 全局安装到指定助手，跳过确认
npx skills add vercel-labs/agent-skills -a claude-code -g -y

# 安装指定技能，跳过确认
npx skills add vercel-labs/agent-skills -s frontend-design -y

---

五、快速开始（整个交互流程）

以 obra/superpowers 仓库举例

运行 npx skills add obra/superpowers后，CLI 会依次询问：

流程一：选择要安装的技能

空格键多选，回车确认。

流程二：选择安装到哪个 AI 助手

CLI 自动检测已安装的助手，支持多选。

AGENT	SKILLS 路径	项目指令文件
Claude Code	~/.claude/skills/	CLAUDE.md
Qwen Code	~/.qwen/skills/	QWEN.md / AGENTS.md
OpenCode	~/.agents/skills/	AGENTS.md
GitHub Copilot	-	.github/copilot-instructions.md
Gemini CLI	-	GEMINI.md

流程三：选择安装范围

选项	说明
Project（项目级）	安装到当前项目，随 Git 提交，团队共享
Global（全局级）	安装到用户目录，所有项目可用

流程四：选择安装方式

选项	说明
Symlink（符号链接）	推荐，更新一处同步所有
Copy（复制）	独立副本

---

六、其他常用命令

查看已安装的技能

npx skills list           # 列出所有技能
npx skills list -g        # 只看全局技能
npx skills list -a claude-code  # 只看指定助手

搜索技能

npx skills find           # 交互式搜索
npx skills find react     # 按关键词搜索

更新技能

npx skills update                 # 更新所有技能
npx skills update frontend-design # 更新指定技能
npx skills update -g              # 只更新全局技能
npx skills check                  # 检查是否有更新

卸载技能

npx skills remove                      # 交互式选择卸载
npx skills remove frontend-design      # 卸载指定技能
npx skills remove frontend-design -g   # 从全局范围卸载
npx skills remove --all                 # 卸载所有技能
npx skills rm frontend-design           # 简写形式

---

七、推荐技能包

Superpowers（AI 工作流）

npx skills add obra/superpowers

包含技能：

• test-driven-development：测试驱动开发
• systematic-debugging：系统化调试
• verification-before-completion：完成前验证

Vercel 官方技能包

npx skills add vercel-labs/agent-skills

包含技能：

• vercel-react-best-practices：React 最佳实践
• web-design-guidelines：Web 设计规范
• skill-creator：技能开发指南

Anthropic 官方技能包

npx skills add anthropics/skills

包含技能：

• frontend-design：前端设计
• pdf：PDF 处理

---

八、常见问题

Q1: 第一次运行很慢？

首次运行时 npx 需要下载 skills 包，之后会使用缓存。

Q2: 安装太多技能会怎样？

AI 启动时需要加载技能元数据，安装太多会影响响应速度。建议只安装常用的。

Q3: 安装后 AI 没有用到技能？

1. 重启 AI 助手
2. 运行 npx skills list 确认安装成功
3. 检查技能是否安装到正确目录

Q4: 团队如何共享技能？

1. 项目级安装（不加 -g）
2. 把 skills-lock.json 提交到 Git
3. 团队成员拉取后运行 npx skills add

Q5: 如何禁用遥测？

export DISABLE_TELEMETRY=1

---

九、命令速查表

命令	作用
npx skills add <仓库> --list	查看仓库有哪些技能
npx skills add <仓库>	安装整个技能包
npx skills add <仓库> -s 技能名	安装指定单个技能
npx skills add <仓库> -s 技能1 -s 技能2	安装多个指定技能
npx skills add <仓库> -s 技能名 -y	非交互式安装
npx skills list	查看已安装技能
npx skills find <关键词>	搜索技能
npx skills update	更新所有技能
npx skills update <技能名>	更新指定技能
npx skills remove <技能名>	卸载技能
npx skills check	检查更新

---

相关资源

【1】技能目录：skills.sh
【2】CLI 源码：github.com/vercel-labs/skills
【3】npx skills 核心拆解
【4】npx skills核心功能速查及技能开发指南
【5】用一条命令为所有 AI Coding Agent 安装 Skills
【6】开放代理技能工具 - npx skills 的详解