Agent Skill 开发指南（包含测试）
GrissomFI约 13 分钟Agent Skill 开发指南
本项目收录了由“原力注入博主”使用和维护的优秀认知技能。这些技能旨在通过自动化的工作流和多智能体协作机制，帮助开发者深入理解代码库结构、提取核心业务逻辑并生成结构化的技术文档。
作为资深程序员，TDD 已经深入骨髓，Skill 很作用，但是如果不能被测试，那岂不是空中楼阁，程序迟早崩塌，我们被迫跑路？此次重点增加了关于 Skill 单元测试部分，供大家参考！
文章比较长，请移步原文查看：https://github.com/ForceInjection/awesome-skills/blob/main/README.md
单元测试说明：Skill 单元测试包含“静态单元测试”与“端到端评估”。结合系统化的测试原则，以确定性信号（行为与产物）构建可复现、可比较、可在 CI 守门的质量闭环，兼容任意 CLI 型开源 Code Agent（如
OpenCode），使团队从“凭感觉的手动验证”走向“结构化、可复现、可对比”的工程化治理。
目录
• 1. 核心技能介绍 • 1.1 深度代码阅读 • 1.2 深度项目架构分析 • 1.3 目录整理 • 1.4 文档评审 • 1.5 Markdown 总结器 • 1.6 代码提交助手 • 1.7 Agent Skill 审查器 • 1.8 OpenSpec 规范驱动开发辅助 • 1.9 网页内容下载器 • 1.10 Markdown 翻译器 • 2. 核心设计理念 • 2.1 语言规范：受众隔离 • 2.2 产物定位：为什么是生成 SKILL 而非 Agent？ • 3. Agent Skill 最佳实践 • 3.1 生产级目录结构 • 3.2 精准的触发描述 • 3.3 渐进式知识披露 • 3.4 状态管理与流程编排 • 3.5 技能测试金字塔 • 3.6 技能命名规范 • 4. 深度解析案例 • 4.1 gstack 项目深度解析 • 4.2 五种智能体技能设计模式 • 4.3 superpowers 深度解析 • 5. 推荐参考资源 • 5.1 MiniMax-AI 官方技能库 • 6. Skill 单元测试
1. 核心技能介绍
本章节将详细介绍当前项目中包含的核心技能，包括它们的设计目标、工作原理以及使用方式。
1.1 深度代码阅读
code-reader 技能旨在系统性地阅读和理解陌生的代码库，并通过严格的验证机制生成可复用的认知技能文件。
该技能引入了类似软件工程团队的三重智能体协作模式（技术作者、测试工程师和初级开发者）。通过 QA 工程师生成测试题并由初级开发者仅根据文档进行解答的“闭卷考试”式验证循环，有效避免了浅尝辄止的代码总结，确保所提取的模块能力、设计逻辑、数据结构和状态流等信息具有极高的准确性和深度。
使用示例如下：
# 触发深度代码阅读工作流
# 参数 source: 本地路径或 GitHub 仓库地址
# 参数 output-dir: 技能文件的输出根目录
# 注意：该工作流会在 output-dir 下为每个识别出的模块生成一个独立目录（如 {project-name}-fj-{module-name}），并包含对应的 SKILL.md 等技能文件。
/code-reader <source> <output-dir>1.2 深度项目架构分析
project-analyzer 技能在 code-reader 的基础上进行了扩展，用于对第三方代码仓库进行全面的逆向工程与静态分析，并生成客观、硬核的《项目架构深度分析报告》。
该技能协同了模块专家、运维工程师和首席架构师（作为第三方代码库分析师）三个角色的多智能体协作模式。它不仅关注代码级别的逻辑，还深入解析构建、测试和部署等工程实践。通过首席架构师汇总代码逻辑和基础设施配置，确保最终输出的架构图和文档在逻辑上保持一致且专业严谨。最终生成的文档中，系统架构、核心模块代码深度解析与执行流程分析约占 70% 的篇幅，其余 30% 涵盖项目全局摘要、质量与性能评估（包括测试覆盖）以及二次开发指南。
使用示例如下：
# 触发深度项目架构分析工作流
# 参数 source: 本地路径或 GitHub 仓库地址
# 参数 output-dir: 深度分析报告及中间分析文件的输出目录
# 注意：该工作流会在 output-dir 下生成以下内容：
# 1. 最终输出文件：<actual-project-name>-deep-dive.md（包含 7 个标准章节的综合性深度分析报告）
# 2. 中间分析文件（基础设施）：由 DevOps 工程师提取生成的构建、测试和部署策略报告
# 3. 中间分析文件（代码模块）：底层调用的 code-reader 生成的各个模块独立目录（如 {project-name}-fj-{module-name}）及包含的 SKILL.md
/project-analyzer <source> <output-dir>1.3 目录整理
dir-organizer 技能旨在帮助用户规范化和优化项目目录结构，从而提升工程的可维护性。
该技能支持对目录和文件进行基础及高级操作，如创建、重命名和移动文件。在执行时，它遵循严格的状态收集与方案审核流程，必须先在回复中完整打印出重构计划，并经用户同意后方可执行。此外，整理完成后该技能还会自动扫描并更新内部引用链接，确保文件间关联的准确性。
使用示例如下：
# 触发目录整理技能
# 参数 target-dir: 需要整理的目标目录路径（如果不提供，通常默认处理当前工作目录或通过对话指定）
/dir-organizer <target-dir>1.4 文档评审
doc-reviewer 技能用于审查技术文档的准确性、一致性、结构规范和专业性，以确保项目文档的高质量。
该技能通过标准的评审闭环流程，逐项检查目标文档的排版结构（如中英文空格、章节编号）与内容质量（如术语统一、脱敏处理）。在明确指出具体问题和修改建议后，它还支持在用户授权下自动应用修复，极大提升了文档维护的效率。
使用示例如下：
# 触发文档评审技能
# 参数 target-file: 需要被审查的 Markdown 技术文档路径
/doc-reviewer <target-file>1.5 Markdown 总结器
md-summarizer 技能用于分析和总结本地的 Markdown 文件，并输出结构化、专业深度的中文分析报告。
该技能能对单个本地 Markdown 文件进行“核心概要”、“深度解析”和“关键要点”的提取，还支持对多个文件进行综合对比分析，提炼出共同主题与核心冲突。
使用示例如下：
# 触发 Markdown 总结器技能
# 提供一个或多个本地 Markdown 文件路径
/md-summarizer ./article1.md ./article2.md1.6 代码提交助手
update-submitter 技能旨在自动分析本地代码仓库的变更，将相关联的文件修改进行逻辑分组，并生成符合 Conventional Commits 规范的提交信息。
该技能通过分析 git status 与 git diff 的输出，智能识别不同类型的变更（如功能开发、问题修复、文档更新等）。在为每个逻辑分组生成标准化的提交信息后，它会先向用户展示完整的提议计划，并在获取明确授权后自动执行提交操作。这有效保持了 Git 历史的整洁与规范。
使用示例如下：
# 触发代码提交工作流
# 参数 target-dir: 可选，目标项目目录路径（如果不提供，默认为当前工作目录）
/update-submitter <target-dir>1.7 Agent Skill 审查器
agent-skill-reviewer 技能旨在自动审查和验证用户编写的 Agent Skill 目录结构与 SKILL.md 文件，确保其符合最佳实践与核心规范。
该技能通过分析目标技能的目录命名、文件结构（如是否按关注点分离）、YAML Frontmatter（如描述是否遵循“功能 + 触发场景 + 关键词”公式）以及核心指令的清晰度。审查完成后，会输出一份包含目录结构、元数据、指令逻辑与改进建议的结构化审查报告，帮助开发者规范技能的编写。
使用示例如下：
# 触发 Agent Skill 审查工作流
# 参数 target-dir: 需要被审查的 Agent Skill 目录路径
/agent-skill-reviewer <target-dir>1.8 OpenSpec 规范驱动开发辅助
openspec-assistant 技能旨在帮助用户使用 OpenSpec 框架进行敏捷且高确定性的规范驱动开发 (SDD) 。
该技能涵盖了意图对齐、规范生成、代码实现与自动化验证的完整生命周期。它支持架构师（撰写 Spec / 评审代码）、开发工程师（编写业务代码）和 QA 测试工程师（编写测试用例）三种角色的无缝协同。通过内置的 /opsx 指令体系，它严格约束 AI 生成代码的边界，确保实现逻辑与业务规范完全一致。
使用示例如下：
# 触发 OpenSpec 协作技能
# 附带你需要执行的具体意图或需求描述
/openspec-assistant [执行意图/变更描述]1.9 网页内容下载器
web-content-downloader 技能用于下载指定的网页内容，剥离无关的 HTML 标签并转换为标准的 Markdown 格式，同时保留网页原始语言（不进行翻译）。
该技能特别强化了对多媒体与排版的支持：不仅能利用 Jina Reader 自动获取排版良好的正文内容，还能智能提取文章中的核心配图，将其批量下载到本地的 img 目录中，并根据上下文进行重命名和 Markdown 链接替换。此外，它还能将网页中的 HTML 表格精准转换为 Markdown 表格，极大地提高了网页内容的本地化存档效率。
使用示例如下：
# 触发网页内容下载与图片提取技能
# 参数 URL: 目标网页地址
/web-content-downloader <URL>1.10 Markdown 翻译器
md-translator 技能用于将指定的本地 Markdown 文件翻译成目标语言（默认中文），并在生成的新文件中添加语言标识后缀。
该技能在翻译过程中会严格保留原有的 Markdown 格式（包括标题、列表、代码块、加粗、链接、图片引用等）。同时内置了对文档排版规范的检查，例如确保中英文之间留有空格、代码块有注释说明，以及将 HTML 表格格式化为标准的 Markdown 表格。
使用示例如下：
# 触发本地 Markdown 文件翻译技能
# 参数 target-file: 本地 Markdown 文件路径
/md-translator <target-file>2. 核心设计理念
本章节概述了上述技能在设计过程中遵循的核心哲学，包括语言规范与产物定位。
2.1 语言规范：受众隔离
为了在保证 AI 推理性能的同时提供良好的用户阅读体验，本项目中的技能严格遵循以下受众隔离的语言规范：
• Agent/LLM 面向文件（全英文）：所有作为外挂知识库供 Agent 读取的 SKILL.md文件，以及控制工作流的*-prompt.md模板文件，均保持纯英文。这能最大化大模型的指令遵循能力和理解准确度。• 人类面向文件（全中文）：最终交付给开发者阅读的产物（如通过 project-analyzer生成的《项目架构深度分析报告》），被严格限制为使用纯中文输出，并要求符合专业的技术文档排版规范。
特例说明 (中文技能文档)：
尽管底层提示词通常建议使用英文，但如 dir-organizer 和 doc-reviewer 等技能的 SKILL.md 采用了全中文编写。这是因为这些技能的核心目标是直接指导开发者制定重构计划或审查中文技术文档规范。采用中文编写能有效降低开发者的理解门槛，同时更精确地传达针对中文语境的排版与组织规则。
2.2 产物定位：为什么是生成 SKILL 而非 Agent？
code-reader 的核心输出是针对每个模块的 SKILL.md，而不是创建专门负责该模块的 Agent。这一设计的巧思在于：
• 解耦与轻量化：如果为每个模块生成一个 Agent，会导致角色泛滥且业务逻辑被硬编码在提示词中。生成 SKILL.md则相当于提取了“技能书”。• 按需挂载：开发者只需要让任何一个通用的 Agent（如默认的编程助手）在需要时加载对应模块的 SKILL.md，该 Agent 就能瞬间“学会”该模块的底层逻辑和修改规范。
3. Agent Skill 最佳实践
本章节提炼了构建和维护 AI 智能体技能时的核心规范。以下实践均参考自 给 Claude 写本“标准操作手册”：Agent Skills 实战与深度解析 文档。
3.1 生产级目录结构
合理的目录结构能够有效解耦指令与实现，提升技能的可维护性。
建议将核心指令、执行脚本与参考资料进行分离，标准结构如下：
• SKILL.md：核心标准操作手册，文件名必须大写。• scripts/：存放具体执行原子操作的可执行脚本。• references/：存放按需加载的补充参考文档。• assets/：存放各类静态资源。
3.2 精准的触发描述
准确的技能描述是大模型进行逻辑推理和决策触发的关键依据。
SKILL.md 头部 Frontmatter 中的 description 字段是系统判断是否加载该技能的唯一标准。编写时应遵循以下黄金公式：
[功能描述] + [触发场景] + [关键词]
确保描述具体且场景明确，避免使用过于宽泛或模糊的表述。
3.3 渐进式知识披露
渐进式加载机制能够有效避免多个技能同时注册导致的上下文窗口溢出。
系统通常采用三层渐进式的知识加载策略：
1. 元数据层（常驻加载）：仅加载所有技能的名称与描述，用于大模型建立可用能力的索引。 2. 核心指令层（按需加载）：当技能被触发时，才将 SKILL.md的正文指令注入当前上下文。3. 详细文档层（引用加载）：执行过程中遇到特定需求时，再读取 references/目录下的外部文档。
3.4 状态管理与流程编排
理解技能的状态属性有助于避免多任务执行时的上下文冲突。
• 非并发安全：与无状态的函数调用不同，Agent Skills 本质上是动态修改当前的对话上下文。因此它是有状态的，在一段对话线程中建议一次只激活一个技能。 • 复杂工作流：技能非常适合作为“指挥官”来编排复杂工作流，例如多工具（MCP）协同、自我迭代纠错以及基于上下文的条件判断。
3.5 技能测试金字塔
系统化的测试是确保技能从可用走向稳定可靠的重要保障。
为了验证技能的健壮性，应建立多维度的评估体系：
• 触发测试：包含正向测试（确保目标场景下能被触发）和负向测试（确保无关对话中不被误触发）。 • 功能测试：验证技能调用的底层脚本或 API 能否正确返回预期结果。 • 性能评估：对比引入技能前后的大模型 Token 消耗情况与交互轮数。
3.6 技能命名规范
规范的命名有助于开发者和系统快速理解技能的用途与角色定位。
推荐使用 名词/执行者（Doer） 形式，而非动词（Action）形式。例如，应使用 agent-skill-reviewer 而不是 agent-skill-review，使用 pdf-translator 而不是 translate-pdf。多个单词之间应使用 kebab-case（短横线）连接。这种命名方式与技能作为“拟人化”智能体角色的定位高度一致。
4. 深度解析案例
本项目不仅收录了实用的 Agent Skills，还包含对业界顶尖 AI 工程实践的深度解析，以帮助开发者更好地理解和构建虚拟工程团队。
4.1 gstack 项目深度解析
我们对 Y Combinator CEO Garry Tan 开源的 gstack 项目进行了详尽的逆向工程与架构分析，提炼出了其核心设计哲学：将结构化的软件工程角色封装为特定的 AI 技能。
该深度解析报告详细拆解了：
• 无头浏览器守护进程：如何解决 AI 代理操作浏览器时的冷启动与状态丢失问题。 • 21 个核心技能全景：覆盖产品规划、质量保障、发布运营等完整生命周期。 • Prompt 工程最佳实践：如防御性设计、跨阶段上下文继承以及注入专家级思维模式。
详细内容请阅读：gstack 项目深度解析报告
4.2 五种智能体技能设计模式
我们翻译并整理了来自 Google Cloud Tech 的关于 Agent Skill 设计模式的深度文章，帮助开发者跳出格式的局限，专注于技能内部逻辑的结构化设计。
该报告详细拆解了五种核心设计模式：
• 工具包装器 (Tool Wrapper)：让 Agent 按需获取特定库或框架的上下文。 • 生成器 (Generator)：通过编排模板与样式指南强制执行一致的文档输出。 • 审查器 (Reviewer)：分离评分标准与检查流程，实现多领域的系统化审查。 • 反转模式 (Inversion)：让 Agent 扮演面试官，在收集完整上下文前阻止执行。 • 管道模式 (Pipeline)：通过硬检查点强制执行严格的多步骤工作流。
详细内容请阅读：每位 ADK 开发者都应掌握的五种智能体技能设计模式
4.3 superpowers 深度解析
该文档对 superpowers 插件与技能体系进行系统化的工程解析与实战指南，涵盖架构分层、核心模块、TDD/SDD 工作流、子智能体协作与钩子注入机制等内容，帮助读者快速掌握如何基于 superpowers 构建高确定性的 AI 工程能力。全文见：superpowers 深度解析。
5. 推荐参考资源
本章节推荐其他优秀的智能体技能合集与相关项目，以供开发者在不同业务场景下参考与借鉴。
5.1 MiniMax-AI 官方技能库
MiniMax-AI/skills 是由 MiniMax 官方维护的优秀技能合集。该项目涵盖了从前端开发到复杂办公文档生成的广泛场景，为开发者提供了丰富的实战参考。
其核心技能模块包括：
• 全栈与客户端开发：涵盖前端 ( frontend-dev)、全栈 (fullstack-dev)、Android (android-native-dev) 以及 iOS (ios-application-dev) 的系统性开发指南与规范。• 多媒体与创意生成：提供着色器开发 ( shader-dev) 与 GIF 动图生成 (gif-sticker-maker) 技能，结合 MiniMax 的图像和视频生成 API，实现高级视觉效果。• 专业文档处理：包含针对 PDF ( minimax-pdf)、PPTX (pptx-generator)、Excel (minimax-xlsx) 和 DOCX (minimax-docx) 的深度处理技能，支持从零生成、模板填充与格式重构。
6. Skill 单元测试
本章节介绍了项目中针对 Agent Skill 的单元测试与评估框架。该框架位于 unit-test 目录下，旨在确保各个技能在不同场景下的稳定性和准确性。
该测试框架包含以下核心组件与文档：
• 测试执行脚本： opencode-skill-eval.sh提供了自动化的测试执行能力。• 测试指南： skill-eval-minimal-guide.md详细说明了如何编写和运行技能的评估测试。• 测试用例与数据：包含 evals（评估逻辑）、fixtures（测试数据，如供doc-reviewer和md-translator使用的示例文档）、skills（被测技能配置）以及tests（具体的测试断言脚本）。
通过系统化的单元测试，我们能够持续验证技能触发的精准度以及任务执行的可靠性。