Skip to content

GUIDE.md

Latest commit

 

History

History
258 lines (187 loc) · 8.69 KB

GUIDE.md

File metadata and controls

258 lines (187 loc) · 8.69 KB
Raw

cc-skills 完整使用指南

本文档说明如何搭建和使用这套多 agent skills 集中管理方案。目标是让任何人照着步骤就能跑起来：一个中央仓库作为唯一真源，Claude Code / Codex / Hermes 通过同步或软链读取同一份 skills。

1. 核心概念

  • 唯一真源：所有 skill 都存放在 ~/Documents/Projects/cc-skills/skills/，创建和修改只发生在这里。
  • 全局分发：~/.claude/skills 用 rsync 同步，~/.codex/skills 用软链，~/.hermes/skills/custom 用 rsync 同步。
  • 项目分发：projects.json 登记项目，每个项目只同步自己需要的 skill 到 <项目路径>/.claude/skills。
  • 统一创建：create-skill 本身也是一个 skill，在任何 agent 中触发，生成目录后自动运行同步。
  • 可回滚：首次搭建前会备份全部受影响路径，restore.ts 可一键恢复到搭建前状态。

2. 目录结构

~/Documents/Projects/cc-skills/
├── skills/                      # 全部 skill 真源
│   ├── create-skill/            # 统一创建入口
│   │   ├── SKILL.md
│   │   ├── reference.md
│   │   └── examples/
│   ├── <your-skill>/            # 每个 skill 一个目录
│   │   ├── SKILL.md
│   │   ├── reference.md         # 可选，大内容放这里
│   │   ├── scripts/             # 可选，辅助脚本
│   │   └── tests/               # 可选
│   └── ...
├── projects.json                # 项目登记表
├── scripts/
│   ├── sync.ts                  # 分发脚本
│   └── restore.ts               # 回滚脚本
├── GUIDE.md                     # 本文档
└── README.md                    # 快速入口

3. 前置要求

  • macOS（Hermes 相关步骤仅本机验证过；Claude Code 和 Codex 的路径在 macOS / Linux 通用）
  • git
  • node >= 22（脚本使用 --experimental-strip-types 直接运行 TypeScript）
  • rsync
  • 已安装的 agent：Claude Code、Codex、Hermes（按需）

4. 首次搭建

4.1 创建仓库

mkdir -p ~/Documents/Projects/cc-skills
cd ~/Documents/Projects/cc-skills
git init -b main

按第 2 节结构创建目录，并把已有 skill 复制进 skills/。本仓库自带 create-skill，可复制一份作为脚手架：

mkdir -p skills/create-skill

4.2 迁移现有 skill（重要：先备份）

把所有会被改动的路径完整备份到一个独立目录，例如 ~/.cc-skills-rollback/：

mkdir -p ~/.cc-skills-rollback
cp -R ~/.codex/skills/<skill-a> ~/.cc-skills-rollback/codex-<skill-a>
cp -R ~/.claude/skills ~/.cc-skills-rollback/claude-skills

备份后再把原目录复制进仓库真源，并把 SKILL.md 中的硬编码路径（例如 /Users/xxx/.codex/skills/...）改成相对路径。

4.3 登记项目（可选）

编辑 projects.json：

{
  "projects": [
    {
      "path": "/path/to/your/project",
      "skills": ["macos-ocr"]
    }
  ]
}

skills 列表为空时表示该项目的 .claude/skills 为空（仍会被 --delete 清空）。

4.4 首次同步

先预览，再实际执行：

cd ~/Documents/Projects/cc-skills
node --experimental-strip-types scripts/sync.ts --dry-run
node --experimental-strip-types scripts/sync.ts

首次同步前，如果 ~/.codex/skills 下已有同名真目录，需要先备份并替换为软链（脚本对非软链目录会跳过而不是覆盖）：

rm -rf ~/.codex/skills/<skill-a>   # 已备份后再删
ln -s ~/Documents/Projects/cc-skills/skills/<skill-a> ~/.codex/skills/<skill-a>

4.5 验证

ls -la ~/.codex/skills             # 应看到指向仓库的软链
ls ~/.claude/skills                # 应看到同步出来的 skill
find ~/.hermes/skills/custom -maxdepth 1 -type d

重启 agent 会话后，确认对应 skill 能被发现。

5. 日常使用

5.1 新建 skill（推荐）

在任意 agent 中触发 create-skill：

  • Claude Code：/create-skill global my-skill 描述 或 /create-skill project my-skill 描述
  • Codex / Hermes：直接说“用 create-skill 建一个 my-skill”

