一键同步Cursor、ClaudeCode、Opencode、Gemini、Codex等各种配置，涵盖Skill、Command、Rule、Hook

拒绝 AI “抽奖式”编程！我构建了一套零幻觉 SOP (Skills+MCP)，并开源 CLI 一键同步Claude、Cursor、Gemini、Codex...

2024 年开始，随着 Cursor 的火爆，ChatGPT、Claude、Gemini 都推出了自家的 AI CLI

那种勃勃生机、万物竞发的景象，犹在眼前。

随着各家 AI CLI 的快速迭代，每个工具都有其独特的配置系统

Commands
Skills
Rules
MCP
Agents
Hooks

这些配置虽然格式相似（大多基于 Markdown 和 JSON），但目录结构、文件格式和转换逻辑却各不相同。

比如 Gemini、IFlow、Codex 是 TOML 格式，Cursor、Claude Code、CodeBuddy、OpenCode 是 JSON 格式。

当我想在不同工具间切换时，面临着一个尴尬的现实：我需要手动复制粘贴、修改格式、调整路径，耗时且容易出错。

特别是 Commands 的参数语法（$ARGUMENTS vs {{args}}）、MCP 的配置格式（JSON vs TOML vs JSONC）、以及不同工具对环境变量的处理方式都存在细微差异。

这正是我开发 ai-sync 的初衷——一个能够自动化处理这些格式转换和路径解析的工具，让我可以在不同 AI CLI 之间无缝迁移配置，专注于代码本身而不是配置文件。

快速上手

源码：github.com/beixiyo/ai-…

安装

npm i -g @jl-org/ai-sync

使用交互式执行，只需要一行命令即可同步配置到不同工具：

$ ai-sync

? 选择要迁移到的工具（使用方向键导航，空格选择，回车确认）：
 ◯  Cursor
 ⬤  Claude Code
 ⬤  OpenCode
 ◯  Gemini CLI
 ◯  IFlow CLI
 ◯  Codex
 ◯  CodeBuddy

? 配置到当前项目（否则为全局配置）？ (y/N) n
? 是否自动覆盖已存在的文件？ (y/N) y

开始迁移...
✓ 迁移 Commands... (2/2)
✓ 迁移 Skills... (1/1)
✓ 迁移 Rules... (1/1)
✓ 迁移 MCP... (1/1)
✓ 迁移 Agents... (1/1)

--- 迁移完成 ---
工具: Claude Code, OpenCode
成功: 15
跳过: 3
错误: 0

开发历程

整个工具都是 AI 驱动开发的，尤其是文档、测试等，我将着重教大家如何使用这些 AI 工具。

尤其是 Commands、Skills、Hooks、Agents、MCP 这些配置的意思，让大家不会一头雾水。

核心技术名词解释

Rules（规则）

定义给 AI 的内置提示词，相当于给 AI 设定的"系统指令"或"行为准则"。

作用：定义 AI 在代码生成、重构、调试等场景下的行为规范
格式：通常是 Markdown 文件，包含项目特定的编码规范、架构原则、命名约定等
文件名：不同工具使用不同的文件名，但通用的是 AGENTS.md（项目级别）
- Claude Code: CLAUDE.md
- Gemini CLI: GEMINI.md
- CodeBuddy: CODEBUDDY.md
特点：全局生效，AI 在所有对话中都会参考这些规则

示例：

# 项目编码规范

- 样式优先使用 TailwindCSS

Commands（命令）

与 Rules 基本一致，但支持交互式调用和参数传递。通过在输入框输入 / 唤起命令，可以传递参数并接收结果。

作用：封装常用的开发任务为可复用的命令
格式：Markdown 文件，支持参数占位符（如 $ARGUMENTS、$1）
特点：按需调用，可以传递参数，支持执行 shell 命令

示例：

---
description: 创建新的 React 组件
---

创建一个名为 `$1` 的 React 组件，包含以下功能：
- 使用 TypeScript
- 支持 className 和 style 属性
- 导出为具名导出

组件路径：`src/components/$1/index.tsx`

Skills（技能）

标准化流程（SOP）或领域知识教学，教 AI 理解某个领域的知识，让它按照步骤执行任务，还可以包含脚本引用。

