eo-skills

一套开发工作流 skill 集合，可装进任何支持 Agent Skills 约定的 agent（Claude Code / Codex / Antigravity 等）。以 change 工件为核心，配套可选的 codegraph 代码召回与 agent-handbook 项目操作手册，把从构思、变更、实施、测试、审查到归档的全流程拆成可独立调用的 skill，并支持跨 agent 协作。

从 v1 升级？破坏性变更与迁移步骤见 docs/migration-v1-to-v2.md。

想直接看每个 skill 的详细用法、典型流程、设计权衡？请看 docs/GUIDE.md。

担心流程的 token 开销？实测数据与 gstack / Anthropic 官方对标见 docs/token-budget-benchmark.md。

依赖

• skill 本体：无硬性运行时依赖——只要 agent 支持 Agent Skills 约定（读 ~/.agents/skills/ 及自身 skills 目录）即可装载，Claude Code / Codex / Antigravity 均在此列，装了哪个就用哪个。
• 终端 CLI（eo-helper / eo-board / eo-sync）：Python 3 标准库，零第三方依赖（macOS / Linux 自带 python3 即可）；POSIX-only，Windows 走 WSL。
• 安装器：npx skills add 需要 Node ≥ 18；无 Node 环境用 install.sh（仅需 git + POSIX sh）。

安装

方式一（推荐）——skills CLI（skills.sh 生态标准安装器）：自动检测本机已装的 agent，把 skill 装入跨 agent 标准位 ~/.agents/skills/，再在各 agent 的 skills 目录建软链：

npx skills add SimpleEve/eo-skills

方式二——install.sh（无需 Node；软链进本仓库的 clone，git pull 后所有 skill 立即生效）：

# 远程安装（自动 clone/update 到 ~/.eo-skills/repo）
curl -fsSL https://raw.githubusercontent.com/SimpleEve/eo-skills/main/install.sh | sh

# 或 clone 后安装
git clone https://github.com/SimpleEve/eo-skills.git ~/code/eo-skills
cd ~/code/eo-skills
sh install.sh

两种方式落到同一拓扑：skill 统一放在 ~/.agents/skills/，检测到的 agent 目录各建软链——

必须整套安装——各 skill 以 ../eo-shared/ 相对路径引用共享规范库，单独装某个 skill 目录会断链（skills CLI 与 install.sh 都会连 eo-shared 一起装）。目标已有同名条目时跳过、不覆盖。install.sh 还会把终端 CLI 链接进 ~/.local/bin（EO_BIN_DIR 可覆盖）。

Windows：install.bat 同拓扑（junction 链接）；终端 CLI 仍 POSIX-only，用 WSL 跑 install.sh 接线。

第一次使用

心智模型一句话：对话里干活（skill），终端里看板（CLI）。skill 在 agent 会话里喊；终端侧日常只需记一条命令——eo-helper（数字菜单直达看板与同步各入口），安装脚本已链接进 ~/.local/bin（POSIX-only，Windows 用 WSL）。

进入任意项目目录，在 Claude Code 里跑：

/eo-project-init

它会生成 .eo-project.json（项目级配置）+ 双侧最小骨架（代码侧 eo-doc/ + 项目管理侧）。所有其它 eo- skill 都依赖它*，没跑过会直接报错。

项目管理侧（roadmap / backlog / 决策 / 教训）放仓库内 .eo-project/，随仓库提交——协作者 clone 即得完整项目记忆。init 成功还会顺手把项目登记进 ~/.eo/projects.json（多项目看板靠它；失败不阻塞，稍后用 eo-helper 菜单「注册本项目」补上）。

协作场景：.eo-project.json 提交进仓库承载团队共享字段；机器相关字段（project_root / mode 等）放进不提交的 .eo-project.local.json 做顶层字段覆盖（协作者 clone 后重跑 /eo-project-init 自动引导生成）。

流程一图流

