硬肝万字解析Skill设计最佳实践，我开源了一个生成Skill的Skill「SkillFather」

老邋遢

530人浏览 · 2026-05-22 12:11:31

老邋遢 · 2026-05-22 12:11:31 发布

硬肝万字解析Skill设计最佳实践，我开源了一个生成Skill的Skill「SkillFather」

一、引言

在 AI Agent 开发的浪潮中，我们面临着这样一个困境：随着项目复杂度的提升，我们需要为 Agent 配置越来越多的能力。这些能力可能包括代码调试、文档生成、数据分析、工作流自动化等等。然而，当我们耗费大量时间编写了几十个 Skill 之后，一个深刻的问题浮现出来——我们是否在重复造轮子？

为了解决这个问题，我开源了一个名为 SkillFather 的项目，它是一个面向 AI Agent 的通用 Skill 创建框架。

开源地址：https://github.com/huanqwer/SkillFather

使用方法：

克隆项目

git clone https://github.com/huanqwer/SkillFather.git

复制skills/skill-father到你工程的skills目录下

macOS/Linux:

# 以Cursor为例
cd SkillFather
cp -r skills/skill-father ~/.cursor/skills/

Windows (PowerShell):

# 以Cursor为例
cd SkillFather
Copy-Item -Recurse skills\skill-father $env:USERPROFILE\.cursor\skills\

Windows (CMD):

# 以Cursor为例
cd SkillFather
xcopy /E /I skills\skill-father %USERPROFILE%\.cursor\skills\skill-father

如果你觉得这个项目对你有帮助，恳请帮忙在 GitHub 上点一个免费的 Star，你的支持是我持续更新的动力！⭐

回到正题，当我们耗费大量时间编写了几十个 Skill 之后，一个深刻的问题浮现出来——我们是否在重复造轮子？

每一个 Skill 的创建似乎都从零开始，缺乏统一的规范和标准。有的 Skill 结构混乱，有的缺乏测试用例，有的难以复用，更别提持续优化了。这种低效的开发方式不仅浪费了宝贵的开发时间，更重要的是，它阻碍了 Agent 能力的规模化扩展。

正是在这样的背景下，SkillFather 应运而生。

SkillFather 的核心理念非常简单却深刻：创建第一个 Skill 之前，你需要一个能创建 Skill 的 Skill。这听起来像是一个递归的定义，但实际上它揭示了一个重要的软件工程原则——元编程（Metaprogramming）的思想在 AI Agent 领域的应用。

SkillFather 不仅仅是一个工具或框架，它是一套完整的面向 AI Agent 的通用型、标准化、测试优先（Test-First）、可组合、可观测、可持续优化的 Skill 创建方法论。它的目标是将我们在创建 Skill 过程中积累的经验，抽象成一个通用且能被复用的框架，让每一个新 Skill 的创建都站在巨人的肩膀上。

本文将深入探讨 SkillFather 的设计思想、核心原则、标准工作流程、技术规范以及实战案例，帮助你理解如何构建高质量的 Agent Skill，从而提升 AI Agent 的能力和可靠性。

二、核心思想

2.1 SkillFather 的设计哲学

SkillFather 的设计哲学源于一个简单的观察：一个优秀的 Skill Creator 首先应具备某个领域相当的专业知识，然后总结出最佳实践，抽象成 SOP（Standard Operating Procedure，标准操作流程）。

这个过程可以分解为三个层次：

领域专业知识：这是基础。要创建一个能够处理 Java Springboot 服务 bug 的 Skill，你必须对 Java、Springboot、常见的 bug 类型、调试方法等有深入的理解。没有领域知识，就无法抽象出有价值的 Skill。
最佳实践总结：在具备领域知识的基础上，你需要总结出处理该领域问题的最佳实践。比如，修复 bug 的标准流程是什么？如何快速定位问题？如何验证修复效果？这些最佳实践是 Skill 的核心内容。
SOP 抽象：将最佳实践进一步抽象成标准化的操作流程，这就是 SOP。SOP 应该清晰、可执行、可复用，能够让 Agent 按照既定的步骤完成任务。

SkillFather 的价值在于，它将这三个层次的经验固化下来，形成了一套可复用的框架。当你需要创建新的 Skill 时，不需要从零开始，而是可以基于 SkillFather 提供的模板和规范，快速构建出高质量的 Skill。

2.2 Skill ≠ Prompt

在深入 SkillFather 之前，我们需要澄清一个重要的概念：Skill 不是 Prompt。

很多人将 Skill 等同于 Prompt，认为写一个 Prompt 就是在创建 Skill。这是一个严重的误解。Prompt 只是 Skill 的一个组成部分，是 Skill 与 Agent 交互的接口。但 Skill 的内涵远不止于此。

Skill 是一个能力单元，它具备完整的生命周期：

生命周期：Skill 有创建、使用、优化、废弃的完整生命周期
Eval：Skill 必须有完整的评估体系，包括触发评估、成功评估、失败评估、对抗评估等
Runtime：Skill 在运行时需要考虑性能、资源消耗、错误处理等
Telemetry：Skill 需要收集运行数据，支持持续优化
Versioning：Skill 需要版本管理，支持演进和回滚
Retrieval：Skill 需要支持动态知识检索，避免知识过时
Workflow： Skill 需要定义清晰的工作流，支持状态管理
State Machine：Skill 需要状态机模型，处理复杂的状态转换

你正在构建的不是 Prompt，而是 Agent 能力基础设施。这个基础设施需要具备工程化的质量标准，包括可测试性、可观测性、可维护性、可扩展性等。