作用：
- 定义标准化流程（SOP），让 AI 按照既定步骤执行任务
- 教授 AI 某个领域的专业知识（如 Excel 处理、PDF 操作等）
- 支持脚本引用，可以调用外部工具或命令
格式：Markdown 文件，包含元数据（metadata）字段（如 description、name）
特点：支持自动检测场景，AI 可以主动推荐合适的技能
常见技能示例：excel-skill、pdf-skill、code-review-skill 等

示例：

---
description: Excel 文件处理技能包
name: Excel Processing
---

## Excel 文件读取
使用以下步骤读取 Excel 文件：
1. 检查文件格式（.xlsx, .xls）
2. 使用 pandas 读取数据
3. 验证数据完整性

## Excel 数据处理
[数据处理的详细步骤...]

Skills 最佳实践

1. 元数据与描述

检查项	要求
name	≤64 字符，小写/数字/连字符
description	非空、≤1024 字符
第三人称	描述用第三人称
WHAT + WHEN	写清「做什么」和「何时用」
触发词	具体、可被匹配

描述需满足「具体 + 触发词 + WHAT/WHEN」的要求。

2. 结构与篇幅

检查项	要求
SKILL.md 行数	建议 <500 行，通过 references 文件夹引用其他文件来实现渐进式披露
渐进式披露	主文件放要点，细节放引用 references 文件夹，脚本放在 scripts 文件夹
引用层级	仅一层引用
术语一致	全文统一用语

Hooks（钩子）

在 AI 执行的不同时间点自动执行操作，类似于 Git hooks 或 Web 框架的生命周期钩子。

作用：在 AI 执行特定操作时自动触发预设的动作
常见场景：
- 文件编辑后：自动执行 ESLint 修复、格式化代码
- 代码生成后：自动运行测试、构建检查
- 命令执行前：验证环境、检查依赖
格式：通常在配置文件中定义（如 settings.json），指定触发时机和执行的命令
特点：自动化工作流，减少手动操作，确保代码质量

Cursor Hooks 示例：

{
  "version": 1,
  "hooks": {
    "afterFileEdit": [
      {
        "command": "bash ..."
      }
    ]
  }
}

Agents（代理）

不占用主上下文的子代理，专注于执行特定任务，然后将结果返回给主代理。

作用：
- 将复杂任务分解为子任务，由专门的 Agent 处理
- 避免占用主 Agent 的上下文，提高效率
- 专注于特定领域（如代码搜索、文档编写、测试生成等）
特点：
- Sub Agent：作为子代理运行，不占用主上下文
- 专注性：每个 Agent 专注于特定任务类型
- 结果返回：执行完成后将结果返回给主 Agent
常见示例：
- search-code agent：Claude Code 内置，专门用于代码搜索
格式：Markdown 文件，包含 Agent 的配置和指令

示例：

---
description: 代码搜索 Agent
mode: subagent
... 其他元数据，比如权限等，各家配置不同
---

你是一个代码搜索专家，专注于在代码库中查找相关代码片段

MCP（Model Context Protocol）

模型上下文协议，本质上是调用本地 stdio 进程或远程接口，但初始会加载所有工具描述，非常浪费 Token。

作用：扩展 AI 的能力，允许调用外部工具和服务
格式：JSON 配置，定义 MCP 服务器的连接信息
特点：
- Local MCP：通过 stdio 与本地进程通信
- Remote MCP：通过 HTTP 调用远程 API
- Token 消耗：启动时会加载所有工具的描述、入参、出参，随着 MCP 数量增加，Token 消耗呈指数级增长
趋势：本地 stdio MCP 逐渐被 CLI、Skills 替代，因为后者更轻量、更高效

示例：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

术语对比

术语	本质	参数支持	自动调用	Token 消耗	适用场景
Rules	内置提示词	--	✅	低	全局规范、项目约定
Commands	可调用提示词	✅	❌	无	常用任务、重复操作
Skills	SOP/领域知识	❌	✅	低	标准化流程、特定领域技能、脚本引用
Hooks	生命周期钩子	--	✅	无	自动化工作流、代码质量保证、关键记录...
Agents	子代理	--	✅	低	任务分解、专注执行、结果返回
MCP	外部工具调用	✅	✅	高	扩展能力、复杂操作、通常实现本地无法实现的复杂功能

开发前准备：从零到一的数据源抓取

以下面这些工具为例，查询它们的配置文档：

