我的 AI Agent Skills 管理工作流

2026.04.30

·agentskills

我本地主要用 Codex、Claude Code 和 Cursor。它们都支持类似 SKILL.md 的能力扩展：把稳定的操作步骤、工具用法、项目约定写成 skill，让 agent 在合适的时候直接调用。

我不想给每个工具各维护一份 skill。这个仓库就是为了解决这件事：

text
GitHub 仓库管源头
vercel-labs/skills 负责安装
Codex / Claude Code / Cursor 只负责使用

工具本身的完整说明放在。这份 README 只写我的使用约定。

1. 我想解决什么 ​

  • 同一个 skill 不在多个 agent 目录里重复维护。
  • 自己写的 skills 能同时给 Codex、Claude Code、Cursor 用。
  • 公开 skills 有一个明确源头，方便更新和分享。
  • 私人路径、公司上下文、发布细节和公开内容分开。
  • 不破坏各个 agent 自己的加载方式。

一开始我想过把 Codex、Claude Code、Cursor 的 skills 目录都 symlink 到同一个目录。后来放弃了。

原因很简单：不同 agent 的 Skill Spec 不完全一样。

  • Claude Code 可能有自己的 frontmatter 或权限约定。
  • Codex 有 .system skills、插件 skills 和自己的加载逻辑。
  • Cursor 也有自己的目录和上下文管理方式。
  • 第三方 skills 虽然都叫 SKILL.md，但很多默认只面向某一个 agent。

所以我不让所有 agent 共享同一个物理目录。更稳的方式是：保留各 agent 的原生目录，用安装器把同一份源头装到正确位置。

2. 目录设计 ​

本地统一放在：

text
/Users/liguwe/skills/
  skills/       # 公开技能库
  832-skills/   # 私有 / 上下文技能库

对应两个 GitHub 仓库：

text
github.com/liguwe/skills       # 公开库
github.com/liguwe/832-skills   # 私有或个人上下文库

公开库放我自己维护、适合公开复用的能力：

  • PNG 压缩、二维码生成这类通用工具能力。
  • 技术文档翻译成中文 VitePress 站点这类可复用工作流。

公开库不放这些东西：

  • 第三方、vendor、工具官方或别人维护的 skills。
  • 公司内部上下文。
  • 私有路径、token、cookie、SSH key、API key。
  • 只能在我本机或公司环境里跑通的流程。

私有库放上下文：

  • 个人默认路径。
  • 私有仓库和发布流程。
  • 公司或项目上下文。
  • 不适合公开的 prompt、runbook、检查清单。
  • 带权限假设的自动化流程。

这个边界很重要。全部公开有泄露风险，全部私有又不方便复用。

3. 为什么用 vercel-labs/skills ​

我用 vercel-labs/skills 做安装和分发。它支持 GitHub、SSH、Git URL 和本地路径。

常见来源：

bash
# GitHub shorthand
npx skills add liguwe/skills

# 完整 GitHub URL
npx skills add https://github.com/liguwe/skills

# SSH URL，适合私有仓库
npx skills add git@github.com:liguwe/832-skills.git

# 本地路径，适合开发和本机安装
npx skills add /Users/liguwe/skills/skills

它也能一次指定多个 agent：

bash
npx skills add /Users/liguwe/skills/skills \
  -g \
  -a codex \
  -a claude-code \
  -a cursor \
  --skill '*' \
  -y

参数含义：

  • -g：装到全局目录，不装到当前项目。
  • -a codex：装给 Codex。
  • -a claude-code：装给 Claude Code。
  • -a cursor：装给 Cursor。
  • --skill '*'：安装仓库里的全部 skills。
  • -y：跳过交互确认。

我的默认约定是 不要加 --copy。

不加 --copy 时，CLI 会优先用 symlink/link。agent 目录里读到的是源仓库里的同一份 skill，改完源文件，下次 agent 读取就是最新内容。

这更适合我的真实流程：

  • 新写的 skill 经常要边用边调试。
  • 调试时只改 /Users/liguwe/skills/skills 或 /Users/liguwe/skills/832-skills。
  • Codex、Claude Code、Cursor 都能直接读到同一份最新内容。
  • 不需要调试完成后再复制或同步一轮。

所以我的规则是：

text
日常安装默认 link/symlink
调试和维护都改源仓库
只有要固定快照或环境不支持 symlink 时才用 --copy

4. 初始化两个技能库 ​

本地根目录：

bash
mkdir -p /Users/liguwe/skills

公开库：

bash
git clone git@github.com:liguwe/skills.git /Users/liguwe/skills/skills

私有库：

bash
git clone git@github.com:liguwe/832-skills.git /Users/liguwe/skills/832-skills

之后只在这两个仓库里维护 skills，不直接去 Codex、Claude Code 或 Cursor 的安装目录里改文件。

5. 安装到不同 agent ​

安装公开库：

bash
npx skills add /Users/liguwe/skills/skills \
  -g \
  -a codex \
  -a claude-code \
  -a cursor \
  --skill '*' \
  -y

