SkillPedia Skills Encyclopedia
中文 EN
今日更新 2026-11-17 UTC

今天还没有新提交

查看更新动态

Guide · 制作技能 — How to build a skill

Make one skill, once.把个人与团队的独门经验,变成 Agent 的复利资产。

"A skill is the vehicle for transferring human judgment to agents." 写 Skill 不只是写 Prompt,而是做 Harness Engineering(缰绳工程):人类掌舵定意图、定原则、定验收标准;Agent 调度工具去执行。通过结构化封装与渐进式披露,将你多年积累的隐性知识、业务心法与踩坑规则固化下来,让整个团队的 Agent 立即共享,并在持续迭代中产生复利。

5833 个站内范本 三层渐进式披露 评估驱动开发 (EDD) 发布即注册,生态 18+ 客户端通用

01 Anatomy & Mechanism · 结构解剖与运行机制

Skill 的本质是什么一个文件夹,三类文件,三层渐进式披露机制

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
1 Layer 1(启动感知):仅加载 ~100 Tokens

客户端启动时,每个 Skill 只载入 name 和 description。模型只感知「存在这个能力」,几乎不占上下文。

2 Layer 2(命中触发):载入主干 SKILL.md

用户对话命中自然语言触发词时,动态加载 SKILL.md 正文。包含背景意图、执行心法与核心动作步骤。

3 Layer 3(按需执行):动态读取与外包脚本

仅在遇到特殊场景时按需读取 references/;遇到确定性任务时调用 scripts/,只返回干净结果,保持上下文纯净。

Description 黄金三原则:写「做什么」+「何时用」,用自然口语

✕ 常见错误:只写功能或使用第一人称

---
name: weekly-report
description: 我可以帮你处理 Excel 文件并整理周会报告。
---

第一人称与系统提示词冲突;缺乏具体触发词。用户说「帮我汇总本周进度发给总监」时,模型无法判断是否调用。

✓ 科学写法:第三人称 + 能力范围 + 用户自然口语触发词

---
name: weekly-report-drafting
description: 为团队主管汇总 Git 提交与工作日志并撰写周会总结。
  当用户提到「周报」「工作进度」「周会更新」或「本周总结」时使用。
---

同时明确能力(做什么)与触发场景(何时用),收录用户在真实工作中最常脱口而出的自然词汇。

02 Triggers & Paths · 触发信号与制作路径

什么时候该做一个 Skill?三个科学信号判断,避免盲目造轮子

Observe your existing workflow for high frequency, domain knowledge, and error cost.不是所有任务都要做成 Skill。观察你的日常工作,出现以下三个信号时才值得封装:

信号 01

高频触发 · 步骤固定High Frequency

同一类型的任务反复出现(做过 3 次以上),每次操作流程高度相似,且你在不同会话中总在重复粘贴相同的提示词。

举例 每周固定格式的项目周报、代码仓库发布规范检查、多尺寸图片导出流水线。

信号 02

私有领域知识 · 行业美角Domain Knowledge

模型预训练绝不可能知道的公司内部路径、团队特有术语(P0/DAU/上线审批链)、不可触碰的业务红线与格式要求。

举例 团队内部 API 鉴权约定、品牌设计色板与排版规范、财务报销核对规则。

信号 03

高出错成本 · 需强标准化High Error Cost

产出物出错代价极大或需直接对外交付(客户、管理层),不能容忍模型即兴自由发挥带来的品质波动。

举例 对外法律合规审查清单、生产环境发布检查单、多方账目对齐流程。

两条制作路径 + 评估驱动开发(EDD)

A 路径一:逆向工程(Reverse Engineering,最推荐新手)

在一个真实会话中与 Agent 协作完成任务,调优跑通后千万不要急着关闭 Session。调用 skill-creator 元技能,让 Agent 将刚刚成功的全套交互过程、纠错记录一键萃取沉淀为可复用的 `SKILL.md`。

B 路径二:主动共创(Thinking Partner,当 AI 的 PM)

脑中有想法但尚未实操时,把 AI 当成思考伙伴。不要只问「你能做什么」,而是明确说明上下文、约束、方法论与最终目标,让人机协同梳理出标准的执行框架。

进阶秘诀 · 评估驱动开发 (Evaluation-Driven Development, EDD):在写规则前,先让 AI 在没有任何先验规则的情况下裸跑一次任务。观察它具体在哪个环节卡住、哪步出错——这些真实卡点才是你真正该补充的系统缺口(缺工具、缺规则、还是缺验收标准),绝不要凭空脑补规则。

03 Architecture & Principles · 架构切分与核心心法

执行心法优先于死板步骤给模型思考空间,把确定性操作交给脚本