OpenCode: opencode.ai/docs/
Claude Code: code.claude.com/docs/zh-CN/…
Gemini CLI: geminicli.com/docs/get-st…
Codex: developers.openai.com/codex/

但是都用 AI 了，我还自己查吗？这不是太麻烦了吗？

所以有两种选择：

使用工具自带的 Web Search 功能
打开浏览器查询

来比较一下这两种方式的优缺点：

使用工具自带的 Web Search 功能
- 优点：方便快捷，不需要打开浏览器
- 缺点：数据源是接口厂商的，你无法保证更新及时性，并且一般不会很全
打开浏览器查询
- 优点：可以精准查询到最新的配置文档
- 缺点：需要打开浏览器，消耗大量的 Token 和计算机资源

为了确保查询的文档准确，所以我选择了第二种方式，打开浏览器查询。

对比 AI 使用浏览器的方案

MCP，比如 Playwright-MCP、Chrome-MCP、Firefox-MCP

优点：方便、简单，直接 npm 安装即可配置完成
缺点：MCP 占用大量 Token，加载时需要读取所有工具描述，随着 MCP 数量增加，Token 消耗呈指数级增长。并且大多数情况下效果不好，它根本不太能理解哪些内容可以交互（比如点击按钮等进入其他页面），所以很难精确地查询所有正确的内容。

CLI 命令行工具，比如 agent-browser

优点：经过特殊处理的返回结果，节省很多 Token
缺点：配置较为麻烦，尤其是 Linux，需要下载很多依赖，而且不支持 Windows

agent-browser 使用方式

agent-browser 是 Vercel Labs 开源的、面向 AI Agent 的无头浏览器自动化 CLI，采用 Rust CLI + Node 守护进程架构，默认使用 Chromium。

NOTE: Windows 不可用，想用只能先用 WSL 安装 Linux

安装

npm install -g agent-browser
agent-browser install   # 下载 Chromium

Linux 需安装系统依赖时：agent-browser install --with-deps（或 npx playwright install-deps chromium）。

推荐工作流（Snapshot + Ref）

打开页面并获取可访问性树（带元素引用 ref）：

agent-browser open example.com
agent-browser snapshot -i        # -i 仅交互元素，减少输出

输出中会得到类似 button "Submit" [ref=e2]、textbox "Email" [ref=e3] 的 ref，用 @e2、@e3 操作：
```
agent-browser click @e2
agent-browser fill @e3 "test@example.com"
agent-browser get text @e1
```
页面变化后再次 snapshot，用新 ref 继续操作。

Ref 方式对 AI 友好：确定性、无需重新查 DOM，且 snapshot 输出紧凑，利于节省 Token。

常用命令速览

类型	命令示例
导航	`agent-browser open <url>`、`back`、`forward`、`reload`
快照	`agent-browser snapshot`（可选 `-i`、`-c`、`-d 深度`、`-s "#selector"`）
点击/输入	`click @e2`、`fill @e3 "文本"`、`type`、`press Enter`
查询	`get text @e1`、`get url`、`get title`
等待	`wait 2000`、`wait --text "Welcome"`、`wait <selector>`
截图/PDF	`screenshot [path]`、`screenshot --full`、`pdf <path>`
多会话	`--session name` 或 `AGENT_BROWSER_SESSION=name`
持久配置	`--profile ~/.my-profile` 持久化 cookies/登录态
Agent 输出	加 `--json` 得到机器可读结果，便于 AI 解析

与 AI 协作时

先 open → snapshot -i --json，让 AI 解析树和 ref；
再用 click @ex、fill @ex "..." 等按 ref 执行；
需要判断状态时用 is visible @ex、is enabled @ex 等。

更多命令与选项见官方文档：agent-browser.dev 或 GitHub README。

使用 agent-browser CLI 查询文档

来看看示例：

我把链接发送给他，让他自己查询文档总结给我
他自己能点击页面查看更多内容，比如图中的 click @e52

验证文档正确性

重要提醒：AI 提供的内容不可完全信赖。 在收集到各工具的配置规则后，我逐一访问官方网站进行了验证。以下是我整理的核心配置规则文档。

各工具 Commands 配置对比：

