微信扫码
添加专属顾问
掌握Claude Code Skill开发规范,10分钟打造高效AI工作流,告别重复劳动。 核心内容: 1. Skill开发的核心方法论与规范体系 2. 复杂任务的分层拆解与执行策略 3. 可直接复用的开发模板与实战案例
过去三个月,我用 Claude Code 创建了 30+ 个工作流 Skill:公众号自动发布、文章批量翻译、PPT 一键生成、代码审查……每个 Skill 都是一套完整的自动化流水线。
在这个过程中,我踩过无数坑:上下文爆满导致任务中断、步骤之间数据传递混乱、复杂流程无法断点恢复。反复试错后,我把这些经验沉淀成一套系统方法论——Skill 规范。
这套规范解决三个核心问题:
我把这套方法论沉淀成 7.8 万字的完整规范文档,并浓缩成这篇指南。掌握后,创建一个新 Skill 的时间从「摸索半天」缩短到「十分钟搞定」。
读完这篇文章,你会获得:
前置知识要求:了解 Claude Code 基本操作即可,不需要编程基础。
用一句话解释:Skill 就是一个文件夹,里面装着告诉 Claude 「做什么、怎么做、做成什么样」的说明文件。
打个比方。你去星巴克点一杯拿铁,店员不需要你解释什么是拿铁、用什么豆子、加多少奶。因为星巴克有标准作业流程(SOP),每个店员只要按 SOP 做,出品就是稳定的。
Skill 就是 Claude 的 SOP。
没有 Skill 的情况:你每次都要从头告诉 Claude「帮我写一篇公众号长文,风格要像某某博主,结构是先抛问题再给方案,最后要有金句……」——费时费力,而且每次说法不一样,效果也不稳定。
有了 Skill 的情况:你只需要说「写公众号长文」,Claude 自动加载对应的 Skill,按照你预设好的风格、结构、流程来执行,输出质量稳定一致。
💡 说人话
Skill = 可复用的 AI 工作模板。写一次,用无数次。
你可能会问:我直接写个 SKILL.md 文件不就行了,为什么还要搞这么多规范?
原因有三个:
第一,Claude 的「记忆」是有限的。Claude Code 的上下文窗口是 200k token,听起来很大,但一个复杂工作流跑下来,很容易就吃满了。规范帮你设计「渐进式加载」机制——只在需要的时候才读取相关文档,不浪费宝贵的上下文空间。
第二,复杂任务需要「分工」。有些事情脚本做更快(比如调 API 采集数据),有些事情必须让 AI 来判断(比如评估内容质量)。规范帮你明确「谁干什么」,避免用 AI 做机械劳动,也避免让脚本做需要智能的事。
第三,团队协作需要「共识」。当你的 Skill 要给别人用、或者要维护升级的时候,没有规范就是灾难。规范让 Skill 变成「可读的代码」,别人一看就知道怎么用、怎么改。
🎯 打个比方
规范之于 Skill,就像建筑规范之于房子。没有规范,你可以盖个能住的房子;有了规范,你盖的房子能通过验收、能卖给别人、能安全地住几十年。
一个 Skill 就是一个文件夹。但这个文件夹里要放什么、怎么组织,直接决定了 Skill 好不好用、好不好维护。
最简单的 Skill 长这样:
没错,只要一个 SKILL.md 文件就能工作。这是「单步骤」Skill,适合简单任务。
当任务变复杂,就需要更丰富的结构:
🧩 结构拆解
把它想象成一个公司的组织架构:
SKILL.md 是「公司章程」——定义这个 Skill 是干什么的 workflow/ 是「部门手册」——每个步骤怎么执行 reference/ 是「知识库」——执行时需要参考的资料 scripts/ 是「工具箱」——确定性的操作用脚本完成 runs/ 是「项目档案」——每次运行的数据记录
重要原则:只创建实际需要的目录。
一个简单的格式转换 Skill,不需要 workflow/、reference/、scripts/。直接在 SKILL.md 里写清楚逻辑就行。
规范给你的是「菜单」,不是「套餐」。你根据需要点菜,而不是把菜单上所有菜都点一遍。
目录添加时机:
SKILL.md 是 Skill 的入口文件,也是最重要的文件。Claude Code 通过读取这个文件来理解 Skill 是干什么的、什么时候触发、怎么执行。
每个 SKILL.md 文件开头必须有 YAML frontmatter:
---
name: xiangyu-social-wechat-creating
description: 创作公众号长文。当用户说「写长文」「公众号创作」时触发。
---
name 字段规则:
-ing 动名词形式四级命名体系:
description 字段规则:
{核心功能}。{触发条件}📝 记住这个
name 是 Skill 的「身份证号」,全局唯一;description 是「自我介绍」,让 Claude 知道什么时候该用这个 Skill。
告诉 Claude 什么关键词会触发这个 Skill:
这是 SKILL.md 的核心——定义整个工作流的步骤。每个步骤包含以下信息:
🏗️ 设计洞见
工作流定义是「地图」,让 Claude 和人类都能快速了解整个流程。Claude 不会一开始就读取所有 workflow/*.md 文件——它只看这个定义,然后在执行到某一步时才去读对应的文档。这就是「渐进式加载」的核心。
这是规范中最重要的设计决策之一:每个步骤由谁来执行。
选对执行者,效率翻倍;选错执行者,事倍功半。
1. 脚本(Script)
适合:确定性操作——输入确定、输出确定、不需要判断
优势:零上下文成本,执行快,结果稳定
2. SubAgent
适合:需要 AI 判断的任务——理解、评估、生成、创作
优势:能处理模糊任务,具备理解和判断能力
3. 主 Agent
适合:简单协调任务——读取配置、流程控制
优势:直接在对话中执行,无需启动新 Agent
4. 准备 SubAgent
适合:大批量数据预处理——需要在执行前先做准备工作
优势:处理海量数据时,避免主 Agent 上下文爆炸
🔬 底层原理
为什么要区分这四种执行者?因为它们的「上下文成本」完全不同:
脚本:零成本(只返回一行 JSON 状态) SubAgent:中等成本(执行历史会注入主对话) 主 Agent:累积成本(所有操作都在主对话中) 准备 SubAgent:可控成本(完成后立即压缩) 200k token 的上下文窗口看似很大,但如果不注意控制,几个步骤就能吃满。
问自己:任务需要做什么?
实战案例对比:
每个步骤都有一个对应的文档,告诉执行者具体怎么做。
步骤文档应包含以下部分:
# Step 02: 数据采集
执行者: 脚本
输入: 用户参数
输出: step02-collect/
---
执行说明:{具体执行步骤描述}
输入文件:说明每个输入文件的来源和用途,
如 state/config.json 来自 Step 01 输出,包含用户配置参数
输出文件:说明每个输出文件的格式和内容,
如 step02-collect/data.json 是 JSON 格式的采集原始数据
脚本执行:cd {skill_dir}/scripts/python && uv run python collect.py --run-dir {run_dir}
验证检查点:
- 2a: 数据文件存在 — step02-collect/data.json 存在且非空
- 2b: JSON 格式正确 — 可解析为有效 JSON
- 2c: 数据量合理 — items.length > 0
下一步:→ Step 03: 内容分析
1. 执行说明:用自然语言描述这一步要做什么,让人和 AI 都能看懂。
2. 输入/输出文件:明确数据从哪来、到哪去。这是步骤之间的「接口合同」。
3. 验证检查点:每个步骤完成后要验证什么。这是质量保障的关键。检查点编号格式:{步骤号}{字母},如 2a、2b、2c。
4. 下一步指引:明确告诉执行者接下来去哪。
❓ 你可能会问
「检查点这么细,会不会太繁琐?」
不会。检查点是你的「安全网」。当 Skill 出问题时,你能精确定位到哪个步骤、哪个检查点失败。没有检查点,出了问题就像大海捞针。
每次运行 Skill,都会在 runs/ 目录下创建一个新的运行目录,存放本次运行的所有数据。
格式:{keyword}-{YYYYMMDD-HHMMSS}
示例:
claude-code-20260130-103000(调研「Claude Code」)karpathy-20260130-143000(分析 @karpathy)运行目录包含以下内容:
progress.json 存放运行状态,核心字段包括:
/compact 后如何恢复🌉 用生活理解技术
progress.json 就像游戏的「存档点」。如果中途退出(或上下文爆满需要压缩),下次进来可以从存档点继续,不用从头开始。
脚本是 Skill 的「执行力」——所有确定性操作都应该用脚本完成。
看一个对比:
用 SubAgent 采集 100 条数据:上下文消耗约 8,000 tokens,执行时间约 30 秒
用脚本采集 100 条数据:上下文消耗约 50 tokens(只返回一行状态),执行时间约 5 秒
节省 99% 的上下文空间。这就是为什么规范强调「能用脚本就不用 Agent」。
编写脚本时需遵循以下规范:
ok 字段表示成功或失败err 字段,截断到 100 字符以控制输出--run-dir 参数传入运行目录,不硬编码路径调用脚本时,必须 cd 到脚本目录确保 pyproject.toml 生效。
这是规范中最容易被忽视、但最容易出问题的部分。
主要消耗来源:
关键警告:SubAgent 的执行历史会注入主对话上下文。如果你全并行启动 6 个 SubAgent,就是一次性注入 60k tokens。
核心规则:每轮最多启动 2 个 SubAgent,完成后必须 /compact。
执行模式:轮次 1 启动 Agent 1 + Agent 2,等待完成后 /compact;轮次 2 启动 Agent 3 + Agent 4,等待完成后 /compact;以此类推。
为什么是 2 个? 因为可用上下文空间约 50k tokens(需为 Agent 返回预留),单 Agent 返回约 10k tokens,安全并行度约为 5,保守取值 2 以留有余量。
SubAgent 完成后只返回状态,不返回内容。例如:{"ok": true, "batch": 1, "count": 30}
禁止返回:文件内容、分析结果列表、详细日志。
⚡ 三秒版
分轮执行 + 极简返回 + 及时压缩 = 上下文可控。
初始化步骤(通常是 Step 01)需要收集用户输入。规范使用 AskUserQuestion 工具来实现。
模式 A:核心输入(通常走 Other)
询问关键词、用户名等核心参数,提供几个示例选项,用户通常选 Other 输入自定义值。
模式 B:预设选择
询问目标市场、语言等,从预设文件读取选项供用户选择。
模式 C:模式切换
询问执行模式,如「完整流程」或「仅采集」,固定选项,切换执行路径。
模式 D:可选补充(含跳过)
询问可选参数,如品牌筛选,第一个选项为「跳过」,允许用户不填。
单次调用收集多个参数(推荐):一次 AskUserQuestion 最多包含 4 个问题,同时收集多个参数。
多轮询问(超过 4 个问题时):第一轮收集核心参数,第二轮根据第一轮结果收集补充参数。
好的 Skill 要能跑,更要能从错误中恢复。
当 /compact 或中断后恢复:
state/progress.json恢复提示 字段有时候一个 Skill 需要支持多种执行模式。比如公众号克隆 Skill,可以从博主主页采集(Clone 模式),也可以从已有数据分析(Timeline 模式)。
多模式 Skill 的 workflow/ 目录按模式分子目录:
不同关键词触发不同模式:
多模式 Skill 的运行目录带模式前缀:
clone-karpathy-20260130-103000timeline-sama-20260130-143000最后,必须了解 Claude Code 的硬性限制,这些是规范设计的「物理边界」。
Claude Sonnet/Haiku/Opus 模型上下文窗口为 200k tokens,有效可用约 180k。
~/.claude/skills/<name>/.claude/skills/<name>/复制下面这段提示词给 Claude Code,从零创建你的第一个 Skill:
你是 AI 工作流架构师。请帮我创建一个完整的 Skill,遵循翔宇 Skill 规范。
**Skill 信息**:
- 名称:xiangyu-{domain}-{target}-{action}(请根据我的需求填写)
- 功能:{我会告诉你具体功能}
**创建要求**:
1. **目录结构**:
- SKILL.md:入口文件,包含 frontmatter(name + description)、触发条件、工作流定义
- workflow/:步骤文档(stepNN-action.md 格式)
- 按需创建 reference/、scripts/、config/
2. **SKILL.md 规范**:
- frontmatter 用 kebab-case
- name 最多 64 字符,小写+数字+连字符
- description 第三人称,格式「{功能}。{触发条件}」
- 工作流定义包含:Step / 职责 / 执行者 / 文档 / 输入 / 输出
3. **步骤文档规范**:
- 文件名:stepNN-{action}.md(NN 两位数字)
- 包含:执行者、输入、输出、执行说明、验证检查点
4. **执行者选择**:
- 确定性操作(API 调用、文件处理)→ 脚本
- 需要 AI 判断(评估、生成)→ SubAgent
- 简单协调 → 主 Agent
5. **上下文管理**:
- SubAgent 每轮最多 2 个
- 完成后返回极简 JSON({"ok": true, ...})
- 及时 /compact
6. **输出目录**:
- 固定目录:state/、output/
- 动态目录:step{NN}-{action}/(与 workflow 文件名对应)
请问你想创建什么功能的 Skill?告诉我具体需求,我会按照规范帮你生成完整的文件结构和内容。53AI,企业落地大模型首选服务商
产品:场景落地咨询+大模型应用平台+行业解决方案
承诺:免费POC验证,效果达标后再合作。零风险落地应用大模型,已交付160+中大型企业
2026-11-12
维护3.3万字符的长Prompt?让优化Agent迭代执行Agent
2026-11-07
简单设置,立刻让WorkBuddy聪明百倍
2026-10-28
生产级提示词案例分析: Claude Fable 5.1 系统提示词
2026-10-21
生产级提示词案例分析:Claude 聊天界面系统提示词
2026-10-14
卡帕西用航空规范教AI「说人话」:我把这套方法做成了技能
2026-10-11
Prompt缓存:文档写了什么
2026-10-06
OpenAI 亲自教你如何用 Astra
2026-10-05
普通人与 AI 协助开发项目的完整闭环(附全套提示词 PDF)
2026-10-02
2026-09-09
2026-09-05
2026-08-26
2026-09-15
2026-10-14
2026-09-13
2026-09-16
2026-08-24
2026-09-25
2026-09-25
2026-08-23
2026-06-17
2026-05-23
2026-05-16
2026-04-14
2026-02-28
2026-02-12
欢迎您使用【53AI 官方网站】(以下简称“本网站”或“我们”)。本《会员服务协议》(以下简称“本协议”)是您(以下简称“会员”或“用户”)与【深圳市博思协创网络科技有限公司】之间关于注册、登录及使用本网站会员服务所订立的法律协议。
在您注册或登录前,请务必审慎阅读、充分理解各条款内容,特别是免除或限制责任的条款、知识产权条款、争议解决条款等。此类条款将以加粗形式提示您注意。 当您通过微信公众号授权、手机验证码验证或其他方式成功登录本网站时,即视为您已完全理解并同意接受本协议的全部内容。
一、 定义
本网站:指由【深圳市博思协创网络科技有限公司】运营的,域名为【53ai.com】的网站及相关移动端页面。
会员服务:指本网站向注册会员提供的知识库文章查阅、内容检索及其他相关增值服务。
知识库内容:指本网站发布的包括但不限于文字、图表、数据、研究报告、行业分析等数字化内容资源。
二、 账号注册与登录
登录方式:本网站支持以下登录方式,您可根据实际情况选择:
微信公众号授权登录:您同意将您的微信OpenID信息授权给本网站,用于创建或关联会员账号。
手机验证码登录:您需提供真实有效的手机号码,并通过短信验证码完成身份验证与登录/注册。
账号安全:您的账号仅限您本人使用,禁止赠与、借用、租用、转让或售卖。因您保管不善导致的账号被盗、密码泄露等损失,由您自行承担。
实名认证:根据相关法律法规要求,我们可能要求您在特定功能下完成实名认证。如您拒绝提供,可能无法使用部分或全部服务。
未成年人保护:若您未满18周岁,请在法定监护人的陪同下阅读本协议,并在征得监护人同意后使用本服务。
三、 服务内容与规范
知识库查阅权限:会员登录后,有权按照其会员等级对应的权限范围,在线浏览、检索本网站知识库中的相关文章及内容。
服务变更:我们有权根据业务发展需要,调整、变更或终止部分服务内容,并将以网站公告、公众号消息等方式提前通知。
禁止行为:您在使用服务时不得实施以下行为:
利用技术手段批量爬取、下载、转存知识库内容;
将知识库内容用于商业目的或未经授权地向第三方传播;
干扰本网站正常运行或侵犯其他用户合法权益;
发布违法违规信息或从事违反公序良俗的活动。
四、 知识产权声明
权利归属:本网站知识库中的排版设计、软件代码等内容的知识产权均归【公司全称】或原权利人所有,受《中华人民共和国著作权法》等法律保护。
有限许可:本网站授予会员一项非独占、不可转让、不可转授权的普通许可,仅限于个人学习、研究之目的在线查阅知识库内容。
侵权追责:未经书面许可,任何单位或个人不得以任何形式复制、转载、摘编、镜像、汇编或以其他方式使用上述内容。一经发现,我们保留追究其法律责任的权利。
五、 个人信息保护
我们重视对您个人信息的保护。关于我们如何收集、使用、存储和保护您的个人信息,请单独阅读 《隐私政策》。
您通过微信公众号授权或手机号验证所提供的信息,我们将严格按照《个人信息保护法》的规定处理,仅用于身份识别、服务提供及安全验证等必要用途。
您可以随时通过网站设置或联系客服行使查阅、更正、删除个人信息及撤回授权同意的权利。
六、 免责声明
内容准确性:知识库内容仅供参考,不构成专业建议。我们不对其完整性、准确性、时效性作任何明示或暗示的保证,您应自行判断并承担使用风险。
不可抗力:因自然灾害、政策法规变化、网络故障、第三方平台接口异常(如微信接口维护、运营商短信通道故障)等不可抗力导致的服务中断或延迟,我们不承担违约责任。
第三方链接:本网站可能包含指向第三方网站的链接,该等网站的内容和服务不受我们控制,请您自行甄别风险。
七、 违约责任
如您违反本协议约定,我们有权视情节采取警告、限制功能、暂停服务、注销账号等措施,并保留要求赔偿损失的权利。
如因您的违约行为导致我们遭受行政处罚、第三方索赔或商誉损失,您应承担全部赔偿责任(包括但不限于罚款、赔偿金、律师费、公证费等)。
八、 法律适用与争议解决
本协议的订立、执行和解释均适用中华人民共和国大陆地区法律。
因本协议产生的或与本协议有关的任何争议,双方应友好协商解决;协商不成的,任何一方均可向【公司所在地】有管辖权的人民法院提起诉讼。
九、 其他
本协议构成双方就本服务达成的完整协议,取代此前任何口头或书面约定。
本协议任一条款被认定为无效或不可执行的,不影响其他条款的效力。
我们对本协议享有最终解释权,并在法律允许的范围内保留随时修改的权利。修改后的协议一经公布即生效,继续使用服务即视为同意修订内容。