2.3 核心价值

SkillFather 的核心价值体现在以下几个方面：

标准化：通过统一的目录结构、元数据规范、评估标准，确保所有 Skill 都遵循相同的质量标准。这使得 Skill 更易于理解、维护和扩展。

可复用：通过能力抽象和模块化设计，Skill 可以在不同场景下复用，避免重复开发。一个精心设计的 Skill 可以成为多个 Agent 的能力模块。

可观测：通过 Telemetry 收集运行数据，实时监控 Skill 的性能、准确率、错误率等指标。这使得 Skill 的优化变得有据可依。

可持续优化：基于 Telemetry 数据和 Eval 结果，Skill 可以持续优化，不断提升性能和可靠性。这使得 Skill 能够适应不断变化的需求和环境。

三、核心原则

SkillFather 的设计遵循 8 大核心原则，这些原则贯穿于 Skill 创建的全过程。

3.1 测试优先（Test First）

测试优先是 SkillFather 最核心的原则。这意味着在编写 Skill 之前，必须先定义 Eval（评估用例）。

为什么要测试优先？原因有三：

明确需求：编写 Eval 用例的过程就是明确需求的过程。你需要思考 Skill 应该在什么情况下触发、应该输出什么、不应该输出什么。这个过程能够帮助你更好地理解需求。
指导开发：Eval 用例可以作为开发的指导。你编写的 Skill 必须能够通过这些测试用例，这确保了 Skill 的正确性。
持续验证：在 Skill 优化过程中，Eval 用例可以持续验证 Skill 的正确性，避免优化引入新的问题。

测试优先并不意味着要编写完整的测试代码，而是要定义清晰的评估标准。这些标准包括触发条件、成功案例、失败案例、对抗案例等。

3.2 Eval 驱动开发（Eval Driven Development）

Eval 驱动开发是测试优先原则的延伸。它强调在整个 Skill 开发过程中，Eval 用例是驱动力。

Eval 驱动开发包括以下几个要点：

优先定义 Eval：在编写任何 Skill 代码之前，先定义完整的 Eval 用例
持续运行 Eval：在开发过程中持续运行 Eval 用例，确保 Skill 的正确性
基于 Eval 优化：优化 Skill 时，以 Eval 结果为依据，确保优化不会降低质量
回归测试：在 Skill 演进过程中，持续运行历史 Eval 用例，避免回归问题

Eval 驱动开发能够显著提升 Skill 的质量和可靠性，是 SkillFather 推荐的开发方式。

3.3 Skill 模块化

Skill 模块化原则强调 Skill 应该是可拆分的、可组合的模块，而不是单体式的逻辑。

模块化的好处包括：

可维护性：模块化的 Skill 更易于理解和维护
可复用性：模块可以在不同 Skill 中复用
可测试性：模块可以独立测试
可扩展性：模块可以独立扩展，不影响其他部分

SkillFather 通过标准目录结构支持模块化设计。例如，scripts/ 目录存放可执行脚本，references/ 目录存放参考文档，assets/ 目录存放模板和静态资源。这些目录都可以独立管理和扩展。

3.4 Skill 可组合

Skill 可组合原则强调 Skill 应该能够组合使用，形成更复杂的能力。

可组合性包括：

输入输出标准化：Skill 的输入输出应该标准化，便于组合
状态管理：Skill 应该支持状态传递，便于组合
错误处理：Skill 应该有统一的错误处理机制，便于组合
依赖管理：Skill 应该明确依赖关系，便于组合

通过可组合性，多个简单的 Skill 可以组合成复杂的工作流，实现更强大的能力。

3.5 Runtime Context Injection

Runtime Context Injection 原则强调 Skill 应该支持运行时上下文注入，而不是将所有上下文硬编码在 Prompt 中。

Runtime Context Injection 的好处包括：

动态性：Skill 可以根据运行时上下文动态调整行为
灵活性：Skill 可以适应不同的运行环境
效率：避免一次性注入大量上下文，节省 Token
准确性：上下文是最新的，避免知识过时

SkillFather 通过动态知识检索、懒加载、渐进式披露等技术支持 Runtime Context Injection。

3.6 Progressive Disclosure

Progressive Disclosure（渐进式披露）原则强调 Skill 应该根据需要逐步披露信息，而不是一次性披露所有信息。

渐进式披露的好处包括：

效率：避免一次性披露大量信息，节省 Token
准确性：根据需要披露相关信息，提高准确性
可维护性：信息分层管理，便于维护

SkillFather 通过分阶段的工作流设计支持渐进式披露。例如，在意图抽取阶段只收集必要信息，在能力抽象阶段才披露更多细节。

3.7 Trigger Optimization

Trigger Optimization 原则强调 Skill 的触发条件应该经过精心设计，确保 Skill 在正确的时候被触发。

Trigger Optimization 包括：

语义触发器：使用语义关键词触发，而不是简单的关键词匹配
触发条件：明确定义应该触发和不应该触发的情况
排除条件：明确定义绝对不应该触发的情况
上下文信号：利用上下文信息提高触发准确率

精心设计的触发条件能够显著提升 Agent 的检索准确率，确保 Skill 被正确使用。

3.8 Telemetry First

Telemetry First 原则强调 Skill 应该从设计之初就考虑可观测性，收集运行数据支持持续优化。

Telemetry First 包括：

数据收集：收集触发准确率、完成率、幻觉率、Token 使用、延迟等数据
成功标准：定义明确的成功标准，如触发准确率 ≥92%、完成率 ≥90%、幻觉率 ≤3%
持续优化：基于 Telemetry 数据持续优化 Skill