特性	Gemini CLI	Cursor	Claude Code	CodeBuddy	OpenCode	Codex CLI
文件格式	TOML	Markdown	Markdown	Markdown	Markdown / JSON	TOML / YAML
项目位置	`.gemini/commands/`	`.cursor/commands/`	`.claude/commands/`	`.codebuddy/commands/`	`.opencode/commands/`	`.codex/prompts/`
全局位置	`~/.gemini/commands`	`~/.cursor/commands/`	`~/.claude/commands/`	`~/.codebuddy/commands/`	`~/.config/opencode/commands/`	`~/.codex/prompts/`
参数语法	`{{args}}`	无特殊语法	`$ARGUMENTS`, `$1`, `$2`	`$ARGUMENTS`, `$1`, `$2`	`$ARGUMENTS`, `$1`, `$2`	`$ARGUMENTS`, `$1`, `$2`, 命名参数
Shell执行	`!{command}`	不支持	`!`command`` (需声明 allowed-tools)	`!`command`` (需声明 allowed-tools)	`!`command`` (无需声明)	配置文件白名单
文件引用	`@{filepath}`	不支持	`@filename`	`@filename`	`@filename`	`@filename`

各工具 Skills 配置对比：

Claude Code 的 Skills 存储在 .claude/skills/<skill_name>/SKILL.md，支持 YAML frontmatter 配置名称、描述、可用的工具列表、运行模型等。

OpenCode 兼容 Claude Code 的 Skills 格式，存储在 .opencode/skills/<name>/SKILL.md 和 ~/.config/opencode/skills/<name>/SKILL.md。

各工具 Rules 配置对比：

Cursor 使用 MDC（Markdown Components）格式，存储在 .cursor/rules/ 目录下的多个文件中。

Claude Code 使用单个 Markdown 文件，全局存储在 ~/.claude/CLAUDE.md，项目存储在 CLAUDE.md 或 .claude/CLAUDE.md。

Gemini CLI 同样使用单个 Markdown 文件，全局存储在 ~/.gemini/GEMINI.md。

各工具 MCP 配置对比：

MCP（Model Context Protocol）允许 AI 工具与外部服务集成。各工具的配置文件位置和格式差异较大：

工具	配置文件路径	结构	Local MCP	Remote MCP
Cursor	`~/.cursor/mcp.json`	`{"mcpServers": {...}}`	`command`, `args`, `env`	`url`, `headers`
Claude Code	`~/.claude.json`	`{"mcpServers": {...}}`	`command`, `args`	`url`, `type`
OpenCode	`~/.config/opencode/opencode.jsonc`	`{"mcp": {...}}`	`type: "local"`, `command[]`	`type: "remote"`, `url`
Gemini CLI	`~/.gemini/settings.json`	`{"mcpServers": {...}}`	`command`, `args`, `env`	`httpUrl`, `type`

关键配置差异总结：

OpenCode 使用 "mcp" 作为根字段，而其他工具使用 "mcpServers"。OpenCode 的 Local MCP 命令格式是数组形式。Gemini 的远程地址使用 httpUrl 而非 url。OpenCode 支持 enabled 字段控制 MCP 开关。

这些配置规则的整理，为后续的迁移逻辑设计奠定了基础。

NOTE: 在我编写代码时，Opencode 的目录是单数形式，比如 command、skill，后面又和其他工具一致改为复数了

拒绝 AI 幻觉：构建高信噪比的结对编程工作流

现在 AI 工具到处都是，已经渗透到了工作的方方面面中。但先别急着嗨，问问自己：你的 AI 是在「写代码」，还是在「猜代码」？

很多人用 AI 的姿势是这样的：打开 Chat 框，扔一句“帮我实现个用户登录”，然后等着 AI 吐出一堆看着像那么回事、跑起来全是 Bug 的代码。接着就是无尽的“改一下这个”、“不对是那个”，最后 Token 爆炸，心态崩了，还得自己重写。

这不叫 AI 编程，这叫抽奖。

真正的高效 AI 交互，不是靠模型抽卡，而是靠工作流（Workflow）。我花了大半年时间调试我的 Agent 技能包（Skills），总结出了一套拒绝幻觉、高信噪比的交互模式。今天不聊虚的，直接把我的核心配置摊开来讲。

一、拒绝“黑盒盲写”：建立计划与进度跟踪

很多人觉得跟 AI 聊计划是浪费时间。大错特错。

没有计划的 AI 就是个无头苍蝇。写个小 Demo 还行，一旦涉及多文件改动，AI 经常写着写着就忘了上下文，或者把 A 文件的改动覆盖了 B 文件的逻辑。

