1. 项目概述与核心痛点如果你和我一样同时用着 Cursor、Claude Code、Google Gemini Antigravity 这几个 AI 编程工具那你肯定也经历过这种“断片”时刻正在 Cursor 里用 Codex 写一个复杂的部署脚本思路正流畅突然提示“上下文窗口已满”或者“Token 不足”。你不想停下来手头正好有 Claude 或者 Gemini 的额度于是你不得不切换到另一个 IDE然后尴尬地发现——刚才在 Cursor 里精心调教好的那个“一键部署”技能Skill在新环境里根本不存在。你只能凭着记忆或者翻找聊天记录手动再创建一遍。这个过程不仅打断了心流还容易出错更别提那些需要跨项目、跨团队共享的标准化技能了。这就是agent-skill-sync诞生的背景。它不是什么复杂的平台而是一个纯粹的、开源的命令行工具用 Python 写成目标只有一个让你在不同 AI 编程助手的技能库之间实现无缝的创建、同步、查看和删除。它解决的就是“技能孤岛”问题。你的技能资产应该像你的代码一样可以方便地移植、备份和共享而不是被锁死在某个特定的 IDE 里。这个工具支持 Claude Code、OpenAI Codex在 Cursor 等 IDE 中以及 Google Gemini Antigravity 这三个主流平台并且设计上预留了接口未来可以轻松扩展支持更多平台。简单来说它让你从“为每个工具重新发明轮子”的困境中解放出来回归到“一次编写处处运行”的高效状态。无论你是独立开发者还是团队的技术负责人只要你在日常工作中需要切换使用多个 AI 编程工具这个工具就能直接提升你的开发连贯性和效率。2. 设计思路与架构解析2.1 核心设计哲学简单、无状态、可组合在设计agent-skill-sync时我坚持了几个原则这些原则也决定了它的最终形态和易用性。首先是“简单”。这个工具不依赖任何外部服务、数据库或网络连接。它就是一个本地的 Python 脚本所有操作都基于文件系统。技能本身在各大 AI IDE 中通常就是一个包含instructions.md技能说明和若干脚本文件的文件夹。agent-skill-sync所做的本质上就是文件复制、移动和删除只不过它知道这些技能文件夹应该放在哪里。这种设计让工具极其轻量没有复杂的依赖也避免了引入新的故障点。其次是“无状态”。工具本身不维护任何中央注册表或索引。它每次运行时都会动态扫描目标目录全局的~/.cursor、~/.claude等或项目内的.cursor/、.claude/等来发现现有的技能。这意味着你可以用任何其他方式比如手动复制、用 Git 管理来管理技能agent-skill-sync都能正确识别并操作。这种设计避免了状态同步的难题也让工具的行为非常可预测。最后是“可组合”。CLI 工具的每个命令create,copy,inspect,remove,list都是独立的、功能单一的。它们可以通过管道pipe和 shell 脚本灵活组合。例如你可以用find命令列出所有 Markdown 文件然后通过管道传给skill-create.py create --stdin来批量创建技能。这种 Unix 哲学让工具能轻松嵌入到你现有的自动化工作流中。2.2 技能存储的双层架构全局与项目级这是agent-skill-sync一个非常关键的设计直接对应了两种主要的使用场景。1. 全局技能Global Skills路径存储在用户的家目录~下例如~/.cursor/skills/,~/.claude/skills/,~/.agent/skills/对应 Gemini Antigravity。用途这些是你个人的、跨所有项目的通用技能。比如“代码审查助手”、“生成单元测试模板”、“解释复杂代码块”等。安装到全局后你在任何项目中打开对应的 AI 助手都能直接使用这些技能。操作使用--scope global默认或省略 scope 参数。2. 项目级技能Project Skills路径存储在特定项目的根目录下例如./.cursor/skills/,./.claude/skills/,./.agent/skills/。用途这些是项目特有的技能。比如“为本项目启动本地开发服务器”、“运行本项目特定的测试套件”、“部署到项目专属的 staging 环境”。这些技能只对当前项目有意义不应该污染全局空间。将项目级技能纳入版本控制如 Git可以确保团队所有成员都拥有一致的 AI 助手能力。操作使用--scope project并指定--project-dir。3. 两者兼顾Both操作使用--scope both。这通常用于当你开发一个通用技能但想先在当前项目中测试和完善同时也希望立即在全局可用。工具会同时向两个位置写入技能文件。注意项目级技能的路径优先级通常高于全局技能。这意味着当你在一个项目中AI 助手可能会优先加载项目.cursor/skills/下的技能而不是~/.cursor/skills/下的。这符合“项目配置覆盖全局配置”的最佳实践。agent-skill-sync的inspect命令可以清晰地告诉你一个技能在哪些位置存在。2.3 平台适配层抽象与扩展不同的 AI 平台其技能目录的命名和结构略有不同。agent-skill-sync内部维护了一个平台适配器Platform Adapter映射表。目前支持claude: 映射到~/.claude/skills/或./.claude/skills/codex: 映射到~/.cursor/skills/或./.cursor/skills/Cursor 是 Codex 的一个主要集成 IDEgemini: 映射到~/.agent/skills/或./.agent/skills/Gemini Antigravity 的默认目录当执行--only claude codex时工具只会操作这两个平台对应的目录。这种设计使得未来添加对新平台如 Windsurf、Zed 等的支持变得非常容易只需要在映射表中添加一个新的条目即可核心的逻辑完全不用改变。这也是开源贡献的一个主要方向。3. 环境准备与工具安装3.1 系统与依赖要求agent-skill-sync对环境的要求非常宽松这也是其优势之一。Python 3.10: 这是核心依赖。使用新版本是为了利用更稳定的标准库和语法特性如类型提示。macOS 和大多数 Linux 发行版都已预装 Python 3但版本可能较旧。你可以通过python3 --version检查。macOS/Linux Shell: 工具设计为在 Bash、Zsh 等 Unix-like shell 环境中运行。它重度依赖命令行参数解析和文件路径操作。文件系统权限: 你需要对你自己的家目录~和目标项目目录有写入权限。如果你的 Python 版本低于 3.10建议使用pyenv进行版本管理。这是一个非常实用的技巧可以让你在系统上无缝切换多个 Python 版本。# 安装 pyenv (以 macOS Homebrew 为例) brew update brew install pyenv # 将 pyenv 初始化脚本添加到你的 shell 配置中如 ~/.zshrc echo export PYENV_ROOT$HOME/.pyenv ~/.zshrc echo command -v pyenv /dev/null || export PATH$PYENV_ROOT/bin:$PATH ~/.zshrc echo eval $(pyenv init -) ~/.zshrc # 重新加载配置 source ~/.zshrc # 安装 Python 3.10 pyenv install 3.10.12 # 设置为全局默认版本或在当前目录使用 pyenv global 3.10.12 # 验证 python --version3.2 获取与安装工具安装过程就是标准的 Git 克隆没有复杂的pip install步骤因为工具是自包含的脚本。# 1. 克隆仓库到本地你喜欢的任何位置比如开发工具目录 git clone https://github.com/breakbottle/agent-skill-sync.git ~/Developer/agent-skill-sync cd ~/Developer/agent-skill-sync # 2. 让脚本可执行。这是关键一步否则无法直接运行。 chmod x skill-create.py # 3. 强烈推荐创建一个 shell 别名这样你可以在任何目录下直接调用 skill-create echo alias skill-create$PWD/skill-create.py ~/.zshrc # 或 ~/.bashrc source ~/.zshrc完成以上步骤后你应该可以直接在终端输入skill-create --help并看到帮助信息。如果提示命令未找到请检查你的 shell 配置文件路径和重新source的操作是否正确。实操心得我习惯把我的所有 CLI 工具都放在~/Developer/或~/Tools/这样的目录下并用 Git 管理。然后通过 shell 别名或修改$PATH环境变量来全局调用。对于agent-skill-sync别名alias的方式更简洁因为它避免了修改$PATH可能带来的冲突。4. 核心功能详解与实战操作4.1 技能创建从想法到多平台部署创建技能是最高频的操作。agent-skill-sync提供了三种灵活的输入方式覆盖了从已有文档到即时创意的所有场景。场景一从 Markdown 文件创建最规范这是最推荐的方式。你事先编写好一个结构清晰的instructions.md文件然后一键分发。# 假设你有一个写好的部署技能文档 skill-create create ./deploy-to-aws.md --name aws-lambda-deployer --description “一键部署代码到 AWS Lambda 函数”发生了什么工具会读取deploy-to-aws.md的内容。如果文件里已经包含了 YAML Frontmatter比如包含name:和description:工具会优先使用文件内的元数据。如果没有则会使用命令行参数--name和--description提供的信息来补全。然后它会在所有支持的平台默认是 claude, codex, gemini的全局技能目录下创建同名文件夹并将instructions.md复制进去。为什么推荐文件方式便于版本控制Git、便于离线编辑和审阅、内容格式可以更复杂支持多级标题、代码块、列表等。场景二从命令行文本直接创建快速原型当你有一个简单的想法不想先创建文件时可以直接用--text参数。skill-create create --text “你是一个 React 组件命名专家。请根据我提供的组件功能描述生成一个符合 PascalCase 规范、语义清晰且简洁的组件名称。只需回复名称不要解释。” --name react-component-namer --description “快速生成 React 组件名”发生了什么工具会将--text的内容直接作为技能指令写入到生成的instructions.md中。这种方式适合创建一些简单、一次性的提示词技能。注意事项由于命令行参数长度限制非常长的指令不适合用这种方式。另外包含复杂格式如代码块的指令在纯文本中难以表达这时还是用文件更合适。场景三从标准输入创建与 AI 协作这是最酷的用法之一可以实现与 AI 助手的“管道”协作。你让一个 AI 助手帮你生成技能指令然后直接通过管道传给agent-skill-sync进行安装。# 假设你正在与 Claude 对话让它生成一个技能 # 在你的 AI 聊天界面中你可以这样“指挥”它 # “请为我写一个用于代码重构的技能指令目标是提取函数。然后假设你有一个命令行工具 ‘skill-create’请生成一个能把这个技能安装到全局 Codex 和 Claude 中的命令。” # Claude 可能会回复一段 Markdown 和一条命令。你可以手动执行或者更自动化 # 1. 将技能指令保存到临时文件或用 echo 模拟 echo “你是一个代码重构助手。当用户给出一个代码块时请识别其中可以独立出来的逻辑片段并将其提取为一个命名良好的新函数。保持原有功能不变并提供重构前后的代码对比。” /tmp/extract-function.md # 2. 通过管道安装这里用 cat 模拟输出实际可能是 AI 工具的直接输出 cat /tmp/extract-function.md | skill-create create --stdin --name extract-function-refactor --description “提取代码块为独立函数” --only codex claude发生了什么--stdin参数告诉工具从标准输入读取内容。管道符|将前一个命令的输出传递过来。这样AI 生成的指令可以直接“流”向安装过程实现了无缝衔接。高级玩法你可以写一个脚本自动调用 OpenAI API 或 Claude API 来生成技能然后通过管道调用skill-create安装实现技能创作的自动化流水线。4.2 技能复制迁移与标准化copy命令用于将一个已存在的技能文件夹复制到其他平台或位置。这在你已经在一个平台比如 Claude上调试好一个技能想快速同步到其他平台时非常有用。# 将 Claude 中一个调试好的技能同步到 Codex 和 Gemini 的全局目录 skill-create copy ~/.claude/skills/my-awesome-debugger --only codex gemini # 复制的同时重命名并只安装到当前项目的 Codex 技能库中 skill-create copy ~/.claude/skills/my-awesome-debugger --name project-specific-debugger --scope project --project-dir . --only codex核心逻辑copy命令会读取源技能文件夹内的所有文件主要是instructions.md也可能包含scripts/子目录等然后将整个文件夹结构原样复制到目标位置。它比create更“底层”直接操作文件夹不关心文件内容。与create的区别create是从一个指令“源”文件、文本、流生成技能。copy是从一个已存在的技能“实体”复制出新的实体。copy更适合技能迁移和备份。4.3 技能检视与列表掌控你的技能资产当技能越来越多管理就变得重要。inspect和list命令帮你摸清家底。inspect定位技能的“分身”一个技能可能同时存在于全局 Claude、项目 Codex 等多个地方。inspect可以精确告诉你它在哪。# 检查 ‘aws-lambda-deployer’ 技能在所有位置的存在情况 skill-create inspect --name aws-lambda-deployer --scope both --project-dir /my/project输出可能类似于Skill ‘aws-lambda-deployer’ found in: Global: - /Users/you/.cursor/skills/aws-lambda-deployer - /Users/you/.claude/skills/aws-lambda-deployer Project (/my/project): - /my/project/.cursor/skills/aws-lambda-deployer这个命令在排查“为什么在这个项目里看不到我的技能”这类问题时非常有用。也许技能只安装在了全局而项目目录下没有。list浏览技能库列出指定范围内所有可用的技能。# 列出全局所有技能 skill-create list --scope global # 列出当前项目所有技能 skill-create list --scope project --project-dir . # 列出所有全局当前项目技能并显示来源 skill-create list --scope both --project-dir . --verbose--verbose参数会显示每个技能所在的完整路径让你一目了然技能的分布。4.4 技能移除精准清理remove命令用于删除技能。为了安全它提供了非常精细的控制选项。# 1. 安全第一干运行dry-run只预览要删除的内容不实际执行 skill-create remove --name old-experimental-skill --scope both --project-dir . --dry-run # 2. 从全局所有平台中移除该技能 skill-create remove --name old-experimental-skill --scope global # 3. 仅从当前项目的 Claude 技能库中移除 skill-create remove --name project-only-skill --scope project --project-dir . --only claude # 4. 强制删除跳过确认提示用于脚本中 skill-create remove --name temp-skill --scope global --force--dry-run的重要性这是我最推荐的习惯。在执行任何删除操作前先加--dry-run看看工具会动哪些文件。确认无误后再去掉这个参数执行真正的删除。作用域--scope和目标平台--only这两个参数让你能进行“外科手术式”的删除避免误伤。例如你只想清理某个项目中为 Codex 创建的临时技能而不影响全局和其他平台。--force标志默认情况下remove命令会要求你手动确认输入 ‘y’。在自动化脚本中可以使用--force跳过确认。请谨慎使用。4.5 高级选项与项目集成技巧--scripts目录为技能注入可执行逻辑一些高级技能除了指令文档还需要配套的脚本文件比如一个 Python 脚本来自动化某些操作。--scripts参数允许你在创建或复制技能时将一个目录下的所有脚本文件一并复制到每个技能文件夹中。# 假设你有一个 scripts/ 目录里面包含 deploy.sh 和 rollback.py skill-create create ./deploy.md --name advanced-deploy --scripts ./scripts/执行后~/.cursor/skills/advanced-deploy/目录下不仅会有instructions.md还会有一个scripts/子目录里面包含deploy.sh和rollback.py。这样你的 AI 技能在给出建议时可以直接引用或指导用户运行这些配套脚本。--sync-gitignore智能管理版本控制这是一个非常贴心的功能。当使用--scope project安装技能时AI 技能目录如.cursor/,.claude/会被创建在项目里。这些目录通常包含个人化的配置或缓存不应该提交到 Git 仓库中。不加--sync-gitignore工具只创建技能目录和文件。加上--sync-gitignore工具会检查项目根目录下的.gitignore文件。如果不存在它会创建如果存在它会检查是否已经忽略了.cursor/、.claude/等目录。如果没有它会将这些条目追加到.gitignore文件的末尾。skill-create create ./team-code-review.md --scope project --project-dir . --sync-gitignore注意这个操作是“保守”的。它只会追加不会修改.gitignore文件的其他部分或删除已有条目。这是一个安全的设计防止工具破坏你精心配置的.gitignore。--home覆盖家目录主要用于测试或者你的全局配置不在默认的~目录下。普通用户很少需要用到。5. 与 AI 助手协同工作的进阶流程agent-skill-sync的设计初衷就是服务于 AI 增强的工作流。除了通过管道pipe传递内容你还可以直接“指挥”你的 AI 助手来运行这个工具实现更高阶的自动化。5.1 将工具“赋能”给 AI 助手核心思路是让你的 AI 助手如 Cursor 中的 Codex、Claude Code能够访问到agent-skill-sync的代码仓库并授予它执行权限。打开你的 AI 编程助手例如 Cursor。在聊天界面或指令框中你可以这样输入“我将给你访问一个工具的权限它叫agent-skill-sync位于/path/to/agent-skill-sync。这个工具是一个 Python 脚本用于在不同 AI 助手的技能目录之间同步技能。请你根据我的要求运行这个工具并执行相应的操作。”接着你可以直接提出要求“请使用agent-skill-sync为我创建一个新的技能。技能名称是 ‘docker-compose-helper’描述是 ‘帮助生成和验证 docker-compose.yml 文件片段’。技能指令是‘你是一个 Docker Compose 专家。当用户描述一个多服务应用架构时例如一个 web 前端一个 REST API 后端一个 PostgreSQL 数据库请生成一个完整的 docker-compose.yml 文件片段确保服务间网络连通卷映射正确并给出简短的运行说明。’ 请将这个技能安装到当前项目的 Claude 和 Codex 目录中。”一个足够智能的 AI 助手特别是拥有代码解释能力的能够理解你的请求定位到skill-create.py脚本并组合出正确的命令例如cd /path/to/agent-skill-sync ./skill-create.py create --text “你是一个 Docker Compose 专家...” --name docker-compose-helper --description “帮助生成和验证 docker-compose.yml 文件片段” --scope project --project-dir /current/project/path --only claude codex它甚至可能会先执行一个--dry-run给你预览等你确认后再执行实际安装。5.2 构建技能创作与分发的自动化管道对于团队或重度用户可以构建一个更系统的流程技能开发仓库创建一个专门的 Git 仓库来管理团队共享的技能 Markdown 文件。每个技能一个文件并做好分类。CI/CD 集成在这个仓库中设置一个 GitHub Action 或 GitLab CI。当有人向仓库提交新的或更新的技能文件如skills/deploy/aws-ecs.md时CI 流程可以自动触发。自动同步脚本CI 任务可以运行一个脚本使用agent-skill-sync的create命令将这些技能文件安装到某个“中央测试环境”或直接推送到团队共享的项目目录中。通知与验证CI 完成后可以在团队频道如 Slack中通知“新的 ‘AWS ECS 部署’ 技能已同步至所有项目的 Codex 和 Claude 目录”。这样技能的管理就变得像管理代码依赖一样规范、可追溯。6. 常见问题与故障排查实录在实际使用中你可能会遇到一些问题。以下是我在开发和日常使用中总结的一些常见场景和解决方法。6.1 问题命令执行报错 “Permission denied”表现zsh: permission denied: ./skill-create.py原因克隆下来的 Python 脚本没有可执行权限。解决确保你已经运行了chmod x skill-create.py。如果已经运行过检查文件所有权是否是你的用户。6.2 问题技能创建成功但在 IDE 中看不到表现skill-create create命令成功执行没有报错但打开 Cursor 或 Claude Code在技能列表里找不到新创建的技能。排查步骤确认安装位置首先用inspect命令确认技能被安装到了哪里。skill-create inspect --name 你的技能名 --scope both --project-dir .检查输出路径是否正确。是全局目录还是项目目录项目目录的路径是否正确 2.检查 IDE 技能目录手动去文件系统查看对应的路径如~/.cursor/skills/下是否存在以技能名命名的文件夹里面是否有instructions.md文件。 3.IDE 重启/刷新有些 IDE 需要重启或手动刷新技能列表。尝试完全关闭 IDE 再重新打开。 4.项目级技能的特殊性如果你安装到了项目目录--scope project请确保你当前在 IDE 中打开的项目根目录就是--project-dir指定的那个目录。IDE 通常只加载当前打开项目下的技能。 5.平台映射错误极少数情况下你的 IDE 可能使用了非标准的技能目录路径。你可以检查 IDE 的设置或文档确认其技能存储位置并与agent-skill-sync的映射表对比。6.3 问题--sync-gitignore没有生效表现运行了带--sync-gitignore的命令但.gitignore文件没有被修改或者 AI 技能目录仍然被 Git 跟踪。排查步骤检查.gitignore语法工具追加的条目类似于/.cursor/和/.claude/。确保你的.gitignore中没有以#开头的注释行错误地包含了这些目录也没有使用可能导致冲突的通配符规则。检查文件权限确保你对项目根目录下的.gitignore文件有写入权限。手动验证你可以手动在.gitignore文件末尾添加一行/.cursor/保存后运行git status看看.cursor目录是否显示为 “untracked”。如果仍然被跟踪可能是.gitignore规则优先级问题或者该目录下已有文件被 Git 暂存index了。对于已暂存的文件需要使用git rm --cached -r .cursor将其从 Git 索引中移除。6.4 问题使用--stdin时内容被截断或出错表现通过管道传递长文本时技能创建不完整或失败。原因可能是 shell 环境或管道缓冲问题或者输入内容中包含特殊字符如空字符、不匹配的引号导致解析错误。解决优先使用文件对于复杂或重要的技能始终优先使用 Markdown 文件作为输入源这是最可靠的方式。检查输入源如果必须用--stdin先用一个简单文本测试管道是否畅通。例如echo “test” | skill-create create --stdin --name test。处理复杂内容如果技能指令包含多行、引号、反斜杠等建议先写入临时文件然后使用文件路径方式创建。6.5 问题如何备份和恢复我的所有技能表现想换电脑或者想对自己的技能库做一次完整备份。解决方案agent-skill-sync本身没有内置的备份命令但因为技能都是文件所以用系统命令很容易实现。备份# 备份全局技能到压缩包 tar -czf ~/ai-skills-backup-global.tar.gz ~/.cursor/skills/ ~/.claude/skills/ ~/.agent/skills/ # 备份特定项目的技能 tar -czf ~/my-project-skills-backup.tar.gz /path/to/project/.cursor/skills/ /path/to/project/.claude/skills/ /path/to/project/.agent/skills/恢复# 解压备份包到临时目录 tar -xzf ~/ai-skills-backup-global.tar.gz -C /tmp/backup # 然后你可以选择性地使用 skill-create copy 命令将备份的技能复制回新的环境 # 例如恢复一个叫 ‘my-backup-skill’ 的技能 skill-create copy /tmp/backup/Users/olduser/.claude/skills/my-backup-skill --name my-backup-skill更彻底的方式是直接解压覆盖家目录下的对应文件夹但请注意这会覆盖现有技能。操作前务必做好现有技能的备份。7. 贡献、测试与未来展望agent-skill-sync是一个社区驱动的开源工具它的实用性和生命力来自于用户的反馈和贡献。如何贡献报告问题如果你发现 bug或者有功能建议欢迎在 GitHub 仓库提交 Issue。提交时请尽量提供详细的环境信息、复现步骤和期望行为。扩展平台支持这是最重要的贡献方向之一。当你使用的 AI 编程工具如 Zed, Windsurf, Codeium 等也支持自定义技能时你可以参考现有代码在平台映射表中添加新的适配器并提交 Pull Request。改进文档补充使用案例、录制演示视频、翻译文档都是非常有价值的贡献。编写测试项目目前只有简单的冒烟测试smoke-test.sh。增加更全面的单元测试和集成测试能极大地提升代码的健壮性。运行测试 在提交代码前运行自带的冒烟测试是一个好习惯它能快速验证核心功能是否正常。./scripts/smoke-test.sh这个脚本会模拟创建、复制、列出、检查、删除等操作并在一个临时目录中进行不会影响你的真实技能数据。个人使用体会与建议 我使用这个工具已经几个月了它彻底改变了我管理 AI 技能的方式。从最初的杂乱无章到现在拥有了一个结构清晰的个人技能库和多个项目专属的技能集。最大的体会是将技能视为代码资产来管理。我给技能文件夹也建立了 Git 仓库用README.md记录技能的用途和版本这让我能随时回溯和分享。一个实用的小技巧是为常用技能创建“别名”或“快捷命令”。例如我在我的 shell 配置里定义了几个函数# 快速安装一个本地调试技能到当前项目 alias add-debug-skill“skill-create create ~/my-skills/debug-helper.md --scope project --project-dir . --sync-gitignore” # 列出我所有的全局技能 alias list-my-skills“skill-create list --scope global | grep -E ‘^[a-zA-Z]’ | sort”这些小小的自动化进一步降低了使用门槛让切换和同步技能变得像呼吸一样自然。工具的价值不在于它本身有多复杂而在于它是否真的融入了你的工作流并让你忘记了那些原本存在的摩擦。agent-skill-sync对我来说就是这样一个“安静的好帮手”。