Claude Skills 编写指南

过去几个月，我创建了 20 个 Claude 技能。其中 12 个都是垃圾。

问题不在于 Claude 本身。而在于我试图预先预判所有情况，编写模糊的描述，并创建了功能单一、无法正确触发的“万能”技能。一旦我掌握了真正有效的模式，我的成功率就翻了一番。

以下是我希望有人在第一天就告诉我的。

1、改变一切的一条规则

你的技能描述不是文档。这是一个触发器。

Claude 会在启动时扫描技能描述，以确定哪些技能存在以及何时使用它们。这发生在读取任何实际指令之前。如果您的描述含糊不清或过于被动，Claude 将不会加载您的技能。如果描述具体且基于条件，它就能神奇地发挥作用。

糟糕的描述：

---
name: csv-handler
description: A skill for handling CSV files
---

这几乎没有告诉 Claude 何时使用该技能。“处理”一词含义模糊。该技能处于休眠状态。

优秀的描述：

---
name: csv-data-analyzer
description: When a user uploads a file with a .csv extension, proactively run a comprehensive data analysis, generate summary statistics, identify missing values, and create visualizations.
---

这描述具体、主动，并精确地描述了触发条件。Claude 能够准确地知道何时加载该技能。

模式：“当[条件]满足时，执行[具体操作]。”

2、构建精简、专注的技能（而非瑞士军刀）

我最糟糕的技能叫做“内容创作者”。它试图涵盖博客文章、社交媒体、电子邮件营销和文档编写。描述过于宽泛，以至于克劳德很少能正确触发它。即使触发了，指令也冗长到克劳德经常做到一半就晕头转向。

我把它拆分成了四个技能：

• 博客文章撰写者（一项任务：根据品牌指南撰写博客文章）
• 社交媒体内容转换者（一项任务：将现有内容转换为社交媒体帖子）
• 电子邮件营销活动生成器（一项任务：创建电子邮件序列）
• 技术文档编写者（一项任务：生成 API 文档）

每个技能都有精准的描述，并且都能可靠地触发。复杂的工作流程是通过构建多个技能来实现的，而不是把所有功能都塞进一个技能里。

原则：每个技能应该专注于做好一件事。如果你在描述中使用了“并且”这样的字眼，那么你需要两个技能。

3、三层架构（及其重要性）

技能分阶段加载信息。理解这一点彻底改变了我构建技能的方式。

第一层：元数据（始终加载）

• 仅包含 YAML 前置元数据中的名称和描述
• 每个技能大约消耗 100 个令牌
• 这就是为什么你可以拥有数百个技能而不会出现性能问题的原因

第二层：指令（触发时加载）

• 包含分步指导的完整 SKILL.md 文档
• 通常消耗少于 5,000 个令牌
• Claude 在这里学习工作流程

第三层：资源（按需加载）

• Python 脚本、模板、参考文档
• 实际上没有限制，因为脚本无需加载到上下文中即可执行
• 确定性操作在此发生

重要性：将触发逻辑放在第一层，推理放在第二层，执行放在第三层。不要混用它们。

我以前编写过包含大量代码片段的二级指令，这种方式既繁琐又不可靠。现在，我编写简洁的二级指令，例如“运行 analyze.py”，并将实际代码放在三级指令中。Claude 会执行脚本，并且只查看输出结果。效率大大提高。

这种渐进式加载架构正是 Skills 与其他 Claude 功能根本区别所在。我之前写过如何正确地为 AI 提供上下文——Skills 在框架层面实现了这些原则。你不再是把所有内容都一股脑地塞进上下文，然后指望 Claude 自己去理解。而是主动管理加载的内容和加载时间。

4、根据任务重写 Claude 的性格

Claude 的默认性格是乐于助人、礼貌周到，并且喜欢问很多问题。这很适合一般的聊天，但对于专门的工作流程来说却很糟糕。

请查看来自 CSV 数据分析器技能的以下指令模式：

## Instructions
When triggered:
1. Immediately run the analysis script
2. Generate ALL relevant charts automatically
3. Be thorough and complete in first response
## NEVER SAY THESE PHRASES:
- "What would you like to do with this data?"
- "What would you like me to help you with?"
- "How can I assist you further?"
- Any sentence ending with '?' asking for user direction
## FORBIDDEN BEHAVIORS:
- Asking what the user wants
- Waiting for user direction before analyzing
- Offering options instead of taking action

这使得 Claude 从被动助手转变为主动专家。用户上传 CSV 文件后即可立即获得完整的分析结果。无需反复沟通。洞察：技能允许您覆盖 Claude 针对特定任务的默认行为。使用明确的否定约束来防止出现不必要的模式。

5、迭代开发流程（而非“完美初稿”陷阱）

我曾浪费数天时间试图从零开始编写完美的技能。更好的方法是与 Claude 进行协作迭代。

真正有效的流程：

