1. 从自定义命令到技能生态这个项目到底在解决什么问题第一次接触 Claude Code 的 Skill 机制时我的反应是这不就是把 prompt 模板换了个壳吗。但真正用起来、并且把团队里十几个零散脚本逐步迁移过去之后我才意识到它想解决的是一个更底层的问题AI 编程助手的能力边界到底该由谁来定义。早期我们用 Claude Code基本就是聊天窗口里丢需求它给代码我们复制粘贴。后来有了自定义命令custom commands可以把常用的 prompt 固化成一个/xxx指令比如/review做代码审查、/commit生成提交信息。这一步已经省了不少事但痛点也很明显——命令是死的它只能做一件事参数靠手填上下文靠人喂稍微复杂点的流程就得写一长串 prompt。Skill 的出现本质上是把一条命令升级成了一套可被 AI 自主调用的能力包。它不再是你敲一个指令它执行一次而是 AI 在理解任务之后自己判断我现在需要用到某个技能然后去加载对应的说明文档、脚本、资源文件按预设的流程把活干完。这个转变听起来只是交互方式变了实际上是把 AI 从被动应答工具推向了能自主编排工作流的执行体。这个项目适合谁看如果你只是偶尔用 AI 写两行代码那自定义命令够用了。但如果你符合下面任意一条Skill 这套东西值得你花时间啃团队里有大量重复性的工程流程代码审查、发布检查、文档生成、数据清洗想让 AI 接管已经在用自定义命令但发现命令越写越多、越来越难维护想让 AI 在特定领域比如某个内部框架、某套业务规范表现得像个老手而不是通用助手对 AI Agent 的能力编排机制感兴趣想搞清楚技能和工具调用的区别我下面会从设计思路、核心机制、实操落地、踩坑排查四个维度把 Skill 这套东西拆开讲。不是官方文档的复述而是我在实际迁移过程中总结出来的、能直接抄作业的经验。2. 核心设计思路拆解为什么是技能而不是命令2.1 自定义命令的天花板在哪里先说清楚自定义命令的机制才能理解 Skill 为什么要另起炉灶。自定义命令本质上是一个 Markdown 文件放在特定目录下文件名就是命令名文件内容是 prompt 模板。你敲/review系统就把这个文件的内容塞进上下文AI 按里面的指示干活。这个模型简单直接但有几个绕不过去的限制第一命令是扁平的。一个命令对应一个 prompt没法组织成层级结构。当你有二十个命令的时候你只能靠命名前缀来分类比如review-security、review-style管理起来很痛苦。第二命令没有资源概念。如果某个命令需要附带一个脚本、一份参考文档、一个配置模板你只能把这些东西的路径写进 prompt 里让 AI 自己去读。AI 读不读、读得对不对全靠运气。第三命令无法被 AI 主动调用。这是最关键的。命令必须由人触发AI 不会在干活干到一半的时候说我这儿需要调用一下 review 命令。它只能等你敲。第四命令的上下文是一次性的。每次调用都是独立的命令之间没法共享状态、没法串联成流水线。我踩过最典型的一个坑写了个/gen-api命令根据数据库 schema 生成接口代码。但生成之前需要先读 schema 文件、再读项目的接口规范文档、再读几个已有的接口作为风格参考。这些前置动作我全塞进 prompt 里结果 prompt 长得像一篇论文AI 经常读到一半就忘了前面的要求。这就是命令模型的天花板——它把流程压扁成了一段文字。2.2 Skill 的设计哲学能力包 自主编排Skill 的核心思路是把一段 prompt升级成一个结构化的能力包。一个 Skill 通常包含这么几层组成作用类比元数据名称、描述、触发条件告诉 AI 我是谁、我什么时候该被用岗位说明书主说明文档SKILL.md描述这个技能的执行流程、步骤、注意事项操作手册脚本/工具可被调用的具体执行逻辑工具箱资源文件模板、参考文档、配置资料柜关键在于元数据里的描述和触发条件。AI 在接到任务时会先扫一遍所有可用 Skill 的描述判断这个任务需不需要某个技能。如果需要它就把那个技能的说明文档加载进上下文按里面的流程执行。这个过程是 AI 自主发起的不需要人敲命令。这就解决了命令模型的四个死穴技能可以组织成目录结构解决扁平问题、技能自带资源解决资源问题、技能可被 AI 主动调用解决触发问题、技能之间可以互相引用解决串联问题。2.3 为什么这个演进方向是对的我一开始也怀疑搞这么复杂不就是把 prompt 拆成多个文件吗但用下来发现这个拆是有讲究的。上下文窗口是稀缺资源。你不可能把所有流程、所有规范、所有参考文档都塞进一次对话。Skill 的机制是按需加载——AI 判断需要某个技能才把那个技能的文档读进来。这跟人干活是一样的你不会把整本手册背下来而是遇到问题去翻对应章节。能力需要被复用和组合。一个代码审查技能可以被提交前检查流程调用也可以被发布前检查流程调用。如果写成命令你得复制两份写成技能引用一下就行。AI 需要知道自己会什么。这是最容易被忽略的一点。当 AI 面对一个复杂任务时如果它清楚自己有哪些技能可用它就能主动规划我先用 A 技能分析再用 B 技能生成最后用 C 技能校验。这种自我认知能力是命令模型给不了的。我的经验是判断一个流程该不该做成 Skill就看它是不是需要 AI 在合适的时机自己想起来要用。如果永远是人主动触发命令就够了如果需要 AI 在流程中自主判断那就该做成 Skill。3. 核心机制与实操要点一个 Skill 到底长什么样3.1 目录结构与文件组织一个规范的 Skill 目录我实测下来最舒服的组织方式是这样skills/ code-review/ SKILL.md # 主说明文档核心 scripts/ check-style.py # 可执行脚本 resources/ style-guide.md # 参考规范 template.md # 输出模板 api-generator/ SKILL.md scripts/ gen.py resources/ schema-example.jsonSKILL.md是整个技能的大脑它需要包含几个关键部分。我一般按这个结构写--- name: code-review description: 对指定代码文件进行审查检查风格、安全、性能问题。当用户要求审查代码或提交前检查时使用。 --- # 代码审查技能 ## 何时使用 当需要审查代码质量、检查潜在问题时。 ## 执行步骤 1. 读取目标文件内容 2. 对照 resources/style-guide.md 检查风格 3. 运行 scripts/check-style.py 做静态检查 4. 汇总问题按严重程度排序 5. 按 resources/template.md 格式输出 ## 注意事项 - 不要修改原文件只输出审查报告 - 安全问题优先级最高这里有个细节很多人会忽略frontmatter 里的 description 是给 AI 看的不是给人看的。它决定了 AI 在什么情况下会想起这个技能。所以 description 要写得像触发条件而不是功能简介。我见过有人写description: 一个代码审查工具这种写法 AI 很难判断什么时候该用写成当用户要求审查代码或提交前检查时使用命中率就高很多。3.2 触发机制AI 是怎么想起某个技能的这是整个机制里最微妙的部分。AI 不会无缘无故加载技能它依赖两个信号信号一description 的语义匹配。用户说帮我看看这段代码有没有问题AI 扫一遍技能列表发现code-review的描述里有审查代码匹配上了就加载。信号二主文档里的显式引用。一个技能可以在自己的流程里写调用 xxx 技能形成技能链。比如发布检查技能里写先调用 code-review 技能审查变更。我实测下来description 的写法对触发率影响极大。几个心得用当……时使用的句式明确触发场景把用户可能说的口语化表达也写进去比如看看有没有问题检查一下不要写得太宽泛否则会误触发也不要太窄否则该触发时不触发踩坑记录我曾经把某个技能的 description 写成处理数据相关任务结果 AI 在任何涉及数据的场景都想加载它包括只是读个 JSON 文件。后来改成当需要对 CSV 数据进行清洗、去重、格式转换时使用误触发就没了。3.3 脚本与资源的调用方式Skill 里的脚本不是自动执行的而是 AI 在流程中决定要执行时才调用。这一点跟很多人想的不一样——它不是技能一加载脚本就跑而是技能告诉 AI 有这么个脚本AI 判断需要时去跑。所以脚本的写法要注意脚本要能独立运行不依赖对话上下文参数通过命令行传入脚本的输出要结构化最好是 JSON 或清晰的文本方便 AI 解析脚本要幂等重复执行不出错因为 AI 可能会重试资源文件参考文档、模板则是被 AI 读取后作为上下文使用的。这里有个技巧资源文件不要写太长。AI 读进来是要占上下文的一份 5000 字的规范文档读进去可能就把其他重要信息挤掉了。我一般把资源文件控制在 1000 字以内只放最关键的规则。3.4 技能之间的组合与依赖Skill 真正强大的地方在于组合。我举个实际例子我们团队有个新接口开发的完整流程拆成了三个技能schema-reader读取数据库 schema输出接口需要的字段定义api-generator根据字段定义生成接口代码code-review审查生成的代码主流程技能new-api的文档里写## 执行步骤 1. 调用 schema-reader 技能获取字段定义 2. 将字段定义传给 api-generator 技能生成代码 3. 调用 code-review 技能审查生成的代码 4. 汇总结果这样 AI 接到帮我开发一个新接口的任务时会自己把这三个技能串起来跑。整个过程我只说了一句话它自己完成了读取、生成、审查、汇总。这种组合能力是命令模型完全做不到的。命令只能一个个敲技能可以编排成流水线。4. 完整实操从零搭一个可用的 Skill4.1 环境准备与目录初始化假设你已经装好了 Claude Code第一步是确认技能目录的位置。不同版本的默认路径可能不同我一般用项目级目录方便跟代码一起版本管理mkdir -p .claude/skills cd .claude/skills项目级的好处是技能跟着项目走团队成员拉下代码就自动有了。全局级放在用户目录下适合放个人通用技能比如生成提交信息这种跟具体项目无关的。我建议新手先从项目级开始因为项目级技能可以引用项目里的文件调试起来直观。4.2 写第一个技能以提交信息生成为例这个技能足够简单适合入门。先建目录mkdir -p .claude/skills/commit-msg然后写SKILL.md--- name: commit-msg description: 当用户要求生成提交信息、写 commit message、或提交代码时使用。 --- # 提交信息生成技能 ## 执行步骤 1. 运行 git diff --staged 查看暂存的变更 2. 分析变更的类型新增功能、修复、重构、文档等 3. 按 Conventional Commits 规范生成提交信息 4. 输出格式type(scope): description ## 类型对照 - feat: 新功能 - fix: 修复 - refactor: 重构 - docs: 文档 - test: 测试 - chore: 杂项 ## 注意事项 - description 用中文不超过 50 字 - 如果变更涉及多个类型选最主要的那个 - 不要编造变更内容只根据 diff 生成写完直接测试在对话里说帮我生成提交信息AI 应该会自动加载这个技能跑git diff然后给出符合规范的提交信息。这里有个关键点技能不需要注册放在目录里就能被识别。这是它比命令方便的地方——命令有时候还要配置技能是放进去就生效。4.3 加入脚本让技能能执行具体逻辑光靠 prompt 的技能能力有限。真正有用的是能跑脚本的技能。我拿代码风格检查举例。先写脚本scripts/check_style.py#!/usr/bin/env python3 import sys import json import re def check_style(filepath): issues [] with open(filepath, r, encodingutf-8) as f: lines f.readlines() for i, line in enumerate(lines, 1): # 检查行尾空格 if line.rstrip(\n) ! line.rstrip(): issues.append({ line: i, type: trailing-whitespace, message: 行尾有多余空格 }) # 检查行长度 if len(line.rstrip(\n)) 100: issues.append({ line: i, type: line-too-long, message: f行长度 {len(line.rstrip())} 超过 100 }) return issues if __name__ __main__: filepath sys.argv[1] result check_style(filepath) print(json.dumps(result, ensure_asciiFalse, indent2))然后在SKILL.md里引用它## 执行步骤 1. 确认目标文件路径 2. 运行 python scripts/check_style.py 文件路径 3. 解析脚本输出的 JSON 4. 按严重程度整理问题输出报告脚本输出 JSON 是关键因为 AI 解析结构化数据比解析自然语言文本准确得多。我试过让脚本直接输出第 5 行有行尾空格AI 有时候会漏读输出 JSON 后几乎不会漏。4.4 参数传递与动态内容技能执行时经常需要接收参数比如审查哪个文件。这个参数怎么传有两种方式。一种是从对话里提取用户说审查一下 utils.pyAI 从这句话里提取出utils.py作为参数。这依赖 AI 的理解能力一般够用。另一种是在技能文档里定义参数格式## 参数 - 目标文件从用户输入中提取如果没指定询问用户 - 检查级别默认 standard可选 strict我实测下来对于简单参数靠 AI 提取就够了对于复杂参数比如多个文件、配置选项最好在文档里明确定义格式减少歧义。4.5 调试技能的方法技能不生效是新手最常遇到的问题。我的排查顺序是这样的第一步确认技能被识别了。在对话里问 AI 你现在有哪些技能可用它会列出加载到的技能。如果列表里没有你的技能说明目录位置不对或文件格式有问题。第二步确认 description 能匹配。如果技能在列表里但你说相关的话它不加载多半是 description 写得不好。试着用 description 里的原词去触发。第三步确认流程能跑通。如果技能加载了但执行出错看是脚本报错还是 AI 理解偏差。脚本问题直接命令行跑一遍理解偏差就细化文档里的步骤描述。第四步看上下文是否超限。如果技能加载后 AI 表现异常比如忘记前面的要求可能是技能文档太长把上下文挤爆了。精简文档把非核心内容移到资源文件里按需读取。我踩过最坑的一次技能文档里写了一大段背景说明结果 AI 每次加载都先读这段背景把真正重要的执行步骤挤到了后面导致它经常跳过步骤直接输出。后来把背景说明删了只留执行步骤问题就没了。技能文档要像操作清单不是设计文档。5. 常见问题与排查技巧实录5.1 技能不触发怎么办这是最高频的问题。我整理了一个排查表现象可能原因解决方法技能列表里没有目录位置错误确认在.claude/skills/下且每个技能有独立子目录技能列表里有但不触发description 不匹配用 description 里的关键词测试或改写 description触发但执行错误步骤描述不清细化步骤每步一个明确动作触发但结果不对资源文件太长精简资源只留关键规则时好时坏上下文超限减少技能文档长度拆分技能有个隐蔽的坑技能名和目录名不一致。frontmatter 里的name和目录名最好保持一致否则可能出现识别混乱。我见过有人目录叫reviewname 写code-review结果触发行为很诡异。5.2 脚本执行失败的排查脚本失败一般有三类原因路径问题。脚本里用了相对路径但执行时的工作目录不是技能目录。解决方法是脚本里用绝对路径或者从环境变量读取项目根目录。依赖问题。脚本依赖的库没装。这个最直接看报错信息装依赖就行。但要注意技能脚本的依赖最好写进项目的依赖文件里否则换台机器就挂。权限问题。脚本没有执行权限。chmod x scripts/xxx.py解决。我一般会在技能文档里加一句如果脚本执行失败输出错误信息并停止不要尝试绕过。这样 AI 不会自作主张地跳过脚本导致结果不可靠。5.3 技能之间冲突怎么处理当技能多了之后会出现两个技能都想处理同一个任务的情况。比如code-review和security-check都可能在检查代码时被触发。处理原则是让 description 的边界清晰。code-review管风格和通用问题security-check只管安全漏洞。如果确实有重叠就在主流程技能里显式指定调用顺序避免 AI 自己纠结。还有一种冲突是技能 A 的流程里调用了技能 B但 B 又调用了 A形成循环。这个要在设计时就避免技能依赖应该是单向的、有层次的。5.4 性能与上下文优化技能用多了最明显的感觉是变慢和变笨。原因通常是上下文被塞满了。我的优化经验技能文档控制在 500 字以内超过就拆资源文件按需读取不要一加载技能就把所有资源读进来脚本输出要精简只输出 AI 需要的信息不要 dump 一大堆日志定期清理不用的技能技能列表越长AI 判断用哪个的负担越重有个反直觉的点技能不是越多越好。我一开始把能拆的都拆成技能结果 AI 经常在多个相似技能之间犹豫反而降低了效率。后来合并了一些保持每个技能职责单一且边界清晰效果才好。6. 从命令到生态这套机制真正改变了什么6.1 对个人开发者的价值对个人来说Skill 最大的价值是把经验变成了可复用的资产。以前你调教 AI 写代码靠的是每次对话里反复强调我们项目用这个规范这个函数要这么写。这些经验散落在对话历史里换个会话就没了。做成技能之后这些经验被固化下来AI 每次都能按同样的标准干活。我自己的感受是用了技能之后跟 AI 的沟通成本大幅下降。以前要写一大段 prompt 才能让它理解需求现在一句话它自己知道该调用哪些技能、按什么流程走。6.2 对团队协作的价值团队场景下Skill 解决的是**规范落地**的问题。代码规范写在文档里没人看写在技能里AI 每次审查都按这个标准来。接口规范写在 wiki 里新人记不住做成技能AI 生成代码时自动遵守。更关键的是技能是可以版本管理的。规范变了改技能文档提交团队成员拉下来就生效。这比发个通知说规范改了靠谱得多。6.3 技能生态的演进方向从命令到技能我看到的演进逻辑是AI 的能力边界正在从模型本身转移到模型 技能生态。模型的能力是通用的、有限的技能生态是专用的、可无限扩展的。一个通用模型加上一套精心设计的技能在特定领域的表现可以超过一个更强的通用模型。这也是为什么我觉得这套机制值得投入时间研究。它不是又一个AI 工具而是一种组织 AI 能力的方式。理解了这种方式你就能把 AI 真正变成自己工作流的一部分而不是一个需要反复调教的聊天机器人。最后分享一个我最近在用的技巧把技能当成给未来自己的文档来写。你今天调教 AI 解决了一个问题明天可能还会遇到同样的问题。与其下次重新调教不如现在就把它写成技能。写得多了你会发现自己的AI 工作流越来越顺越来越像一套真正的工具链而不是一堆零散的 prompt。这个方向后续还能怎么扩展我目前在尝试的是把技能和项目的 CI 流程打通让 AI 在提交代码时自动跑一遍技能链把审查结果作为提交的一部分。另外也在探索技能的参数化——同一个技能通过不同参数适配不同项目减少重复。这些还在摸索阶段等跑通了再单独写一篇。