自定义 Claude Skill 怎么创建？开发者实战教程

30 秒了解自定义 Claude Skill

自定义 Claude Skill 就是写一份 SKILL.md（带 YAML frontmatter 的 Markdown）+ 可选的支持文件，告诉 Claude「遇到某类任务按这个 SOP 干」。最小可用 Skill 一份 SKILL.md 就够，半小时能跑通。

Skill 的核心机制是 progressive disclosure（渐进披露）：Claude 先只读所有 Skill 的 description（描述），决定要用谁，再加载那个 Skill 的完整内容。所以 description 写得好不好直接决定 Skill 能不能被正确触发。

本文带你从零写第一个 Skill，包括：

• 文件结构和命名
• SKILL.md 的 frontmatter 字段
• 怎么写一个高命中率的 description
• 怎么调试不被触发的问题
• 怎么打包分发给团队

不熟悉 Skill 是什么的，先看 Claude Skills 是什么。

准备工作

1. 工具准备

2. 文件结构

最小 Skill：

my-skill/
└── SKILL.md

复杂 Skill 可加支持文件：

my-skill/
├── SKILL.md              # 主说明（必需）
├── templates/            # 模板文件
│   └── report-template.md
├── examples/             # 示例输出
│   └── example-output.md
├── references/           # 参考文档
│   └── style-guide.md
└── scripts/              # 可执行脚本（可选）
    └── validate.py

3. 想清楚 Skill 的边界

写 Skill 前先回答 4 个问题：

1. 这个 Skill 解决什么具体任务？
2. 什么对话会触发它？
3. 期望输出长什么样？
4. 跟我已经装的其他 Skill 会冲突吗？

边界不清的 Skill 会被 Claude 频繁误触发或永远触发不到。

详细操作步骤

第 1 步：写 SKILL.md 的 frontmatter

SKILL.md 顶部必须有 YAML frontmatter，至少含 description 字段：

---
name: nda-review
description: Use this skill when the user uploads an NDA (Non-Disclosure Agreement) PDF or pastes NDA text and asks for review, analysis, risk assessment, or comparison. Covers both unilateral and mutual NDAs. Outputs a 12-point checklist report with risk levels.
---

字段说明：

第 2 步：写一个高命中 description

description 是整个 Skill 的灵魂。Anthropic 官方建议同时写「Skill 做什么」+「什么时候用」。

反例（不好）：

description: Helps with contract review.

太模糊。Claude 不知道是哪种合同、什么场景下用。

正例（好）：

description: Use this skill when the user uploads or pastes a Non-Disclosure Agreement (NDA) and asks for review, risk assessment, clause-by-clause analysis, or comparison with industry standards. Handles both unilateral and mutual NDAs. Triggers on phrases like “review this NDA”, “audit this confidentiality agreement”, “compare these two NDAs”, “is this NDA fair to me as the receiving party”. Outputs a 12-point risk checklist with severity ratings (high/medium/low) and specific rewriting suggestions in Chinese.

好的 description 包含 4 个要素：

1. 触发条件：用户上传 / 输入什么
2. 覆盖范围：处理哪些子类型
3. 典型提问句式：列 3-5 个真实可能说的话
4. 输出格式：说清产出什么

第 3 步：写 Skill 主体

Frontmatter 下面就是给 Claude 的指令。结构化写法效果最好：

---
name: nda-review
description: ...（上面那段）
---

# NDA 审查 Skill

你被激活了，因为用户需要审查一份 NDA。请严格按下面的流程执行。

## 流程

### 第一步：确认 NDA 类型
检查这份 NDA 是单向（unilateral）还是双向（mutual）。
- 单向：只有一方有保密义务
- 双向：双方互相保密
告诉用户你的判断，并询问这是否符合用户预期。

### 第二步：12 项检查清单
按以下顺序逐项检查：

