当前位置：首页 > news >正文

Agent Skills 实战指南：从模板到自建技能

news 2026/8/28 12:02:35

Agent Skills 实战指南：从模板到自建技能

【免费下载链接】skillsPublic repository for Agent Skills项目地址: https://gitcode.com/GitHub_Trending/skills3/skills

每次让 AI 生成文档，都要重新交代一遍公司的排版规范和导出要求？把这些规则写进一个技能文件夹，Claude 以后会在合适的时机自己加载它们。这份仓库（Anthropic 官方的 Agent Skills 集合）把这件事做成了标准形态：每个技能是一个带SKILL.md的文件夹，靠渐进式披露控制上下文开销，可以直接装进 Claude Code，也可以照着模板写出你自己的技能。

重复喂规则？把流程固化进技能文件夹

技能长什么样：一个文件夹加一个 SKILL.md

技能不是插件、不是 pip 包，就是一个目录。最小结构只有一个文件：

my-skill/ └── SKILL.md

SKILL.md由 YAML frontmatter 和 Markdown 正文两部分组成，前者告诉 Claude "这个技能叫什么、什么时候该用"，后者是触发后执行的指令。仓库里的template/SKILL.md就是这个最小形态，spec/目录则指向 Agent Skills 规范。

仓库里现成的四类技能

skills/目录下可以直接抄作业，大致分四类：

文档类：skills/docx、skills/pdf、skills/pptx、skills/xlsx——驱动 Claude 文档能力的生产级实现，是学习复杂技能组织方式的最佳样本
创意类：skills/canvas-design（海报/视觉设计）、skills/frontend-design（UI 设计方向）、skills/brand-guidelines、skills/theme-factory、skills/slack-gif-creator
开发类：skills/mcp-builder（写 MCP 服务器的完整方法论）、skills/webapp-testing
企业协作类：skills/internal-comms（含新闻稿、FAQ 等范文）、skills/doc-coauthoring

三层渐进式披露：控制上下文开销

元数据层：常驻的约百词

技能再多也不怕上下文爆炸，因为加载是分层的。第一层只有name和description两项元数据常驻上下文，约百词。这就是为什么 description 是技能最重要的字段——它决定了 Claude 在几十上百个技能里能不能准确挑中你。

正文层：500 行是软上限

第二层是SKILL.md正文，技能触发时才进上下文。仓库的惯例是控制在 500 行以内；逼近上限就再拆一层，在正文里写明"什么时候去读哪个文件"。超过 300 行的大参考文件，自己加个目录索引。

资源层：scripts 与 references 按需加载

第三层是随技能打包的资源，目录约定如下：

skill-name/ ├── SKILL.md ├── scripts/ # 可执行代码，跑完即弃，不必读进上下文 ├── references/ # 按需加载的文档 └── assets/ # 输出用的模板、字体等

支撑多个变体时按变体拆文件，例如references/aws.md、references/gcp.md，Claude 只读相关的那一份。

在 Claude Code 里装好现成技能

注册 marketplace 并安装插件

在 Claude Code 中把本仓库注册为插件 marketplace，然后按需安装：

git clone https://gitcode.com/GitHub_Trending/skills3/skills /plugin marketplace add anthropics/skills /plugin install document-skills@anthropic-agent-skills /plugin install example-skills@anthropic-agent-skills

两个插件分别对应文档技能包和示例技能包，装哪个取决于你日常处理的是 Word/PDF 还是设计、协作类任务。

使用时只提一句

安装后不需要任何额外配置，在对话里点名即可：

"用 PDF skill 把report.pdf里的表单字段提取出来"

Claude 会加载对应技能并按SKILL.md里的流程执行。付费版 Claude.ai 和 Claude API 也内置了这批技能，上传自定义技能的流程在各端入口一致。

🔧 用模板写出第一个技能

frontmatter 只有两个必填字段

把template/SKILL.md拷出来改名，填好这两个字段就是一个合法技能：

--- name: my-skill-name description: A clear description of what this skill does and when to use it --- # My Skill Name [Add your instructions here]

name用小写加连字符，全局唯一。

description 要写得"敢触发"

skills/skill-creator/SKILL.md里给了一个关键提醒：Claude 目前倾向于"欠触发"——该用技能时不用。对策是把 description 写得稍微"强势"一点，同时说清做什么和什么时候用。对比仓库里的两个真实写法：

skills/pdf/SKILL.md："If the user mentions a .pdf file or asks to produce one, use this skill."——把触发条件写成祈使指令
skills/docx/SKILL.md：把 "report"、"memo"、"letter" 等可能出现在用户嘴里的词全部列进触发清单，并明确排除边界（"Do NOT use for PDFs, spreadsheets"）

正文：祈使句加按任务拆节

正文用祈使句写指令，按任务而非按概念分节。skills/pdf/SKILL.md的开头就按"合并/拆分/抽取/填表"分节，每节给出最短可运行的代码，进阶内容指向reference.md，填表流程单独放进forms.md——这正是第二层拆到第三层的标准示范。

从 docx 看复杂技能的组织方式

SKILL.md 放决策表，脏活交给 scripts

skills/docx/SKILL.md开头就是一张任务-方案对照表：新建用 docx-js 脚本，编辑已有文件走 "unzip → 改word/document.xml→ zip"，读取用pandoc -t markdown。模型一触发技能就能选对路线，不会被长篇解释淹没。

真正的工作由skills/docx/scripts/下的脚本承担：accept_changes.py处理修订、comment.py插入批注、office/validators/里是整套 XML 校验器。脚本可以执行而无需读进上下文，这就是资源层的价值。

把踩坑点写成 gotchas

这个技能最值得学的是"gotchas"一节——模型知道 API，但不知道坑：

- 页面默认 A4，US Letter 要显式设 12240x15840 (DXA) - 表格要双重宽度：table 和 cell 都设 DXA 宽度 - 底纹用 ShadingType.CLEAR，SOLID 会渲染成黑色 - ImageRun 必须带 type: ("png" / "jpg")

写完还要验证产出。skills/docx/SKILL.md给出的流程是转成 PDF 再转成图片自己"看"：

python scripts/office/soffice.py --headless --convert-to pdf output.docx pdftoppm -jpeg -r 100 output.pdf page

skills/pdf、skills/pptx、skills/xlsx都带同样的校验脚本结构，四者可以互相参照。

✅ 用 skill-creator 打磨与评估

先跑测试提示词，再看量化指标

skills/skill-creator是"写技能的技能"，它定义了一条迭代回路：写草稿 → 准备几条测试提示词 → 带着技能跑一遍 → 用eval-viewer/generate_review.py生成结果评审页 → 根据定性反馈和量化指标改写 → 重复，直到满意再扩大测试集。配套脚本在skills/skill-creator/scripts/下：run_eval.py跑单条评估，aggregate_benchmark.py做带方差分析的基准聚合，improve_description.py专门优化 description 的触发准确率。