create-skill 会自动：

  1. 在 skills/<name>/ 生成 SKILL.md（统一模板）
  2. project 模式：把当前项目登记进 projects.json
  3. 运行同步脚本
  4. 提示测试

5.2 手动新建

cd ~/Documents/Projects/cc-skills
mkdir -p skills/my-skill/scripts skills/my-skill/references

用 skills/create-skill/examples/skill-template.md 作为模板写 SKILL.md，然后运行同步。

5.3 修改 skill

只改 ~/Documents/Projects/cc-skills/skills/<name>/ 下的文件，然后：

node --experimental-strip-types ~/Documents/Projects/cc-skills/scripts/sync.ts

5.4 删除 skill

cd ~/Documents/Projects/cc-skills
rm -rf skills/<name>              # 建议先 git rm 保留历史
node --experimental-strip-types scripts/sync.ts

--delete 会同步删除 ~/.claude/skills、Hermes custom 和项目里的同名 skill；Codex 侧的过期软链也会被 sync.ts 清理。

6. sync.ts 参数

在仓库根目录运行：

node --experimental-strip-types scripts/sync.ts
node --experimental-strip-types scripts/sync.ts --target global
node --experimental-strip-types scripts/sync.ts --target project
node --experimental-strip-types scripts/sync.ts --target claude
node --experimental-strip-types scripts/sync.ts --target hermes
node --experimental-strip-types scripts/sync.ts --target codex
node --experimental-strip-types scripts/sync.ts --only macos-ocr,hatch-pet
node --experimental-strip-types scripts/sync.ts --dry-run

说明：

  • 默认 --target all：同步全局（Claude + Hermes + Codex 软链）和所有登记项目
  • --only a,b：只同步指定 skill
  • --dry-run：只打印将执行的命令，不实际修改
  • --target claude|hermes|codex：只处理单个全局目标

7. SKILL.md 规范

统一模板见 skills/create-skill/examples/skill-template.md，关键字段：

---
name: my-skill
description: What it does + when to use + the words a user would naturally say
when_to_use: trigger phrases
disable-model-invocation: true    # task 型必加；reference 型不加
argument-hint: '[args]'
version: 1.0.0
author: your-name
license: MIT
metadata:
  hermes:
    tags: [tag1, tag2]
    related_skills: []
---

规则：

  • description 是唯一必需字段，决定自动触发，写清“做什么 + 何时用 + 用户会怎么说”
  • task 型（有副作用的操作）加 disable-model-invocation: true，只允许显式调用
  • reference 型（规范、知识、风格指南）不加，允许模型自动触发
  • 正文控制在 500 行以内，大内容放 reference.md，按需加载
  • 脚本一律用相对路径（如 scripts/foo.sh），不要写死 agent 目录
  • Hermes 字段（version、author、license、metadata.hermes）用于兼容校验

8. 回滚

首次搭建前的备份在 ~/.cc-skills-rollback/，其中 manifest.json 记录每个受影响路径与备份位置。一键恢复：

node --experimental-strip-types ~/Documents/Projects/cc-skills/scripts/restore.ts

恢复动作：

  • 删除 ~/.codex/skills/<name> 软链，从备份复制回原目录
  • 从备份恢复 ~/.claude/skills
  • 删除 ~/.hermes/skills/custom
  • 按清单恢复或删除各项目 .claude/skills

恢复完成后重启 agent 会话。中央仓库和备份目录可自行保留或删除。

9. 边界与注意事项

  • ~/.codex/skills/.system/ 属于 Codex 系统自带，绝不删除或覆盖
  • ~/.hermes/skills/ 内置分类（如 apple/、creative/）由 Hermes 自管，只使用 custom/ 分类
  • ~/.agents/skills 不在本方案范围内，不创建、不删除
  • ~/.claude/skills 完全由仓库管理，直接在里面手动新建的 skill 会被下次 --delete 清掉
  • 远程机器同步暂不支持；如需部署到远程，可自行扩展 sync.ts 的 SSH 目标
  • 修改仓库后记得提交 git，保留历史：
git add -A
git commit -m "update skills"

10. 常见问题

Q: 运行 sync 时提示某个 Codex skill 存在且不是软链怎么办？

A: 说明该目录是旧的独立副本。先备份再替换成软链，或删掉后重新运行 sync。

Q: Hermes 加载 custom skill 失败？

A: 检查 SKILL.md 是否满足 Hermes 校验：name、description 必需，建议补齐 version、author、license、metadata.hermes。

Q: --dry-run 后没看到任何输出？

A: 说明源和目标一致；也可以直接执行同步确认。

Q: 新建的 skill 没出现在某个 agent 里？

A: 确认跑过 sync.ts，然后重启该 agent 的会话。