使用 Agent-Skills-for-Context-Engineering 模板编写高质量 Agent Skill：结构与规范实战指南

使用 Agent-Skills-for-Context-Engineering 模板编写高质量 Agent Skill结构与规范实战指南【免费下载链接】Agent-Skills-for-Context-EngineeringA comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, or debugging agent systems that require effective context management.项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-Skills-for-Context-Engineering本篇技术指南基于 Agent-Skills-for-Context-Engineering 仓库中的 template/SKILL.md 展开系统讲解如何从零编写一个符合该仓库工程规范的 Agent Skill包括 frontmatter 元数据的合法格式、正文八段式结构、500 行体积约束、所有权边界划分以及激活条件When to Activate的书写纪律。读完本文你将掌握一套可被 Agent 发现、可被脚本校验、可被搜索引擎与 LLM 检索引用的技能文件编写方法论并能在仓库源码级理解这些规范背后的实现机制frontmatter 解析器与健康检查脚本。为什么需要一个 Skill 模板在 Agent-Skills-for-Context-Engineering 仓库中skills/目录下每一条技能都是一个独立的目录目录内以SKILL.md为入口文件。SKILL.md同时服务于两类读者人类开发者阅读、维护、评审与Agent 模型在技能发现阶段被注入系统提示、在任务执行阶段被加载为上下文。这种双重读者决定了技能文件不能随意书写Agent 需要靠description字段判断这条技能是否适用于当前任务人类需要靠统一的章节结构快速定位这条技能的边界、用法、坑在哪里。template/SKILL.md正是为回答这两个问题而设计的骨架——它不只是文档格式约定还通过与仓库内校验脚本的联动成为工程质量的门禁。FrontmatterAgent 发现技能的第一道关卡模板的开头是 YAML frontmatter--- name: skill-template description: Template for creating new Agent Skills for context engineering. Use this template when adding new skills to the collection. ---这两行元数据是整个技能文件最关键的字段仓库内 researcher/scripts/skill_frontmatter.py 对它们的约束可以从源码中直接读出name必须存在且为字符串。解析器在_validate_required_fields中会检查name缺失报missing name或类型错误报name must be a string健康检查脚本还会进一步校验name必须与所在目录名一致否则报name xxx does not match directory yyy见 researcher/scripts/skill_health.py。description必须存在、长度不低于 20 个字符MIN_DESCRIPTION_LENGTH 20且健康检查要求不超过 1024 字符。description 是注入系统提示、决定技能激活与否的核心文本太短或为空都会导致校验失败。description 必须使用双引号包裹的 JSON 风格字符串。测试套件 researcher/scripts/tests/test_skill_frontmatter.py 中的test_all_skills_parse_clean用正则\ndescription: 逐一断言仓库内所有发布技能都遵守该格式。这是因为未加引号的冒号会被严格 YAML 解析器视为非法StrictYamlRegressionTests.test_unquoted_colon_is_rejected专门守护了这个回归点。description 必须是第三人称。健康检查会匹配\b(I can|Use me|You can use this)\b模式并报description may not be third person。此外解析器还做了防御性处理支持 BOMstrip_bom、支持 LF/CRLF 换行、支持-折叠块标量test_block_scalar_description、能识别未闭合的 frontmatter 分隔符test_unterminated_frontmatter。这意味着即使没有安装 PyYAML也会走_parse_frontmatter_fallback的行级回退解析保证校验工具在最小依赖环境下仍可运行。500 行体积约束把正文当首屏上下文经营模板在第 10 行给出了一条硬性要求Important: Keep the total SKILL.md body under 500 lines for optimal performance. Move detailed reference material to separate files in thereferences/directory.这条约束在 researcher/scripts/skill_health.py 中被量化为line_count_ok record.line_count 500超限即被标记为异常flagged。其背后逻辑是SKILL.md 通常在技能激活初期就被完整加载进上下文行数越多token 成本越高且会稀释真正行为相关的指令密度。模板同时给出了配套的分层方案长篇幅的深度内容移到references/目录下的独立文件中SKILL.md 只保留索引与链接。仓库中template/references/提供了两个占位文件作为示例template/references/topic-details.md用于承载会让 SKILL.md 过长或首屏上下文过噪的详细资料template/references/reference-file.md用于承载 schema、清单、来源笔记等仅在需要时才加载的支撑材料。这种索引 按需加载的模式与仓库机制注册表中的progressive-disclosure-loading机制见 researcher/mechanisms/registry.jsonl同构先暴露名称、描述、索引只有当激活条件命中时才加载完整内容从而避免 context stuffing上下文塞满。所有权边界防止技能越权抢活模板用一段专门的话强调每一条技能正文都必须把它的所有权边界写清楚——description与When to Activate要说明这条技能拥有什么、哪些相邻技能拥有附近的活儿否则宽泛的技能会从更窄的技能手里偷走激活机会。这与仓库的激活用例activation cases设计直接呼应。在 researcher/fixtures/activation-cases.jsonl 中每条用例都声明了expected_primary_skill、acceptable_secondary_skills与rejected_skills。例如提示词Create a pairwise LLM-as-judge rubric with position-bias mitigation应激活advanced-evaluation而非宽泛的evaluation提示词Build a deterministic quality gate and regression test suite应激活evaluationtool-design被明确拒绝提示词Design an autonomous research loop with locked rubrics, editable drafts, rollback...应激活harness-engineeringhosted-agents被明确拒绝。这些用例的reason字段揭示了边界划分的判据判断标准是核心问题属于哪一层而不是哪些技能听起来相关。模板要求你在When to Activate中写出的Do not activate块本质就是把这类判据固化进技能正文。正文八段结构每个段落都有明确的工程目的健康检查脚本REQUIRED_SECTIONS定义了八个强制章节researcher/scripts/skill_health.py缺失任何一节都会导致技能被标记。这八个章节不是排版习惯而是分别服务于不同的质量维度。When to Activate直接触发与间接信号模板要求同时列出直接触发具体关键词或任务类型与间接信号更宽泛的相关模式并强调全程使用第三人称。原因在模板中写得很清楚description会被注入系统提示人称不一致会导致技能发现失败。给出的正反示例非常典型正确Processes Excel files and generates reports错误I can help you process Excel files同一规则在健康检查脚本中也有自动化防线description 中出现I can之类的第一人称表述即判为不合法。相邻技能用简短的 Do not activate 块划定边界例如模板示例Do not activate for project-level pipeline shape:project-development.Do not activate for individual tool schema design:tool-design.Core Concepts只补充模型没有的知识模板在这里给出了一条反直觉的默认假设Claude is already very smart。书写者必须对每一段信息做三道自我质询这个解释模型真的需要吗我能否假设模型已经知道这一段是否值得它的 token 成本模板还规定优先写改变行为的机制而非泛泛的背景知识如果某个概念应当跨语料复用应该在 researcher/mechanisms/registry.jsonl 中新增或更新记录。这与仓库的机制注册表设计相吻合——注册表记录的是mechanism_id、owning_skill、status、激活场景、行为改变、证据与失败模式用于跨技能去重与新颖性判定见structured-novelty-gate机制。Detailed Topics深内容外移的触发点模板在此提供二级标题### Topic 1、### Topic 2的组织方式并明确给出外移指引主题过长时把内容放进references/并在正文中链接例如模板中的写法See detailed reference for complete implementation注意仓库规范要求链接使用相对路径指向技能自身的引用文件。而在发布成文、跨目录引用时则应从仓库根目录出发书写路径。Practical Guidance按任务脆弱度匹配自由度模板引入了一个非常实用的决策框架——根据任务脆弱度选择指导的具体程度High freedom多种方案都成立决策依赖上下文Medium freedom存在首选模式允许一定变体Low freedom操作脆弱必须遵循特定顺序。模板还给出了一条硬性规则实践指导必须能被 Agent 执行——必须是工作流、检查清单、决策表或具体操作规则如果某段内容只是在讲历史或动机就移到references/。这与仓库中harness-engineering等真实技能的写法一致如 skills/harness-engineering/SKILL.md 的 Harness Design Checklist 八步清单。Examples输入/输出对优先模板要求示例展示 before/after 对比、正确用法演示或边界情况处理并推荐使用输入/输出对Input: [describe input] Output: [show expected output]健康检查脚本对代码示例数量有量化要求code_score normalize(record.code_example_count, target2)即每条技能正文至少需要两个代码围栏块fence否则该项得分不为满分。Guidelines 与 Gotchas可验证规则与经验性失败模式Guidelines列出可检查、可验证的行动规则每条带明确的成功条件。仓库真实技能如harness-engineering给出了十条可执行准则先锁定评估器、可编辑表面收窄到可靠 diff、在压缩前写入持久日志、按维度而非聚合分数汇报等。Gotchas被模板称为任何技能中信号密度最高的内容the highest-signal content in any skill要求每条都是具体的、可操作的、与正文其他指导不重叠的失败模式并使用编号格式。健康检查脚本同样量化了这一维度gotcha_score normalize(record.gotcha_count, target3)即至少三条 gotcha 才能拿满该项分数。以harness-engineering为例其 Gotchas 覆盖了可变评估器导致刷分、仅存聊天记忆导致压缩后失忆、无失败记录导致重复踩坑、复杂度堆积等真实事故模式。Integration跨技能关系用纯文本列举模板特别强调相关技能用纯文本plain text列出不使用链接以避免跨目录引用问题cross-directory reference issues。这一规定是有工程依据的——技能目录一旦被移动或改名硬编码的相对链接就会失效纯文本列举则让技能间的关系声明保持稳健。harness-engineering的 Integration 章节提供了范例例如filesystem-context- Durable logs, scratchpads, and thread files preserve state。References三类来源的划分模板将参考文献分成三类技能自身的内部引用用相对路径指向references/、本仓库内相关技能、外部资源论文、文档、指南。同时给出了一条与仓库校验体系强相关的要求Numeric, benchmark, volatile, or vendor-performance claims need an inlineclaim-*ID backed by researcher/claims/index.jsonl, or they should be softened and moved to dated reference material.这条约束在健康检查脚本中有完整的自动化实现NUMERIC_CLAIM_PATTERNS会扫描百分比、倍数、毫秒、秒、token 数以及\dk|M|B|x之类的数字声明并识别LoCoMo、SWE-bench、MMLU等基准名称collect_claim_ids会提取正文中的claim-*ID 并与声明注册表比对未注册的 ID 会被记为claim_ids_unknown。这意味着技能正文中的任何量化断言都必须有claim-*凭证否则健康评分会被扣分。结尾的 Skill Metadata版本与溯源模板在正文末尾保留了元数据块**Created**: [Date] **Last Updated**: [Date] **Author**: [Author or Attribution] **Version**: [Version number]该块不参与健康评分的章节统计但为人类读者与维护脚本提供了版本溯源。仓库根目录的 SKILL.md 展示了真实填法如Version: 2.5.0每条具体技能如harness-engineering的Version: 1.1.0也都带有自己的创建/更新日期。从模板到真实技能以 harness-engineering 为范本模板的每个章节都能在仓库的真实技能中找到落地实例。以 skills/harness-engineering/SKILL.md 为例frontmatter 的description以第三人称描述适用场景This skill should be used when designing autonomous agent harnesses: research loops, evaluation scaffolds, locked and editable surfaces...When to Activate列出六条直接触发场景并以四行 Do not activate 划清与evaluation、tool-design、project-development、hosted-agents的边界Core Concepts用一张四类表面Locked / Editable / Append-only / Human-controlled的表格解释 harness 边界正对应激活用例activation-harness-vs-project中对控制表面与治理的归属判定Gotchas提供八条编号失败模式Integration以纯文本列出七个相关技能及关系References用仓库相对路径指向researcher/rubrics/harness-change.md与researcher/runbooks/autonomous-research-loop.md。这种模板 — 校验脚本 — 真实技能三位一体的结构正是这个仓库保证技能质量的方式。如何验证你写的技能健康检查脚本模板本身不含命令但仓库为其配套了可执行的验证工具。健康检查脚本 researcher/scripts/skill_health.py 对skills/目录下每个技能计算综合得分权重分配为必需章节完整度 20%、gotcha 数量 15%、代码示例 10%、内部链接解析率 15%、激活用例覆盖 10%、数字声明凭证覆盖 15%、机制注册覆盖 10%、frontmatter 合法性 5%。任何技能得分低于 0.75、超 500 行、缺必需章节或 frontmatter 非法都会被标记。运行方式在仓库根目录下# 默认生成报告到 researcher/reports/skill-health.json python3 researcher/scripts/skill_health.py # 输出机器可读 JSON python3 researcher/scripts/skill_health.py --json # 任一技能被标记时以非零退出码结束可用于 CI python3 researcher/scripts/skill_health.py --strict # 可选对外部链接发起 HEAD 请求验证可达性默认关闭 python3 researcher/scripts/skill_health.py --check-urls --url-timeout 10脚本本身是确定性的它不调用任何 LLM默认也不发外部 HTTP 请求适合纳入持续集成。配套的单元测试 researcher/scripts/tests/test_skill_frontmatter.py 可用以下命令直接运行python3 -m unittest researcher.scripts.tests.test_skill_frontmatter其中CorpusIntegrationTests.test_all_skills_parse_clean会遍历skills/下所有SKILL.md断言 frontmatter 零问题、name与目录名一致、description使用双引号格式test_example_and_template_frontmatter_is_strict_yaml还会把template/SKILL.md与examples/下的所有技能纳入严格 YAML 校验——也就是说模板文件本身就是被测试守护的标准答案之一。编写一份合格 SKILL.md 的最终检查清单综合模板约束与仓库校验规则可归纳出如下发布前自检清单frontmatter 包含name与目录名一致与description201024 字符、第三人称、双引号包裹、JSON 风格字符串正文总行数 ≤ 500深内容已外移到references/八个必需章节齐全When to Activate、Core Concepts、Practical Guidance、Examples、Guidelines、Gotchas、Integration、ReferencesWhen to Activate同时含直接触发与间接信号并带 Do not activate 边界块Core Concepts 只写改变行为的知识每段信息通过 token 成本质询Examples 至少两个代码围栏块优先输入/输出对Gotchas 至少三条编号书写、具体可操作、与正文不重叠Integration 用纯文本列相关技能不使用链接References 中任何数字、基准或供应商性能声明均带claim-*ID注册于 researcher/claims/index.jsonl用skill_health.py与test_skill_frontmatter.py跑通校验得分离于 0.75 且无标记。结语template/SKILL.md的价值不在于它是一份好看的文档模板而在于它把**技能发现description、上下文预算500 行、技能边界When to Activate、行为改变Core Concepts、经验沉淀Gotchas与证据纪律claim-***全部固化为可检查的结构。配合仓库内的 frontmatter 解析器、健康检查脚本与单元测试这份模板构成了一个闭环任何人按它写出的技能都能被 Agent 正确发现、被脚本自动校验、被搜索引擎与 LLM 稳定检索与引用。对任何希望构建可维护的 Agent Skill 语料库的团队而言这套模板 校验 真实范例的组合都值得直接借鉴。【免费下载链接】Agent-Skills-for-Context-EngineeringA comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, or debugging agent systems that require effective context management.项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-Skills-for-Context-Engineering创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考