# Claude Code Skill 究竟是什么？完整解读与实战指南 许多用户在使用 Claude Code 时，仍将其视为普通的对话式 AI 工具。简单输入指令，期待直接输出答案。结果好则惊喜，结果差则归咎于模型能力。 然而，真正将 AI 转化为生产力的人，关注的不是“如何问”，而是“如何让 AI 严格按照我的标准、流程与节奏稳定交付”。这正是 Skill 的核心价值所在。 Skill 并非某种神秘插件，而是一份面向 AI 的标准操作手册：它明确告知 Claude Code 何时触发、按什么步骤执行、读取哪些文件、调用哪些脚本、输出结果存放位置，以及失败时的恢复步骤。 这篇文章对应的是我开源的 Workflow Agent Skill 规范： * GitHub 仓库地址：https://github.com/xiangyugongzuoliu/workflow-agent-skill-spec * 文章侧重设计思路：为什么需要分层、脚本与 Prompt 如何分工、为什么必须包含运行状态和测试机制。 * 仓库提供可直接复制的结构目录：`docs/`、`templates/`、`schemas/`、`evals/`、`scripts/validate-spec.py`。 如果你只想理解 Skill 的设计方法论，优先阅读这篇文章。如果你希望 Agent 直接按照规范帮你新建、审查或升级 Skill，则可将 GitHub 仓库交给它。  ## 先建立全局图：五层架构 一个生产级 Skill，我将其拆解为五层架构。 第一层是核心层：`SKILL.md`、工作流表格、平台约束。它定义 Skill 是什么、何时触发、执行几项步骤。 第二层是执行层：`scripts/`、`prompts/`、变量占位符。脚本负责确定性的体力活，Prompt 负责需要判断的脑力活。 第三层是数据层：`runs/`、`state/`、`config/`、`params.schema.json`。它决定每次运行的数据存放位置、进度记录方式以及断点恢复逻辑。 第四层是资源层：`credentials/`、`definitions/`、`presets/`、`templates/`。它管理凭证、常量、预设和输出模板，使 Skill 更安全、更可配置。 第五层是工程化层：`setup.md`、`guide.md`、`changelog.md`、`troubleshoot.md`。它让其他人能够安装、理解、维护和排查问题。 最小可用 Skill 只需要第一层。真正稳定复用的 Skill 通常会逐步长出后面四层。  ## 第一部分：核心概念 一个 Skill 的入口永远是 `SKILL.md`。 你可以把它理解为一本书的封面和目录。封面告诉系统“我叫什么、我能做什么”，目录告诉 Claude Code“按什么顺序执行”。 最小结构如下： ``` my-first-skill/ └── SKILL.md ``` 更完整的结构会变成： ``` my-first-skill/ ├── SKILL.md └── workflow/ ├── step01-init.md ├── step02-process.md └── step03-output.md ``` `SKILL.md` 的 frontmatter 至少需要两个字段：`name` 和 `description`。 `name` 使用小写字母和连字符，便于系统识别。`description` 要清晰写明功能和触发条件，尽量采用第三人称，避免“我可以帮你”这类对话式表述。 真正重要的是工作流表格。它必须详细说明每一步的职责、执行者、文档、输入和输出。 一个优秀的 Skill 不是把所有工作都交给 Claude Code 临场发挥，而是将流程拆分成清晰的任务单元：第一步初始化，第二步采集，第三步分析，第四步输出。  ## 第二部分：执行层 Skill 开发中最容易踩的坑是：让 Claude Code 直接处理所有事情。 核心原则很简单：确定性操作交给脚本，需要判断的任务交给模型。 例如批量重命名、读取 JSON、合并 CSV、下载图片、校验文件结构等，都应该写成脚本。脚本稳定、高效，不会消耗大量上下文。  而判断标题是否吸引人、分析用户痛点、选择写作角度、诊断内容质量等任务，则适合交给 Claude。 Prompt 模板也需要标准化。一个生产级 Prompt 至少应包含六项内容： 1. 角色：你是谁。 2. 任务：你要做什么。 3. 输入：从哪里读取数据。 4. 输出：写入哪个文件。 5. 约束：哪些操作不允许。 6. 验收：如何判断完成。  变量占位符负责将这些部分串联起来，例如 `{input_path}`、`{run_dir}`、`{output_path}`。不要让 Agent 自行猜测路径，路径必须从状态文件或参数中明确传递。 ## 第三部分：数据层 复杂 Skill 最怕的不是失败，而是运行到一半不知进展。 因此每次运行都应该有独立的运行目录： ``` runs/ └── article-20260430-130000/ ├── state/ │ └── progress.json ├── output/ └── logs/ ``` `progress.json` 是心跳文件。它至少需记录当前步骤、输入路径、输出路径、状态、错误信息和时间戳。 这样，当上下文被压缩、会话中断或任务失败后，Agent 仍然可以通过状态文件知道：已进行到哪一步、下一步该做什么、是否可以恢复。  配置也需要分层管理。 交互参数是本次运行时用户临时给出的，例如主题、平台、风格。默认配置是 Skill 自带的稳定参数，如输出目录、模型偏好。预设配置是可复用的选项，例如“公众号风格”“小红书风格”“专业报告风格”。 这三层不能混在一起，否则后续维护必然混乱。 ## 第四部分：资源层 资源层解决的是“不要把隐性规则散落到各处”。 凭证放入 `credentials/`，且真实密钥不能进入 Git。常量放入 `definitions/`，例如平台枚举、评分项、字段名。用户可选项放入 `presets/`，如风格、模板、输出尺寸。HTML 或 Markdown 输出样式放入 `templates/`。 为什么要这么繁琐？ 因为魔法字符串会破坏可维护性。 如果你在 8 个文件中手动写入同一个平台名、同一个字段名、同一个风格选项，每次修改都需要全局搜索。更糟糕的是，Agent 可能只修改了其中 5 个，留下 3 个旧值。 生产级 Skill 的资源层，本质上是在为 Agent 保留一套“唯一真相源”。 ## 第五部分：工程化层 如果一个 Skill 只有你自己能用，它还不算真正完成。 `setup.md` 解决安装和依赖问题。`guide.md` 指导新手如何使用。`changelog.md` 记录版本变更。`troubleshoot.md` 列出常见故障及解决方案。 这四件套看似不性感，但非常关键。 当 Skill 数量增多时，你会发现真正耗时的是：三周后你忘了如何安装、半年后你不知道它为什么坏、换一台电脑后你不知道缺少哪个依赖。 工程化文档就是给未来的自己省时间。  ## 实战：20 分钟做第一个 Skill 最适合入门的案例，是一个文章翻译 Skill。 需求很简单：输入一篇英文 Markdown 文件路径，输出翻译后的中文 Markdown，保留标题、列表、代码块和链接。 目录只需要三个文件： ``` xiangyu-content-article-translating/ ├── SKILL.md └── workflow/ ├── step01-init.md └── step02-translate.md ``` `SKILL.md` 可以这样写： ```markdown --- name: xiangyu-content-article-translating description: 将英文 Markdown 文章翻译为中文，保留原文格式和结构。当用户说「翻译文章」「translate article」「转中文」时触发。 --- # 文章翻译 Skill ## 工作流 Step 01 初始化：读取用户提供的文件路径，创建 runs 目录和 progress.json。 Step 02 翻译输出：启动 SubAgent 读取源文件，翻译后写入 output/translated.md。 ## 执行规范 - 渐进式披露：执行一步读一步。 - 传路径，不传全文。 - SubAgent 返回极简状态，翻译结果写文件。 ``` 第一步初始化，检查文件是否存在，创建运行目录。第二步翻译输出，启动 SubAgent，将源文件路径和输出路径传给它。 关键点不是翻译本身，而是设计习惯：路径明确、输出明确、状态明确、验证明确。 这就是 Skill 开发的基本功。  ## 最后 写 Skill 的过程，本质上是在把你的隐性经验变成显性流程。 你脑子里“怎么写一篇好文章”的直觉变成步骤文档；你“怎么做一次质量检查”的经验变成检查清单；你“怎么排查失败”的经验变成 `troubleshoot.md`。 这就是 AI 工作流真正的价值所在：不是让 AI 偶尔帮你一次，而是让你的方法可以被复用、被调用、被改进。 从这个角度看，Skill 不是插件。 Skill 是你的数字操作手册。 ## 常见问题 ### 不会写代码能开发 Claude Code Skill 吗？ 可以。最小可用 Skill 只需要一个 `SKILL.md` 文件。只有当工作流需要调用 API、批量处理文件或复用确定性逻辑时，才需要增加脚本。 ### Skill 和 MCP 有什么区别？ MCP 是让 AI 调用外部工具的接口，Skill 是让 AI 按固定流程完成任务的操作手册。Skill 可以在执行步骤里调用 MCP 工具，两者是互补关系。 ### 一个 Skill 应该做多少步？ 没有硬性上限，但生产实践中建议控制在 6 到 8 步以内。超过 10 步时通常应该拆成多个 Skill，或者把确定性部分下沉到脚本。