有个活我教了它不下二十遍。每次都得重新交代一遍先跑哪个命令、输出扔到哪个目录、结果按什么格式整理、注意那两个例外。说完它做得挺好下次再问又是从零开始。后来我把这套话写成了一个文件。现在我只说一句按那个来它就知道该干什么。这个文件叫 SKILL.md。它和 AGENTS.md 不是一回事AGENTS.md 是常驻的规矩每次对话它都要读一遍。技能不一样它的正文只在被用到的那一刻才加载进去。这个差别很值钱。Claude 官方文档里的原话是——技能的内容只在用到时才加载所以哪怕你塞进去一大堆参考资料不用的时候几乎不花成本。所以我现在是这么分的规矩放 AGENTS.md成套的动作放技能。前者是你在这个项目里要守什么后者是遇到这类活该按什么步骤干。一个技能长什么样先放对位置项目里用.claude/skills/技能名/SKILL.md提交上去团队一起用自己用~/.claude/skills/技能名/SKILL.md本机所有项目都能用文件内容官方给的最小示例是这样一个---description:Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed,wants a commit message,or asks to review their diff.---## Current changes!git diff HEAD## InstructionsSummarize the changes above in two or three bullet points,then list any risks you notice such as missing error handling,hardcoded values,or tests that need updating. If the diff is empty,say there are no uncommitted changes.这里有三处值得说开头那对横线必须是文件的第一行。官方文档专门提过如果它不在第一行整个文件包括那两条横线会被当成技能正文设置就全失效了。字段基本都是可选的但description强烈建议写。它是唯一常驻在上下文里的部分——模型靠它判断什么时候该调用这个技能。所以光写整理变更摘要不够得把什么时候用也写进去。上面那个官方示例就是标准写法先说做什么再说何时用。!包起来的命令会先执行再把输出填进去。上面那个例子里的git diff HEAD技能被调用时真的会跑一遍把当前改动贴进上下文。等于技能自带现场数据。目录里还能塞别的东西技能不只是一个文件它是一个目录my-skill/ ├── SKILL.md 必需总览和导航 ├── reference.md 详细资料需要时才读 ├── examples.md 用法示例需要时才读 └── scripts/ └── helper.py 脚本被执行不进上下文SKILL.md 只负责讲清楚这是什么、怎么走细节全部推到旁边的文件里。脚本更特别它是被执行的不占上下文。官方给的体量建议是 SKILL.md 不要超过五百行——超了就说明该往旁边拆了。我自己打包的第一个给你看个真的我现在还在用的--- name: 查线上问题 description: 排查线上接口报错。用户说线上炸了接口报错看看日志时使用。 allowed-tools: Bash(ssh:*), Read --- ## 步骤 1. 先问清楚大概几点开始报错 2. 拉日志ssh ops tail -n 2000 /var/log/app/error.log 3. 只看报错那一段别把整个日志贴进对话 4. 找出第一条报错往上翻三行看上下文 5. 只报三样错误类型、首次出现时间、涉及哪个接口 ## 注意 - 日志里有手机号和身份证汇报时打码 - 拿不准就明说是推测这个技能里最花心思的其实是第四步和注意那两条。前面几步写起来很快但真正让结果能用的是别把整个日志贴进来省上下文和打码防事故这两个约束——它们是踩过坑之后才补上去的。什么样的活值得打包我自己的判断标准就三条一、你已经跟它交代过三遍以上。到第三遍就别再重复了。二、步骤能一口气说清楚。说不清楚说明你自己还没理明白这时候打包出来也是乱的。三、里面有一堆每次都要重复交代的例外。越是大部分时候这样但有两个情况要那样的活越值得写下来——那些例外正是你每次都要敲一遍的部分。反过来一次性的活、没有固定流程的活别打包。技能是给重复动作准备的。现在它成了我的一个习惯我现在的做法很土同一个活交代到第三遍我就停下来花十分钟把它写成文件。这十分钟后面会连本带利还回来——不只是我省了重复说明是它做这件事的稳定性也上来了因为步骤被固定住了。你手上有没有那种已经跟它说过三遍、下次还得从头再交代一次的活那个就是第一个该打包的。