信号 01
高频触发 · 步骤固定High Frequency
同一类型的任务反复出现(做过 3 次以上),每次操作流程高度相似,且你在不同会话中总在重复粘贴相同的提示词。
举例 每周固定格式的项目周报、代码仓库发布规范检查、多尺寸图片导出流水线。
Guide · 制作技能 — How to build a skill
"A skill is the vehicle for transferring human judgment to agents." 写 Skill 不只是写 Prompt,而是做 Harness Engineering(缰绳工程):人类掌舵定意图、定原则、定验收标准;Agent 调度工具去执行。通过结构化封装与渐进式披露,将你多年积累的隐性知识、业务心法与踩坑规则固化下来,让整个团队的 Agent 立即共享,并在持续迭代中产生复利。
01 Anatomy & Mechanism · 结构解剖与运行机制
Progressive disclosure is why agents don't blow up the context window.为什么系统里挂载上百个 Skill,模型的上下文窗口(Context Window)却从不溢出?理解这一机制,是科学设计 Skill 的起点。
推荐目录结构
# 推荐目录结构 my-skill/ ├── SKILL.md ← 唯一入口:包含 frontmatter 与核心执行心法 ├── references/ ← 细节外挂:长输出模板、术语表、边缘案例 │ ├── output-format.md │ └── terminology.md └── scripts/ ← 确定性外包:排序、数据抓取、格式验证脚本 └── fetch_data.sh
客户端启动时,每个 Skill 只载入 name 和 description。模型只感知「存在这个能力」,几乎不占上下文。
用户对话命中自然语言触发词时,动态加载 SKILL.md 正文。包含背景意图、执行心法与核心动作步骤。
仅在遇到特殊场景时按需读取 references/;遇到确定性任务时调用 scripts/,只返回干净结果,保持上下文纯净。
✕ 常见错误:只写功能或使用第一人称
--- name: weekly-report description: 我可以帮你处理 Excel 文件并整理周会报告。 ---
第一人称与系统提示词冲突;缺乏具体触发词。用户说「帮我汇总本周进度发给总监」时,模型无法判断是否调用。
✓ 科学写法:第三人称 + 能力范围 + 用户自然口语触发词
--- name: weekly-report-drafting description: 为团队主管汇总 Git 提交与工作日志并撰写周会总结。 当用户提到「周报」「工作进度」「周会更新」或「本周总结」时使用。 ---
同时明确能力(做什么)与触发场景(何时用),收录用户在真实工作中最常脱口而出的自然词汇。
02 Triggers & Paths · 触发信号与制作路径
Observe your existing workflow for high frequency, domain knowledge, and error cost.不是所有任务都要做成 Skill。观察你的日常工作,出现以下三个信号时才值得封装:
信号 01
同一类型的任务反复出现(做过 3 次以上),每次操作流程高度相似,且你在不同会话中总在重复粘贴相同的提示词。
举例 每周固定格式的项目周报、代码仓库发布规范检查、多尺寸图片导出流水线。
信号 02
模型预训练绝不可能知道的公司内部路径、团队特有术语(P0/DAU/上线审批链)、不可触碰的业务红线与格式要求。
举例 团队内部 API 鉴权约定、品牌设计色板与排版规范、财务报销核对规则。
信号 03
产出物出错代价极大或需直接对外交付(客户、管理层),不能容忍模型即兴自由发挥带来的品质波动。
举例 对外法律合规审查清单、生产环境发布检查单、多方账目对齐流程。
在一个真实会话中与 Agent 协作完成任务,调优跑通后千万不要急着关闭 Session。调用 skill-creator 元技能,让 Agent 将刚刚成功的全套交互过程、纠错记录一键萃取沉淀为可复用的 `SKILL.md`。
脑中有想法但尚未实操时,把 AI 当成思考伙伴。不要只问「你能做什么」,而是明确说明上下文、约束、方法论与最终目标,让人机协同梳理出标准的执行框架。
03 Architecture & Principles · 架构切分与核心心法
Principles over narrow SOPs. Offload deterministic logic to scripts.当今大模型的推理能力已非常出色,过窄的死板步骤会让 Agent 丧失弹性。一份优秀的 Skill 应当传授思考哲学,并科学切分架构。
告诉 Agent「为什么这样做」和「按什么标准做判断」。例如周报心法:「周报是写给主管看的,核心标准不是『我做了什么』,而是『主管需要知道什么』;以项目卡点(Blockers)与下一步行动为第一优先级。」当模型领会了心法,面对不同周次的数据波动就能自适应做出最优判断。
判断方法很简单:如果事情有客观标准(如表单字段校验、API 参数格式),写严格的固定步骤;如果属于内容创作、信息提炼、方案设计等无绝对对错的任务,只写原则框架与优先级。
LLM 加载的无关 Token 越多,大海捞针的检索精度越低。SKILL.md 建议控制在 200 行以内(上限 500 行)。超长输出格式、完整公司术语表、罕见的 corner cases 一律抽离到 references/ 按需加载。
scripts/
排序、时间筛选、API 数据抓取、数学计算等不依赖 AI 思考的确定性操作,直接写成独立脚本。正文里只需一句「执行 scripts/fetch.sh 并读取返回值」。代码本身不进上下文,只回传纯净结果,既保证 100% 稳定性,又大幅节省 Token。
在商业级高严谨任务中,主 Agent 容易「球员兼裁判」。开辟一个拥有干净 Context 的独立 Subagent,将验收 Checklist 作为输入,让它独立审查主 Agent 的产出并回传修改建议。
04 Step by step · 七步实战流程
对照「高频固定、私有领域知识、高出错成本」三大信号。挑选一件你近期必须交付的真实工作,切忌凭空虚构需求。
推荐任务 每周跨工具日志汇总 · 团队代码合规自动化审查 · 多平台发布物料批量渲染
name 用小写字母加连字符(如 weekly-digest),保持动名词结合、语义明确。在对应客户端的技能目录中创建项目:
目录约定:不同的 AI 客户端可能读取当前工程下的 .claude/skills/ 或全局配置目录。修改完成后记得重启或刷新客户端会话。
包含第三人称、功能边界与自然口语触发词,让 Agent 在第一层就能精准识别:
--- name: weekly-digest description: 汇总 Git 提交、任务卡片与工作笔记并生成结构化团队周报。 当用户提到「周报」「工作汇总」「本周进度」或要求整理团队状态时使用。 ---
核心正文聚焦于目标、心法与标准输出:
## 何时使用 触发短语、上下文环境及前置条件。 ## 执行心法与判断原则 核心思考标准、优先级次序(如:卡点风险 > 常规进展)、价值权衡哲学。 ## 执行流程 1. 调用 scripts/fetch_logs.sh 获取近五天纯净提交。 2. 按照执行心法过滤并组织关键事项。 3. 关键业务判断遇歧义时,必须中断并向人类确认。 ## 输出格式 提供完整、规范、可直接对照对齐的范本样例。
拿即将交付的真实业务任务跑一次,重点检查:① 是否被自动触发(若未触发,优化 Description 的口语词);② 关键心法是否被遵守;③ 产出质量与格式是否符合预期。
当正文开始逼近 200 行时,果断拆分:将长范本、边缘案例放入 references/;将复杂的数据抓取与规则计算封装入 scripts/,保持核心文档精炼。
推到任意公开或团队私有 Git 仓库,依托开箱即用的包管理命令一键分发安装:
05 Pitfalls & Rules · 常见避坑与写作规矩
给执行心法与优先级「周报核心是突出风险与下一步,而非记录流水账」
写死死板机械步骤「第一步按时间排序、第二步每条写一行、第三步标黑体」
口语化触发词收纳日常自然会说的话(如「整理进展」「本周汇报」)
堆砌生僻技术名词「本模型库包含关于时空序列进度提取的分析器」
确定性操作外包脚本将数据过滤、计算、校验写进可执行脚本
让 LLM 大海捞针要求模型自行猜解 API 语法或在巨大原始数据中心算
主干精简,细节外挂复杂模板与边缘个案统统放进 references
巨型单文件贪大求全把数百行字典与参考样例全塞进一个 SKILL.md
原因:Description 写成了功能介绍,或触发词都是生僻技术词汇。对策:在 Description 中明确说明「何时用」,并补齐真实口语化短语。
原因:只写了粗浅操作,缺少关键的「判断哲学与质量标准」,模型在临场猜测。对策:补充「执行心法」与优先级排定规则。
原因:触发了上下文腐烂(Context Rot),大量冷门细节稀释了核心指示。对策:把非通用细节挪去 references,核心主干收敛到 200 行内。
原因:单会话自我审查存在认知盲区与上下文污染。对策:在关键环节引入独立 Subagent,持 Checklist 执行盲审。
06 Maintenance & Compounding · 科学维护与复利机制
A skill is not a static artifact. It is a compounding digital asset.真正让效率呈指数上升的,是持续的维护与迭代机制。没有维护的 Skill 会逐渐退化成混乱的补丁堆,而科学维护能让它历久弥新。
时机 01
每次底层模型升级(如从 Sonnet 3.5 升级到新一代模型),先跑一遍既有 Skill。重点剔除当初为了弥补旧模型弱点而加的琐碎规则。让上下文恢复纯净,Token 越烧越少,产出反而更聪明。
时机 02
每次复杂工作流执行完毕,不要直接关掉会话。给一句提示:「请复盘刚才的执行过程,列出犯了哪些错误、背后根因是什么,并评估是否需融入现有 Skill?」人类确认后规范并入。
双 Session 法
开两个会话:Session A 专门研究 Skill 最佳实践与架构优化;Session B 真实触发并执行业务任务。把 Session B 的实操卡点与失败记录丢给 Session A 提出优化方案,由人类审核合并。
① 删除冗余:常识与一次讲清的原则绝不反复念叨;② 重整骨架:通读全文,保持人类可读性与清晰架构;③ 外抽细节:把膨胀的示例与 corner cases 坚决抽离到 references/。
过去教会一个新人需要数周手把手教学,现在将团队业务 SOP 打包成 Skill,新入职员工的 Agent 瞬间掌握全套方法论。团队的集体智慧得以数字化继承与无缝传承。
07 Pre-flight checklist · 发布前自检清单
Agent Skill 高品质自检 · 10 项
08 Read the good ones · 站内优质范本
Learn the architecture before writing the details.精选站内高星、结构规范的 Agent Skills 范本,观察它们如何设计 Frontmatter、如何传授执行心法、如何切分脚本与参考文献:
不要等待万事俱备。挑一个你做过三次的日常流程,写清执行心法,跑通一遍,分享给团队。技能是在真实使用中迭代磨练出来的,更是属于未来的组织数字化资产。