Telemetry First 使得 Skill 的优化变得有据可依，能够持续提升性能和可靠性。

四、标准工作流程

SkillFather 定义了一个 6 步的标准工作流程，确保 Skill 的创建过程规范、高效、高质量。

Step 1：意图抽取（Intent Extraction）

意图抽取是 Skill 创建的第一步，目标是分析用户的真实需求。

在这一步，你需要使用 ask_question MCP 工具（如果没有提问 MCP 工具，则使用普通对话）询问用户问题，不断循环直到提取到完整的信息：

用户目标：用户想要达成什么目标？
任务边界：任务的范围是什么？哪些在范围内，哪些不在？
输入输出：任务需要什么输入？期望什么输出？
工具需求：任务需要什么工具或资源？
状态变化：任务会导致什么状态变化？
是否具备复用性：这个任务是否具备复用价值？
是否适合 Agent 自动化：这个任务是否适合 Agent 自动执行？

如果任务不具备复用价值、不适合作为能力模块、不适合工作流抽象，则应该 STOP，不要生成 Skill。

意图抽取的关键是深入理解用户的真实需求，而不是表面的描述。有时候用户的需求可能表述不清，需要通过提问来澄清。

Step 2：能力抽象（Capability Abstraction）

能力抽象是将用户需求转换为可复用能力的过程。

在这一步，你需要将用户需求转换为：

可复用能力：将需求抽象为可复用的能力模块
工作流节点：将需求分解为工作流中的节点
状态机：定义状态转换规则
工具接口：定义工具的输入输出接口
运行时行为：定义运行时的行为逻辑

在能力抽象过程中，必须避免：

超长 Prompt：避免将所有逻辑写在一个超长的 Prompt 中
单体式逻辑：避免单体式的逻辑设计
强耦合结构：避免强耦合的结构
一次性生成逻辑：避免一次性生成所有逻辑

Skill 必须：

可拆分：能够拆分为独立的模块
可组合：能够组合使用
可独立测试：每个模块能够独立测试

能力抽象完成后，需要用户审查并确认以下内容：

用户意图是否被正确理解
任务边界是否合理
输入输出是否清晰
工具需求是否准确
状态变化是否合理
工作流是否正确

循环直至所有信息被完全确认。如果无法确认，则 STOP，不要生成 Skill。

Step 3：定义 Eval（强制步骤）

定义 Eval 是 SkillFather 最重要的一步，也是强制步骤。必须优先生成 Eval，禁止跳过。

Eval 包括以下几个部分：

Trigger Eval

Trigger Eval 定义哪些情况应该触发该 Skill，以及触发的 Skill 是否被路由到正确的 category。

Trigger Eval 需要考虑：

语义触发器：使用什么语义关键词触发？
触发条件：在什么情况下应该触发？
路由正确性：Skill 是否被路由到正确的 category？

Non-Trigger Eval

Non-Trigger Eval 定义哪些情况绝对不能触发 Skill。

Non-Trigger Eval 需要考虑：

排除条件：在什么情况下绝对不应该触发？
边界情况：边界情况如何处理？

Success Eval

Success Eval 定义 Skill 的正确输出示例。

Success Eval 需要考虑：

正确输出示例：Skill 应该输出什么？
测试用例覆盖：测试用例需要覆盖所有场景
TDD 思想：优先编写测试用例

Failure Eval

Failure Eval 定义失败案例。

Failure Eval 需要考虑：

失败案例：什么情况下会失败？
测试用例覆盖：测试用例需要覆盖所有失败场景

Adversarial Eval

Adversarial Eval 定义对抗性测试用例，包括：

Prompt Injection：如何防范 Prompt Injection？
模糊输入：如何处理模糊输入？
幻觉诱导：如何防范幻觉诱导？
上下文污染：如何防范上下文污染？
Token Overload：如何处理 Token Overload？

如果无法定义 Eval，则 STOP，不要生成 Skill。

Step 4：生成 Skill

在完成 Eval 定义后，就可以开始生成 Skill 了。

SkillFather 要求生成以下文件和目录：

SKILL.md：必需，Skill 的主要文档
skill.yaml：必需，Skill 的元数据
evals/：必需目录，Eval 测试用例
- trigger_cases.json
- success_cases.json
- failure_cases.json
- benchmarks.json
workflows/：必需目录，工作流定义
- state-machine.yaml
scripts/：必需目录，可执行脚本
references/：必需目录，参考文档
assets/：必需目录，模板和静态资源
README.md：可选，Skill 说明

必须使用标准化目录结构：

skill-name/
├── SKILL.md              # 必需
├── skill.yaml            # 必需
├── evals/                # 必需：Eval 测试用例（JSON 格式）
│   ├── trigger_cases.json
│   ├── success_cases.json
│   ├── failure_cases.json
│   └── benchmarks.json
├── workflows/            # 必需：工作流定义（YAML 格式）
│   └── state-machine.yaml
├── scripts/              # 必需：可执行脚本
├── references/           # 必需：参考文档
├── assets/               # 必需：模板和静态资源
└── README.md             # 可选：Skill 说明

重要：所有标准目录（evals/、workflows/、scripts/、references/、assets/）必须在创建 Skill 时被创建。即使目录暂时为空，也要创建目录结构。这确保了目录结构的一致性和可扩展性。

Skill 必须：

