01MVP Starter Kit

为什么值得关注

如果你已经在用 Claude Code、Cursor、Codex、Windsurf 这类 AI 编程工具，接下来大概率会遇到一个问题：别人写好的 Skill，怎么快速装到自己的 Agent 里？

现在最值得优先了解的答案就是：npx skills。

这不是一个没人用的小脚本，而是 Vercel Labs 开发的开源 Skill 管理工具。它的 GitHub 仓库已经有 16,500+ Stars，Vercel 官方文档也把 skills.sh 作为 Skill 发现入口。skills.sh 本身已经开始像一个 Agent Skill 的公共目录：你可以在上面浏览 Skill，再用一条命令安装到自己的 AI 工具里。

更关键的是，它已经有了真实使用规模：

skills.sh 上 最热门的 Skill 累计安装超 130 万次
Microsoft 的 azure-skills 系列在榜单上显示总安装量超 540 万
vercel-labs/skills 官方说明支持 Claude Code、Cursor、Codex、OpenCode 等 50+ 种 AI 工具
skills.sh 公开榜单已经展示 260+ 个 Skill，且数量还在增长

如果把 Skill 看成 AI Agent 的“插件包”，那 npx skills 正在变成很常见的安装方式。它解决的是一个很实际的问题：你不需要手动找目录、复制 SKILL.md、记每个工具自己的路径，只要一条命令，就能把 Skill 安装到对应的 Agent 环境里。

所以这篇不只是介绍一个命令，而是帮你掌握 Agent Skill 生态里越来越基础的一块能力：怎么找、怎么装、怎么更新、怎么管理。

它是什么

npx skills 是 Vercel Labs 开发的 Skill 管理工具。功能上你可以把它理解成 Skill 领域的 npm：安装、更新、删除、搜索，一条命令搞定，不用手动建目录或复制文件。

# 装一个 Skill
npx skills add anthropics/skills --skill commit

# 看装了哪些
npx skills list

CLI 源码在 github.com/vercel-labs/skills，Skill 发现和浏览在 skills.sh。

npx skills add 实际上是从 GitHub 下载文件。如果你的网络环境无法直接访问 GitHub，需要先配置代理。可以设置 HTTPS_PROXY 环境变量，或用 VPN。

基本用法

安装 Skill

npx skills add <owner/repo>                          # 装某个仓库的全部 Skill
npx skills add <owner/repo> --skill <skill-name>     # 只装某个
npx skills add <owner/repo> -y                       # 跳过确认

也支持直接从 URL 安装单个 SKILL.md 文件：

npx skills add https://example.com/my-skill/SKILL.md

安装后，Skill 文件会被放到 .agents/skills/ 目录（项目级）或 ~/.agents/skills/（全局级），同时对已安装的 AI 工具创建对应的符号链接（比如 .claude/skills/）。

指定 AI 工具

默认只会为当前检测到的 AI 工具安装。用 --agent 可以指定：

npx skills add anthropics/skills --skill commit --agent claude-code cursor
npx skills add anthropics/skills --skill commit --agent '*'    # 所有支持的工具

全局 vs 项目安装

加 --global（-g）装到全局，不加则装到项目目录：

npx skills add anthropics/skills --skill commit        # 项目级
npx skills add anthropics/skills --skill commit -g     # 全局级

场景	安装位置	理由
每个项目都用	全局	省得每个项目装一遍
只在特定项目用	项目	不污染其他项目的上下文
团队共享	项目 + 提交到 Git	跟着代码走

其他安装选项

--copy          # 复制文件而不是创建符号链接
--all           # 等同于 --skill '*' --agent '*' -y
--full-depth    # 即使子目录有 SKILL.md 也搜索更深层
-l, --list      # 只列出仓库里有哪些 Skill，不实际安装

查看已安装

npx skills list                # 项目级
npx skills ls -g               # 全局级
npx skills ls -a claude-code   # 按 AI 工具过滤
npx skills ls --json           # JSON 输出，方便脚本

搜索 Skill

find 命令提供交互式搜索，输入关键词就能从 skills.sh 上找到社区 Skill：

npx skills find                # 交互式搜索
npx skills find typescript     # 带关键词搜索

更新 Skill

update 命令把已安装的 Skill 更新到最新版本（别名 upgrade）：

npx skills update              # 更新所有项目级 Skill
npx skills update my-skill     # 只更新某个
npx skills update -g           # 只更新全局 Skill
npx skills update -p           # 只更新项目级 Skill
npx skills upgrade             # 同 update

更新是基于 Lock 文件中记录的来源（source）去重新拉取。如果你手动改过 Skill 内容，更新会覆盖你的修改。

删除 Skill

npx skills remove              # 交互式选择要删的
npx skills remove my-skill     # 按名称删除
npx skills remove -g           # 从全局删除
npx skills rm --all            # 删除所有（需确认）

创建 Skill

npx skills init my-skill       # 创建 my-skill/SKILL.md

生成的 SKILL.md 包含 frontmatter 模板，编辑完后可以：

