开发自己的 Claude Code Skills指南

开发自己的 Claude Code Skills 是提升开发效率、固化团队规范的最佳方式。简单来说Skill 就是把你的**“最佳实践”和“重复性指令”**封装成一个可复用的插件。根据最新的 Claude Code 架构2026年开发 Skills 主要有两种路径“零代码自动生成”适合新手和**“手动编写配置”**适合进阶开发者。以下是完整的开发指南️ 核心概念Skill 是什么一个 Skill 本质上是一个包含SKILL.md文件的文件夹。触发机制Claude 会根据你输入的自然语言与 Skill 的description描述进行匹配自动决定是否激活该 Skill。执行逻辑激活后Claude 会读取SKILL.md中的指令Instructions严格按照你定义的步骤执行任务。 方法一零代码自动生成推荐新手如果你不想处理文件格式可以直接使用官方的skill-creator工具通过对话让 AI 帮你生成 Skill。1. 安装创建工具在终端执行npx skills-installerinstallanthropics/claude-code/skill-creator--clientclaude-code2. 启动创建流程在 Claude Code 中输入指令描述你的需求指令示例“创建一个 Skill能够按照公司规范写技术文档要求包含 API 描述、请求参数、返回值、错误码和调用示例。”3. 自动化生成Claude 会引导你确认细节然后自动生成SKILL.md文件并安装到指定目录。 方法二手动开发进阶/团队规范如果你想完全掌控 Skill 的逻辑或者需要为团队开发通用的规范库建议手动创建。1. 目录结构规范一个标准的 Skill 文件夹结构如下以java-code-checker为例java-code-checker/ # 技能目录建议 kebab-case 命名 ├── SKILL.md # 【核心】技能指令文件必须全大写 ├── scripts/ # 【可选】辅助脚本如格式化脚本 │ └── format.sh ├── assets/ # 【可选】资源文件如模板图片 └── reference/ # 【可选】参考文档如公司规范PDF └── style-guide.pdf2. 编写 SKILL.md灵魂文件这是 Skill 的核心分为YAML 元数据和Markdown 指令两部分。示例代码--- name: java-code-checker description: 检查 Java 代码格式问题如命名规范、缩进、大括号位置等。当用户提到“检查代码风格”、“代码审查”或“格式化”时自动触发。 allowed-tools: Read, Bash --- # Java 代码格式审查专家 你是一个严格的 Java 代码审查员负责确保代码符合《阿里巴巴Java开发手册》规范。 ## 核心规则 1. **命名规范** - 类名必须使用 PascalCase - 方法名和变量名必须使用 camelCase - 常量必须使用 UPPER_SNAKE_CASE 2. **格式规范** - 缩进必须为 4 个空格 - 大括号必须独占一行或遵循项目统一风格 ## 工作流程 当用户请求检查代码时 1. 使用 Read 工具读取目标文件。 2. 逐行分析代码对照上述规则进行检查。 3. 生成一份检查报告列出 - **严重问题**必须修复 - **建议优化**非强制 4. 如果发现问题提供修复后的代码片段。 ## 输出示例 **发现 2 个问题** 1. [严重] 第 15 行方法名 GetUser 不符合 camelCase 规范建议改为 getUser。 2. [建议] 第 23 行Import 语句建议按字母顺序排列。 关键点description字段决定了 Claude 什么时候会自动调用这个 Skill一定要写得具体包含用户可能会说的关键词。 安装与部署开发好文件夹后你需要将其安装到 Claude Code 中。1. 个人级安装全局可用将 Skill 文件夹移动到全局目录# Linux/Macmvjava-code-checker ~/.claude/skills/# Windows (PowerShell)Move-Item java-code-checker ~\.claude\skills\2. 项目级安装团队共享将 Skill 放入项目根目录的.claude/skills/下并提交到 Gitmkdir-p.claude/skillsmvjava-code-checker .claude/skills/gitadd.claude/skillsgitcommit-mfeat: add java code checker skill这样团队成员git pull后即可自动拥有该技能。3. 使用命令行工具安装如果你使用npx skills工具# 本地安装测试npx skillsadd--local./java-code-checker-aclaude-code-y 调试与验证1. 验证安装查看已安装的 Skillsnpx skillsls-aclaude-code-l2. 测试触发在 Claude Code 中输入自然语言例如“帮我看看UserService.java的代码风格有没有问题”如果配置正确Claude 会回复“我将使用java-code-checker技能来分析代码…”并执行你定义的步骤。3. 强制触发如果自动触发失败可以使用斜杠命令强制调用/java-code-checker 检查 src/main/java/App.java 常见问题排查问题可能原因解决方案Skill 不触发description写得太模糊在描述中加入用户可能使用的具体词汇如“检查”、“规范”、“格式化”找不到 Skill文件名错误确保核心文件名为SKILL.md全大写文件夹名为kebab-case权限不足缺少工具权限在 YAML 头中添加allowed-tools: Read, Bash, Edit等权限逻辑混乱指令太复杂将复杂逻辑拆分为多个步骤或使用scripts/目录下的外部脚本辅助 总结开发 Skills 的核心在于**“把经验文档化”**。新手用skill-creator对话生成。老手手写SKILL.md利用 YAML 头控制触发逻辑利用 Markdown 正文控制执行细节。团队放入.claude/skills目录并通过 Git 共享。