在此之前，我会要求 AI 必须先读取 invoke-plan 技能。

---
name: invoke-plan
description: 当用户提出复杂需求或大型功能开发、提到"计划"/"规划"/"任务分解"等关键词、或需要将模糊需求转化为具体执行步骤时使用。创建自驱动的分步执行计划，实时更新进度
---

## Rules
创建自驱动的分步执行计划，实时更新进度

## Execution Steps
1. 需求澄清：询问背景、目标、技术栈（已明确则跳过）
2. 计划创建：生成 `/plan/<plan-name>.md`，包含背景、Todo Checklist、进度更新
3. 逐步执行：每次执行一个步骤，完成后更新计划
4. 等待确认：每步完成后等待验收确认再进行下一步

1. 核心规则：自驱动的分步执行

遇到复杂需求（比如“实现 Commands 迁移逻辑”），不要直接写代码。必须先生成一个 /plan/commands-migration.md 文件。

这个计划文件不仅仅是给人看的，更是给 AI 的外部存储器。

需求澄清：背景是什么？技术栈是什么？（不知道就问，别瞎猜）
Todo Checklist：把大任务拆解成原子操作。
实时更新：每完成一步，AI 必须去更新这个 Markdown 文件的状态。

# ❌ 错误示范
User: 帮我实现 commands 工具迁移的代码。
AI: 好的，这是代码... (直接生成，大概率忽略了参数格式差异)

# ✅ 正确姿势 (基于 invoke-plan skill)
AI: 收到。这是一个复杂任务，我将创建一个执行计划 `/plan/commands-migration.md`：
1. [ ] 分析 Cursor 与 Claude Code 的 Commands 格式差异
2. [ ] 编写 Markdown 解析器
3. [ ] 实现参数占位符转换 ($ARGUMENTS -> $1)
4. [ ] 编写单元测试
...
请确认计划，确认后我将执行第一步。随后我会跟踪进度，并更新计划文件。

这样做的最大好处是：随时可以中断，随时可以恢复。 哪怕你关机睡觉，第二天回来，AI 读一下 plan 文件，立马就能接上进度。

二、治好 AI 的“瞎编症”：多级搜索策略

AI 最让人头疼的就是幻觉。尤其是遇到新的库或者不熟悉的 API，它特别喜欢一本正经地胡说八道。

比如你要用 Hono 写后端，AI 可能会凭记忆给你编一个不存在的 hono.useCustomMiddleware()。

为什么不用自带的 Web Search？

很多 AI 助手（如 Cursor、ChatGPT）都自带 Web Search 功能，那为什么还需要额外的工具？

搜索质量低：很多时候，自带的 Web Search 结果类似于百度，充满了广告、SEO 垃圾内容、或者 CSDN 这类低质量搬运。AI 很难从这些垃圾堆里找到准确的 API 定义。
非 AI 友好：普通的网页包含大量 HTML 标签、导航栏、脚本，这些对于 AI 来说都是“噪音”，浪费 Token 且容易干扰判断。
缺乏针对性：通用搜索无法区分“我想找官方文档”还是“我想找代码示例”。

核心 MCP 工具详解

为了解决这个问题，我引入了一系列专门为 AI 优化过的 MCP 工具，它们各司其职：

Context7 MCP
- 官网: github.com/upstash/con…
- 核心功能: Upstash 推出的工具，解决 LLM 数据过时问题。它提供实时更新的文档数据库，防止 AI 在使用 Next.js、LangChain 等快速迭代的库时出现幻觉。
Ref MCP
- 官网: ref.tools
- 核心功能: 专为 AI Coding Agents 设计。相比通用搜索，它更专注于技术文档索引，提供高效的文档搜索 (ref_search_documentation) 和网页阅读 (ref_read_url) 能力。
Grep.app MCP (gh-grep-mcp)
- 官网: grep.app
- 核心功能: 基于 grep.app 的接口封装。允许 AI 在 GitHub 上数百万个公共仓库中进行毫秒级的正则搜索。文档看不懂时，用它找真实世界的使用案例最有效。
Exa MCP (search-mcp)
- 官网: exa.ai
- 核心功能: 专为 AI 设计的搜索引擎。它返回清洗后的纯净文本，而不是充满广告的网页，能大幅减少 Token 消耗并提高上下文质量。