标准化：遵循统一的规范
结构化：有清晰的结构
AI 阅读友好：便于 AI 理解和使用
使用标准化的 evals/ 目录结构：Eval 测试用例使用 JSON 格式
使用标准化的 workflows/ 目录结构：工作流定义使用 YAML 格式

Step 5：优化 Trigger

优化 Trigger 是提升 Agent 检索准确率的关键步骤。

在这一步，你需要优化：

描述：Skill 的描述是否准确？
语义触发器：语义触发器是否准确？
检索质量：检索质量是否满足要求？

描述必须包含：

用户意图：用户想要达成什么？
同义表达：有哪些同义表达？
典型场景：典型场景是什么？
上下文信号：有哪些上下文信号？
排除条件：有哪些排除条件？

描述的目标不是介绍 Skill，而是提升 Agent 检索准确率。因此，描述应该从 Agent 的角度出发，考虑 Agent 如何检索和匹配 Skill。

Step 6：Runtime 优化

Runtime 优化是确保 Skill 在运行时高效、稳定的关键步骤。

在这一步，Skill 必须支持：

动态知识检索：支持动态检索知识，避免知识过时
懒加载：按需加载资源，避免一次性加载
渐进式披露：逐步披露信息，避免一次性披露
运行时上下文注入：支持运行时上下文注入
Token 感知执行：感知 Token 使用，避免超限

禁止：

一次性注入全部上下文：避免一次性注入大量上下文
超长 Prompt：避免超长 Prompt
全量知识硬编码：避免将所有知识硬编码

Runtime 优化能够显著提升 Skill 的性能和可靠性，是 SkillFather 推荐的最佳实践。

五、标准目录结构

SkillFather 定义了严格的标准目录结构，确保所有 Skill 都遵循统一的组织方式。这种标准化的目录结构不仅便于 AI 理解和使用，也便于人类开发者维护和扩展。

5.1 完整目录结构

skill-name/
├── SKILL.md              # 必需：Skill 的主要文档
├── skill.yaml            # 必需：Skill 的元数据
├── evals/                # 必需：Eval 测试用例（JSON 格式）
│   ├── trigger_cases.json
│   ├── success_cases.json
│   ├── failure_cases.json
│   └── benchmarks.json
├── workflows/            # 必需：工作流定义（YAML 格式）
│   └── state-machine.yaml
├── scripts/              # 必需：可执行脚本
├── references/           # 必需：参考文档
├── assets/               # 必需：模板和静态资源
└── README.md             # 可选：Skill 说明

5.2 目录详解

SKILL.md

SKILL.md 是 Skill 的核心文档，包含 Skill 的完整描述。它应该包括：

Frontmatter：使用 YAML 格式的元数据，包括 name、version、description、category、author、license 等
Overview：Skill 的用途概述
触发时机：明确描述 Skill 应该在什么情况下被触发
适用文件类型：列出 Skill 适用的文件类型（可选）
标准流程：详细描述 Skill 的标准操作流程
状态流转：描述 Skill 的状态转换规则

SKILL.md 应该使用 Markdown 格式，便于 AI 和人类阅读。

skill.yaml

skill.yaml 是 Skill 的元数据文件，使用 YAML 格式。它包含 Skill 的完整元数据，包括：

基本信息：name、version、description、author、license
分类信息：category（多标签分类）
触发信息：trigger（语义触发器、触发条件、不触发条件）
输入输出：inputs、outputs
依赖信息：dependencies
性能预算：token_budget、latency_budget
风险等级：risk_level
可观测性：observability（数据收集配置）
评估策略：eval_strategy（评估方法和成功标准）

skill.yaml 是 Skill 的配置文件，应该保持简洁和准确。

evals/

evals/ 目录存放 Eval 测试用例，使用 JSON 格式。它包含以下文件：

trigger_cases.json：触发测试用例，定义哪些情况应该触发 Skill
success_cases.json：成功测试用例，定义 Skill 的正确输出示例
failure_cases.json：失败测试用例，定义失败案例
benchmarks.json：基准测试用例，定义性能基准

evals/ 目录是 Skill 质量保证的核心，必须完整定义。

workflows/

workflows/ 目录存放工作流定义，使用 YAML 格式。它包含以下文件：

state-machine.yaml：状态机定义，描述 Skill 的状态转换规则

workflows/ 目录是 Skill 工作流的核心，必须明确定义状态转换规则。

scripts/

scripts/ 目录存放可执行脚本。这些脚本可以是：

启动脚本：用于启动或重启服务的脚本
测试脚本：用于测试的脚本
工具脚本：用于特定任务的脚本

scripts/ 目录中的脚本应该具有清晰的命名和文档。

references/

references/ 目录存放参考文档。这些文档可以是：

技术文档：相关技术的文档
最佳实践：最佳实践文档
API 文档：API 文档
示例代码：示例代码

references/ 目录中的文档应该与 Skill 密切相关。

assets/

assets/ 目录存放模板和静态资源。这些资源可以是：

模板文件：代码模板、文档模板等
静态资源：图片、图标等
配置文件：配置文件模板

assets/ 目录中的资源应该便于复用。

README.md

README.md 是 Skill 的说明文档，可选。它应该包括：

Skill 简介：简要介绍 Skill 的用途
快速开始：如何快速使用 Skill
使用示例：使用示例
注意事项：注意事项

README.md 应该简洁明了，便于快速上手。

5.3 目录创建原则

SkillFather 强调以下目录创建原则：

必须创建：所有标准目录（evals/、workflows/、scripts/、references/、assets/）必须在创建 Skill 时被创建
即使为空也要创建：即使目录暂时为空，也要创建目录结构
保持一致性：所有 Skill 应该使用相同的目录结构
支持扩展：目录结构应该支持未来扩展

