1. 三份 skills 目录改一处忘两处如果你同时用 Kiro、Claude Code、Codex 这三个 AI 编码工具大概率遇到过这个场景在 Kiro 里调好一个巡检 skill用着很顺换到 Claude Code 想复用发现它读的是~/.claude/skills/里面根本没有再切到 Codex又是第三个目录。于是你把同一个SKILL.md拷了三份改了一处另外两处忘了同步半年后三个版本各说各话。这就是 Skills as Code 想解决的核心问题Skill 本质是知识资产应该像代码一样有单一数据源、有版本控制、能持续迭代而不是散落在三个工具目录里各自漂移。这篇就给你一条可落地的路径——选一个目录做主仓库另外两个工具用软链接指过去一次编写、三处生效维护成本从 O(3n) 降到 O(n)。适合谁本机同时装了 Kiro CLI、Claude Code、Codex CLI已经攒了一些 skill或者准备开始系统化写 skill 的开发者。全程 macOS/Linux 命令Windows 用户可用 WSL 或 Git Bash 等价操作。先看三个工具默认的 skill 路径差异工具定位默认 Skill 路径Kiro CLI运维自动化、云端管理~/.kiro/skills/Claude Code通用编码、深度推理~/.claude/skills/Codex CLI终端编码、Shell 自动化~/.codex/skills/三个工具都从各自目录扫描SKILL.md靠 YAML frontmatter 里的description做语义匹配决定是否触发。路径不同但文件格式一致——这正是能共用同一份配置的前提。2. 前置准备确认工具版本与 Skill 目录动手前先确认三件事避免改到一半发现某个工具压根没装或路径不一样。第一确认三个工具都能正常启动并且各自认识 skills 目录。分别在终端里跑一下版本命令能出版本号即可kiro --version claude --version codex --version第二确认三个 skills 目录当前是否存在、各有多少个 skill。这一步是后面合并的基础先摸清家底for d in ~/.kiro/skills ~/.claude/skills ~/.codex/skills; do if [ -d $d ]; then echo $d: $(ls $d | wc -l) skills else echo $d: 不存在 fi done第三确认SKILL.md的格式要求。Claude Code 对 YAML frontmatter 是硬性要求——文件第一行不是---就直接忽略连报错都不给。所以后面合并时补齐 frontmatter 是绕不开的一步。注意如果你的某个工具目录不存在先手动创建空目录再继续否则软链接会指向一个不存在的目标。命令是mkdir -p ~/.claude/skills。关于模型调用和 API Key 的准备如果你打算在 skill 里调用大模型能力可以提前在 TaoToken 控制台把 key 建好后面配置里会用到。入口放在这里方便你按需取用模型对话入口 https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodel_chat API Keys 管理 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi_keys 。这一步不是必须纯本地 skill 可以跳过。3. 可复制配置单一数据源 软链接核心思路一句话选一个目录当唯一数据源另外两个工具目录用软链接指过去。为什么选软链接而不是 Git 子模块或 rsync看对比方案实时性维护成本适合场景软链接即时零单机多工具本场景Git 子模块需 push/pull高团队协作rsync 定时有延迟中需 cron跨机器单机多工具场景下软链接是实时且零维护的改主仓库立刻三处生效。下面按步骤来。3.1 备份现有 skills任何批量操作前先备份出问题能回滚cp -r ~/.kiro/skills ~/.kiro/skills.bak.$(date %Y%m%d) cp -r ~/.claude/skills ~/.claude/skills.bak.$(date %Y%m%d) cp -r ~/.codex/skills ~/.codex/skills.bak.$(date %Y%m%d)3.2 批量补齐 YAML frontmatter假设你选 Kiro 做主仓库。实测下来Kiro 的 skill 里经常有一批缺 YAML frontmatterClaude Code 会直接忽略它们。用一个脚本批量补import os, re SKILLS_DIR os.path.expanduser(~/.kiro/skills) for entry in os.listdir(SKILLS_DIR): skill_md os.path.join(SKILLS_DIR, entry, SKILL.md) if not os.path.isfile(skill_md): continue with open(skill_md) as f: content f.read() if content.startswith(---): continue # 已有 YAML跳过 # 提取一级标题作为 name 的参考 title for line in content.split(\n): m re.match(r^#\s(.), line) if m: title m.group(1).strip() break # 提取触发关键词取前 3 个 triggers, in_trigger [], False for line in content.split(\n): if re.match(r^##\s触发条件, line): in_trigger True continue if in_trigger: if line.startswith(## ): break kw line.strip().lstrip(- ).strip() if kw and 用户提到 not in kw: triggers.append(kw.split( / )[0].strip()) desc title (f。触发{, .join(triggers[:3])} if triggers else ) frontmatter f---\nname: {entry}\ndescription: {desc}\n---\n with open(skill_md, w) as f: f.write(frontmatter content) print(fADD {entry}: {desc})跑完打印一堆ADD xxx说明补齐成功。这一步只对缺 frontmatter 的文件动手已有的不动。3.3 合并其他工具独有的 skill主仓库选 Kiro 不代表其他工具的 skill 就丢掉。先找出 Codex 独有的再合并进来# 找出 Codex 独有的 skill comm -13 (ls ~/.kiro/skills/ | sort) (ls ~/.codex/skills/ | sort) # 把独有的合并到主仓库 for name in alb-diagnose ecs-diagnose iot-diagnose lambda-diagnose rds-diagnose aws-security-audit; do cp -r ~/.codex/skills/$name ~/.kiro/skills/$name donecomm -13输出的是只在第二个文件里出现的行也就是 Codex 独有的。合并前建议先看一眼列表确认没有重名冲突。3.4 创建软链接这是最关键的一步。注意rm -rf后面不要加尾部斜杠原因见第 5 节踩坑rm -rf ~/.claude/skills ln -s ~/.kiro/skills ~/.claude/skills rm -rf ~/.codex/skills ln -s ~/.kiro/skills ~/.codex/skills3.5 验证链接echo Kiro: $(ls ~/.kiro/skills/ | wc -l) skills (canonical) echo Claude: $(ls ~/.claude/skills/ | wc -l) skills - $(readlink ~/.claude/skills) echo Codex: $(ls ~/.codex/skills/ | wc -l) skills - $(readlink ~/.codex/skills)期望输出三个数字一致后两个的箭头指向~/.kiro/skillsKiro: 61 skills (canonical) Claude: 61 skills - /Users/you/.kiro/skills Codex: 61 skills - /Users/you/.kiro/skills4. 验证请求三个工具分别加载同一 Skill链接建好只是目录层面通了还得确认三个工具真的能读到并触发。分三层验证。4.1 文件层确认 YAML 在第一行head -5 ~/.kiro/skills/aws-health-check/SKILL.md输出应该以---开头紧跟name和description--- name: aws-health-check description: AWS Health Dashboard 巡检。触发Health Dashboard, AWS Health, scheduled change ---如果第一行不是---Claude Code 会静默忽略这个 skill务必先修。4.2 触发层在工具里说关键词分别在三个工具里输入触发关键词比如「帮我做一次 AWS Health 巡检」观察它是否执行对应流程。三个工具都从各自 skills 目录扫描因为软链接指向同一份文件理论上行为一致。4.3 确认层直接问 AI 用了哪个 skill最直接的验证方式——在对话里问一句「你刚才用了哪个 skill把步骤复述一下」。能准确复述出SKILL.md里的执行流程说明加载成功。这一步比看日志还直观。如果你在 skill 里集成了模型调用验证时可以顺带确认 API 通路。TaoToken 的接入文档在这里接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc 。需要长期跑编码类 skill 或 Agent 的可以看 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding_plan 按用量规划更省心。4.4 一个最小 Skill 骨架如果你还没有现成 skill用这个骨架起手三个工具都能识别--- name: my-first-skill description: 演示用 skill。触发demo, 演示, 测试 skill --- # 演示 Skill ## 触发条件 - demo / 演示 - 测试 skill ## 输入参数 - region默认 us-east-1 - days查询天数默认 30 ## 执行流程 ### Step 1打印环境信息 bash uname -a echo region$regionStep 2输出结果把上一步结果整理成表格返回。写完存到 ~/.kiro/skills/my-first-skill/SKILL.md三个工具立刻都能用。 ## 5. 本篇常见错排查 迁移过程中最容易踩的坑按出现频率排 **YAML frontmatter 缺失。** Claude Code 直接忽略不报错。新 skill 第一件事就是写 YAML别等触发不了才回头查。 **description 写得太泛。** 比如只写「运维工具」AI 语义匹配不上。要把用户可能说的具体关键词塞进去像「Health Dashboard, AWS Health, scheduled change」这种。 **rm -rf path/ 尾部斜杠。** 这是最危险的坑。Shell 遇到尾部斜杠会解析软链接到目标再删等于把主仓库删了。删软链接时永远不加末尾 /。 **工具更新覆盖软链接。** 某些工具升级时会重建自己的 skills 目录把软链接替换成真实目录。备一个恢复脚本出问题跑一下 bash #!/bin/bash set -e MAIN$HOME/.kiro/skills [ ! -d $MAIN ] echo ERROR: $MAIN 不存在 exit 1 fix() { if [ -L $1 ]; then echo OK: $2 - $(readlink $1) elif [ -d $1 ]; then rm -rf $1 ln -s $MAIN $1 echo FIX: $2 重建 else ln -s $MAIN $1 echo FIX: $2 创建 fi } fix $HOME/.claude/skills Claude Code fix $HOME/.codex/skills Codex echo Done存成~/ops/recover-skills-symlink.sh加执行权限chmod x需要时跑一下。Skill 里硬编码绝对路径。换工具或换机器就挂。统一用~或相对路径。多机同步忘了建链接。新机器 clone 完主仓库后别忘了补两条ln -s否则另外两个工具还是读不到。6. 日常维护与版本控制单一数据源建好后日常操作变得极简# 新增——写完即三工具生效 mkdir -p ~/.kiro/skills/my-new-skill vim ~/.kiro/skills/my-new-skill/SKILL.md # 修改——改完即生效 vim ~/.kiro/skills/aws-health-check/SKILL.md # 删除——三工具同时消失 rm -rf ~/.kiro/skills/obsolete-skill强烈建议把主仓库纳入 Git 管理skill 是知识资产值得版本化cd ~/.kiro/skills git init git add . git commit -m init: 61 skills git remote add origin gitgithub.com:your-org/skills-private.git git push -u origin main新机器上恢复git clone gitgithub.com:your-org/skills-private.git ~/.kiro/skills ln -s ~/.kiro/skills ~/.claude/skills ln -s ~/.kiro/skills ~/.codex/skills写 skill 时记住四条原则description 即索引把关键词塞满命令即文档写能直接跑通的渐进式细节从标题到触发到参数到步骤由粗到细考虑容错参数给默认值、危险操作加确认。排查出新问题就追加回 skill让它持续迭代。这套做法跑通后写完一个 skill 三个工具同时可用改完一个 skill 三个工具同时生效再也不用操心同步。如果你还想把 skill 里的模型调用统一管理可以到控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsole 看看 key 和用量配置配合上面的软链接方案整条链路就闭环了。