Search 技能配置

基于这些工具，我定义了一套严格的 Search 优先级策略，写在 search/SKILL.md 里。

---
name: search
description: 当需要查资料、找文档、搜代码示例或联网检索时使用。按优先级选择工具，仅在上述工具都无结果时才使用 Web Search
---

# 搜索策略

**对症下药**选择工具，但要尽量避免一上来就用 Web Search。只有当前述更「专用」的工具都不合适/查不到，或明确需要强实时/新闻类信息时，才使用 Web Search

## 工具与推荐使用场景

| 工具 | 作用 | 典型场景 |
|------|------|----------|
| **ref-mcp** | 通过 Ref 搜索库/框架/API 的**官方文档和私有文档**（包括 GitHub 仓库、PDF/Markdown 等） | 语法、API 签名、配置项、概念说明 + 自己项目的文档 |
| **context7-mcp** | 通过 Context7 获取库/框架的**最新版本文档与代码示例**（可与 ref 二选一或互补） | 版本准确的文档 + 示例代码、用法、最佳实践 |
| **gh** (CLI) | 查询 **GitHub 仓库/文件/分支/Issue/PR** | 已知仓库名、看源码、看 Issue/PR、仓库元信息 |
| **gh-grep-mcp** | 使用 Grep.app 在 GitHub 上按**代码模式（literal/正则）**搜索 | 找真实项目里的代码片段、用法模式、最佳实践实现，而不是自然语言问答 |
| **search-mcp** | 使用 Exa 的 **Web Search API** 进行联网搜索 | 教程、博客、报错信息、事实性问题、需要较新/较干净网页内容的通用检索 |
| **Web Search** | 通用联网搜索（最后手段） | 仅当 ref/context7/gh/gh-grep/search-mcp 都无结果或需强实时/新闻时使用 |

## 使用说明

### 文档类（API、语法、概念）
- **ref-mcp**、**context7-mcp**：都是「查文档」，可先试一个，不够再试另一个
- 已知是某库/框架的用法时，优先用这两个，再考虑 GitHub 或搜索

### GitHub 类
- **gh**：已知 `owner/repo` 或要查某个仓库里的文件、分支、Issue、PR 时用 gh
- **gh-grep-mcp**：不知道/不关心具体仓库，只想「在大量 GitHub 仓库里按代码模式（literal/正则）搜索」时用，适合找真实项目里的代码示例和用法模式

### 联网与兜底
- 教程、报错信息、事实性/通用问题：优先 **search-mcp**（Exa Web Search）
- **Web Search**：仅在前述工具都找不到或明确需要最新/实时信息时使用

## 场景示例（按真实问题选工具）

- **「React Router v6 里 useNavigate 的全部参数有哪些？」**  
  先用 `ref-mcp` 查官方文档；如果需要结合「当前最新小版本 + 示例代码」，再用 `context7-mcp`

- **「我要在 Next.js 14 里做基于中间件的 JWT 鉴权，有没有一整套示例？」**  
  用 `context7-mcp`，指定 Next.js 对应版本，查「middleware + JWT」相关文档和代码示例

- **「不知道该看哪个仓库，只想看看大家实际怎么写 useEffect 清理事件监听？」**  
  用 `gh-grep-mcp`，按代码模式搜索类似：`(?s)useEffect\\(\\(\\) => {.*removeEventListener`，筛选 TSX/JSX 代码

- **「我已经知道是 vercel/next.js 这个仓库，想看官方示例里的某个中间件实现细节」**  
  用 `gh`（GitHub CLI）直接查看 `vercel/next.js` 仓库里的对应文件/目录

- **「线上报错：`TypeError: Cannot read properties of undefined (reading 'map')`，想看别人怎么排查/避免？」**  
  用 `search-mcp` 搜索该错误信息，优先看高质量的博客/问答/最佳实践文章

- **「想了解 React 最新的官方 Roadmap 或刚发布的 19 版本变更点」**  
  如果 Ref/Context7 还没更新到最新公告，优先用 `search-mcp`，不够再用 `Web Search` 查“最新新闻/博客”

- **「需要看今天刚出的某条技术新闻或政策原文」**  
  直接用 `Web Search`，这是典型「强实时性」场景

1. 优先级链条 (Priority Chain)

我不允许 AI 上来就由着性子乱搜。它必须按这个顺序来：