1. 保密信息定义是否清晰
2. 保密期限是否合理（业界惯例 2-5 年）
3. 例外条款是否标准（公开信息、独立开发等）
4. 违约金条款是否过重
5. 司法管辖与争议解决
6. 保密信息销毁义务
7. 知识产权归属
8. ……

### 第三步：输出报告

用以下 Markdown 表格格式输出：

| 项目 | 现状 | 风险等级 | 建议改写 |
|---|---|---|---|
| 保密期限 | 永久 | 高 | 改为 3 年 |
...

## 风格约束

- 中文输出
- 不要客套话
- 引用原文必须带引号
- 不确定的条款明确说「需要找专业律师确认」

## 不在范围内
- 不审 NDA 之外的合同（请告诉用户用其他 Skill）
- 不出具法律意见书

第 4 步：本地测试 Skill

在 claude.ai 网页端：

1. Settings → Capabilities → Skills → Add custom skill
2. 上传你的 SKILL.md 或整个文件夹（打包成 zip）
3. 启用 Skill
4. 新开一个对话，发一句应该触发的话
5. 观察 Claude 是否调用了 Skill

正常情况下，Claude 会在回答开头或思考过程中显示「Using skill: nda-review」。

第 5 步：调试触发问题

如果 Skill 不被触发，可能的原因：

请帮我诊断我的 Skill 为什么没被触发。
我装了一个 Skill 叫 [nda-review]，description 是「[贴 description]」。
我问了：「[贴你的提问]」
但 Claude 没用这个 Skill，是直接默认回答的。
请告诉我：

我的 description 跟我的提问到底匹配度多高（从你模型视角看）
改怎么写 description 才能让我这种问法稳定触发
我的提问要怎么改也能稳定触发（如果不想改 description）
有没有可能跟我装的其他 Skill 冲突了（让我列出所有装的 Skill 帮我看）

Claude 自己会帮你分析。改完 description 重新上传测试。

第 6 步：添加支持文件

复杂 Skill 把模板和示例拆出来：

# SKILL.md 主文档

当需要 NDA 输出报告时，请参考 templates/report-template.md 的格式。

需要示例可以看 examples/example-1.md 和 examples/example-2.md。

然后单独写 templates/report-template.md：

# NDA 审查报告

**审查日期**：[DATE]
**审查人**：Claude
**合同名称**：[CONTRACT_NAME]
**合同类型**：[unilateral / mutual]

## 核心风险摘要

[3 句话总结]

## 12 项详细检查

| 项目 | 现状 | 风险等级 | 建议改写 |
|---|---|---|---|
...

## 总体建议

[5 行内]

Claude 会在生成报告时按模板填充。

第 7 步：通过 API 上传 Skill

API 调用 Claude 时也能用 Skill：

具体步骤（以 Anthropic API 为例）：

把 Skill 文件夹打包成 zip
调用 Files API 上传 zip（POST /v1/files），拿到 file_id
创建一个 Skill resource（POST /v1/skills），关联 file_id
在 Messages API 请求里加 skills 参数：
请求体示例：
{
“model”: “claude-opus-4-7”,
“max_tokens”: 4096,
“skills”: [{“id”: “skill_xxxxx”}],
“messages”: [{“role”: “user”, “content”: “审一下我的 NDA”}]
}
完整字段定义请查 platform.claude.com 上的 Skills API 文档。

5 个让 Skill 更好用的技巧

1. 一个 Skill 只解决一件事

不要写「全能法律 Skill」。拆成「NDA 审查」「劳动合同审查」「采购合同审查」三个 Skill，命中更精准、复用更灵活。

2. description 用「使用动词」开头

Use this skill when... Apply this skill if... Triggers on...——这类动词让 Claude 更容易识别触发条件。模糊的「This skill handles…」效果差很多。

3. 主体 Markdown 要简短

Claude 加载 Skill 时整段进上下文，每个 Token 都花钱。主体超过 2000 字时考虑拆成支持文件（让 Claude 按需读）。

4. 用版本号管理 Skill

