Claude Skills 创建完全指南

Claude Skills 创建完全指南从零开始手把手教你创建、调试、发布自己的 Claude Skill适用于所有 Claude 客户端Windsurf、Claude Desktop、Claude Code 等目录一、Skill 是什么二、核心概念三、目录结构详解四、SKILL.md 详解五、实战从零创建一个 CSS 美化 Skill六、进阶技巧七、发布与分享八、常见问题 FAQ一、Skill 是什么Skill 是 Claude 的能力扩展模块。你可以把它理解为给 AI 写的岗前培训手册——它把一个通用 AI 变成某个领域的专家。类比概念类比Skill一本岗位操作手册SKILL.md手册正文description手册封面的简介决定什么时候翻开这本手册references/手册附录按需查阅scripts/手册附带的工具箱assets/手册附带的素材包Skill 能提供什么专业工作流— 多步骤的领域操作流程工具集成— 特定文件格式或 API 的操作指令领域知识— 公司规范、数据库 schema、业务逻辑复用资源— 脚本、模板、素材二、核心概念2.1 触发机制Skill 的触发完全依赖description字段。Claude 会根据用户的请求匹配所有已安装 Skill 的 description决定是否激活某个 Skill。用户说帮我美化这个页面 ↓ Claude 扫描所有 Skill 的 description ↓ 匹配到 css-beautify 的 description 中有 美化页面、优化 CSS 样式 ↓ 加载 css-beautify 的 SKILL.md body ↓ Claude 按照 SKILL.md 中的指令执行关键点什么时候触发必须写在description里写在 SKILL.md 正文里没用因为正文是触发后才加载的。2.2 渐进式加载三层架构这是 Skill 设计的核心思想——上下文窗口是公共资源不能浪费。┌─────────────────────────────────────────────────┐ │ 第 1 层元数据name description │ │ 状态始终在上下文中 │ │ 大小~100 词 │ │ 作用触发判断 │ ├─────────────────────────────────────────────────┤ │ 第 2 层SKILL.md 正文 │ │ 状态Skill 被触发后才加载 │ │ 大小建议 5000 词500 行以内 │ │ 作用核心工作流和指令 │ ├─────────────────────────────────────────────────┤ │ 第 3 层Bundled Resources │ │ 状态Claude 判断需要时才读取 │ │ 大小无限制 │ │ 作用详细参考文档、脚本、素材 │ └─────────────────────────────────────────────────┘2.3 自由度匹配不同类型的任务需要不同程度的管控力自由度适用场景Skill 中怎么写例子高多种方案都行依赖上下文文字指引、原则性描述“选择合适的动画效果”中有偏好模式允许变通伪代码、带参数的模板“卡片 hover 用 translateY(-2px) shadow 增强”低操作脆弱、一致性要求高具体脚本、固定参数“PDF 旋转必须用 scripts/rotate_pdf.py”经验法则想象 Claude 在走一条路——窄桥需要护栏低自由度空旷草原随便走高自由度。三、目录结构详解my-skill/ ├── SKILL.md # [必须] 核心文件 └── [可选资源] ├── scripts/ # 可执行脚本 ├── references/ # 参考文档 └── assets/ # 输出用素材3.1 SKILL.md必须唯一的必须文件。包含YAML frontmatternamedescriptionMarkdown 正文工作流指令3.2 scripts/可选放可执行脚本Python/Bash 等。什么时候用同一段代码反复被重写需要确定性的可靠结果不能让 AI 每次现写例子scripts/ ├── rotate_pdf.py # PDF 旋转脚本 ├── optimize_image.sh # 图片压缩脚本 └── validate_schema.py # Schema 校验脚本优势脚本可以直接执行不需要加载到上下文中极其省 token。3.3 references/可选放参考文档——需要时才读取的详细信息。什么时候用数据库 schema 文档API 文档公司业务规范详细的操作指南例子references/ ├── animations.md # 动画 CSS 代码集合 ├── color-palettes.md # 配色方案 └── api-docs.md # API 接口文档最佳实践超过 10000 词的文件在 SKILL.md 中提供 grep 搜索关键词信息不要同时出现在 SKILL.md 和 references 中去重超过 100 行的文件顶部加目录3.4 assets/可选放输出用素材——不需要读进上下文直接用在输出中。什么时候用项目模板boilerplateLogo、图标、字体PPT/Word 模板前端模板代码例子assets/ ├── logo.png ├── template.pptx └── hello-world/ # 前端项目脚手架 ├── index.html ├── style.css └── app.js3.5 不要放的文件以下文件绝对不要创建❌README.md— Skill 是给 AI 用的不需要人类 README❌CHANGELOG.md— 没有意义❌INSTALLATION_GUIDE.md— 不需要❌QUICK_REFERENCE.md— 信息放 SKILL.md 或 references 就行四、SKILL.md 详解4.1 完整结构--- name: my-skill-name description: 做什么 什么时候触发。尽量详细、覆盖所有使用场景。 --- # Skill 标题 ## 工作流 [核心步骤] ## 规则/原则 [必须遵守的约束] ## 快速参考 [常用代码片段/模板] ## 进阶参考 [链接到 references/ 下的文件]4.2 Frontmatter 写法Frontmatter 只需要两个字段---name:css-beautifydescription:这里写什么决定了 Skill 什么时候被触发...---name用kebab-case小写短横线简短、有描述性好的css-beautify、pdf-editor、vue-component-gen坏的my-skill、tool1、newdescription最重要这是整个 Skill 最关键的部分。写得不好 Skill 永远不会被触发。模板[做什么]。[什么时候用覆盖所有触发场景]。好的 descriptiondescription:通用前端 CSS 美化与样式优化。当用户要求美化页面、 优化 CSS 样式、添加动画效果、改善布局、实现视觉特效、 或对现有页面进行 UI 升级时使用。覆盖场景包括 (1) CSS 动画与过渡效果 (2) 现代布局技巧(Grid/Flexbox) (3) 响应式设计 (4) 微交互与 hover 效果 (5) 配色与排版优化 (6) 毛玻璃/渐变/阴影等视觉特效 (7) 暗色模式适配。坏的 description# 太短触发范围太窄description:CSS 样式美化工具# 太模糊description:帮助前端开发# 把触发条件写在正文里没用正文触发后才加载description:前端工具4.3 正文写法原则原则 1只写 AI 不知道的AI 已经知道怎么写 CSS、怎么用 Flexbox。你不需要教它基础知识。要写的你的偏好“动画时长用 200-400ms”你的项目约束“用 CSS 变量统一管理”具体的代码模板“卡片 hover 效果用这个”工作流“先诊断 → 再确定方向 → 再实施”不要写的“CSS 是层叠样式表”“Flexbox 是一种布局方式”“animation 属性可以…”原则 2用祈使句# 好的 - 使用 CSS 变量统一管理颜色 - 动画时长控制在 200-400ms - 优先用 CSS-only 方案 # 坏的 - CSS 变量是一种管理颜色的方式 - 建议动画时长在 200-400ms 之间 - 你可以考虑使用 CSS-only 方案原则 3代码示例 文字描述# 好的直接给代码 ### 卡片 hover 效果 ​css .card:hover { box-shadow: var(--shadow-lg); transform: translateY(-2px); } ​ # 坏的只有文字 ### 卡片 hover 效果 鼠标悬浮时增加阴影深度并轻微上移 用 box-shadow 和 transform 实现...原则 4引用 references 文件在 SKILL.md 末尾或相关章节中引用## 进阶参考 - **动画食谱**: 详见 [references/animations.md](references/animations.md) - **配色方案**: 详见 [references/color-palettes.md](references/color-palettes.md)Claude 看到这些链接后会在需要时自行决定是否读取。五、实战从零创建一个 CSS 美化 SkillStep 1明确用例先想清楚用户会怎么用“帮我美化这个页面”“这个表格太丑了优化一下”“给这个按钮加个 hover 效果”“页面缺少层次感帮我调一下”“加个入场动画”Step 2创建目录mkdir-p~/.claude/skills/css-beautify/referencesStep 3编写 SKILL.md创建~/.claude/skills/css-beautify/SKILL.md--- name: css-beautify description: 通用前端 CSS 美化与样式优化。当用户要求美化页面、优化 CSS 样式、添加动画效果、改善布局、实现视觉特效、或对现有页面进行 UI 升级时使用。覆盖场景包括(1) CSS 动画与过渡效果 (2) 现代布局技巧(Grid/Flexbox) (3) 响应式设计 (4) 微交互与 hover 效果 (5) 配色与排版优化 (6) 毛玻璃/渐变/阴影等视觉特效 (7) 暗色模式适配。 --- # CSS 美化指南 当用户请求前端样式优化时遵循以下流程。 ## 工作流 1. **诊断现状** — 阅读现有样式代码识别问题 2. **确定方向** — 后台系统偏简洁克制C 端偏活泼大胆 3. **实施优化** — 最小改动原则 4. **细节打磨** — 过渡动画、hover 反馈、间距微调 ## 核心原则 - **最小侵入**: 不重构已有结构只增强视觉效果 - **一致性**: 使用 CSS 变量统一管理颜色/间距/圆角 - **层次感**: 通过阴影、透明度、字号对比建立视觉层级 - **动效克制**: 动画时长 200-400ms缓动用 cubic-bezier ## CSS 变量模板 ​css :root { --primary: #4f46e5; --primary-light: #818cf8; --bg: #ffffff; --bg-secondary: #f8fafc; --text-primary: #1e293b; --text-secondary: #64748b; --border: #e2e8f0; --radius-md: 8px; --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05); --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1); --ease-out: cubic-bezier(0.16, 1, 0.3, 1); } ​ ## 进阶参考 - **动画食谱**: 详见 [references/animations.md](references/animations.md) - **配色方案**: 详见 [references/color-palettes.md](references/color-palettes.md)Step 4编写 references 文件创建references/animations.md放入常用的 keyframes、微交互代码。创建references/color-palettes.md放入精选配色方案。具体内容参考前面已创建的文件Step 5验证确认目录结构find~/.claude/skills/css-beautify-typef应该看到~/.claude/skills/css-beautify/SKILL.md ~/.claude/skills/css-beautify/references/animations.md ~/.claude/skills/css-beautify/references/color-palettes.mdStep 6测试重新打开一个 Claude 对话输入“帮我美化一下这个页面的样式”如果 Claude 的回复风格变了比如开始使用 CSS 变量、遵循你定义的工作流说明 Skill 生效了。六、进阶技巧6.1 多变体拆分如果你的 Skill 支持多个框架/场景不要全塞 SKILL.mdfrontend-style/ ├── SKILL.md # 通用流程 选择逻辑 └── references/ ├── vue2-element.md # Vue 2 Element UI 专用 ├── vue3-antd.md # Vue 3 Ant Design 专用 ├── react-tailwind.md # React Tailwind 专用 └── vanilla-css.md # 原生 CSSSKILL.md 中这样引用## 框架适配 根据项目技术栈选择对应参考 - Vue 2 Element UI → [references/vue2-element.md](references/vue2-element.md) - Vue 3 Ant Design → [references/vue3-antd.md](references/vue3-antd.md) - React Tailwind → [references/react-tailwind.md](references/react-tailwind.md) - 原生 CSS → [references/vanilla-css.md](references/vanilla-css.md)6.2 大文件处理如果 reference 文件超过 10000 词在 SKILL.md 中加搜索提示## 数据库 Schema 参考 详见 [references/schema.md](references/schema.md) 常用搜索关键词 - 用户表: users_table - 订单表: orders_table - 产品表: products_table6.3 条件加载只在需要高级功能时才加载对应文档## 基础功能 直接使用 CSS 变量模板即可。 ## 高级功能按需查阅 - **复杂动画编排**: 详见 [references/advanced-animations.md](references/advanced-animations.md) - **主题切换系统**: 详见 [references/theming.md](references/theming.md) - **CSS Houdini**: 详见 [references/houdini.md](references/houdini.md)6.4 脚本集成如果有可复用的脚本放在scripts/下# scripts/generate_palette.py# 根据主色调自动生成完整配色方案importcolorsysimportsysdefgenerate(hex_color):# ... 生成逻辑passif__name____main__:print(generate(sys.argv[1]))SKILL.md 中引用## 自动配色 运行 scripts/generate_palette.py #4f46e5 生成完整配色方案。6.5 资产模板把常用的 HTML 模板放在assets/下assets/ └── landing-page/ ├── index.html ├── style.css └── assets/ └── hero-pattern.svgSKILL.md 中引用## 项目模板 新建落地页时复制 assets/landing-page/ 作为起始模板。七、发布与分享7.1 本地使用最简单直接放在~/.claude/skills/目录下即可Claude 客户端自动识别。# 你的 skill 放这里~/.claude/skills/my-skill/SKILL.md7.2 打包为 .skill 文件.skill文件本质是一个 zip 包方便分享。方法 A使用官方脚本如果可用# 如果 skill-creator 的 scripts 目录有 package_skill.pypython scripts/package_skill.py ~/.claude/skills/css-beautify方法 B手动打包cd~/.claude/skillszip-rcss-beautify.skill css-beautify/生成的css-beautify.skill可以发给任何人。7.3 别人如何安装你的 Skill收到.skill文件后# 解压到 skills 目录cd~/.claude/skillsunzipcss-beautify.skill或者直接在 Claude 客户端中导入如果支持 GUI 导入。7.4 通过 Git 分享# 初始化仓库cd~/.claude/skills/css-beautifygitinitgitadd.gitcommit-minit: css-beautify skill# 推送到 GitHubgh repo create css-beautify-skill--publicgitpush-uorigin main别人使用cd~/.claude/skillsgitclone https://github.com/yourname/css-beautify-skill css-beautify八、常见问题 FAQQ: Skill 没有被触发怎么办原因 1description 不够具体检查你的 description 是否覆盖了用户可能说的话。用户说美化但你的 description 只写了CSS optimization可能匹配不上。原因 2跟其他 Skill 冲突多个 Skill 的 description 覆盖范围重叠时Claude 可能选了别的。让你的 description 更加精准。原因 3需要重启对话修改 Skill 文件后可能需要开一个新的对话才能生效。Q: SKILL.md 应该多长建议 500 行以内、5000 词以内。超过这个量说明你应该把内容拆到 references/ 下。Q: references 文件会自动加载吗不会。Claude 看到 SKILL.md 中的链接后会自行判断是否需要读取。这是按需加载的核心设计。Q: 可以在 Skill 里用中文吗可以。name 建议用英文 kebab-casedescription 和正文可以用中文。Q: Skill 之间可以互相引用吗不可以。每个 Skill 是独立的不能 import 其他 Skill。但多个 Skill 可以同时被触发。Q: 如何调试 Skill新开对话输入应该触发 Skill 的请求观察 Claude 的回复是否符合 Skill 中定义的工作流如果不符合检查 description 是否匹配逐步调整 description 和正文内容Q: 我的 Skill 适合开源吗如果不包含公司敏感信息内部 API、业务数据、私有 schema完全可以开源。通用型 Skill如 CSS 美化、PDF 处理非常适合分享。附录Skill 设计清单创建 Skill 前过一遍这个清单description 是否覆盖所有触发场景SKILL.md 是否只写了 AI 不知道的东西正文是否在 500 行以内大段内容是否拆到 references/ 下是否提供了代码示例而不是纯文字描述references 文件是否在 SKILL.md 中被引用是否有多余的文件README、CHANGELOG 等脚本是否经过实际测试本文基于 Claude Skill Creator 官方文档编写适用于所有 Claude 客户端环境Windsurf、Claude Desktop、Claude Code 等。