这些原则确保了目录结构的一致性和可扩展性。

六、skill.yaml 元数据规范

skill.yaml 是 Skill 的元数据文件，使用 YAML 格式。它包含 Skill 的完整元数据，是 Skill 标准化的关键。

6.1 基本信息字段

name

Skill 的名称，使用英文小写，使用连字符分隔单词。

name: java-springboot-bug-fix

version

Skill 的版本号，遵循语义化版本规范（Semantic Versioning）。

version: 1.0.0

description

Skill 的描述，使用多行字符串，详细描述 Skill 的用途和功能。

description:
  一个面向 Java Springboot 服务的 Bug 修复 Skill。
  该 Skill 用于系统性地诊断和修复 Java Springboot 服务中的 bug。

author

Skill 的作者。

author: gavin.qin

license

Skill 的许可证，使用标准许可证标识符。

license: Apache-2.0

6.2 触发信息字段

trigger

Skill 的触发信息，包括语义触发器、触发条件、不触发条件。

trigger:
  semantic:
    - 修复 bug
    - 改 bug
    - 处理后端问题
    - 接口报错
    - springboot 错误

  should_trigger_when:
    - 用户提到"修复bug"、"改bug"、"接口报错"等关键词
    - 后端服务出现异常或错误
    - API 接口返回错误状态码或异常响应

  should_not_trigger_when:
    - 前端问题
    - 数据库问题（除非与 Java 代码相关）
    - 部署问题

6.3 输入输出字段

inputs

Skill 的输入，列出 Skill 需要的输入参数。

inputs:
  - task_description
  - error_logs
  - stack_trace
  - environment_info

outputs

Skill 的输出，列出 Skill 的输出结果。

outputs:
  - bug_analysis_report
  - fix_suggestions
  - test_cases
  - documentation_updates

6.4 依赖信息字段

dependencies

Skill 的依赖，列出 Skill 依赖的其他 Skill 或服务。

dependencies:
  - retrieval-system
  - eval-engine
  - telemetry-runtime

6.5 性能预算字段

token_budget

Skill 的 Token 预算，包括软限制和硬限制。

token_budget:
  soft_limit: 12000
  hard_limit: 24000

latency_budget

Skill 的延迟预算，目标延迟时间（毫秒）。

latency_budget:
  target_ms: 8000

6.6 风险等级字段

risk_level

Skill 的风险等级，包括 low、medium、high。

risk_level: medium

6.7 可观测性字段

observability

Skill 的可观测性配置，包括数据收集配置。

observability:
  enabled: true

  collect:
    - trigger_accuracy
    - completion_rate
    - hallucination_rate
    - token_usage
    - latency
    - recovery_attempts

6.8 评估策略字段

eval_strategy

Skill 的评估策略，包括评估方法和成功标准。

eval_strategy:
  methodology:
    - trigger-eval
    - execution-eval
    - regression-eval
    - adversarial-eval

  success_criteria:
    trigger_accuracy: ">= 92%"
    completion_rate: ">= 90%"
    hallucination_rate: "<= 3%"

6.3 完整示例

---
name: java-springboot-bug-fix

version: 1.0.0

description:
  一个面向 Java Springboot 服务的 Bug 修复 Skill。
  该 Skill 用于系统性地诊断和修复 Java Springboot 服务中的 bug。

category:
  - backend-development
  - java
  - springboot
  - bug-fix

author: gavin.qin

license: Apache-2.0

trigger:
  semantic:
    - 修复 bug
    - 改 bug
    - 处理后端问题
    - 接口报错
    - springboot 错误

  should_trigger_when:
    - 用户提到"修复bug"、"改bug"、"接口报错"等关键词
    - 后端服务出现异常或错误
    - API 接口返回错误状态码或异常响应

  should_not_trigger_when:
    - 前端问题
    - 数据库问题（除非与 Java 代码相关）
    - 部署问题

inputs:
  - task_description
  - error_logs
  - stack_trace
  - environment_info

outputs:
  - bug_analysis_report
  - fix_suggestions
  - test_cases
  - documentation_updates

dependencies:
  - retrieval-system
  - eval-engine
  - telemetry-runtime

token_budget:
  soft_limit: 12000
  hard_limit: 24000

latency_budget:
  target_ms: 8000

risk_level: medium

observability:
  enabled: true

  collect:
    - trigger_accuracy
    - completion_rate
    - hallucination_rate
    - token_usage
    - latency
    - recovery_attempts

eval_strategy:
  methodology:
    - trigger-eval
    - execution-eval
    - regression-eval
    - adversarial-eval

  success_criteria:
    trigger_accuracy: ">= 92%"
    completion_rate: ">= 90%"
    hallucination_rate: "<= 3%"
---

七、可观测性与 Telemetry

可观测性是 SkillFather 的核心特性之一。通过 Telemetry 收集运行数据，可以实时监控 Skill 的性能、准确率、错误率等指标，为持续优化提供依据。

7.1 数据收集

SkillFather 支持收集以下数据：

触发准确率（Trigger Accuracy）

触发准确率衡量 Skill 是否在正确的时候被触发。

collect:
  - trigger_accuracy

触发准确率的计算方式：

触发准确率 = 正确触发次数 / 总触发次数

完成率（Completion Rate）

完成率衡量 Skill 是否能够成功完成任务。

collect:
  - completion_rate

完成率的计算方式：

完成率 = 成功完成次数 / 总执行次数

幻觉率（Hallucination Rate）