查文档 (ref-mcp / context7-mcp)：这是第一优先级。
- 要写 API？先去查官方文档。
- context7-mcp 非常好用，它能直接拿到带代码示例的文档片段。
查 GitHub (gh CLI)：文档查不到？看源码。
- 利用 gh 命令行工具，直接去仓库里看 README 或者 examples 目录。
- 不要让 AI 猜参数，直接用 gh repo view 看项目元数据。
搜代码 (gh-grep-mcp)：不知道怎么用？看别人怎么用。
- 在 GitHub 上 grep 真实项目的用法。看看开源大佬们是怎么写这个配置的。
联网搜 (search-mcp / Web Search)：最后手段。
- 只有前面都挂了，或者找报错信息、最新新闻时，才允许联网 Google。

2. 真实场景演示

找到 agent-browser 关于 Windows 使用的 issue。这比我自己找问题快多了
找到 CDP 模式 issue
查询文档验证

gh CLI（Github CLI），让你的 AI 掌握整个 Github

GitHub CLI 是一个命令行工具，用于在终端中直接与 GitHub 交互。适合让 LLM 通过命令行查阅和阅读仓库内容，节省 MCP Token 消耗。

安装

# Windows (使用 winget 或 scoop)
# 或者 Github Releases 下载
winget install --id GitHub.cli
# 或
scoop install gh

# macOS
brew install gh

# Linux
# 参考：https://github.com/cli/cli/blob/trunk/docs/install_linux.md#debian
(type -p wget >/dev/null || (sudo apt update && sudo apt install wget -y)) \
	&& sudo mkdir -p -m 755 /etc/apt/keyrings \
	&& out=$(mktemp) && wget -nv -O$out https://cli.github.com/packages/githubcli-archive-keyring.gpg \
	&& cat $out | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \
	&& sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
	&& sudo mkdir -p -m 755 /etc/apt/sources.list.d \
	&& echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
	&& sudo apt update \
	&& sudo apt install gh -y

身份验证：

gh auth login              # 交互式登录
gh auth status             # 查看认证状态
gh auth refresh            # 刷新 token

# 读取文件内容（需解码）
gh api "repos/{owner}/{repo}/contents/{path/to/file}" --jq '.content' | base64 -d

# 读取 README
gh api "repos/{owner}/{repo}/readme" --jq '.content' | base64 -d

# 列出目录（仅显示名称，节省 Token）
gh api "repos/{owner}/{repo}/contents/{path}" --jq '.[].name'

更多命令让 AI 教你就行了，我就不浪费大家时间了

三、对抗“金鱼记忆”：上下文总结与交接

LLM 的 Context Window 再大也是有限的。更可怕的是，上下文越长，AI 的注意力越涣散（Lost in the Middle 现象）。

当你发现 AI 开始车轱辘话来回说，或者忽略你刚发的要求时，就是时候重置上下文了。

但我绝不会直接清空对话，那样还得把需求重说一遍。我使用 summary 技能来进行“无损交接”。

Context Handoff Summary

我会让 AI 生成一份标准化的交接文档，格式锁死：

背景与目标：一句话说清楚我们在干嘛。
当前进度：哪些文件改了？哪些测试挂了？
重要文件引用：别把所有文件都扔进去，列出最核心的 3-5 个文件路径。
下一步指令：直接告诉“下一个我”（New Session 的 AI）该干什么。

---
name: summary
description: 总结当前任务的上下文和进度，以便切换 LLM 或重置上下文
---

# Context Handoff Summary

请分析当前的对话上下文、代码修改记录和任务目标，并结合重要上下文，生成一份详细的任务交接文档。这份文档将用于提供给另一个 LLM 以继续当前的工作

## 任务摘要要求

请按照以下格式输出：

### 1. 背景与目标 (Background & Goals)
- 简述当前任务的核心背景
- 明确当前阶段的最终目标

### 2. 当前进度与现状 (Current Progress)
- 列出已经完成的工作
- 描述当前正在进行的修改
- **特别说明**: 如果当前代码有逻辑错误、编译失败或运行异常，请详细说明现状及你认为的原因

### 3. 重要文件引用 (Key File References)
- 列出与任务核心相关的最重要的文件路径
- 简要说明每个文件的作用或为何重要

