使用 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正是为回答这两个问题而设计的骨架——它不只是文档格式约定，还通过与仓库内校验脚本的联动，成为工程质量的门禁。

Frontmatter：Agent 发现技能的第一道关卡

模板的开头是 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。

此外，解析器还做了防御性处理：支持 BOM（strip_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"应激活evaluation，tool-design被明确拒绝；
• 提示词"Design an autonomous research loop with locked rubrics, editable drafts, rollback..."应激活harness-engineering，hosted-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, target=2)，即每条技能正文至少需要两个代码围栏块（fence），否则该项得分不为满分。

Guidelines 与 Gotchas：可验证规则与经验性失败模式

• Guidelines列出可检查、可验证的行动规则，每条带明确的成功条件。仓库真实技能如harness-engineering给出了十条可执行准则（先锁定评估器、可编辑表面收窄到可靠 diff、在压缩前写入持久日志、按维度而非聚合分数汇报等）。
• Gotchas被模板称为"任何技能中信号密度最高的内容"（the highest-signal content in any skill），要求每条都是具体的、可操作的、与正文其他指导不重叠的失败模式，并使用编号格式。健康检查脚本同样量化了这一维度：gotcha_score = normalize(record.gotcha_count, target=3)，即至少三条 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 数以及\d+k|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 的最终检查清单

综合模板约束与仓库校验规则，可归纳出如下发布前自检清单：

1. frontmatter 包含name（与目录名一致）与description（20～1024 字符、第三人称、双引号包裹、JSON 风格字符串）；
2. 正文总行数 ≤ 500，深内容已外移到references/；
3. 八个必需章节齐全：When to Activate、Core Concepts、Practical Guidance、Examples、Guidelines、Gotchas、Integration、References；
4. When to Activate同时含直接触发与间接信号，并带 "Do not activate" 边界块；
5. Core Concepts 只写"改变行为"的知识，每段信息通过 token 成本质询；
6. Examples 至少两个代码围栏块，优先输入/输出对；
7. Gotchas 至少三条，编号书写、具体可操作、与正文不重叠；
8. Integration 用纯文本列相关技能，不使用链接；
9. References 中任何数字、基准或供应商性能声明均带claim-*ID（注册于 researcher/claims/index.jsonl）；
10. 用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