在文件夹名或 SKILL.md 里加版本号（如 nda-review-v1.2），改 Skill 时新建版本而不是覆盖。这样回滚方便。

5. 写完让 Claude 帮你审

把你写好的 SKILL.md 直接发给 Claude：

请帮我审一下这份 SKILL.md。从以下角度给意见：

description 是否够具体，会被精准触发吗？
主体指令有没有歧义、漏洞、逻辑跳跃？
输出格式定义是否够清晰？
边界（不在范围内）说清楚了吗？
整体长度是否合理（300-2000 字最佳）？
如果我说 [一句典型提问]，你会调用这个 Skill 吗？为什么会 / 不会？
请给具体的修改建议，逐条对应行号。

常见坑 + 解决办法

一个完整可跑的 Skill 示例

最小可用「周报生成」Skill，整个内容 200 字：

---
name: weekly-report
description: Use this skill when the user asks to generate, write, or draft a weekly report (周报). Triggers on phrases like "写周报", "生成本周周报", "draft weekly report", "this week's update". Outputs a structured 5-section report in Chinese using the problem-solution-risk-metric framework.
---

# 周报生成 Skill

你被激活了，因为用户要写周报。按以下 5 段结构输出：

## 1. 本周完成（成果）
列 3-5 条具体完成的事，每条带量化指标。

## 2. 本周问题（卡点）
列 1-3 个遇到的问题，明确求助内容。

## 3. 下周计划
列 3-5 条下周要做的事，按优先级排序。

## 4. 风险预警
列 1-2 个潜在风险，并给缓解建议。

## 5. 度量数据
关键指标对比上周变化。

风格要求：
- 每条不超过 30 字
- 用动词开头
- 不要套话

保存为 weekly-report/SKILL.md，上传到 claude.ai，下次说「帮我写周报」就会自动调用。

下一步

• Claude 是什么？小白入门
• Claude Skills 是什么：先搞懂 Skill 概念
• Claude Projects 怎么用：Skill + Project 配合
• Claude 记忆功能：跟 Skill 的区别
• Claude 桌面版怎么装：本地开发 Skill 更顺
• Claude 创建文件：Skill 产出文档时用得上

常见问题

Q：写 Skill 一定要会编程吗？

不需要。最小 Skill 就是一份 Markdown，会写 Word 文档就会写 Skill。需要加可执行脚本时才需要 Python / JavaScript 基础。

Q：Skill 主体可以用中文写吗？

可以。description 建议英文（更容易被精准匹配），主体可中文。Claude 双语处理能力相当。

Q：一个账号能装多少个 Skill？

官方没公开硬上限。实测装 20-30 个 Skill 没问题，更多时建议按场景分文件夹组织。Skill 之间不冲突，只在触发时按需加载。

Q：Skill 能调用 API 或工具吗？

直接调用不行。Skill 是「指令文档」不是「代码」。需要外部能力时配合 MCP（Model Context Protocol）服务器，让 Skill 指挥 Claude 用 MCP 工具。

Q：怎么给团队共享 Skill？

三种方式：① Team/Enterprise 套餐让管理员推到组织维度；② 把 Skill 文件夹打包发给同事手动导入；③ 放 GitHub 仓库，团队按需 clone。

Q：Skill 写错了能反悔吗？

能。每次改 SKILL.md 重新上传即可。建议用 Git 管理，方便回滚和对比版本。

Q：Skill 会被 Anthropic 偷看吗？

按 Anthropic 政策，你上传的 Skill 内容只在你账号 / 组织内使用，不会用于训练或对外。Enterprise 套餐有更严的承诺。但写 Skill 时还是不要包含敏感原始数据（公司机密、客户信息），只写「方法论」就好。

Q：开源 Skill 哪里找？

最权威的是 GitHub 上 anthropics/skills 官方仓库。社区也有不少汇总仓库，搜「awesome claude skills」能找到大量第三方贡献。