• 手动演练：在与 Claude 的聊天中手动完成任务。暂时不要尝试构建技能。
• 提供实时反馈：在 Claude 执行任务的过程中进行纠正。“不，语气应该更直接一些。”“将图表放在总结之前。”“请使用完全相同的格式。”
• 提取技能：一旦任务完美运行，就说：“将我们整个对话转换为一个名为 [技能名称] 的新技能。”
• 训练极端情况：使用该技能。当它出现错误时，在聊天中进行纠正，然后说：“使用我刚刚所做的更正更新 [技能名称] 技能。”
• 重复：技能的提升在于实践，而非预先规划。

这使我的开发时间从几天缩短到几小时。我让 Claude 通过展示我的需求来帮助我构建技能，而不是试图在第一次尝试时就完美地记录所有内容。

6、安全性：allowed-tools 字段至关重要

技能可以执行代码并访问文件。这既强大又危险。

我构建了一个只读的数据分析技能——它不应该修改任何文件。但我没有限制它。在测试过程中，Claude 误解了一个请求，意外地覆盖了一个文件。

现在我在 YAML 的 frontmatter 中使用 allowed-tools：

---
name: data-analyzer
description: Analyze CSV and JSON files, generate reports
allowed-tools: |
  bash: cat, grep, head, tail, wc, python (read-only analysis)
---

这创建了一个沙箱。技能只能使用指定的工具。它无法删除文件、发起网络调用或执行任意命令。

规则：如果某个技能不需要写入权限，则应明确限制其权限。遵循最小权限原则。

7、使用 XML 标签构建结构（Claude 会注意）

Claude 经过优化，能够识别 XML 标签作为硬边界。请使用它们在您的二级指令中创建清晰的结构。

不使用 XML 标签：

## Instructions
First, validate the input. Then, process the data. Finally, generate output.

Claude 可能会模糊这些步骤或跳过验证。

使用 XML 标签：

## Instructions
<validation>
Before processing:
- Check file format
- Verify required fields exist
- Confirm data types are correct
</validation>
<processing>
After validation passes:
- Clean missing values
- Calculate statistics
- Generate visualizations
</processing>
<output>
Final deliverables:
- Summary report in markdown
- Charts saved to /outputs
</output>

这些标签创建了明确的边界。Claude 将每个部分视为一个独立的阶段，很少跳过步骤。

8、示例：展示，而非空谈

SKILL.md 文件中的 ## 示例 部分至关重要。一个具体的例子胜过千言万语。

不好的示例：

## Examples
Use this Skill to generate reports from data.

优秀示例部分：

## Examples
### Example 1: Sales Data
User uploads: "Q3_sales_data.csv"
Expected output:
- Summary: "Analyzed 1,247 transactions across 5 regions"
- Top insight: "West region outperformed by 23%"
- 3 visualizations: revenue trend, regional breakdown, top products
- Delivery format: Markdown report with embedded charts
### Example 2: Customer Feedback
User uploads: "customer_reviews.json"
Expected output:
- Sentiment analysis showing 78% positive
- Common themes extracted (shipping, quality, price)
- Word cloud of frequent terms
- Actionable recommendations

像这样的多样本示例可以帮助 Claude 了解您的具体期望。格式、语气、细节程度——它会通过观察预期输出来学习。

9、哪些内容不应该被构建为技能

并非所有内容都应该被构建为技能。我通过构建从未使用过的技能才明白这一点。

不要为以下情况创建技能：

• 一次性任务：如果某件事只做一次，直接使用常规提示即可。技能适用于重复性任务。
• 不断变化的工作流程：我创建了一个“每周简报”技能。简报格式每三周更换一次。我花在更新技能上的时间比从头开始编写提示的时间还要多。
• 模糊的需求：“帮我提高写作水平”不属于技能范畴。它过于主观，且依赖于具体情境。
• 更适合作为项目的内容：始终相关的背景知识应该放在项目说明中，而不是技能里。

务必构建以下技能：

• 重复性工作流程：每周或每日重复执行的任务
• 多步骤流程：需要特定顺序的任务
• 领域专业知识：需要专业知识的工作流程
• 团队标准化：所有成员都需要相同输出的流程

10、技能 vs. 项目 vs. 自定义指令（何时使用）

这个问题困扰了我好几周，直到我理清思路：

自定义指令 = 您的个性

• 所有对话的全局设置
• “始终使用主动语态”或“我喜欢简洁的回复”
• 用途：沟通风格、一般偏好

项目 = 您的参考库

• 静态上下文，在该项目中每次聊天开始时加载
• 始终处于上下文中，永不发布
• 用途：背景文档、公司背景、技术规范

Skills = 您的专家团队

• 按需加载，然后发布
• 可以包含可执行代码
• 用途：特定任务的工作流、专门的流程

MCP（模型上下文协议）= 您的外部连接

• 将 Claude 连接到工具和数据源的标准化方式
• 可以将其视为 AI 领域的 USB-C——一个协议，多种集成
• 用途：数据库访问、API 连接、工具集成

