Claude Code Skill 开发手把手教程
去年到现在，我用 Claude Code 做了 30 多个自动化工具。有帮公众号发文的小助手，有批量翻译文章的工具，还有一键生成 PPT 的脚本。这些工具帮我省下大量时间。
做第一个工具时，我踩了不少坑。做着做着程序就卡住不动，数据传到后面步骤就乱了，做到一半想停都不知道从哪继续。后来慢慢摸索出一套做法，现在十分钟就能做出一个新工具。
这篇文章就是把这套做法分享出来。看完你会明白：
一个自动化工具该长什么样
怎么把大任务拆成小步骤
哪里用脚本，哪里交给 AI 判断
中间断了怎么接着跑
你只要会用 Claude Code 就行，不需要会写代码。
自动化工具到底是什么
说白了，自动化工具就是一个文件夹。里面放着告诉 AI「干什么、怎么干」的文件。
打个比方。你去麦当劳点个汉堡，店员不用问你要几片面包、加多少酱。因为店里有一套标准做法，每个人照着做就行。
自动化工具就是 AI 的标准做法。
没有工具的时候：每次你都要从头告诉 AI「帮我写篇文章，语气像谁谁谁，开头要讲故事，结尾要金句……」——费劲不说，每次效果还不一样。
有工具的时候：你只要说「写篇文章」，AI 自己找到对应的做法，按你定好的套路写，出来的东西每次都稳定。
工具 = 能反复用的 AI 模板。写一次，用无数次。
为什么要定规矩
你可能会想：我直接写个文件不就行了，搞这么复杂干嘛？
三个原因。
第一，AI 能记住的东西有限。Claude Code 一次能记 20 万 token，看着不少吧？但一个复杂任务跑下来，很快就满了。好的规矩能让你只读需要的内容，省着用空间。
第二，复杂事情要分着干。有些事用脚本做又快又准（比如从网上抓数据），有些事必须 AI 来判断（比如文章写得好不好）。规矩帮你分清楚谁干什么。
第三，给别人用的时候，没规矩就乱了。你的工具别人一看就懂，不用你每次去解释。
打个比方：规矩就像盖房子的图纸。没图纸也能住人，但有图纸才能盖高楼。
工具长什么样
一个工具就是一个文件夹。里面放什么、怎么放，直接决定了工具好不好用。
最简单的情况
最简单的工具长这样：
xiangyu-format-converter/ — 工具文件夹
SKILL.md — 入口文件，说明干什么只要一个文件就能用。适合干一件事的小工具。
复杂的工具
事情多了，就要多放几个文件：
xiangyu-wechat-creating/ — 工具文件夹
SKILL.md — 入口文件，整体说明
workflow/ — 分步骤执行说明
01-collect.md — 第一步干什么
02-analyze.md — 第二步干什么
03-write.md — 第三步干什么
scripts/ — 脚本文件夹
python/ — Python脚本
reference/ — 参考资料
runs/ — 每次运行的数据（自动生成）这样放的好处：
SKILL.md 像「公司章程」——说清楚这个工具是干嘛的
workflow/ 像「员工手册」——每一步怎么干
scripts/ 像「工具箱」——确定性的事交给脚本
runs/ 像「档案柜」——每次干活的记录都在这里
记住一个原则：需要什么建什么，不要硬套。简单工具一个文件就够了。
入口文件怎么写
SKILL.md 是工具的入口，AI 最先读它。开头必须有这段：
---
name: xiangyu-social-wechat-creating
description: 写公众号长文。用户说「写长文」「公众号创作」时用
---
起名字有规矩：
全小写，用短横线连着
不能超过64个字
不能包含 claude 这些保留词
格式：谁-干什么-给谁-做什么
说明怎么写：
用第三人称（不要写「我能帮你」）
先说干什么，再说什么时候用
接着写触发条件：
触发条件：
「写长文」「公众号文章」 → 执行全部步骤
「看结果」 → 显示最近写的文章最后写工作流（这是最重要的部分）：
| 步骤 | 干什么 | 谁干 | 说明文件 | 输入 | 输出 |
|---|---|---|---|---|---|
| 01 | 收集素材 | 脚本 | workflow/01-collect.md | 用户说的关键词 | 文章列表 |
| 02 | 分析内容 | SubAgent | workflow/02-analyze.md | 文章列表 | 分析结果 |
| 03 | 写文章 | SubAgent | workflow/03-write.md | 分析结果 | 成稿 |
这样写的好处： AI 先看这张表，跑到哪一步才去读哪一步的说明，不一次性读完所有文件，省空间。
谁干什么活
这是最重要的问题。选对了，又快又省；选错了，又慢又卡。
四种干活的人
1. 脚本
适合做不用动脑子的事——输入固定，输出固定。
从网上抓数据
读写文件
数据转换
上传下载
好处：不占 AI 空间，跑得快，结果准。
2. SubAgent
适合需要动脑子的事——理解、判断、创作。
评估文章质量
总结内容
写文章
处理特殊情况
好处：能处理模糊任务，有判断力。
3. 主 Agent
适合简单协调的事——读个配置、控制流程。
看懂用户说的话
记录进度
叫别人干活
好处：直接在对话里干，不用新开窗口。
4. 准备 SubAgent
适合处理大量数据——干正事前先做好准备。
数数有多少条，算要分几批
生成批次清单
干完立刻清掉
好处：处理大批数据时，不会把 AI 空间撑爆。
怎么选
问自己：这步要干什么？
抓数据、读写文件、格式转换？ → 用脚本
需要 AI 理解、判断、写东西？
数据超过500条？ → 用准备 SubAgent（先分批） + SubAgent（再执行）
数据不超过500条？ → 直接用 SubAgent
简单协调、读配置？ → 用主 Agent
举个实际例子：
抓100篇文章：用脚本抓。如果用 AI 抓，费时又费空间。
判断30篇文章质量：脚本干不了，必须用 AI 判断。
分1000条数据：先用准备 SubAgent 分成10批，再用 SubAgent 一批批处理。主 Agent 直接读1000条会撑爆。
每一步怎么干
每步都有一个说明文件，告诉干活的怎么干。比如 workflow/02-analyze.md：
# Step 02: 内容分析
执行者: SubAgent
输入: step01-collect/data.json
输出: step02-analyze/result.json
---
**干什么：**
读收集来的文章，给每篇打分（1-5分），看值不值得写成公众号。
**输入文件：**
`step01-collect/data.json` — 上一步收集的文章列表
**输出文件：**
`step02-analyze/result.json` — 每篇的分数和推荐理由
格式：
[
{
"title": "文章标题",
"score": 5,
"reason": "这个话题最近很火"
}
]
**检查点：**
- 2a: 文件存在 — result.json 生成了
- 2b: 格式正确 — 能读成JSON
- 2c: 分数合理 — 分数在1-5之间
**下一步：**
→ Step 03: 写文章检查点很重要。 格式是步骤号+字母，如2a、2b。出了问题，能马上知道是哪步哪点没通过。
每次干活的记录
每次跑工具，都会在 runs/ 下面新开一个文件夹，放这次的所有数据。
文件夹名字：关键词-年月日-时分秒
比如：
claude-code-20260130-103000（查「Claude Code」那次）
karpathy-20260130-143000（分析「@karpathy」那次）
里面结构：
runs/claude-code-20260130-103000/
state/ — 进度文件
progress.json — 干到哪一步了
output/ — 最后结果
article.md — 写好的文章
step01-collect/ — 第一步产生的数据
data.json
step02-analyze/ — 第二步产生的数据
result.jsonprogress.json 是关键，记录了：
json
{
"keyword": "claude-code",
"current_step": "02",
"completed_batches": [1, 2, 3]
}就像打游戏存档。 中间停了或者空间不够要清一下，下次进来可以从存档点接着打。
脚本怎么写
所有不用动脑子的事，都用脚本干。
为什么这么重要？
用 AI 抓100条数据：占空间约8000 tokens，跑30秒
用脚本抓100条数据：占空间约50 tokens（只返回一行状态），跑5秒
省下99%的空间。所以规矩强调「能用脚本就不用 AI」。
Python 脚本核心要点：
python
#!/usr/bin/env python
import json
import sys
from pathlib import Path
def main():
# 读参数
run_dir = None
for i, arg in enumerate(sys.argv):
if arg == '--run-dir' and i+1 < len(sys.argv):
run_dir = Path(sys.argv[i+1])
if not run_dir:
print(json.dumps({"ok": False, "err": "缺少 --run-dir 参数"}))
return
try:
# 干活...
result = {"status": "成功", "count": 100}
# 只返回状态
print(json.dumps({"ok": True, "data": result}))
except Exception as e:
# 错误信息截短，别太长
err_msg = str(e)[:100]
print(json.dumps({"ok": False, "err": err_msg}))
if __name__ == "__main__":
main()调用时先切到脚本目录：
cd /path/to/skill/scripts/python && python collect.py --run-dir /path/to/run怎么省着用空间
AI 一次能记20万 token，但很容易就用满。要知道什么占空间。
主要消耗：
系统说明 — 约5000
SKILL.md — 约2000-5000
每步说明 — 约1000-3000
读文件 — 约100-25000
SubAgent 返回 — 每个约10000
对话历史 — 越积越多
特别注意： SubAgent 干完活回来，它干活的记录会全塞进主对话。如果同时跑6个 SubAgent，就是一下子塞进6万。
怎么省着用：
一次最多叫2个 SubAgent，干完马上清一下。
流程：
第1轮：叫 Agent1 + Agent2 干活
等他们干完，清一下空间
第2轮：叫 Agent3 + Agent4 干活
再清一下
以此类推
为什么一次只叫2个？因为要留空间给它们回来。一个回来占1万，安全情况下可以等5个，保守点就等2个。
什么时候必须清：
准备 SubAgent 干完
每轮 SubAgent 干完
整步干完
空间用了70%以上
返回格式要精简：
SubAgent 干完只返回状态，不返回内容。比如：
{"ok": true, "batch": 1, "count": 30}禁止返回： 文件内容、分析结果列表、详细日志。
一句话：分轮干 + 少说话 + 及时清 = 空间够用。
怎么问用户要信息
第一步通常要问用户想要什么。Claude Code 有专门的问问题工具。
限制：
一次问1-4个问题
每个问题给2-4个选项
标题不超过12个字
自动有「其他」选项，不用自己加
四种问法：
第一种：要关键词（通常选「其他」）
问用户想查什么，给几个例子，大部分人直接输自己的词。
第二种：从选项里选
问目标市场、语言之类的，从文件里读选项让用户选。
第三种：选模式
问要完整跑还是只干一部分，固定两个选项，走不同流程。
第四种：可填可不填（带「跳过」）
问要不要加过滤条件，第一个选项是「跳过」，用户不想填就选这个。
怎么组合：
最好一次把几个问题问完（最多4个）。如果问题多，第一轮问核心的，第二轮根据第一轮的结果问补充的。
出错了怎么办
好的工具不光能跑，还得能从错误里爬起来。
五层检查：
文件在不在，空不空 — 不在就重跑
格式对不对 — 不对就重跑
该有的字段有没有 — 没有就重跑
值合不合理 — 标记出来
符不符合业务要求 — 标记失败
错误分两种：
暂时性错误（网络超时、接口限流）— 可以重试，等会儿再试
永久错误（参数错了、格式错了）— 不能重试，停掉并报告
权限错误（登录失效、token过期）— 不能重试，停掉并让用户检查
资源错误（空间满了、磁盘满了）— 不能重试，清理后再试
怎么恢复：
清空间或中间停了，重新进来时：
读 state/progress.json
看「恢复提示」
确认接着干还是重新干
从断点接着跑
一个工具干几件事
有时一个工具要支持几种干法。比如做公众号文章的工具，可以从博主主页抓素材（克隆模式），也可以从已有文章分析（时间线模式）。
文件夹怎么放：
workflow/clone/ — 克隆模式的步骤
workflow/timeline/ — 时间线模式的步骤
workflow/shared/ — 共用的步骤触发词怎么设：
「克隆」「clone」 → 克隆模式，从博主主页抓
「时间线」「timeline」 → 时间线模式，从已有文章分析
运行文件夹怎么起名：
加个模式前缀：
clone-karpathy-20260130-103000
timeline-sama-20260130-143000
什么时候用一个工具干几件事： 最后出来的东西差不多，而且很多步骤能共用。
什么时候分两个工具： 最后出来的东西完全不一样，或者没几步能共用。
不能碰的红线
最后要知道 Claude Code 的限制，这些是定规矩的「物理边界」。
空间： 20万 token，实际能用约18万
工具限制：
读文件 — 一次最多2.5万 token，超过2000行就截断
写文件 — 必须先读过
改文件 — 必须先读过
跑命令 — 输出最多3万字符，默认2分钟超时
叫 SubAgent — 一次建议不超过2个
Skill — 整个文件预算1.5万字符
工具装在哪：
用户级（默认）— ~/.claude/skills/工具名/
项目级 — .claude/skills/工具名/
从零开始做一个
复制下面这段话给 Claude Code，让它帮你做第一个工具：
你帮我做个自动化工具，按规矩来。
**工具信息：**
- 名字：xiangyu-【干什么】-【给谁】-【做什么】（你帮我填）
- 功能：我想【说你要干什么】
**要求：**
1. **文件夹结构：**
- SKILL.md：入口文件，开头写 name 和 description，还有触发条件和工作流
- workflow/：每一步的说明
- 需要什么建什么，不用都建
2. **SKILL.md规矩：**
- name 用小写字母、数字、短横线
- description 用第三人称，先说干什么，再说什么时候用
- 工作流要有：步骤 / 干什么 / 谁干 / 说明文件 / 输入 / 输出
3. **步骤文件规矩：**
- 文件名：step数字-干什么.md
- 内容：谁干、输入、输出、干什么、检查点
4. **选谁干：**
- 不用动脑子的事（抓数据、读写文件）→ 脚本
- 需要动脑子的事（判断、写东西）→ SubAgent
- 简单协调 → 主 Agent
5. **省空间：**
- SubAgent 一轮最多2个
- 干完只返回简单状态 {"ok": true, ...}
- 及时清空间
6. **输出目录：**
- 固定目录：state/、output/
- 动态目录：step数字-干什么/（和工作流文件对应）
你想做什么工具？告诉我具体需求，我按规矩帮你生成。最后说两句
这套规矩是我做了30多个工具后总结出来的。刚开始可能觉得麻烦，但用习惯了就会发现好处：
思路清楚了，知道每一步该干什么
空间够用了，不会做着做着卡住
出了问题知道从哪找
给别人用，不用每次解释
最重要的是，有了这套规矩，做个新工具从「摸索半天」变成「十分钟搞定」。
你先从简单的做起。做个公众号文章工具，或者做个翻译工具。跑通一个，后面就快了。
本文内容仅供个人学习、研究或参考使用，不构成任何形式的决策建议、专业指导或法律依据。未经授权，禁止任何单位或个人以商业售卖、虚假宣传、侵权传播等非学习研究目的使用本文内容。如需分享或转载，请保留原文来源信息，不得篡改、删减内容或侵犯相关权益。感谢您的理解与支持！