安装私有库：

bash
npx skills add /Users/liguwe/skills/832-skills \
  -g \
  -a codex \
  -a claude-code \
  -a cursor \
  --skill '*' \
  -y

如果从远端安装私有库，用 SSH URL：

bash
npx skills add git@github.com:liguwe/832-skills.git \
  -g \
  -a codex \
  -a claude-code \
  -a cursor \
  --skill '*' \
  -y

SSH URL 可以复用本机 GitHub SSH 权限，适合 private repo。

6. Agent 专属 skill ​

不是所有 skill 都要装给所有 agent。

只适合 Claude Code 的 skill，只装给 Claude Code：

bash
npx skills add /Users/liguwe/skills/832-skills \
  -g \
  -a claude-code \
  --skill my-claude-only-skill \
  -y

只适合 Codex 的 skill，只装给 Codex：

bash
npx skills add /Users/liguwe/skills/832-skills \
  -g \
  -a codex \
  --skill my-codex-only-skill \
  -y

我的原则：

  • 通用 skill 可以装给多个 agent。
  • agent 专属 skill 精确装给对应 agent。
  • 不手工改 agent 的系统内置 skills。
  • 不迁移 Codex .system skills、plugin cache、vendor imports。

7. 日常新增一个 skill ​

后续我自己新增或维护 skills，说明层默认用中文写，包括 SKILL.md、references/ 和 agents/openai.yaml。

这些内容可以保留英文：

  • skill 名
  • 命令和参数
  • 代码
  • 文件路径
  • 包名
  • API 名称
  • 专有名词

新增公开 skill：

bash
cd /Users/liguwe/skills/skills
mkdir my-new-skill
$EDITOR my-new-skill/SKILL.md

新增私有 skill：

bash
cd /Users/liguwe/skills/832-skills
mkdir my-private-skill
$EDITOR my-private-skill/SKILL.md

最小 SKILL.md：

markdown
---
name: my-new-skill
description: Describe when this skill should be used.
---

# My New Skill

Write the workflow, rules, commands, and constraints here.

检查能不能被 CLI 发现：

bash
npx skills add /Users/liguwe/skills/skills --list

安装到本机 agent：

bash
npx skills add /Users/liguwe/skills/skills \
  -g \
  -a codex \
  -a claude-code \
  -a cursor \
  --skill my-new-skill \
  -y

提交公开库：

bash
cd /Users/liguwe/skills/skills
git add my-new-skill README.md
git commit -m "Add my new skill"
git push

提交私有库时同理，只在 /Users/liguwe/skills/832-skills 里操作。

8. 公开库里的 skills ​

目前公开库只放我自己创建和维护的 skills：

  • png-optimize
  • qr-code-generate
  • translate-docs-to-zh-vitepress
  • xiaoyuzhou-audio-download

translate-docs-to-zh-vitepress 里有我的发布偏好，比如 VitePress、GitHub Pages、liguwe.site。但它本质上还是一个可以公开复用的工作流：把技术文档翻译成中文站点并部署到 GitHub Pages。

所以我的分类标准不是“有没有个人偏好”，而是：

text
核心能力能公开复用，就可以放公开库
涉及私有上下文和权限假设，就放私有库

9. 安全检查 ​

公开库提交前检查：

  • 没有 token、cookie、SSH key、API key。
  • 没有公司内部域名、内部 API、内部业务流程。
  • 没有不能公开的个人路径或部署机器信息。
  • 没有默认执行危险命令。
  • 没有搬运第三方、vendor 或别人维护的 skills。
  • description 写清楚什么时候应该使用这个 skill。

私有库也不提交真实密钥。private repo 只适合放上下文、流程和约定，不适合放 secret。

10. 验证命令 ​

检查公开库 skills：

bash
npx skills add /Users/liguwe/skills/skills --list

检查私有库 skills：

bash
npx skills add /Users/liguwe/skills/832-skills --list

检查全局安装：

bash
npx skills ls -g -a codex -a claude-code -a cursor

检查两个仓库状态：

bash
git -C /Users/liguwe/skills/skills status --short --branch
git -C /Users/liguwe/skills/832-skills status --short --branch

重新安装公开库：

bash
npx skills add /Users/liguwe/skills/skills \
  -g \
  -a codex \
  -a claude-code \
  -a cursor \
  --skill '*' \
  -y

重新安装私有库：

bash
npx skills add /Users/liguwe/skills/832-skills \
  -g \
  -a codex \
  -a claude-code \
  -a cursor \
  --skill '*' \
  -y

11. 最后的原则 ​

text
源头在 GitHub repo
安装靠 skills CLI
调试和维护都改源仓库
agent 通过 link 消费同一份 skill

公开库沉淀我自己维护的可公开能力。私有库沉淀个人上下文。第三方、vendor、工具官方 skills 继续留在它们自己的上游来源、插件、系统 skills 或 agent 原生安装流程里。

这个方式比“每个工具各维护一份”简单，也比“所有工具共享同一个目录”稳。