幻觉率衡量 Skill 产生幻觉（输出错误或无关信息）的比例。

collect:
  - hallucination_rate

幻觉率的计算方式：

幻觉率 = 产生幻觉的次数 / 总输出次数

Token 使用（Token Usage）

Token 使用衡量 Skill 的 Token 消耗情况。

collect:
  - token_usage

Token 使用包括：

输入 Token 数
输出 Token 数
总 Token 数

延迟（Latency）

延迟衡量 Skill 的执行时间。

collect:
  - latency

延迟包括：

总延迟
各阶段延迟

恢复尝试（Recovery Attempts）

恢复尝试衡量 Skill 在遇到错误时的恢复能力。

collect:
  - recovery_attempts

恢复尝试包括：

恢复尝试次数
恢复成功率

7.2 成功标准

SkillFather 定义了明确的成功标准，确保 Skill 的质量。

success_criteria:
  trigger_accuracy: ">= 92%"
  completion_rate: ">= 90%"
  hallucination_rate: "<= 3%"

这些成功标准是 Skill 质量的最低要求，Skill 应该努力超越这些标准。

7.3 持续优化

基于 Telemetry 数据，Skill 可以持续优化。

优化流程：

收集数据：收集 Telemetry 数据
分析数据：分析数据，找出问题
制定优化方案：制定优化方案
实施优化：实施优化
验证效果：验证优化效果
迭代优化：持续迭代优化

7.4 Telemetry 架构

SkillFather 的 Telemetry 架构包括：

数据收集层：收集运行数据
数据存储层：存储运行数据
数据分析层：分析运行数据
数据可视化层：可视化运行数据
优化决策层：基于数据做出优化决策

这种分层架构确保了 Telemetry 的可扩展性和可维护性。

八、实战案例：Java Springboot Bug Fix Skill

为了更好地理解 SkillFather 的使用方法，我们以 Java Springboot Bug Fix Skill 为例，展示如何使用 SkillFather 创建高质量的 Skill。

8.1 完整示例展示

Frontmatter 元数据

---
name: java-springboot-bug-fix
description: 处理Java Springboot服务的bug
version: 1.0.0
author: system
license: Apache-2.0
---

Overview

本 skill 用于修复 Java Springboot 服务中的 bug。当用户报告后端问题、接口报错或需要修复 bug 时，Agent 应使用此 skill 来系统性地诊断和解决问题。

触发时机

用户提到"处理后端问题"、“修复bug”、“改bug”、"接口报错"等关键词
后端服务出现异常或错误
API 接口返回错误状态码或异常响应

适用文件类型

.java - Java 源代码文件
application.yml / application.properties - Spring 配置文件
pom.xml - Maven 依赖配置文件
build.gradle - Gradle 构建文件

标准流程

问题收集
- 使用 scripts/java-springboot-local-reboot.md 启动或者重启本地 springboot 应用（强制）
- 收集用户描述的问题现象，如果用户没有使用以下规范反馈 bug，则建议用户使用下面的固定格式，然后继续后续任务
```
建议您使用规范格式更方便agent定位问题：
复现步骤：（详细描述您是如何稳定复现此bug的）
xxx
实际：（您实际看到的现象，可以贴接口response）
xxx
期望：（您期望的返回或行为）
xxx
```
- 按复现步骤复现后获取错误日志、堆栈信息
- 确认问题发生的上下文（请求参数、环境等）
问题定位
- 分析错误日志，定位异常代码位置
- 检查相关代码逻辑
- 排查配置问题
根因分析
- 确定问题的根本原因
- 分析代码逻辑缺陷
- 检查依赖版本兼容性
解决方案设计
- 设计修复方案
- 评估方案的影响范围
- 考虑向后兼容性
代码修复
- 实施修复代码
- 添加必要的注释
- 遵循项目代码规范
验证测试
- 编写或更新单元测试
- 进行本地测试验证
- 确认修复效果
文档更新
- 更新相关文档（如需要）
- 记录修复说明

状态流转

[待处理] → [问题收集中] → [问题定位中] → [根因分析中] → [方案设计中] → [代码修复中] → [验证测试中] → [已完成]

8.2 关键设计要点

问题收集的标准化反馈格式

在问题收集阶段，SkillFather 强调使用标准化的反馈格式。这个格式包括：

复现步骤：详细描述如何稳定复现 bug
实际：实际看到的现象，可以贴接口 response
期望：期望的返回或行为

这个标准化格式的好处包括：

清晰：问题描述清晰，便于理解
完整：信息完整，便于定位问题
可复现：步骤详细，便于复现问题

本地启动脚本的固定化

在问题收集阶段，SkillFather 强调使用固定的本地启动脚本。这个脚本应该：

标准化：使用统一的启动脚本
可复用：脚本可以在不同场景下复用
可维护：脚本易于维护和更新

本地启动脚本的固定化确保了调试过程的一致性和可复现性。

TDD 测试优先理念

SkillFather 强调 TDD（Test Driven Development）测试优先理念。这意味着：

优先编写测试用例：在编写修复代码之前，先编写测试用例
测试驱动开发：以测试用例驱动开发
持续验证：持续运行测试用例，确保修复的正确性

TDD 测试优先理念能够显著提升代码质量和可靠性。

可变部分 vs 固定部分的识别

在 Java Springboot Bug Fix Skill 中，SkillFather 识别了可变部分和固定部分：

可变部分：

问题原因分析
解决方案设计
代码修复

固定部分：

本地启动和调试过程
问题收集的标准化反馈格式
标准流程的步骤

