我把自己找到的所有资源整合在一起，制作了一门完整的 Claude Skills 课程。不到 10 分钟，你就能构建并部署你的第一个自定义技能。读完这篇文章后，你对 Claude Skills 的理解将超过 99% 的人（是的，真的）。
你即将获得一整套关于如何创建 Claude Skill 的课程——这是一种永久的指令文件，用来告诉 Claude 如何准确执行某个特定任务。
以下是如何使用这篇文章：
模块 1：基础
模块 2：架构
模块 3：测试与迭代
模块 4：生产部署
模块 1：基础
在每个模块中，我都会给你基础知识 + 如何让 AI 帮助你，以便你 1：理解发生了什么，2：正确构建它而无需技术技能。
让我们直接开始吧……
技能 vs 项目 vs MCP：
在你构建任何东西之前，你需要了解技能在 Claude 中的位置。三个工具，三个不同的工作：
Projects = 你的知识库。上传一份品牌指南 PDF，就相当于在告诉 Claude：“这是你需要了解的内容。” 静态。参考资料。一个资料库。
Skills = 你的操作手册。你是在告诉 Claude：“这是你执行这个任务的确切方式，一步一步来。” 程序化。自动化。一个经过训练的员工。
MCP（模型上下文协议）= 你的连接层。它将 Claude 接入实时数据源（你的日历、数据库、收件箱）。而 Skills 则告诉 Claude 如何使用这些数据。
Do you need a skill? If you've typed the same instructions at the start of more than three conversations, that's a Skill begging to be built, or if you want to help Claude become a professional operator in various tasks then creating skills help it become an "employee" in different sectors.
一个 Skill 的结构：
大多数指南就是在这里把事情搞得过于复杂（而且你的 Claude 反正也会帮你把这个做出来，所以我不会太担心）：
一个 Skill 就是你电脑上的一个文件夹。这个文件夹里有一个文本文件。就这么简单。
一个文件夹，里面有一个叫做 SKILL.md 的文本文件。
文件夹遵循三个规则：
根文件夹必须使用短横线命名法。这意味着小写字母，单词之间用连字符分隔。invoice-organiser。email-formatter。csv-cleaner。不能有空格。不能有下划线。不能有大写字母。
SKILL.md is the brain. This is case-sensitive. Not skill.md. Not README.md. Exactly SKILL.md. All your instructions live here.
references/ is optional. If your instructions need a massive brand guide or a long template, drop it in this subfolder instead of pasting it into SKILL.md.
将整个文件夹放入你机器上的 ~/.claude/skills/ 文件夹中。
Claude 会自动找到它。
我希望你能理解这一点，这样你就能明白了。
它们运行在哪里？
这件事比大多数指南告诉你的都更重要。
Claude Code 是面向开发者的命令行工具。这里的 Skills 存放在你的项目目录 .claude/skills/ 下，或全局目录 ~/.claude/skills/ 下。它们可以访问文件系统、bash 命令，并且能够执行代码。这也是你构建 Skills 的地方——用于操作文件、运行脚本，并与你的代码库交互。
Claude Desktop（CoWork）是面向非开发者的桌面代理。这里的 Skills 通过桌面界面运行，并可以通过代理的能力与你的屏幕、应用程序和文件交互。使用相同的 SKILL.md 格式，但执行环境不同。
如果你不确定，随时都可以使用这个提示：
构建你的第一个技能：
步骤 1：定义任务
在你写下任何一个字之前，先回答三个问题：
这个 Skill 做什么？要极其具体。“帮助处理数据”毫无用处。“把杂乱的 CSV 文件转换为带有正确表头的干净电子表格，统一为 YYYY-MM-DD 日期格式，并删除空行”才是一个真正有效的 Skill。
什么时候应该触发它？想想你自己实际会输入什么。“清理这个 CSV。”“修复这些表头。”“格式化这些数据。”这些就是你的触发词。
“好”是什么样子？你需要一个具体的最终输出示例。不是描述，而是真正的前后对比示例。
仔细听。这一步是90%的糟糕技能诞生的地方。模糊的指示会产生模糊的结果。每次都是这样。
不确定自己能描述得够具体？这个提示会逼你说得更精准。
提示：技能定义面试：
步骤 2：编写 YAML 触发器
在你的 SKILL.md 文件顶部，你需要在 --- 行之间写一段元数据块。这被称为 YAML frontmatter。它告诉 Claude 何时激活你的技能。
示例如下：
三个决定你触发器成败的规则：
Write in third person. "Processes files..." not "I can help you..."
列出确切的触发短语。Claude 在激活方面比较保守。你需要明确说明用户可能会说什么。要强势一点。
设定负面边界。告诉 Claude 何时不要触发。这可以防止你的技能劫持无关的对话。
很多人都会忽略这一点：description 字段是你整个 Skill 中最重要的一行。如果它写得不够有力，你的 Skill 就永远不会被触发；如果它写得太宽泛，它又会在你不希望的时候被触发。
这个提示词会根据你的定义生成一个经过实战验证的 YAML 头部：
提示词：YAML 触发器生成器：
第 3 步：编写 Instructions
在 --- 标记下方，用通俗的英文写出你的工作流程。使用带标题的结构。按顺序编写。少于500行。
这个方法由两个部分组成：
步骤。将工作流程拆分为一个合乎逻辑的顺序：
首先，读取提供的文件以了解其结构
识别包含真实列标题的行
删除任何空行或仅包含逗号的行
强制使用正确的数据类型（日期必须为 YYYY-MM-DD 格式）
输出清理后的文件，并附上所做更改的摘要
示例。这里是魔法的所在。一个具体的例子，展示输入和预期输出，比50行抽象的描述更有价值。
提示：技能说明架构：
步骤4：一层深度规则（引用）
如果你的说明引用了庞大的品牌指南或模板，千万不要将它们全部粘贴到SKILL.md中。
将其作为单独的文件保存在 references/ 文件夹中。然后在你的说明中直接链接到它。
但这里有一个关键限制：绝不要让参考文件再链接到其他参考文件。Claude 会截断读取并错过信息。只允许一层深度，仅此而已。
如果你有现有文档（品牌指南、样式表、模板、SOP 等）需要你的 Skill 进行引用，这个提示词可以把它们转换为格式正确的参考文件：
提示词：参考文件整理器：
步骤 5：组装并部署
You've now got every component. Time to put it together.
您的文件夹结构应该如下所示：
将文件夹拖入您机器上的 ~/.claude/skills/ 目录。
完成。
但等等。在你部署之前，你需要确保整个系统没有漏洞。这个提示会对你的完整 SKILL.md 文件进行最后的质量检查：
提示：技能质量审计员
自动化构建你的第一个技能：
如果上面的内容都让你觉得太费劲，其实有一个捷径。
Anthropic 构建了一个名为 skill-creator 的元技能，可以通过对话为你创建 Skills。
它的工作方式如下：
1. 打开一个新的聊天。输入：“使用 skill-creator 帮我为 [your task] 构建一个技能。”
2. Upload your assets. Templates you use. Examples of past work. Brand guidelines. Anything that shows Claude what "good" looks like.
3. 回答面试。技能创作者会向你提出澄清性问题，询问你的过程、边界情况以及质量标准。
4. 它生成一切。格式化的 SKILL.md。推销性的描述。文件夹结构。打包并准备就绪。
5. 将该文件夹保存到 ~/.claude/skills/。完成。
下次当你让 Claude 执行该任务时，你的技能会自动触发。
模块 1 完成。你现在已经部署了一个技能。在模块 2 中，你将学习如何利用架构。
模块 2：架构
你最终会拥有相当多的技能，这时候架构就成为你工具库中一个重要的部分。
再说一遍，我会先教你这个的手动版本，然后再给你一些提示词，让你可以让它替你完成这件事。但了解为什么要构建这种架构是很有必要的，这也是我保留手动部分的原因……
WHEN INSTRUCTIONS AREN'T ENOUGH:
到目前为止，你构建的一切都使用了简单的英文指令。Claude 会读取这些指令、按其执行，并生成输出。
但有些任务需要计算。它们需要可运行的代码，需要执行的计算，以及那些对自然语言指令来说过于精确的数据转换。
这就是 scripts/ 目录的用途。
何时使用脚本：
当任务涉及判断、语言、格式或决策时，使用指令。"用我们的品牌语气重写这个。" "分类这些会议记录。" "草拟一封电子邮件。" Claude 的语言能力可以完美处理这些。
当任务需要精确计算、文件操作、数据转换或与外部工具集成时，使用脚本。"计算这些数字的运行平均值。" "解析这个 XML 文件并提取特定字段。" "将该文件夹中的所有图像调整为 800x600。"
Use both when: The task requires computation AND judgement. "Process this CSV (script), then write a human-readable summary of the anomalies found (instructions)."
技能内部脚本的工作原理
Your Skill's instructions tell Claude when and how to execute the scripts. The scripts themselves live in the scripts/ folder and do the actual computation.
Here's a complete example:
在你的 SKILL.md 中，你是这样引用这些脚本的：
关键的洞察是：脚本负责处理计算，指令负责进行判断。它们协同工作。
脚本最佳实践
保持脚本专注。一个脚本只做一件事。parse-csv.py 不应该同时计算统计数据，那应该是另一个独立的脚本。
Make scripts accept arguments. Your script should take input/output file paths as command-line arguments, not hardcode them. This makes the Skill flexible.
Include error handling. Your script should exit with a clear error message if the input is malformed, missing, or the wrong format. Claude can then read the error and communicate it to the user.
记录接口文档。在每个脚本的顶部，包含一个注释块，说明：脚本的作用、它需要哪些参数、它会输出什么，以及可能抛出的错误。
这里有一个用于为你的 Skill 构建脚本的提示：
提示：技能SCIPT构建器：
多技能编排：
当你构建了第五个技能之后，会发生这样的情况。你开始注意到冲突。
例如：当你本来想用邮件草拟器时，你的品牌语气执行器却触发了。你的代码审查助手会在一段代码片段上被激活，而你其实只是想格式化它，而不是进行审查。两个技能都认为自己应该处理同一个请求。
这就是多技能编排问题。而且你构建的技能越多，情况就越糟。
为什么 & 如何？
当你发出请求时，Claude 会扫描所有可用的 Skills，并根据你的提示对它们的 YAML 描述进行评估。选择过程大致如下：
Claude reads all available Skill descriptions
它会根据与你的请求的相关性为每个描述打分
得分最高的技能会被触发
如果没有任何技能的评分超过激活阈值，则不会触发任何技能。
问题在于：如果两个技能的触发短语有重叠，可能会触发错误的技能。如果描述过于模糊，技能会在不相关的请求上被触发。如果描述过于狭窄，技能则可能永远不会被触发。
多技能协同规则：
规则一：无重叠领域。每项技能必须有一个清晰定义的领域，不得与其他技能的领域重叠。品牌声音执行者负责声音合规，邮件编写者负责邮件撰写，内容再创作者负责格式转换。没有重叠。
规则 2：强硬的负向边界。每个 Skill 的 YAML 描述必须明确将其他 Skill 的领域列为排除项。你的 Email Drafter 应写明“不要用于品牌语气检查或内容再利用。”你的 Brand Voice Enforcer 应写明“不要用于从零起草电子邮件或内容再利用。”
规则 3：独特的触发语言。每个 Skill 都应有仅属于其功能的触发短语。“Check the voice” 只应匹配 Brand Voice Enforcer。“Draft an email” 只应匹配 Email Drafter。如果你发现为两个 Skill 使用了相同的触发短语，那么其中一个的范围定义就存在问题。
诊断技能冲突
When the wrong Skill fires, the problem is almost always in the YAML description. Here's a prompt that audits your entire Skill library for conflicts:
PROMPT: SKILL CONFLICT AUDITOR
参考策略：
模块1涵盖了基础内容：一个参考文件，一层深度，保持压缩。
但当你的技能需要引用一本50页的品牌指南、一本30页的风格手册，以及一个模板库时，会发生什么呢？
你需要帮助它避免在当前任务中使用不必要的引用，防止烧掉上下文窗口：
提示：参考架构设计师：
Module 2 complete. You now understand the advanced architecture: scripts for computation, multi-skill orchestration for conflict-free deployment, and reference strategies that scale.
在第3模块中，你将学习如何证明你的技能确实有效。不是“试试看”。而是用数据来证明。
模块 3：测试 + 迭代
一个“勉强能用”的 Skill 与一个像训练有素的员工一样运行的 Skill 之间的差别，就在这个模块。通过测试、调试和不断迭代，直到消除各种失败模式。
失效模式：
Before you test anything, you need to know what you're testing for. Every Skill failure falls into one of five categories. Learn to diagnose the category and the fix becomes obvious.
Failure Mode 1: The Silent Skill (Never Fires)
Symptoms: You type a request that should trigger your Skill. Claude responds normally without using the Skill. No indication it was even considered.
根本原因：您的YAML描述过于弱。Claude的激活阈值要求用户请求与描述之间有强烈的匹配。如果您的描述模糊、通用或缺少关键的触发短语，它永远无法超过阈值。
诊断：检查您的描述。它是否明确列出了您刚才输入的单词和短语？如果您说的是"清理这个电子表格"，但您的描述只提到了"CSV文件"，那么您找到了差距。
Fix: Make your description more pushy. Add more trigger phrases. Add context clues. The description should be almost embarrassingly explicit about when to activate.
Failure Mode 2: The Hijacker (Fires on Wrong Requests)
症状：你向Claude询问了一些不相关的事情，但你的技能却被触发了。你本来想起草一封电子邮件，但却启动了内容再利用工具。
根本原因：你的YAML描述过于宽泛，或者缺少负面边界。该描述匹配了过多类型的请求。
诊断：查看你输入的内容，找出请求中哪些词语与该技能的描述相匹配。然后检查这些词语是否本应被排除。
修正：添加负面界限。“请勿用于 [列出所有类似但不同的任务]。”将你的触发短语收紧，使其更具体地对应你技能的实际功能。
故障模式 3: 漂泊者（触发但输出错误）
症状: 技能正确触发，但输出与预期不符。虽然接近，但不完全正确。格式有误、语气不对，或者跳过了某些步骤。
根本原因: 你的指令不明确。有多种方式可以解释你写的内容，而Claude选择了与你意图不同的解释。
诊断: 仔细阅读你的指令，仿佛你从未见过它们。找出那些可能有两种解释的句子。这就是漂泊发生的地方。
修复：用具体、可测试的指令替代模糊的语言。"格式化整齐"变为"每个部分使用H2标题，粗体显示每段的第一句话，每段最多三行。"不留任何解释空间。
失败模式 4：脆弱技能（有时有效，边缘情况时失败）
症状：该技能在干净、格式良好的输入上运行完美。但当你给它一些稍微奇怪的东西（不完整的数据、不寻常的格式、缺失的字段）时，它就崩溃了。
根本原因：你的边缘情况处理不完整。你没有预见到现实世界输入的混乱情况。
诊断：给你的技能输入每种最坏情况的版本。缺少字段。多余的字段。错误的数据类型。部分损坏的文件。混合语言。看看在哪些地方会出错。
修复：添加明确的边界情况指令。对于每一个出错的场景，添加一个具体的指令："如果[条件]，则[特定操作]。"
故障模式 5：过度表现者（添加了你没有要求的内容）
Symptoms: The Skill produces the requested output but also adds unsolicited commentary, extra sections, or creative embellishments you didn't want.
根本原因：你的指令告诉 Claude 应该做什么，但没有说明不应该做什么。没有约束时，Claude 默认会尽可能提供帮助，这有时意味着会做超出你要求的内容。
诊断：查看额外的输出。然后检查你的指令中是否有关于范围和输出边界的明确约束。
解决方法：添加明确的范围约束。“除非用户要求，否则不要添加解释性文字、评论或建议。仅输出[指定格式]，不要输出其他内容。”
提示：故障模式诊断：
测试你的技能：
大多数人容易出错的地方在这里。
他们开发了一个技能，试用两次，看起来“没问题”，然后就继续前进。结果在第三个未预料到的极端情况时，技能惨烈失败。
Skills 2.0 更新消除了猜测的环节。你现在可以在 Claude 内使用内置的专业级测试，所以快去用吧！
评估：编写测试提示。明确定义预期行为。系统将根据这些提示运行你的技能，并返回通过/失败成绩，而不是‘看起来还可以’。通过或失败。
基准：跟踪你的技能的通过率、令牌消耗（成本）和执行速度随时间的变化。你可以查看版本 3 的重写是否真的改进了功能，还是仅仅感觉上有所改善。
A/B 比较器：对两种版本的技能说明进行盲测。得出哪一个版本获胜的硬数据。
描述优化器：明确告诉你，当用户请求任务时，你的 YAML 触发器是否会正确触发。
持续迭代，直到连续两次评估运行都没有显著改进。那就是你的信号：你的 Skill 已经可以投入生产使用。
模块 3 完成。你现在拥有一个生产级的 Skill。
模块 4 是最后一环：部署能够跨会话使用的技能。
模块 4：生产部署
你的技能有效。它们经过测试，已经部署。
Now the question shifts from "does it work?" to "does it work at scale, over time, across sessions?"
状态管理：
当你在多个会话中运行一个技能时（例如写一本书、构建一个复杂的应用程序、或管理一个为期数周的项目），Claude 的上下文窗口最终会被填满。
它忘记了昨天发生的事情。
专家级技能建设者通过"交接班"系统解决这个问题。在你的SKILL.md文件中，你添加一个指令：
"在每次会话开始时，先阅读 context-log.md，看看我们上次完成了什么。在每次会话结束时，写一段总结，说明你已经完成了什么以及还有哪些待处理。"
就是这样。Claude 会读取上一轮会话的笔记，并从上次停止的地方继续。
把它想象成医院的交接班。接班的医生阅读病历。他们清楚地知道发生了什么，待处理的事项，以及需要注意的事项。你的AI也一样。
FINALLY...
You can keep opening Claude every morning and typing the same instructions you typed yesterday. And the day before. And the day before that. Burning through minutes that compound into hours that compound into weeks of lost output.
Or you can spend 10 minutes right now, build one Skill, and never type those instructions again.
构建技能的人们正在像操作定制系统一样使用 Claude，根据他们的具体需求进行调优。
其他人只是像使用聊天框一样使用它。
今天就构建你的第一个技能。选择你最常重复的一项任务。按照上面的步骤操作。部署它。记录下一次使用时运行的速度提升。
然后再构建一个技能。
你首先要自动化的是哪一项任务？在评论区留言吧。我会阅读每一条。
附注：技能创建者元技能可以仅通过对话在不到 5 分钟内帮你构建第一个技能。如果你还在犹豫，不妨从这里开始。
每周：
我都会整理一份简报，涵盖我认为关于现代科技和金融最重要的一切：
你可以在这里阅读每周日发布的免费新闻通讯：
引用列表：
Anthropic 的官方 Agent 技能文档：涵盖技能编写的核心原则、正确的目录结构，以及渐进式披露（progressive disclosure）加载系统。
《Claude 技能构建完整指南》：Anthropic 的一份全面的 32 页指南，详细介绍了用于构建独立技能的基础规则、YAML frontmatter 参考以及工作流程模式。
SKILL.md 模式：深入解析隐式调用与显式调用的区别。
《忙碌人士的 Claude Skills 入门》：一个由社区推动的实用解析，讲解如何快速构建一个 skill，以及 Skills 与 Model Context Protocol (MCP) 之间的根本区别。
技能 2.0 测试与框架：新评估工具的解释，包括 Evals、基准测试、多智能体并行测试和盲 A/B 比较器。
技能创造者元技能：使用 Anthropic 的自动化工作流工具生成、测试和完善明确的技能描述和提示的详细信息。
显示英文原文 / Show English Original
I have combined every resource I have found to create a full course on Claude Skills. In less than 10 minutes you'll have built and deployed your first custom skill. After reading this article you will understand Claude Skills better than 99% of people (yes, really). You're about to be given a full course on creating a Claude Skill, a permanent instruction file that tells Claude exactly how to execute a specific task. Here's how to utilise this article: Module 1: foundations Module 2: architecture Module 3: testing and iteration Module 4: production deployment Module 1: Foundations
In every module I will give you the foundations + how to get AI to help you so that you 1: understand what's going on, and 2: build it correctly without needing technical skills. Let's get straight into it... SKILLS vs PROJECTS vs MCP: Before you build anything, you need to understand where Skills fit inside Claude. Three tools, three different jobs: Projects = your knowledge base. Upload a brand guideline PDF and you're telling Claude: "Here's what you need to know." Static. Reference material. A library. Skills = your instruction manual. You're telling Claude: "Here's exactly how you perform this task, step by step." Procedural. Automated. A trained employee. MCP (Model Context Protocol) = your connection layer. This plugs Claude into live data sources (your calendar, your database, your inbox). Skills then tell Claude what to do with that data. Do you need a skill? If you've typed the same instructions at the start of more than three conversations, that's a Skill begging to be built, or if you want to help Claude become a professional operator in various tasks then creating skills help it become an "employee" in different sectors.
ANATOMY OF A SKILL: Here's where most guides overcomplicate this (and your Claude will help you create this anyway so I wouldn't panic about this): A Skill is a folder on your computer. Inside that folder is a text file. That's it. A folder with a text file called SKILL.md. The folder follows three rules: The Root Folder must use kebab-case naming. That means lowercase, words separated by hyphens. invoice-organiser. email-formatter. csv-cleaner. No spaces. No underscores. No capitals. SKILL.md is the brain. This is case-sensitive. Not skill.md. Not README.md. Exactly SKILL.md. All your instructions live here. references/ is optional. If your instructions need a massive brand guide or a long template, drop it in this subfolder instead of pasting it into SKILL.md.
Drop the whole folder into ~/.claude/skills/ on your machine. Claude finds it automatically. I want you to have this basic understanding so you understand it. WHERE DO THEY RUN? This matters more than most guides tell you. Claude Code is the command-line tool for developers. Skills here live in your project directory under .claude/skills/ or globally at ~/.claude/skills/. They have access to the file system, bash commands, and can execute code. This is where you build Skills that manipulate files, run scripts, and interact with your codebase. Claude Desktop (CoWork) is the desktop agent for non-developers. Skills here work through the desktop interface, and can interact with your screen, applications, and files through the agent's capabilities. Same SKILL.md format. Different execution environment. If you are ever unsure you can always use this prompt:
BUILDING YOUR FIRST SKILL: Step 1: Define the Job Before you write a single word, answer three questions: What does this Skill do? Be ruthlessly specific. "Help with data" is useless. "Transform messy CSV files into clean spreadsheets with proper headers, enforce YYYY-MM-DD date formatting, and strip empty rows" is a Skill that works. When should it fire? Think about what you'd actually type. "Clean up this CSV." "Fix these headers." "Format this data." Those are your triggers. What does "good" look like? You need a concrete example of the finished output. Not a description. An actual before-and-after. Listen closely. This step is where 90% of bad Skills are born. Vague instructions create vague outputs. Every time. Don't trust yourself to get specific enough? This prompt forces the precision out of you.
PROMPT: THE SKILL DEFINITION INTERVIEW: Step 2: Write the YAML Triggers At the top of your SKILL.md file, you write a block of metadata between --- lines. This is called YAML frontmatter. It tells Claude when to activate your Skill. Here's an example: Three rules that make or break your triggers: Write in third person. "Processes files..." not "I can help you..." List exact trigger phrases. Claude is conservative about activation. You need to spell out what the user might say. Be pushy. Set negative boundaries. Tell Claude when NOT to fire. This prevents your Skill from hijacking unrelated conversations.
Here's the thing most people miss. The description field is the single most important line in your entire Skill. If it's weak, your Skill never fires. If it's too broad, it fires when you don't want it to. This prompt generates a battle-tested YAML header from your definition: PROMPT: THE YAML TRIGGER GENERATOR: Step 3: Write the Instructions Below the --- marks, you write your workflow in plain English. Structured with headings. Sequential. Under 500 lines. Two components make this work: The Steps. Break the workflow into a logical sequence: First, read the provided file to understand its structure
Identify the row containing the true column headers Remove any empty rows or rows containing only commas Enforce proper data types (dates must be YYYY-MM-DD) Output the cleaned file with a summary of changes made The Examples. This is where the magic lives. A single concrete example showing input and expected output is worth more than 50 lines of abstract description. PROMPT: THE SKILL INSTRUCTION ARCHITECT: Step 4: The One Level Deep Rule (References) If your instructions reference a massive brand guideline or template, don't paste it all into SKILL.md.
Save it as a separate file inside the references/ folder. Then link to it directly from your instructions. But here's the critical constraint: never have reference files linking to other reference files. Claude will truncate its reading and miss information. One level deep. That's it. If you have existing documents (brand guides, style sheets, templates, SOPs) that your Skill needs to reference, this prompt converts them into properly formatted reference files: PROMPT: THE REFERENCE FILE ORGANISER: Step 5: Assemble and Deploy You've now got every component. Time to put it together. Your folder structure should look like this: Drop the folder into ~/.claude/skills/ on your machine.
Done. But wait. Before you deploy, you want to make sure the whole thing is airtight. This prompt does a final quality assurance pass on your complete SKILL.md file: PROMPT: THE SKILL QA AUDITOR AUTOMATE BUILDING YOUR FIRST SKILL: If everything above feels like too much effort, there's a shortcut. Anthropic built a meta-skill called skill-creator that constructs Skills for you through conversation. Here's how it works: 1. Open a new chat. Type: "Use the skill-creator to help me build a skill for [your task]."
2. Upload your assets. Templates you use. Examples of past work. Brand guidelines. Anything that shows Claude what "good" looks like. 3. Answer the interview. The skill-creator asks you clarifying questions about your process, your edge cases, and your quality standards. 4. It generates everything. The formatted SKILL.md. The pushy description. The folder structure. Packaged and ready. 5. Save the folder to ~/.claude/skills/. Done. Next time you ask Claude to perform that task, your Skill fires automatically. Module 1 complete. You now have a deployed Skill. In Module 2, you're going to learn how to utilise architecture. Module 2: Architecture You'll eventually have quite a few skills, this is where architecture becomes an important part of your arsenal.
Again, I will teach you the manual version of this and then give you prompts to get this done for you, but it's good to know why you're building architecture, that's why I've kept the manual section in... WHEN INSTRUCTIONS AREN'T ENOUGH: Everything you've built so far uses plain English instructions. Claude reads them, follows them, produces output. But some tasks need computation. They need code that runs. Calculations that execute. Data transformations that are too precise for natural language instructions. That's what the scripts/ directory is for. WHEN TO USE SCRIPTS: Use instructions when: The task is about judgement, language, formatting, or decision-making. "Rewrite this in our brand voice." "Categorise these meeting notes." "Draft an email." Claude's language capabilities handle these perfectly. Use scripts when: The task requires precise computation, file manipulation, data transformation, or integration with external tools. "Calculate the running average of these numbers." "Parse this XML file and extract specific fields." "Resize all images in this folder to 800x600."
Use both when: The task requires computation AND judgement. "Process this CSV (script), then write a human-readable summary of the anomalies found (instructions)." How Scripts Work Inside a Skill Your Skill's instructions tell Claude when and how to execute the scripts. The scripts themselves live in the scripts/ folder and do the actual computation. Here's a complete example: In your SKILL.md, you reference the scripts like this: The key insight: The scripts handle the computation. The instructions handle the judgement. They work together. Script Best Practices Keep scripts focused. One script, one job. parse-csv.py doesn't also calculate statistics. That's a separate script.
Make scripts accept arguments. Your script should take input/output file paths as command-line arguments, not hardcode them. This makes the Skill flexible. Include error handling. Your script should exit with a clear error message if the input is malformed, missing, or the wrong format. Claude can then read the error and communicate it to the user. Document the interface. At the top of each script, include a comment block explaining: what the script does, what arguments it expects, what it outputs, and what errors it might throw. Here's a prompt that builds scripts for your Skill: PROMPT: THE SKILL SCIPT BUILDER: MULTI-SKILL ORCHESTRATION: Here's what happens after you build your fifth Skill. You start noticing conflicts. For example: Your Brand Voice Enforcer fires when you wanted the Email Drafter. Your Code Review Assistant activates on a code snippet you just wanted formatted, not reviewed. Two Skills both think they should handle the same request.
This is the multi-skill orchestration problem. And it gets worse the more Skills you build. WHY & HOW? When you make a request, Claude scans all available Skills and evaluates their YAML descriptions against your prompt. The selection process works roughly like this: Claude reads all available Skill descriptions It scores each description against your request for relevance The highest-scoring Skill fires If no Skill scores above the activation threshold, none fires The problem: If two Skills have overlapping trigger phrases, the wrong one might win. If descriptions are too vague, Skills fire on irrelevant requests. If descriptions are too narrow, Skills never fire at all.
RULES FOR MULTI-SKILL HARMONY: Rule 1: Non-overlapping territories. Every Skill must have a clearly defined domain that doesn't bleed into another Skill's domain. The Brand Voice Enforcer handles voice compliance. The Email Drafter handles email composition. The Content Repurposer handles format transformation. No overlap. Rule 2: Aggressive negative boundaries. Every Skill's YAML description must explicitly list the other Skills' territories as exclusions. Your Email Drafter should say "Do NOT use for brand voice checks or content repurposing." Your Brand Voice Enforcer should say "Do NOT use for drafting emails from scratch or repurposing content." Rule 3: Distinctive trigger language. Each Skill should have trigger phrases that are unique to its function. "Check the voice" should only match the Brand Voice Enforcer. "Draft an email" should only match the Email Drafter. If you find yourself using the same trigger phrase for two Skills, one of them has a scope problem. Diagnosing Skill Conflicts When the wrong Skill fires, the problem is almost always in the YAML description. Here's a prompt that audits your entire Skill library for conflicts: PROMPT: SKILL CONFLICT AUDITOR REFERENCE STRATEGIES:
Module 1 covered the basics: one reference file, one level deep, keep it compressed. But what happens when your Skill needs to reference a 50-page brand guide, a 30-page style manual, AND a library of templates? You need to help it from burning its context window on references it doesn't need for the current task at hand: PROMPT: REFERENCE ARCHITECTURE DESIGNER: Module 2 complete. You now understand the advanced architecture: scripts for computation, multi-skill orchestration for conflict-free deployment, and reference strategies that scale. In Module 3, you're going to learn how to prove your Skills work. Not "try it and see." Prove it with data. Module 3: Testing + Iteration The difference between a Skill that "kind of works" and a Skill that runs like a trained employee is this module. Testing, debugging, iterating until the failure modes are eliminated.
FAILURE MODES: Before you test anything, you need to know what you're testing for. Every Skill failure falls into one of five categories. Learn to diagnose the category and the fix becomes obvious. Failure Mode 1: The Silent Skill (Never Fires) Symptoms: You type a request that should trigger your Skill. Claude responds normally without using the Skill. No indication it was even considered. Root cause: Your YAML description is too weak. Claude's activation threshold requires a strong match between the user's request and the description. If your description is vague, generic, or missing key trigger phrases, it never crosses the threshold. Diagnosis: Look at your description. Does it explicitly list the words and phrases you just typed? If you said "clean up this spreadsheet" but your description only mentions "CSV files," you've found the gap. Fix: Make your description more pushy. Add more trigger phrases. Add context clues. The description should be almost embarrassingly explicit about when to activate. Failure Mode 2: The Hijacker (Fires on Wrong Requests)
Symptoms: You ask Claude something unrelated and your Skill activates. You wanted to draft an email but the Content Repurposer fired instead. Root cause: Your YAML description is too broad, or your negative boundaries are missing. The description matches too many types of requests. Diagnosis: Look at what you typed and find which words in your request matched the Skill's description. Then check whether those words should have been excluded. Fix: Add negative boundaries. "Do NOT use for [list every similar-but-different task]." Tighten your trigger phrases to be more specific to your Skill's actual function. Failure Mode 3: The Drifter (Fires But Produces Wrong Output) Symptoms: The Skill activates correctly but the output doesn't match what you expected. It's close but not right. Formatting is off, tone is wrong, or it skips steps. Root cause: Your instructions are ambiguous. There's more than one way to interpret what you wrote, and Claude chose a different interpretation than you intended. Diagnosis: Read your instructions as if you've never seen them before. Find the sentences that could mean two different things. That's where the drift happens.
Fix: Replace ambiguous language with specific, testable instructions. "Format nicely" becomes "Use H2 headings for each section, bold the first sentence of each paragraph, keep paragraphs to 3 lines max." Leave zero room for interpretation. Failure Mode 4: The Fragile Skill (Works Sometimes, Breaks on Edge Cases) Symptoms: The Skill works perfectly on clean, well-formed inputs. But when you give it something slightly weird (incomplete data, unusual formatting, missing fields), it collapses. Root cause: Your edge case handling is incomplete. You didn't anticipate the messy reality of real-world inputs. Diagnosis: Feed your Skill the worst-case version of every input. Missing fields. Extra fields. Wrong data types. Partially corrupted files. Mixed languages. See where it breaks. Fix: Add explicit edge case instructions. For every scenario where it breaks, add a specific instruction: "If [condition], then [specific action]." Failure Mode 5: The Overachiever (Adds Things You Didn't Ask For) Symptoms: The Skill produces the requested output but also adds unsolicited commentary, extra sections, or creative embellishments you didn't want.
Root cause: Your instructions tell Claude what TO do but not what NOT to do. Without constraints, Claude defaults to being maximally helpful, which sometimes means doing more than you asked. Diagnosis: Look at the extra output. Then check your instructions for explicit constraints about scope and output boundaries. Fix: Add explicit scope constraints. "Do NOT add explanatory text, commentary, or suggestions unless the user asks for them. Output ONLY the [specified format] and nothing else." PROMPT: THE FAILURE MODE DIAGNOSTIC: TESTING YOUR SKILL: Here's the thing most people get wrong. They build a Skill, try it twice, it looks "fine," and they move on. Then it fails spectacularly on the third edge case they didn't anticipate. The Skills 2.0 update killed the guesswork. You now have professional-grade testing built in to Claude so go and use it!
Evals: Write test prompts. Define exactly what the expected behaviour should be. The system runs your Skill against those prompts and returns a Pass/Fail grade. Not "looks okay." Pass. Or Fail. Benchmarks: Track your Skill's pass rate, token consumption (cost), and execution speed over time. You can see whether your version 3 rewrite actually made things better or just felt like it did. A/B Comparator: Run a blind test between two versions of your Skill's instructions. Hard data on which one wins. Description Optimiser: Tells you definitively whether your YAML triggers will fire correctly when users ask for the task. Keep iterating until two consecutive evaluation runs show no significant improvement. That's your signal. Your Skill is production-ready. Module 3 complete. You now have a production-grade skill. Module 4 is the final piece: deploying skills that work across sessions. Module 4: Production Deployment
Your Skills work. They're tested. They're deployed. Now the question shifts from "does it work?" to "does it work at scale, over time, across sessions?" STATE MANAGEMENT: When you're running a Skill across multiple sessions (writing a book, building a complex app, managing a multi-week project), Claude's context window eventually fills up. It forgets what happened yesterday. Expert Skill builders solve this with a "shift handover" system. Inside your SKILL.md, you add one instruction: "At the start of every session, read context-log.md to see what we completed last time. At the end of every session, write a summary of what you finished and what's still pending." That's it. Claude reads its own notes from the previous session and picks up exactly where it left off.
Think of it like a hospital shift change. The incoming doctor reads the chart. They know exactly what happened, what's pending, and what to watch for. Your AI works the same way. FINALLY... You can keep opening Claude every morning and typing the same instructions you typed yesterday. And the day before. And the day before that. Burning through minutes that compound into hours that compound into weeks of lost output. Or you can spend 10 minutes right now, build one Skill, and never type those instructions again. The people who build Skills are operating Claude like a custom-built system tuned to their exact specifications. Everyone else is using it like a chatbox. Build your first Skill today. Pick the one task you repeat most often. Follow the steps above. Deploy it. Time how much faster your next session runs. Then build another one.
Which task are you automating first? Drop a comment. I read every one. P.S. The skill-creator meta-skill can build your first Skill in under 5 minutes through conversation alone. If you're still on the fence, start there. EVERY WEEK: I put together a newsletter including everything I deem important about modern technology and finance: You can read every Sunday's free newsletter here: Citation list: Anthropic's Official Agent Skills Documentation: Covers the core principles of skill authoring, proper directory structures, and the progressive disclosure loading system. The Complete Guide to Building Skills for Claude: Anthropic's comprehensive 32-page guide detailing foundational rules, YAML frontmatter reference, and workflow patterns for building standalone skills.
The SKILL.md Pattern: Provides a deep dive into implicit versus explicit invocation. The Busy Person's Intro to Claude Skills: A practical, community-driven breakdown of how to build a skill quickly and the fundamental differences between Skills and the Model Context Protocol (MCP). Skills 2.0 Testing and Frameworks: Explanations of the new evaluation tools, including Evals, Benchmarks, multi-agent parallel testing, and blind A/B comparators. The Skill-Creator Meta-Skill: Details on using Anthropic's automated workflow tool to generate, test, and refine explicit skill descriptions and prompts.