发布到 GitHub：推到你的仓库，别人就能用 npx skills add <your-repo> 安装
托管到任意 URL：别人用 npx skills add https://... 安装

Lock 文件

安装 Skill 后会产生 Lock 文件，用来记录安装来源和版本信息。有两套：

全局 Lock 文件

路径：~/.agents/.skill-lock.json

这个文件跟踪你全局安装了哪些 Skill。每条记录包含：

{
  "version": 3,
  "skills": {
    "mj-design": {
      "source": "makerjackie/skills",
      "sourceType": "github",
      "sourceUrl": "https://github.com/makerjackie/skills",
      "skillPath": "skills/mj-design/SKILL.md",
      "skillFolderHash": "abc123...",
      "installedAt": "2026-04-29T10:00:00.000Z",
      "updatedAt": "2026-04-29T10:00:00.000Z"
    }
  }
}

skills update 就是读这个文件，根据 source 和 skillPath 去拉最新版本。skillFolderHash 用来判断是否有更新。

项目 Lock 文件

路径：项目根目录的 skills-lock.json

这个文件是给项目用的，设计为提交到 Git。团队成员克隆后，运行 npx skills experimental_install 就能从 Lock 文件恢复所有项目级 Skill：

{
  "version": 1,
  "skills": {
    "fumadocs-i18n": {
      "source": "foreveryh/claude-skills-tutorial",
      "sourceType": "github",
      "skillPath": ".claude/skills/fumadocs-i18n/SKILL.md",
      "computedHash": "4030ba5e..."
    }
  }
}

和全局 Lock 的区别：项目 Lock 文件故意不存时间戳，减少 Git 合并冲突。computedHash 是从本地文件内容计算的，不是 GitHub tree SHA。

实验性命令

# 从 skills-lock.json 恢复安装（类似 npm install 读 package-lock.json）
npx skills experimental_install

# 把 node_modules 里的 Skill 同步到 AI 工具目录
npx skills experimental_sync
npx skills experimental_sync -a '*'     # 指定工具
npx skills experimental_sync -y         # 跳过确认

实战：维护自己的 Skill 仓库

如果你有一组自己常用的 Skill，可以把它们放在一个 GitHub 仓库里统一维护。比如 github.com/makerjackie/skills 就是这样一个仓库。

仓库结构

skills/
├── mj-writer/
│   ├── SKILL.md
│   └── README.md
├── mj-design/
│   ├── SKILL.md
│   └── README.md
├── voice-to-article/
│   ├── SKILL.md
│   └── README.md
└── ...

每个 Skill 是一个目录，里面必须有 SKILL.md。

工作流

在仓库里编辑 Skill——改完推到 GitHub
在任何项目里安装或更新：

# 安装某个 Skill
npx skills add makerjackie/skills --skill mj-writer

# 安装全部
npx skills add makerjackie/skills -y --all

# 全局安装全部（新机器初始化用）
npx skills add makerjackie/skills -g -y --all

# 后续更新
npx skills update

这个模式的好处很直接：你在一个地方维护所有 Skill，改完之后各处 update 就同步了。

它支持的 AI 工具

npx skills 支持 40+ 种 AI 工具，安装时会自动检测当前环境里有哪些：

工具	开发方	安装路径
Claude Code	Anthropic	`.claude/skills/`
Cursor	Cursor Inc.	`.cursor/skills/`
Codex	OpenAI	`.codex/skills/`
Cline	开源社区	`.cline/skills/`
Windsurf	Codeium	`.windsurf/skills/`
Gemini CLI	Google	`.gemini/skills/`
Amp	Amplified	`.agents/skills/`
Goose	开源社区	`.goose/skills/`

完整列表见 npx skills ls --json 输出。通用目录 .agents/skills/ 是所有"universal agent"共享的位置。

安全审计

Skills.sh 会对首次被安装的 Skill 自动生成安全审计，合作方包括 Gen Agent Trust Hub、Socket、Snyk 等。安装时 CLI 会展示审计结果：

Skilled Name         Gen             Socket          Snyk
mj-writer            Safe            0 alerts        Low Risk

这不意味着每个 Skill 都安全可靠——审计只覆盖已知风险类别。安装社区 Skill 前，建议先看一眼它的源码。

遥测

CLI 默认开启匿名遥测，只记录安装了哪些 Skill，不收集个人信息。关闭方式：

DISABLE_TELEMETRY=1 npx skills add ...

遥测数据用来给 skills.sh 的排行榜排名。

常见问题

报错怎么办？

最常见的原因是网络问题。npx skills add 需要能访问 GitHub。试试：

# 设置代理
export HTTPS_PROXY=http://127.0.0.1:7890
npx skills add makerjackie/skills --skill mj-writer

装完没生效？

npx skills list 确认文件在正确目录下
当前对话需要新开一轮才能加载新 Skill

装好 Skill 后想了解怎么用 → 快速入门
想了解全局 vs 项目目录的取舍 → Skill 的局限和常见坑
想自己创建 Skill → 创建 Skill
想了解 Skill 和 MCP 怎么配合 → Skills + MCP 组合

npx skills 命令行指南