通过识别可变部分和固定部分，SkillFather 能够将固定部分脚本化或资源化，供 Agent 直接调用，从而提升效率。

九、执行约束与成功标准

SkillFather 定义了明确的执行约束和成功标准，确保 Skill 的质量和可靠性。

9.1 禁止事项

SkillFather 明确禁止以下行为：

生成超大单体 Prompt

禁止生成超大单体 Prompt。超大单体 Prompt 会导致：

难以理解：Prompt 过长，难以理解和维护
难以复用：Prompt 过长，难以复用
难以测试：Prompt 过长，难以测试
性能差：Prompt 过长，性能差

应该将 Prompt 拆分为多个模块，每个模块专注于一个功能。

跳过 Eval

禁止跳过 Eval。跳过 Eval 会导致：

质量无法保证：没有 Eval，无法保证 Skill 的质量
无法验证：没有 Eval，无法验证 Skill 的正确性
无法优化：没有 Eval，无法优化 Skill

必须先定义 Eval，然后编写 Skill。

忽略 Trigger 边界

禁止忽略 Trigger 边界。忽略 Trigger 边界会导致：

触发不准确：Skill 可能在错误的时候被触发
检索准确率低：Agent 的检索准确率会降低
用户体验差：用户体验会变差

必须明确定义 Trigger 边界，包括触发条件和不触发条件。

忽略失败场景

禁止忽略失败场景。忽略失败场景会导致：

鲁棒性差：Skill 的鲁棒性会变差
错误处理差：Skill 的错误处理会变差
用户体验差：用户体验会变差

必须定义完整的失败场景，包括各种边界情况和异常情况。

忽略可观测性

禁止忽略可观测性。忽略可观测性会导致：

无法监控：无法监控 Skill 的运行情况
无法优化：无法基于数据优化 Skill
无法演进：无法持续演进 Skill

必须从设计之初就考虑可观测性，收集运行数据。

忽略 Runtime 成本

禁止忽略 Runtime 成本。忽略 Runtime 成本会导致：

性能差：Skill 的性能会变差
成本高：Skill 的运行成本会变高
用户体验差：用户体验会变差

必须考虑 Runtime 成本，包括 Token 使用、延迟等。

9.2 必须事项

SkillFather 要求必须做到以下事项：

模块化设计

必须采用模块化设计。模块化设计的好处包括：

可维护性：模块化的 Skill 更易于理解和维护
可复用性：模块可以在不同 Skill 中复用
可测试性：模块可以独立测试
可扩展性：模块可以独立扩展

应该将 Skill 拆分为多个模块，每个模块专注于一个功能。

Eval First

必须采用 Eval First。Eval First 的好处包括：

明确需求：编写 Eval 用例的过程就是明确需求的过程
指导开发：Eval 用例可以作为开发的指导
持续验证：Eval 用例可以持续验证 Skill 的正确性

必须先定义 Eval，然后编写 Skill。

Trigger Optimization

必须优化 Trigger。Trigger Optimization 的好处包括：

触发准确：Skill 在正确的时候被触发
检索准确率高：Agent 的检索准确率高
用户体验好：用户体验好

必须精心设计 Trigger，包括语义触发器、触发条件、不触发条件等。

Runtime Safety

必须确保 Runtime Safety。Runtime Safety 的好处包括：

稳定可靠：Skill 运行稳定可靠
错误处理好：Skill 的错误处理好
用户体验好：用户体验好

必须考虑各种异常情况，包括边界情况、错误情况等。

Skill Composability

必须确保 Skill Composability。Skill Composability 的好处包括：

可组合：Skill 可以组合使用
可扩展：Skill 可以扩展
可复用：Skill 可以复用

必须确保 Skill 的输入输出标准化，支持状态传递，有统一的错误处理机制。

Telemetry Collection

必须收集 Telemetry。Telemetry Collection 的好处包括：

可观测：Skill 的运行情况可观测
可优化：可以基于数据优化 Skill
可演进：可以持续演进 Skill

必须从设计之初就考虑可观测性，收集运行数据。

9.3 成功标准

SkillFather 定义了明确的成功标准，确保 Skill 的质量。

Trigger 正确

Skill 的 Trigger 必须正确，包括：

触发准确率 ≥92%：Skill 在正确的时候被触发的比例不低于 92%
不触发准确率 ≥95%：Skill 在不应该触发的时候不被触发的比例不低于 95%

执行稳定

Skill 的执行必须稳定，包括：

完成率 ≥90%：Skill 成功完成任务的比率不低于 90%
错误率 ≤5%：Skill 出现错误的比率不高于 5%

抗 Prompt Injection

Skill 必须能够抗 Prompt Injection，包括：

Prompt Injection 检测率 ≥95%：检测到 Prompt Injection 的比率不低于 95%
Prompt Injection 防御率 ≥98%：成功防御 Prompt Injection 的比率不低于 98%

幻觉率低

Skill 的幻觉率必须低，包括：

幻觉率 ≤3%：Skill 产生幻觉的比率不高于 3%

支持组合调用

Skill 必须支持组合调用，包括：

输入输出标准化：Skill 的输入输出标准化
状态传递支持：Skill 支持状态传递
错误处理统一：Skill 有统一的错误处理机制

支持持续优化

Skill 必须支持持续优化，包括：

Telemetry 数据收集：收集运行数据
优化机制：有优化机制
版本管理：有版本管理

可通过 Telemetry 演化

Skill 必须可通过 Telemetry 演化，包括：

