ClaudeCodeSkill实战：构建可复用指令系统的技术指南
初次接触ClaudeCode的那段时间，我几乎每天都在重复同一件事：告诉AI要用什么编码风格、遵循什么规范。这些重复的指令占据了大量token，也让对话变得冗长。直到我发现Skill这个机制，一切才真正改变。
问题的本质：为什么你的Claude总在"听不懂"
在使用ClaudeCode时，有一个痛点几乎每个开发者都会遇到：每次对话都要重新说明项目规范。Vue项目的style属性写法、React组件的命名约定、或者某段历史遗留代码的特殊处理方式——这些信息你可能要重复上百次。
Skill的核心价值就体现在这里。它本质上是一个文件夹，包含SKILL.md文件，通过预置指令让Claude在特定场景下自动加载对应配置。与CLAUDE.md的全局加载不同，Skill采用按需加载策略，不激活时不占用任何上下文空间。
技术架构：Skill的存放位置与调用机制
Skill支持三种存放位置，开发者应根据使用范围选择合适的层级。个人级Skill存放在~/.claude/skills/
调用方式分为手动和自动两种。手动调用通过/命令前缀触发，自动调用则依赖description字段的语义匹配——当Claude判断用户意图与某个Skill的描述相符时，会自动加载该Skill。
核心要素：description不是摘要而是触发器
编写Skill的核心要点在于理解description字段的真实作用。它不是对Skill功能的概括，而是触发条件的集合。错误的写法是"这是一个代码生成工具"，正确的写法是"生成Vue3组合式组件。当用户要求创建页面、组件或Vue文件时触发"。
这个区别至关重要。把Claude当作你的合伙人而不是工具，说明书越详细，合伙人越能准确执行。触发词和使用场景是description编写的两个核心维度。
工程实践：500行限制与文件拆分策略
当Skill内容超过500行时，必须进行拆分。标准做法是在SKILL.md同目录下创建template、examples、scripts等子目录存放参考资料，在主文件中通过相对路径引用。这种方式既保持了SKILL.md的核心指令简洁，又为复杂场景提供了充足的扩展空间。
动态注入是另一个关键技术。`!`command``语法允许在Skill加载前执行shell命令，将输出结果注入到提示词。常见的pr-review场景中，可以先用gitdiff获取变更内容，再基于实际diff进行代码审查。
参数传递：让Skill真正可复用
$ARGUMENTS变量实现了Skill的参数化调用。调用/fix-issue42时，$ARGUMENTS会被替换为42。也可以使用$0、$1按位置获取单个参数。配合步骤编号，Claude能够严格按照预定顺序执行任务流程。
对于有副作用的操作（部署、发送消息等），强烈建议添加disable-model-invocation:true配置，防止Claude在未经确认的情况下擅自执行关键操作。