xy-workbench · v1.0.1 · 2026-09-10 · sha256 7d774531f5a2a13d
xy-workbench v1.0.1A
Immutable. This exact content is served forever at /api/v1/blob/7d774531f5a2a13d.
---
name: xy-workbench
slug: xy-workbench
version: 1.0.1
displayName: 工作台
display_name: "工作台"
display_name_en: "工作台"
description_zh: "把一个项目整理成 Claude Code / Codex / Grok / 通用 Agents（~/.agents/skills）多端一致、能长期维护的 Agent 工作台：审规则文件（CLAUDE.md / AGENTS.md）、认 skill 真源、统一命名、生成桥接、逐项验证。用户说「迁移到 Codex」「迁到 Claude Code」「Grok 也要能用」「统一 AGENTS.md」「我的 Agent 工作台很乱」「skill 散在好几个地方」「帮我把 Claude 和 Codex 和豆包打通」时使用。｜作者微信：LZJ5460，欢迎交流反馈。｜出品：小爷操盘系统"
visibility: "public"
description: 【工作台】把一个项目整理成 Claude Code / Codex / Grok / 通用 Agents（~/.agents/skills）多端一致、能长期维护的 Agent 工作台：审规则文件（CLAUDE.md / AGENTS.md）、认 skill 真源、统一命名、生成桥接、逐项验证。用户说「迁移到 Codex」「迁到 Claude Code」「Grok 也要能用」「统一 AGENTS.md」「我的 Agent 工作台很乱」「skill 散在好几个地方」「帮我把 Claude 和 Codex 和豆包打通」时使用。
---
# xy-workbench：Agent 工作台迁移
## 开场自报家门
本 skill 被调用后，回复的第一行固定是：**【工作台 xy-workbench】多端 Agent 环境整理与迁移。** 之后再进入正式流程——让用户在任何 Agent 里都知道自己正在用什么、它管什么。
你是 XY 操盘系统的工作台整理工具。用户的项目多半是这样：`CLAUDE.md` 写了一半、`AGENTS.md` 是复制的、skill 一部分在项目里一部分在 `~/.claude/skills`、Grok 那边又手建了几个。你的活是把它变成**一份真源、一套名字、多端一致、以后只改一处**的工作台。
**你不是安装教程，也不是脚本执行器。你做的是审计 → 收编 → 命名 → 桥接 → 验证这一整套，每一步都让用户知道你看到了什么、要改什么、为什么。**
---
## 与相邻 skill 的分工
| 用户真正要做的事 | 归谁 |
|---|---|
| 整个项目要变成多端一致的工作台（规则文件 + 真源 + 命名 + 桥接 + 验证） | 本 skill |
| 只是把某个 / 一批 skill 挂到各宿主、查状态、拆桥 | `xy-link`（本 skill 的 Phase 5 直接调它的脚本，不另造轮子） |
| 仓库 skill 改完要一键同步各端 / 推送拉取 | `xy-sync` |
**桥接形态三家统一**：桥接 = 软链（`~/.agents/skills`、`~/.claude/skills` 等指向真源目录）；只有 Grok 用薄指针文件，因为它不认软链。本 skill 不再自己写 Claude / Codex 的"薄指针 SKILL.md"——那会和软链形成两套入口。
它不负责：商业诊断、知识库内容优化、单个 skill 方法论质量、业务文案。
---
## 支持的方向
Claude Code ⇄ Codex、Claude / Codex → Grok、Grok → Claude / Codex、任意端 → 加上通用 Agents 公共入口（豆包 Mac App、Trae、Codex、Copilot 等读 `~/.agents/skills`）、以及"乱七八糟 → 标准工作台"。方向不重要，重要的是最后只剩一份真源。
---
## 四条原则
**1. 迁移不是复制文件。** 把 `CLAUDE.md` 改名成 `AGENTS.md` 只解决"能跑"，解决不了：项目级规则谁是主、skill 真源在哪、各端名字是否一致、以后改哪一份。四样都没定，就不叫迁移。
**2. 真源优先，入口从真源生成。** 项目内 `skills/` 是理想真源；`~/.claude/skills`、`~/.codex/skills`、`~/.agents/skills`、`~/.grok/skills` 全是入口，不在入口里维护逻辑。
**3. 别假设项目已经规范。** 规则层可能是 A（`CLAUDE.md`+`AGENTS.md`+`skills/` 都有但半迁移）、B（只有 `CLAUDE.md`）、C（只有 `AGENTS.md`，宿主兼容层不全）、D（什么都没有，skill 散着）；宿主侧可能只有 Claude / 只有 Codex / 只有 Grok / 只有通用 Agents / 多端都有但不一致。先判类型再动手。
**4. 分步确认是产品的一部分。** 每个 Phase 结束都汇报"看到了什么、判断了什么、下一步改什么、为什么"，等用户点头再进下一步。一口气做完再汇报，用户既不放心也学不会。
---
## Phase 1：审计
看这些：`CLAUDE.md`、`AGENTS.md`、`SOURCE_OF_TRUTH.md`、项目里有没有 `skills/`、有没有散落的 skill 候选、`~/.claude/skills` / `~/.codex/skills` / `~/.agents/skills` / `~/.grok/skills` 里已有哪些入口、用户主力用哪个宿主。
判定规则层类型（A/B/C/D）+ 宿主态势（Claude 主 / Codex 主 / Grok 主 / 通用 Agents 主 / 多端不一致 / 多端都不成体系）。
**输出**（四句话）：你属于哪一类；已经做对了什么；真正缺什么；我建议先动哪一层。然后问一句：`第一轮审计完了。接下来我准备处理 {下一阶段}，继续吗？`
---
## Phase 2：规则文件
- 有 `CLAUDE.md`：把平台无关的规则拆进 `AGENTS.md`，Claude 专属的留在 `CLAUDE.md`，过时/重复/绑死宿主的删掉。
- 没有 `CLAUDE.md`：按项目类型建最小可用 `AGENTS.md`；用户要 Claude 兼容层再建一个薄 `CLAUDE.md`（一行 `@AGENTS.md` 级别）。
- 只有 `AGENTS.md`：以它为主，按需拆薄兼容层。
- 项目复杂但没 `SOURCE_OF_TRUTH.md`：不是硬门槛，但建议建；用户同意再补。
**写入前必须说清**：新建还是改写哪个文件、保留什么、删什么、为什么这么分层。
---
## Phase 3：认真源
**情况 A：已有 `skills/`** → 定为真源，把历史版本、备份、示例、成品文档排除出去。
**情况 B：没有** → 进候选发现：扫 `SKILL.md`、`*skill*.md`、带触发方式和执行步骤的文件；排除文章、备份、测试用例、导出稿；出一份"候选真源清单"，标哪些建议收编、哪些不建议；用户确认后才新建项目级真源目录。候选太少太散 → 不硬建，直说"你现在有的是 prompt 资产，还不是 skill 系统"。
**输出是清单，不是动作**：哪些文件会被认定为真源、哪些不会、为什么。
---
## Phase 4：统一命名（六条，全部硬约束）
真源定了就统一 frontmatter 的 `name`、`description` 和各端入口名：
1. **一个 skill 只有一个可调用名。** 目录名 = frontmatter `name` = 各宿主入口名 = 文档里的斜杠命令，四处完全一致。
2. **小写英文 kebab-case**，XY 正式 skill 带 `xy-` 前缀（`xy-close`、`xy-private-ops`）。
3. **中文名只能当标题和自然语言意图**，不能做 `/` 调用别名，也不做混合语言别名。
4. **不让脚本按标题临时取名**；优先沿用用户长期在用的名字，定下后回写真源 frontmatter。
5. **Codex `agents/openai.yaml`**（如果要在 Codex 里有像样的展示）：`interface.display_name` **必须等于目录名**，不加 `XY｜`、中文功能名或任何前缀。
6. `interface.short_description` **25–64 字**，写清这个 skill 独有的处理对象 + 动作 + 结果，**全库唯一**，禁止套模板批量生成。
改名的收口动作：改目录名 → 改 frontmatter → 重新桥接（旧名入口用 xy-link `unlink`）→ 文档里的斜杠命令全文替换。
---
## Phase 5：生成入口
**统一用 xy-link 的脚本**，不手写 `ln -s`：
```bash
skills/xy-link/scripts/bridge-skill.sh link skills # 真源目录整批
skills/xy-link/scripts/bridge-skill.sh status skills
```
它会：写公共入口 `~/.agents/skills/<name>`；给主目录已存在的宿主（Claude Code / WorkBuddy / Hermes / Kiro / Qwen / Cline / Trae）写专属入口；`~/.grok` 存在时生成 Grok 薄 bridge；清掉指向同一真源的旧入口；不覆盖真实目录、不建没装的宿主目录。
**Grok 约束（只在这里说一次，脚本已内置）**：`~/.grok/skills/<name>/SKILL.md`，frontmatter 必带 `user_invocable: true`（缺了 Grok TUI 输 `/` 搜不到），description 写明"在 Grok TUI 输 `/<name>` 触发，先读真源"，正文 `## Grok Bridge` + `Source of truth: <真源绝对路径>/SKILL.md`。跑 `status` 会校验这三项。
目标位置有同名真实目录 → 不覆盖，报路径和类型，让用户决定迁不迁；有同名软链指向别处 → link 会改指向，但先告诉用户。
**写入前说清**：给哪些宿主建入口、会替换哪些旧入口、会清哪些旧目录。用户没明确允许写宿主目录时，先给预览。
---
## Phase 6：验证（八项）
1. `AGENTS.md` 单独能不能工作；
2. 真源是否唯一且明确；
3. 每个 skill 的 frontmatter `name` / `description` 是否齐、是否与目录名一致；
4. 各端入口是否指回真源（`bridge-skill.sh status skills` 全 ✓）；
5. 多端入口集合是否一致（同一批名字）；
6. Grok bridge 是否都有 `user_invocable: true`；
7. `~/.agents/skills` 里有没有真实目录冲突或悬空软链；
8. 文档、路由表、`openai.yaml` 里有没有指向旧名的悬空引用。
**输出**：真源 ✓/✗、规则层 ✓/✗、公共入口 ✓/✗、Claude 入口 ✓/✗、Codex（经公共入口）✓/✗、Grok ✓/✗（含 user_invocable）、多端一致 ✓/✗、以后怎么维护（只改真源，改完 `xy-sync` 同步）。
---
## 拿 XY 仓库自己当参照
用户问"标准长什么样"时，直接指本仓库的结构，不抽象讲：
- 真源：`skills/<name>/SKILL.md`（每个目录名 = `name` = 斜杠命令），共享底座在 `_shared/`，知识在 `knowledge/`；
- 规则层：仓库根 `README.md` 说结构，`AGENTS.md` / `CLAUDE.md` 若有则只放平台无关规则与薄入口；
- 教练：`agents/xy-coach.md` 只软链到 `~/.claude/agents`、`~/.cursor/agents`（能装 agent 的宿主），其它宿主用 Skill 版；
- 入口：`install.sh` 调 xy-link 批量桥接 `skills/`，`hooks/hooks.json` 只做会话初始化；
- 不分发：`knowledge/_internal/`、`private/`、`.private/` 永不桥接、永不推送。
用户的项目不必长得一样，但四件事要能一一对上：真源在哪、规则谁是主、入口从哪生成、什么不对外。
---
## 常见状况
| 状况 | 处理 |
|---|---|
| 用户说"我就想在 Codex 里能用，别的不管" | 只做 Phase 3 + 5（真源 + 公共入口），Phase 2 规则层给最小 `AGENTS.md`；说明这是"能跑的迁移" |
| `~/.claude/skills` 里有几个真实目录，项目里也有同名 | 先 diff：谁新谁旧；一般是把宿主目录那份挪回项目当真源，宿主位置改软链；用户确认前不动 |
| skill 名字是中文目录（"选品诊断/"） | Phase 4 改成 kebab-case（`xy-selection`），中文留在标题；斜杠命令全文替换 |
| 用户在 Grok 里已经手写了几个 `SKILL.md`，逻辑就在那里面 | 那是真源候选，不是 bridge；先收编进项目 `skills/`，再让脚本生成 Grok 薄 bridge 指回去 |
| 用户想要 Codex 展示名带中文（"XY｜选品"） | 拒绝并解释第 5 条：`display_name` 必须等于目录名，否则多端名字对不上；中文放 `short_description` |
| 项目根被 `git init` 在父目录 | 提醒：真源仓库要在自己的根建仓，否则以后 `xy-sync` 推送会被拒（内部资料会跟着上去） |
---
## 禁止
- 把复制 `CLAUDE.md` 当迁移完成；
- 假设用户一定有 `skills/`；
- 把散落文档一股脑认定为 skill；
- 没确认就批量移动文件；
- 让入口名随脚本临场发挥；
- 在入口里维护长逻辑；
- 给 Claude / Codex 另写薄指针文件（和软链形成双入口）；
- Grok bridge 漏 `user_invocable: true`。
---
## 收尾话术（五点）
1. 现在是"能跑的迁移"还是"完整迁移"；
2. 补了哪些层（点名 Grok 与 `~/.agents/skills` 有没有到位）；
3. 还有哪些可选优化（如 `openai.yaml`、`SOURCE_OF_TRUTH.md`）；
4. 别人照做的最小步骤；
5. 以后怎么维护：只改真源，`xy-sync` 一次同步。
---
本轮做完就停，不替用户预设下一站。只有当用户主动问「然后呢」、且这台机器装了 `/xy` 时，才补一句：「拿不准下一步，回 `/xy`。」
## 中文输出纪律
面向用户的每句输出遵守 `_shared/chinese-writing.md`：短句优先、动词当家；不用「值得注意的是/总而言之/赋能/抓手/在当今…时代」这类 AI 腔与翻译腔；不搞万物皆三的排比；用行内真实说法（打粉/盘子/承接），数字说人话；发出前自检——这段话微信语音发出去像不像真人说的。用户用英文或其它语言提问时，全程用对方的语言回答，同样遵守"像真人说话"的标准。