npx skills 核心拆解

1. 工具定位

npx skills 是 Vercel 发布的 Agent Skills 管理工具，核心逻辑源自 add-skill 项目。它旨在建立开放的 Agent Skills 生态，实现技能的一次安装，多 Agent 共享。 目前可在 Skills.sh 市场查看和搜索可用技能。

2. 核心工作流

执行 npx skills add <repo> 的核心步骤如下：

1. 下载 (Clone)：将完整的目标 Git 仓库克隆至系统临时目录。
2. 识别 (Detect)：扫描仓库中的 SKILL.md 等标识文件，识别可用技能。
3. 存储 (Store)：将选定的技能文件移动至用户主目录下的统一存储库 ~/.agents/skills/<skill_name>。
4. 分发 (Link)：检测系统中已安装的 AI Agent（如 Cursor, Windsurf, Claude Code 等），通过 符号链接 (Symlink) 将统一存储库中的技能映射到各 Agent 的配置目录。
5. 锁定 (Lock)：更新 ~/.agents/.skill-lock.json，记录技能来源、版本 Commit Hash 和安装时间。
6. 清理 (Clean)：删除临时下载的仓库文件。

   注：实际验证发现，macOS 下临时目录位于 /var/folders/.../T/skills-XXXXXX。

3. 目录结构与管理机制

系统通过中心化的 ~/.agents 目录管理所有技能，避免重复存储。

安装到用户维度：

~/.agents/
├── .skill-lock.json            # [状态管理] 依赖锁定文件（记录版本、来源、时间）
└── skills/                      # [物理存储] 技能源文件存放地
    ├── docx/
    │   ├── SKILL.md            # 技能定义文件
    │   └── scripts/            # 辅助脚本（如 Python/JS 脚本）
    ├── planning-with-files/
    │   ├── SKILL.md
    │   └── templates/          # 模板文件
    └── ...

映射关系示例：

• Cursor: ~/.cursor/skills/docx -> ~/.agents/skills/docx
• Windsurf: ~/.codeium/windsurf/skills/docx -> ~/.agents/skills/docx
• Claude Code: ~/.claude/skills/docx -> ~/.agents/skills/docx

4. 常用命令速查

# 1. 安装技能
npx skills add <user>/<repo>                # 安装仓库内所有技能
npx skills add <url> --skill <name>         # 安装指定技能

# 2. 维护管理
npx skills check                            # 检查更新
npx skills update                           # 更新所有技能到最新 Commit
npx skills generate-lock --dry-run          # 生成/预览锁定文件