Principles over narrow SOPs. Offload deterministic logic to scripts.当今大模型的推理能力已非常出色,过窄的死板步骤会让 Agent 丧失弹性。一份优秀的 Skill 应当传授思考哲学,并科学切分架构。

1 给执行心法(Guiding Principles),而非过窄的死板 SOP

告诉 Agent「为什么这样做」和「按什么标准做判断」。例如周报心法:「周报是写给主管看的,核心标准不是『我做了什么』,而是『主管需要知道什么』;以项目卡点(Blockers)与下一步行动为第一优先级。」当模型领会了心法,面对不同周次的数据波动就能自适应做出最优判断。

2 辨别「有客观对错」与「主观权衡」

判断方法很简单:如果事情有客观标准(如表单字段校验、API 参数格式),写严格的固定步骤;如果属于内容创作、信息提炼、方案设计等无绝对对错的任务,只写原则框架与优先级。

3 精炼主干(< 200 行),警惕上下文腐烂(Context Rot)

LLM 加载的无关 Token 越多,大海捞针的检索精度越低。SKILL.md 建议控制在 200 行以内(上限 500 行)。超长输出格式、完整公司术语表、罕见的 corner cases 一律抽离到 references/ 按需加载。

4 确定性操作外包给 scripts/

排序、时间筛选、API 数据抓取、数学计算等不依赖 AI 思考的确定性操作,直接写成独立脚本。正文里只需一句「执行 scripts/fetch.sh 并读取返回值」。代码本身不进上下文,只回传纯净结果,既保证 100% 稳定性,又大幅节省 Token。

5 高要求场景:引入 Subagent 独立质检(Separation of Concerns)

在商业级高严谨任务中,主 Agent 容易「球员兼裁判」。开辟一个拥有干净 Context 的独立 Subagent,将验收 Checklist 作为输入,让它独立审查主 Agent 的产出并回传修改建议。

04 Step by step · 七步实战流程

从一个想法到一个能装的技能标准工程管线,命令可直接复制

  1. 01

    Pick the task观察信号,锁定真实高频任务

    对照「高频固定、私有领域知识、高出错成本」三大信号。挑选一件你近期必须交付的真实工作,切忌凭空虚构需求。

    推荐任务 每周跨工具日志汇总 · 团队代码合规自动化审查 · 多平台发布物料批量渲染

  2. 02

    Name it规范命名与目录定位

    name 用小写字母加连字符(如 weekly-digest),保持动名词结合、语义明确。在对应客户端的技能目录中创建项目:

    mkdir -p ~/.claude/skills/weekly-digest/{references,scripts,assets}

    目录约定:不同的 AI 客户端可能读取当前工程下的 .claude/skills/ 或全局配置目录。修改完成后记得重启或刷新客户端会话。

  3. 03

    Frontmatter严谨编写触发 Description

    包含第三人称、功能边界与自然口语触发词,让 Agent 在第一层就能精准识别:

    ---
    name: weekly-digest
    description: 汇总 Git 提交、任务卡片与工作笔记并生成结构化团队周报。
      当用户提到「周报」「工作汇总」「本周进度」或要求整理团队状态时使用。
    ---
  4. 04

    Body正文标准四段式结构

    核心正文聚焦于目标、心法与标准输出:

    ## 何时使用
    触发短语、上下文环境及前置条件。
    
    ## 执行心法与判断原则
    核心思考标准、优先级次序(如:卡点风险 > 常规进展)、价值权衡哲学。
    
    ## 执行流程
    1. 调用 scripts/fetch_logs.sh 获取近五天纯净提交。
    2. 按照执行心法过滤并组织关键事项。
    3. 关键业务判断遇歧义时,必须中断并向人类确认。
    
    ## 输出格式
    提供完整、规范、可直接对照对齐的范本样例。
  5. 05

    Test & Refine以真实任务检验三件事

    拿即将交付的真实业务任务跑一次,重点检查:① 是否被自动触发(若未触发,优化 Description 的口语词);② 关键心法是否被遵守;③ 产出质量与格式是否符合预期。

  6. 06

    Modularize架构外挂与脚本外包

    当正文开始逼近 200 行时,果断拆分:将长范本、边缘案例放入 references/;将复杂的数据抓取与规则计算封装入 scripts/,保持核心文档精炼。

  7. 07

    Publish推送到 GitHub,即刻全生态通用

    推到任意公开或团队私有 Git 仓库,依托开箱即用的包管理命令一键分发安装:

    # 1. 提交并推送到 GitHub 仓库
    git init && git add . && git commit -m "feat: add weekly-digest skill"
    git remote add origin https://github.com/<owner>/<repo>.git
    git push -u origin main
    
    # 2. 团队成员一条命令装上(支持 Claude Code、Cursor、Codex 等 18+ 款主流客户端)
    npx skills@latest add <owner>/<repo>