我曾详细撰文阐述 MCP 如何解决连接器碎片化问题。关键区别在于：MCP 处理连接，Skills 处理工作流。MCP 服务器可以授予 Claude 访问您的 CRM 数据的权限。Skills 定义了“使用该 CRM 数据生成季度销售报告”的工作流。

我将这三者结合使用。我的自定义说明设置了我的写作风格。我的项目包含公司背景和品牌指南。我的技能可以处理诸如“生成季度报告”或“审核博客文章是否符合品牌规范”之类的特定任务。

11、“技能即代码”分发模型

技能并非仅供个人使用。我发现团队的最佳模式是将技能视为代码。

• 在项目仓库中创建 skills/ 目录
• 每个技能都是一个子文件夹，其中包含 SKILL.md 文件和任何脚本
• 像提交其他代码一样提交到 Git
• 团队成员在执行 git pull 时会自动获取技能
• 更新受到版本控制并可进行审核

这解决了分发问题。技能无需手动共享或上传到多个位置，而是通过您现有的开发工作流程进行传播。

我们以这种方式构建了一个包含 30 多个技能的库。新团队成员克隆仓库后即可立即访问我们的完整技能库。

12、实际示例：财务模型技能

我将向您展示一个在生产环境中实际运行的完整技能。

---
name: dcf-model-generator
description: When user requests a discounted cash flow valuation model, generate a complete DCF analysis with all standard components including revenue projections, expense assumptions, free cash flow calculations, WACC determination, and terminal value computation.
allowed-tools: |
  bash: python
---
# DCF Model Generator
<task>
Generate a complete discounted cash flow valuation model following standard financial modeling practices.
</task>
<validation>
Before starting, confirm you have:
- Company name
- Historical financials (minimum 3 years)
- Projection period (default to 5 years if not specified)
- Discount rate or inputs to calculate WACC
</validation>
<execution>
1. Run `python generate_dcf.py --company [name]`
2. The script creates the base Excel model with formulas
3. Review the output for completeness
4. Generate a summary markdown report
</execution>
<output_format>
Deliver two files:
1. `[company]_DCF_Model.xlsx` - Full Excel model with linked sheets
2. `[company]_Valuation_Summary.md` - Executive summary with key findings
The summary must include:
- Enterprise value range (base/bull/bear cases)
- Implied share price
- Key assumptions and sensitivities
- Model limitations
</output_format>
<critical_rules>
- Always show your work and assumptions
- Include sensitivity tables for WACC and terminal growth rate
- Flag any missing data that required estimation
- Never present a single-point valuation (always show range)
</critical_rules>
## Examples
[Include 1-2 concrete examples showing input and exact expected output]

此技能之所以有效，是因为它：

• 在描述中包含特定的触发条件
• 使用 XML 标签以保持清晰的结构
• 将推理（二级指令）与执行（generate_dcf.py 脚本）分开
• 包含明确的规则和输出格式
• 仅使用所需的工具

13、我经常看到的错误

人们编写的技能描述读起来像文档。他们用抽象的术语解释技能的功能。Claude 需要的是指令，而不是描述。

文档风格（无效）：

## Instructions
This Skill helps analyze CSV files. It can generate various statistics and create helpful visualizations to understand your data better.

说明风格（有效）：

## Instructions
1. Read the uploaded CSV file
2. Run data validation: check for missing values, verify column types
3. Calculate summary statistics for all numeric columns
4. Generate three visualizations: distribution histogram, correlation heatmap, time series if date column exists
5. Write findings in markdown format with insights highlighted
6. Never ask "what would you like me to analyze?" - just do the complete analysis

第二个版本清晰明确地告诉 Claude 该做什么，按顺序执行，没有任何歧义。

14、从小处着手，逐步构建

不要试图将整个工作流程构建成一个超级技能。从最小的实用单元开始。

我最初使用了：

• csv-validator（仅检查 CSV 文件格式是否正确）

然后添加了：

• csv-statistics（生成汇总统计信息）

然后添加了：

• csv-visualizer（创建图表）

现在，当有人上传 CSV 文件后，所有三个技能都可以协同工作。每个技能都简洁、专注且可靠。复杂性并非源于单个技能本身，而是源于技能的组合。

这种模块化方法也让调试变得更加容易。当出现问题时，我可以准确地知道是哪个技能出了故障。

15、结束语

技能可以将 Claude 从一个聊天机器人转变为一个专业的副驾驶。但它们只有在以下情况下才能发挥作用：

• 编写具体的、基于条件的描述（而不是模糊的摘要）
• 构建专注于做好一件事的技能
• 正确使用三层架构
• 针对特定任务覆盖 Claude 的默认性格
• 通过向 Claude 展示您的需求来进行迭代开发
• 出于安全考虑限制工具的使用
• 使用 XML 标签和具体示例

能否从技能中获益的关键在于是否理解这些模式。技能并非魔法——它们只是一个框架。遵循这个框架，您就能构建出真正有效的功能。

原文链接：Writing Claude Skills That Actually Work: A Guide to What Works (And What Doesn't)

汇智网翻译整理，转载请标明出处