Claude Code Skills |2开发进阶指南2026最新一、创建第一个 Skill1.1 最小结构1.2 创建步骤1.3 SKILL.md 基本格式1.4 测试 Skill二、SKILL.md 详解2.1 完整结构2.2 Frontmatter 字段速查表2.3 调用控制配置场景1仅手动调用敏感操作场景2仅 AI 调用背景知识场景3双向调用默认2.4 工具访问限制只读模式文件操作模式2.5 Markdown 内容结构三、参数与动态内容3.1 参数传递使用 $ARGUMENTS 占位符使用索引访问参数3.2 命令注入语法示例获取当前分支工作流程3.3 实战案例API 文档生成器四、管理多个 Skills4.1 目录结构说明4.2 使用管理脚本4.3 版本控制建议4.4 手动管理命令五、最佳实践5.1 编写黄金法则法则1Description 是触发器不是文档法则2专注单一功能法则3避免过度预判5.2 安全注意事项敏感信息处理命令执行安全5.3 性能优化优化 Description使用引用文件控制技能数量5.4 常见陷阱六、速查表6.1 命令速查6.2 Windows 命令速查6.3 目录结构速查6.4 Skills 参数变量在 SKILL.md 中使用6.5 Windows 环境变量在命令行/脚本中使用6.6 常见错误速查七、学习资源官方资源社区 Skills 资源MCP 扩展与 Skills 不同是另一套体系持续学习建议一、创建第一个 Skill1.1 最小结构创建一个 Skill 最简单的方式只需要一个文件。C:\Users\用户名\.claude\skills\my-first-skill\ └── SKILL.md # 只需要这一个文件1.2 创建步骤REM 1. 创建目录 mkdir %USERPROFILE%\.claude\skills\hello-skill REM 2. 创建 SKILL.md cd /d %USERPROFILE%\.claude\skills\hello-skill notepad SKILL.md1.3 SKILL.md 基本格式--- name: hello-skill description: 简单的问候技能 --- # Hello Skill ## 目的 这是一个简单的示例技能用于学习 Skills 的基本结构。 ## 执行指令 1. 向用户问好 2. 询问用户需要什么帮助 3. 提供友好的回应 ## 示例 用户输入/hello-skill AI 响应你好我是 Hello Skill很高兴为你服务1.4 测试 Skill保存文件重启 Claude Code测试/hello-skill二、SKILL.md 详解2.1 完整结构一个完整的 SKILL.md 包含两部分--- ← YAML Frontmatter 开始 name: my-skill ← 基本信息 description: 功能描述 argument-hint: [参数1] [参数2] disable-model-invocation: false ← 调用控制 user-invocable: true allowed-tools: [] ← 工具限制 --- ← YAML Frontmatter 结束 # Skill 内容Markdown ← Markdown 内容开始 ## 目的 说明用途... ## 执行指令 1. 步骤1 2. 步骤2 ## 示例 使用示例...2.2 Frontmatter 字段速查表字段类型必需说明默认值namestring否技能名称小写字母、数字、连字符最多64字符目录名descriptionstring推荐功能描述Claude 用此判断何时使用第一段内容argument-hintstring否参数提示如[issue-number]无disable-model-invocationboolean否禁止 AI 自动调用falseuser-invocableboolean否是否在/菜单中显示trueallowed-toolsarray否允许使用的工具列表无限制2.3 调用控制配置场景1仅手动调用敏感操作---name:deploy-proddescription:部署到生产环境disable-model-invocation:true# AI 不能自动调用user-invocable:true# 用户可以手动调用---适用场景部署到生产环境删除数据库发送邮件通知其他敏感操作场景2仅 AI 调用背景知识---name:coding-standardsdescription:公司编码规范disable-model-invocation:false# AI 可以自动加载user-invocable:false# 不在菜单中显示---适用场景编码规范项目约定背景知识参考文档场景3双向调用默认---name:code-reviewdescription:代码审查# 默认配置两者都可以调用---适用场景代码审查文档生成测试编写大多数常规操作2.4 工具访问限制只读模式---name:code-explorerdescription:探索代码库只读allowed-tools:-readFile-readMultipleFiles-listDirectory-grepSearch-fileSearch---文件操作模式---name:code-refactordescription:代码重构allowed-tools:-readFile-readMultipleFiles-listDirectory-grepSearch-fileSearch-strReplace-fsWrite---2.5 Markdown 内容结构推荐的章节结构# Skill 名称 ## 目的Purpose 说明这个 Skill 的用途和价值。 ## 触发条件Trigger Conditions 列出会触发此 Skill 的关键词或场景。 ## 执行指令Instructions 1. 第一步操作 2. 第二步操作 3. 第三步操作 ## 示例Examples **示例1** - 用户输入/my-skill example - AI 响应执行相应操作... ## 支持文件Supporting Files 如果需要引用其他文件 - scripts/process.py: 数据处理脚本 - references/api-spec.md: API 规范文档三、参数与动态内容3.1 参数传递使用 $ARGUMENTS 占位符---name:fix-issuedescription:修复 GitHub Issueargument-hint:[issue-number]---# Fix GitHub Issue修复 Issue#$ARGUMENTS遵循以下步骤1. 查看 Issue 详情 2. 分析问题根源 3. 实现修复方案 4. 编写测试用例 5. 提交 PR使用方法/fix-issue 123Claude 会将$ARGUMENTS替换为123。使用索引访问参数---name:migrate-componentargument-hint:[component-name][from-framework][to-framework]---# Migrate Component将组件 $0 从 $1 迁移到 $2。# 或使用完整语法将组件 $ARGUMENTS[0]从 $ARGUMENTS[1]迁移到 $ARGUMENTS[2]。使用方法/migrate-component Button React Vue变量值$0或$ARGUMENTS[0]Button$1或$ARGUMENTS[1]React$2或$ARGUMENTS[2]Vue$ARGUMENTSButton React Vue3.2 命令注入语法!command执行命令并将输出替换到 Skill 内容中。示例获取当前分支---name:git-status-summarydescription:Git 状态摘要---# Git Status Summary## 当前分支!gitbranch--show-current## 未提交的更改!gitstatus--short## 最近的提交!gitlog--oneline-5 请分析当前 Git 状态并提供建议。工作流程Skill 被触发所有!command立即执行命令输出替换占位符Claude 接收完整渲染的内容⚠️注意这是预处理不是 Claude 执行的命令。3.3 实战案例API 文档生成器---name:api-docdescription:生成 API 文档argument-hint:[method][path]---# API Documentation Generator## 参数-HTTP 方法$0-API 路径$1## 生成内容1. API 概述 2. 请求参数表格 3. 响应示例 4. 多语言代码示例cURL、JavaScript、Python## 使用方法/api-doc POST /users四、管理多个 Skills4.1 目录结构说明推荐目录结构C:\Users\用户名\.claude\skills\ # 已安装的技能带前缀 ├── ccs-anth-pdf\ # 来自 anthropics ├── ccs-anth-docx\ # 来自 anthropics ├── ccs-sup-test-driven-development\ # 来自 superpowers ├── ccs-jeff-react-expert\ # 来自 jeffallan └── my-custom-skill\ # 自己创建的不需要前缀 C:\Users\用户名\claude-skills-repos\ # 仓库缓存目录不要删除 ├── anthropics-skills\ ├── superpowers\ └── jeffallan-skills\前缀说明ccs-表示通过脚本安装的技能anth-、sup-、jeff-表示来源仓库自己创建的技能不需要前缀4.2 使用管理脚本第一篇文章提供了完整的skills-manager.cmd脚本功能包括✅ 一键安装三大仓库✅ 一键更新自动 git pull✅ 一键卸载✅ 查看已安装列表使用方法skills-manager.cmd install # 安装 skills-manager.cmd update # 更新 skills-manager.cmd uninstall # 卸载 skills-manager.cmd list # 查看列表详见《Claude Code Skills 安装使用完全指南》3.3 节4.3 版本控制建议团队项目将项目级 Skills 提交到 GitREM .gitignore 不要忽略 .claude 目录 REM !.claude/skills/ git add .claude\skills\ git commit -m feat: add team skills git push创建 INSTALLED.txt 记录已安装的 Skills 来自 anthropics/skills - ccs-anth-pdf (v1.0, 2026-02-15) - ccs-anth-docx (v1.0, 2026-02-15) 来自 obra/superpowers - ccs-sup-test-driven-development (v2.0, 2026-02-10) - ccs-sup-code-review (v2.0, 2026-02-10) 自定义 Skills - my-workflow (v1.0, 2026-02-20)4.4 手动管理命令REM 查看已安装技能 dir /B %USERPROFILE%\.claude\skills REM 删除单个技能 rmdir /S /Q %USERPROFILE%\.claude\skills\技能名 REM 删除所有脚本安装的技能 for /d %%i in (%USERPROFILE%\.claude\skills\ccs-*) do rmdir /S /Q %%i REM 打开技能目录 explorer %USERPROFILE%\.claude\skills五、最佳实践5.1 编写黄金法则法则1Description 是触发器不是文档❌错误description:这是一个复杂的工具用于处理各种文档格式包括 PDF、Word、Excel 等支持转换、合并、拆分等多种操作...✅正确description:处理文档转换和合并原因Claude 使用 description 判断何时触发简洁的关键词更有效。法则2专注单一功能❌错误---name:super-skilldescription:做所有事情---支持-代码生成-测试编写-文档生成-部署-监控✅正确---name:commit-messagedescription:生成 Git 提交信息---# Commit Message Generator根据代码变更生成规范的提交信息。原因专注的 Skill 更可靠、更易维护、触发更精准。法则3避免过度预判❌错误如果用户想要 A则执行 X 如果用户想要 B则执行 Y 如果用户想要 C则执行 Z 如果用户没说清楚则询问...✅正确执行以下步骤 1. 分析需求 2. 实施方案 3. 验证结果原因让 Claude 根据实际情况灵活处理。5.2 安全注意事项敏感信息处理❌错误---name:deploy---使用以下凭证部署 API_KEYsk-1234567890abcdef DATABASE_URLpostgresql://user:passwordhost/db✅正确---name:deploy---部署步骤 1. 确保环境变量已设置-%API_KEY%-%DATABASE_URL% 2. 运行部署脚本命令执行安全❌危险!%ARGUMENTS%✅安全!gh pr view %ARGUMENTS% --json title5.3 性能优化优化 Description使用简洁的关键词避免冗长的描述专注核心功能不超过 50 字符使用引用文件❌不推荐---name:api-guide---[10000 行 API 文档内容...]✅推荐---name:api-guide---# API Guide核心指令...## 详细文档需要时查看 references\api-spec.md控制技能数量个人使用10-20 个团队项目5-15 个总计不超过 30 个5.4 常见陷阱陷阱问题解决方案Description 过于复杂触发不准确简洁关键词过度预判逻辑混乱让 Claude 灵活处理忽略安全敏感信息泄露使用环境变量文件过大加载慢使用引用文件同名冲突随机选择添加前缀或只装一个六、速查表6.1 命令速查命令说明/skills列出所有可用的 Skills/skill-name手动调用指定 Skill/skill-name arg1 arg2带参数调用 Skill/context查看当前上下文使用情况/permissions管理工具权限6.2 Windows 命令速查命令说明示例mkdir创建目录mkdir %USERPROFILE%\.claude\skills\my-skilldir列出目录dir %USERPROFILE%\.claude\skillstype查看文件type SKILL.mdxcopy复制目录xcopy /E /I 源 目标rmdir删除目录rmdir /S /Q my-skillcd /d切换目录cd /d D:\Projectsexplorer打开文件夹explorer %USERPROFILE%\.claude\skills6.3 目录结构速查个人级配置C:\Users\用户名\.claude\skills\ ├── skill-1\ │ ├── SKILL.md │ ├── scripts\ # 可选 │ ├── templates\ # 可选 │ └── references\ # 可选 └── skill-2\ └── SKILL.md项目级配置D:\Projects\项目文件夹\ ├── .claude\ │ └── skills\ │ └── project-skill\ │ └── SKILL.md ├── src\ └── package.json6.4 Skills 参数变量在 SKILL.md 中使用变量说明示例$ARGUMENTS所有参数/skill a b c→a b c$0第一个参数/skill a b c→a$1第二个参数/skill a b c→b$2第三个参数/skill a b c→c!command命令输出注入!git branch --show-current注意这些是 Skills 的参数变量用$符号。6.5 Windows 环境变量在命令行/脚本中使用变量说明示例值%USERPROFILE%用户主目录C:\Users\张三%USERNAME%用户名张三%CD%当前目录D:\Projects%TEMP%临时目录C:\Users\张三\AppData\Local\Temp注意这些是 Windows 系统环境变量用%符号在 CMD/脚本中使用。6.6 常见错误速查错误原因解决方案Skill 不触发description 不明确使用简洁关键词触发过于频繁description 太宽泛更精确的描述看不到所有 Skills超出字符预算减少技能数量或简化内容权限问题未设置权限检查/permissions命名冲突同名 Skill重命名或只装一个参数传递失败argument-hint 配置错误检查$ARGUMENTS语法七、学习资源官方资源资源链接说明Anthropic 官方文档docs.anthropic.comSkills 概念、配置指南Anthropic Skills 仓库GitHub官方维护的 SkillsAgent Skills 标准GitHubSkills 标准规范社区 Skills 资源资源Stars说明superpowers29,000工作流/TDD/调试/代码审查jeffallan/claude-skills2,70065个语言/框架技能awesome-claude-skills16,500300 高质量技能收录MCP 扩展与 Skills 不同是另一套体系资源Stars说明awesome-mcp-servers80,3003,000 个MCP服务器收录提示MCPModel Context Protocol是另一套扩展体系与 Skills 不同。如需了解 MCP请参考专门的 MCP 教程。持续学习建议每周任务使用 3-5 个技能记录体验发现改进点每月任务更新技能仓库清理不用的技能优化性能