05 Pitfalls & Rules · 常见避坑与写作规矩

常见错误诊断与写作守则按症状查因,少走弯路

✓ 推荐做法✕ 典型反模式

给执行心法与优先级「周报核心是突出风险与下一步,而非记录流水账」

写死死板机械步骤「第一步按时间排序、第二步每条写一行、第三步标黑体」

口语化触发词收纳日常自然会说的话(如「整理进展」「本周汇报」)

堆砌生僻技术名词「本模型库包含关于时空序列进度提取的分析器」

确定性操作外包脚本将数据过滤、计算、校验写进可执行脚本

让 LLM 大海捞针要求模型自行猜解 API 语法或在巨大原始数据中心算

主干精简,细节外挂复杂模板与边缘个案统统放进 references

巨型单文件贪大求全把数百行字典与参考样例全塞进一个 SKILL.md

症状:装上了,但 Agent 从来不主动触发

原因:Description 写成了功能介绍,或触发词都是生僻技术词汇。对策:在 Description 中明确说明「何时用」,并补齐真实口语化短语。

症状:同一个技能,这周表现很好,下周突然走样

原因:只写了粗浅操作,缺少关键的「判断哲学与质量标准」,模型在临场猜测。对策:补充「执行心法」与优先级排定规则。

症状:技能迭代越来越长,产出精度反而大幅下降

原因:触发了上下文腐烂(Context Rot),大量冷门细节稀释了核心指示。对策:把非通用细节挪去 references,核心主干收敛到 200 行内。

症状:主模型既当选手又当裁判,忽略明显疏漏

原因:单会话自我审查存在认知盲区与上下文污染。对策:在关键环节引入独立 Subagent,持 Checklist 执行盲审。

06 Maintenance & Compounding · 科学维护与复利机制

Skill 的真正价值在于「复利效应」今天做一版,每次使用修一版,越用越值钱

A skill is not a static artifact. It is a compounding digital asset.真正让效率呈指数上升的,是持续的维护与迭代机制。没有维护的 Skill 会逐渐退化成混乱的补丁堆,而科学维护能让它历久弥新。

时机 01

新模型升级时:剪去历史补丁Model Upgrade

每次底层模型升级(如从 Sonnet 3.5 升级到新一代模型),先跑一遍既有 Skill。重点剔除当初为了弥补旧模型弱点而加的琐碎规则。让上下文恢复纯净,Token 越烧越少,产出反而更聪明。

时机 02

工作流执行后:引导 Agent 复盘Post-Workflow Debrief

每次复杂工作流执行完毕,不要直接关掉会话。给一句提示:「请复盘刚才的执行过程,列出犯了哪些错误、背后根因是什么,并评估是否需融入现有 Skill?」人类确认后规范并入。

双 Session 法

双会话迭代测试技巧Dual-Session Optimization

开两个会话:Session A 专门研究 Skill 最佳实践与架构优化;Session B 真实触发并执行业务任务。把 Session B 的实操卡点与失败记录丢给 Session A 提出优化方案,由人类审核合并。

1 维护核心三动作:删冗余、整骨架、抽细节

① 删除冗余:常识与一次讲清的原则绝不反复念叨;② 重整骨架:通读全文,保持人类可读性与清晰架构;③ 外抽细节:把膨胀的示例与 corner cases 坚决抽离到 references/。

2 从个人技能到团队知识网络

过去教会一个新人需要数周手把手教学,现在将团队业务 SOP 打包成 Skill,新入职员工的 Agent 瞬间掌握全套方法论。团队的集体智慧得以数字化继承与无缝传承。

07 Pre-flight checklist · 发布前自检清单

逐条核对,交付高可靠性 Skill点一下就能勾选,本地即时自检

Agent Skill 高品质自检 · 10 项

08 Read the good ones · 站内优质范本

先参考优秀实践,再动手写阅读成熟技能的组织方式与文件切分

Learn the architecture before writing the details.精选站内高星、结构规范的 Agent Skills 范本,观察它们如何设计 Frontmatter、如何传授执行心法、如何切分脚本与参考文献:

Turn your expertise into compounding skills.这周就把你的第一份独门心法沉淀成 Skill

不要等待万事俱备。挑一个你做过三次的日常流程,写清执行心法,跑通一遍,分享给团队。技能是在真实使用中迭代磨练出来的,更是属于未来的组织数字化资产。

浏览站内高分技能范本