LPZ 的个人网站

Appearance

npx skills：一行命令给 AI 编码代理装上"技能包"

发布日期：AICLIAgentSkills

Why：为什么需要 skills？ ​

主流 AI 编码代理（Claude Code、Codex、Cursor、Trae、OpenCode 等）都支持 Skill——一段写在 SKILL.md 里的"专家提示词 + 操作指引"，可以让代理掌握特定领域的工作流（生成 release notes、对接 Linear、按团队规范开 PR 等）。

但每个代理的 skills 目录都不一样：Claude 在 .claude/skills/，Cursor 在 .cursor/skills/，Codex 在 ~/.codex/skills/……

手动维护意味着：

  • 想给多个代理装同一个 skill，要复制多份；
  • 升级时要逐个目录同步；
  • 团队协作时无法统一来源。

vercel-labs/skills 就是为了解决这件事——一个 CLI，一次安装，自动分发到所有代理。

What：它是什么？ ​

一句话：开放的 Agent Skills 生态 CLI。

核心特性：

  • 多源安装：GitHub 简写 / 完整 URL / GitLab / 任意 git URL / 本地路径都支持；
  • 多代理分发：内置 50+ 代理路径映射，自动检测本机已装的代理；
  • 符号链接共享：一份正本，多代理软链，更新时一处生效；
  • 作用域隔离：项目级（随仓库走）和全局级（-g，跨项目复用）；
  • 完整生命周期：add / list / find / update / remove / init。

Skill 本身遵循开放规范 agentskills.io，跨代理通用；可在 skills.sh 浏览社区作品。

How：怎么用？ ​

1. 安装一个 skill 包 ​

bash
# GitHub 简写：owner/repo
npx skills add vercel-labs/agent-skills

# 也支持完整 URL / 子路径 / git / 本地路径
npx skills add ./my-local-skills

CLI 会扫描仓库里的 SKILL.md，让你勾选要装哪些、装到哪些代理。

2. 常用参数速查 ​

参数作用
-g, --global装到 ~/<agent>/skills/，跨项目可用
-a, --agent <names...>指定代理（如 claude-code、cursor、trae-cn），'*' 表示全部
-s, --skill <names...>指定要装的 skill 名，'*' 表示该仓库全部
-l, --list只列出，不安装
--copy用复制代替软链（部分环境不支持软链时用）
-y, --yes跳过所有交互确认
--all-s '*' -a '*' -y 的别名

3. 典型场景 ​

bash
# 浏览仓库里有哪些 skill
npx skills add vercel-labs/agent-skills --list

# 只装 frontend-design 到全局的 Claude Code（CI 友好）
npx skills add vercel-labs/agent-skills \
  --skill frontend-design -g -a claude-code -y

# 全家桶：把仓库里所有 skill 装到所有代理
npx skills add vercel-labs/agent-skills --all

4. 安装作用域 ​

作用域标记路径适用场景
项目默认./<agent>/skills/跟随仓库提交，团队共享
全局-g~/<agent>/skills/个人偏好，跨项目复用

推荐安装方式：Symlink（默认）。多个代理软链到同一份正本，升级一次全部生效。

5. 后续维护 ​

bash
npx skills list             # 查看已装（别名 ls）
npx skills find typescript  # 按关键词搜索 skill
npx skills update           # 升级到最新版
npx skills remove <name>    # 卸载
npx skills init my-skill    # 创建一份 SKILL.md 模板

6. 自己写一个 skill ​

新建一个目录，里面放一份 SKILL.md：

markdown
---
name: my-skill
description: 说明这个 skill 是干什么的，什么时候触发
---

# My Skill

代理在被激活时应遵循的指令。

## When to Use

描述触发场景。

## Steps

1. 先做这个
2. 再做那个

必填字段：

  • name：唯一标识（小写，可用连字符）；
  • description：触发条件 + 用途的简短说明。

可选字段：

  • metadata.internal: true：默认隐藏，仅在 INSTALL_INTERNAL_SKILLS=1 时可见，适合 WIP 或内部专用。

写好后用本地路径直接安装验证：

bash
npx skills add ./my-skill

一个 mental model ​

Skill 是给 AI 看的"操作手册"，npx skills 是分发这些手册的包管理器。

把它当作"AI 代理界的 npm"理解就够了：

  • npx skills add ≈ npm install
  • npx skills update ≈ npm update
  • SKILL.md ≈ package.json + README

当你下次想给团队的代理统一加上"生成 PR 描述"或"按某框架最佳实践写代码"的能力时，写一份 SKILL.md 推到 GitHub，团队成员一行 npx skills add 就能装上。

参考 ​

Copyright © 2019-present LPZ