flowchart TD
    Init["/eo-project-init<br/>(必跑一次)"]:::entry --> Change
    Brain["/eo-brainstorming<br/>(可选：方向发散 + 拆首批 change)"] -.捕获出口.-> Change["/eo-change<br/>change.md 四问骨架"]
    Change --> Imp["/eo-implement<br/>按 Batch 写代码 + 自验勾 AC"]
    Imp --> Arch["/eo-archive<br/>四问核对门 + 更新活文档 + 冻结 change"]

    Change -.信号命中/点名.-> CR["/eo-change-review<br/>方案审查（可选闸门）"]:::gate
    CR -.P0.-> Change
    Imp -.信号命中/点名.-> Test["/eo-test<br/>独立测试（可选闸门）"]:::gate
    Imp -.信号命中/点名.-> Rev["/eo-review<br/>代码审查（可选闸门）"]:::gate
    Test -.失败.-> Fix2["/eo-fix 循环内分支"] -.修复.-> Test
    Rev -.P0/P1.-> Fix2 -.修复.-> Rev
    Test --> Arch
    Rev --> Arch

    Fix["/eo-fix<br/>bug 口喷入口：定位 + 直接修复"] -.需求变更.-> Change


    Init --> Doc["/eo-doc-manager<br/>维护 eo-doc/"]
    Init --> Rec["/eo-recall<br/>回忆：当时怎么设计的?"]
    Init --> PRec["/eo-project-record<br/>项目记忆：决策 + 教训"]

    Imp -.clear 前快照.-> Hand["/eo-handoff<br/>tmp/eo/handoff/&lt;topic&gt; .md"]:::cross

    classDef entry fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
    classDef cross fill:#dbeafe,stroke:#3b82f6,stroke-dasharray: 3 3
    classDef gate fill:#f3f4f6,stroke:#9ca3af,stroke-dasharray: 5 5

/eo-handoff 横切整个流程：clear 前在任意节点都可触发，把当前状态写到 tmp/eo/handoff/<topic>.md 供下个会话载入。图中仅以 implement 阶段示意。

v3 默认主路只有三站：change → implement → archive；change-review / test / review 是可选闸门——风险信号命中（不可逆操作 / 权限资金 / 外部契约 / 大影响面）或你点名时才挂，豁免一个词的事。样式微调、多语言这类 trivial 改动走直改模式（不开 change，判据见 eo-shared/granularity.md），改完常规 commit 即结算。

互不干扰的工作可并行：Batch 可标同层并行组（Batch 2a/2b）——由 /eo-loop 派发到隔离 worktree 并行推进；超标拆出的 change 序列标「依赖 #N」，按依赖序串行推进（判据、机械校验与合流 checkpoint 见 eo-shared/granularity.md §6）。

我该用哪个？

不在表里的 skill（eo-change-review）是可选闸门之一（方案审查，implement 之前），详见 GUIDE。

看板与同步

日常只需记一条命令：

eo-helper

数字菜单覆盖全部高频动作——全局实时看板、注册项目、同步看板卡片、看板自动跟手、全局终端速览。每次选数字会先回显将执行的底层命令再执行，用熟了自然过渡到原生命令。

最常用的几条原生命令速查：

eo-board --serve        # 全局实时 dashboard http://127.0.0.1:7333（3 秒热刷新）
eo-board                # 全局终端速览；单项目直达用 --project <名|路径>
eo-sync run             # 同步看板卡片 / GitHub issue·PR（幂等，跑几遍都无副作用）
eo-sync watch --all     # 常驻：所有注册项目状态一变自动追平（推荐挂一个终端）

全量参数（静态快照、注册表维护、扫描兜底、轮询间隔等深层旗标）见 docs/cli-reference.md。同步基本不用手动跑：/eo-archive 归档自动跑一次；平时挂「看板自动跟手」全自动（无变化时零成本静默）。同步目标在 .eo-project.json 的 sync 段配置（init 问答写好；老项目旧段自动等价映射，无需改）。

想接 Notion/飞书？同步是插件化的：PATH 上放一个 eo-sync-<name> 可执行 + 配置启用即可，协议见 docs/sync-adapter-protocol.md。

常见问题

• 看板卡片怎么不动了？ 状态流转期间不再实时写卡（设计如此：写路径不为呈现层付费）。挂「看板自动跟手」（eo-helper 菜单 4）即秒级跟手；或随时同步一次（菜单 3）；归档时总会自动同步。
• 看板卡片删错了？ 卡片是派生数据，eo-sync run 随时全量重建；孤儿清理只在快照可证完整时执行，扫描异常一律保守跳过。
• 协作时配置里全是别人的路径？ 重跑 /eo-project-init，机器相关字段会写进你自己的 .eo-project.local.json（不提交）。
• 老项目的 project_root 写成了相对路径？ v1 配置常写软链相对路径——现在会自动按 repo root 解析并解软链，照常可用，只是每次多一行告警；重跑 /eo-project-init 即回写绝对路径消除告警。解析不到目录时仍会报错（不猜路径）。
• 删了工具会丢数据吗？ 不会。一切真相都在 markdown 文件里，CLI 只写派生卡片/注册表（~/.eo/ 下）。

两种 review 别混用

信号清单见 eo-shared/granularity.md §5。

License

MIT