数据驱动优化：基于数据优化
持续迭代：持续迭代优化
性能提升：性能持续提升

十、快速开始

SkillFather 提供了快速开始的方式，帮助你快速上手。

10.1 使用方式

直接复制 create-skill 文件夹

如果你已经创建了自己的项目，你可以复制 skills/create-skill 文件夹到你的工程 skills 文件夹下。

cp -r /path/to/SkillFather/skills/create-skill /path/to/your-project/skills/

命令行操作

你也可以使用命令行操作：

git clone https://github.com/huanqwer/SkillFather.git
cd SkillFather
cp skills/create-skill {yourSkillsDir}

10.2 最佳实践

在自己工程中使用

不建议在 SkillFather 工程里直接使用，因为在自己的工程中使用，AI 会工作的更好。这是因为：

上下文完整：在自己的工程中，AI 有完整的上下文
相关性高：在自己的工程中，Skill 与工程的相关性更高
定制化强：在自己的工程中，可以更好地定制化 Skill

测试优先的设计理念

SkillFather 强调测试优先的设计理念。这意味着：

优先定义 Eval：在编写任何 Skill 代码之前，先定义完整的 Eval 用例
持续运行 Eval：在开发过程中持续运行 Eval 用例
基于 Eval 优化：优化 Skill 时，以 Eval 结果为依据

测试优先的设计理念能够显著提升 Skill 的质量和可靠性。

持续优化的可观测性

SkillFather 强调持续优化的可观测性。这意味着：

从设计之初就考虑可观测性：在 Skill 设计之初就考虑可观测性
收集运行数据：收集运行数据，包括触发准确率、完成率、幻觉率等
基于数据优化：基于数据优化 Skill

持续优化的可观测性使得 Skill 的优化变得有据可依。

遵循 agentskills.io 规范

SkillFather 强调遵循 agentskills.io 规范。这意味着：

阅读最新规范：阅读 https://agentskills.io/specification 上的最新规范
使用备份规范：如果网络不支持访问，使用工程中的备份规范 specs/skill-spec-bak-2026-05-21.md
保持更新：保持 Skill 与最新规范同步

遵循 agentskills.io 规范确保 Skill 的标准化和兼容性。

渐进式披露和 Token 感知执行

SkillFather 强调渐进式披露和 Token 感知执行。这意味着：

渐进式披露：根据需要逐步披露信息，避免一次性披露
Token 感知执行：感知 Token 使用，避免超限
动态知识检索：支持动态知识检索，避免知识过时

渐进式披露和 Token 感知执行能够显著提升 Skill 的性能和效率。

十一、总结

SkillFather 是一个面向 AI Agent 的通用 Skill 创建框架，它将我们在创建 Skill 过程中积累的经验，抽象成一个通用且能被复用的框架。

11.1 核心价值

SkillFather 的核心价值体现在以下几个方面：

标准化：通过统一的目录结构、元数据规范、评估标准，确保所有 Skill 都遵循相同的质量标准。

可复用：通过能力抽象和模块化设计，Skill 可以在不同场景下复用，避免重复开发。

可观测：通过 Telemetry 收集运行数据，实时监控 Skill 的性能、准确率、错误率等指标。

可持续优化：基于 Telemetry 数据和 Eval 结果，Skill 可以持续优化，不断提升性能和可靠性。

11.2 适用场景

SkillFather 适用于以下场景：

需要创建可复用 Skill：当你需要创建可复用的 Skill 时
需要标准化 Skill：当你需要标准化 Skill 时
需要可观测 Skill：当你需要可观测的 Skill 时
需要持续优化 Skill：当你需要持续优化 Skill 时

11.3 未来展望

SkillFather 的未来展望包括：

更多模板：提供更多 Skill 模板，覆盖更多场景
更好工具：提供更好的工具，支持 Skill 创建和管理
更强社区：建立更强的社区，促进 Skill 的共享和协作
更深集成：与更多 AI Agent 平台集成，提升兼容性

11.4 范式转变

SkillFather 代表了从 Prompt 工程到 Skill 工程的范式转变。

Prompt 工程关注的是如何编写好的 Prompt，而 Skill 工程关注的是如何构建完整的 Agent 能力基础设施。

这种范式转变包括：

从单体到模块：从单体 Prompt 到模块化 Skill
从静态到动态：从静态 Prompt 到动态 Skill
从不可观测到可观测：从不可观测到可观测
从不可优化到可持续优化：从不可优化到可持续优化

SkillFather 正是这种范式转变的体现，它帮助我们构建高质量的 Agent Skill，从而提升 AI Agent 的能力和可靠性。

结语

SkillFather 不仅仅是一个工具或框架，它是一套完整的面向 AI Agent 的通用型、标准化、测试优先、可组合、可观测、可持续优化的 Skill 创建方法论。通过 SkillFather，我们可以将经验抽象成可复用的框架，让每一个新 Skill 的创建都站在巨人的肩膀上。

希望本文能够帮助你理解 SkillFather 的设计思想、核心原则、标准工作流程、技术规范以及实战案例，从而构建高质量的 Agent Skill，提升 AI Agent 的能力和可靠性。

AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

AtomGit 首发：PhyAI 具身智能推理引擎开源入驻

AtomGit开源社区

告别网页点点点，一行命令管理开源项目——AtomGit CLI 带你飞

AtomGit开源社区

CANN 开发者 Meetup 南京站圆满落幕：轻量开发专场，硬核技术面对面

AtomGit开源社区

所有评论(0)

查看更多评论

老邋遢

@itkfdektxa

已为社区贡献3条内容