### 4. 待办事项与下一步计划 (Remaining Tasks & Next Steps)
- 明确接下来需要执行的具体步骤
- 提供给新 LLM 的建议指令

有了这个，点击 IDE 的 "New Chat"，把这段话往里一贴，无缝衔接。

四、守门员：代码审查与 Bug 修复原则

代码写完了，能不能用？别急着 merge。

1. Code Review 的六维检查

在 code-review/SKILL.md 里，我要求 AI 必须按六个维度审查代码，而不是只会说“代码写得很棒”这种废话：

重复代码 (DRY)
逻辑冲突
多余逻辑 (KISS)
SRP 违反 (一个函数干了十件事？重写！)
模块耦合
硬编码/死代码

并且，分级报告：🔴严重、🟡警告、🟢建议。没有红灯才能过。

---
name: code-review
description: 当用户要求进行代码审查、提到"review"/"审查"/"重构"/"优化代码"等关键词、或代码需要质量检查时使用。检查重复代码、逻辑冲突、多余逻辑、SRP违反、模块耦合、硬编码/死代码等6个维度
---

## Target
检查6个维度：重复代码、逻辑冲突、多余逻辑、SRP违反、模块耦合、硬编码/死代码

## Execution Steps
检查以下6个维度，用🔴严重/🟡警告/🟢建议分级：

1. **重复代码** - 相同或相似的代码逻辑在多处出现
2. **逻辑冲突** - 存在矛盾或互相抵消的逻辑
3. **多余逻辑** - 不必要的计算、判断或冗余代码
4. **SRP违反** - 单一职责原则违反，一个函数/类做了太多事情
5. **模块耦合** - 模块间依赖关系过于复杂或紧耦合
6. **硬编码/死代码** - 魔法数字、未使用的代码、永远不会执行的分支

## Format

问题 1 — 重复逻辑

位置: src/foo.ts 行 120-160；src/bar.ts 行 20-40
描述: 两处实现相同的数据转换逻辑
严重度: 🟡警告
推荐修复: 提取 utils/transform.ts，新增单元测试


## NOTE
- 只进行观察和分析，不修改代码直到用户确认
- 优先报告严重问题（🔴），再是警告（🟡），最后是建议（🟢）
- 每个问题都要说明"为什么这是个问题"和"如何修复"
- 如果代码整体质量很好，也要明确指出

2. Fix Bug：不猜测，只验证

这是我最喜欢的一条规则：遵循“不猜测，只验证”原则。

很多 AI 看到报错就开始瞎猜：“可能是版本问题？可能是环境问题？” 然后让你试一堆没用的命令。

在 fix-bug/SKILL.md 里，我规定了死流程：

分析：先看代码。
索要上下文：缺日志？缺配置？主动问我，别脑补。
日志打印：不确定哪里挂了？加 console.log。
迭代：修复 -> 验证 -> 再修复。

---
name: fix-bug
description: 当用户报告 Bug 或错误、提到"bug"/"错误"/"异常"/"问题"等关键词、或代码运行不符合预期时使用。遵循"不猜测，只验证"原则，系统性排查和解决复杂Bug
---

## Rules
遵循"不猜测，只验证"原则

## Execution Steps
1. 分析：根据提供的信息，浏览相关代码分析问题
2. 索要上下文：需要额外信息（环境变量、依赖版本、配置、日志）且无法获取时，主动提问
3. 日志打印：信息不足时，建议在特定位置添加日志，要求重新运行并提供输出
4. Web项目：可访问时打开浏览器调试；无法获取时，指导查看DevTool并要求提供错误/API详情
5. 迭代修复：提出修复方案 → 等待反馈 → 持续循环直到确认修复

结语：给 AI 装上方向盘

AI 确实很强，但如果不加以引导，它就是一匹脱缰的野马。

通过 ai-sync，我解决了配置迁移的痛点；通过 Skills 和 Workflow，我解决了 AI 幻觉和不可控的问题。

这套组合拳打下来，我的编程体验发生了质的变化：从“抽奖式编程”变成了“指挥官式编程”。

如果你也想体验这种掌控感：

试试 ai-sync: npm i -g @jl-org/ai-sync
来 GitHub 点个 Star: github.com/beixiyo/ai-…
复制我的 Skills: 上面的所有 Skill 配置，你都可以直接抄作业，放到你的 ~/.claude/skills 或 ~/.cursor/skills 里。