aibot88 Agent Skill
本文档是面向通用 Python Agent 系统的 Agent Skill 设计规范。
本文档关注 Agent Skills 本身，不依赖任何具体项目实现，也不绑定某个特定框架、目录结构或运行时。目标是为开发者提供一套可以直接落地的 Skill 设计、定义、治理与演进规则，使 Skill 成为 Agent 系统中的稳定能力抽象，而不是临时拼接的函数集合。
Agent Skill 的核心理念来自 Agent Skills 生态：将一项可复用能力封装为一个可被发现、理解、选择、加载、执行和治理的能力单元。它既可以承载 instruction，也可以承载结构化 schema 与 executable handler，还可以作为 workflow 组成部分被更高层 Agent 编排。
1. Overview
在 Agent 系统中，Skill 的定义是：
一个可复用、可组合、可路由、可执行、可治理的能力单元，用于让 Agent 以稳定方式完成某一类任务。
一个完整的 Skill 应当回答以下问题：
- 这个能力做什么
- 在什么任务条件下应该被选中
- 接受什么输入
- 产生什么输出
- 通过什么
handler执行 - 有哪些 side effects
- 需要哪些权限、依赖与上下文
Skill 在 Agent 系统中承担三种核心角色：
Capability packaging把一项能力打包成可复用单元，例如web_search、file_read、document_summarize、robot_plan_navigation。Routing target为 Agent、Router 或 Planner 提供可选择目标，使系统能够从当前任务中判断“是否应使用该 Skill”。Execution boundary提供结构化输入输出边界，使校验、权限控制、异常归一化、监控和审计都可统一接入。
Skill 与 function、tool、API 的区别：
functionfunction是实现细节，解决局部逻辑。Skill是 Agent 可感知的能力抽象，内部可以调用多个function。tooltool是底层操作单元，例如发请求、读文件、执行 shell。Skill可以编排一个或多个tool。APIAPI是外部系统提供的接口。Skill可以依赖API，但Skill本身是面向 Agent 的能力契约。
简化理解：
function回答“如何实现一段逻辑”tool回答“如何执行一个底层动作”API回答“如何访问一个外部系统”Skill回答“Agent 如何稳定完成一类任务”
规范要求：
- 任何希望被 Agent 发现、选择、复用、治理的能力，都应设计为
Skill - 任何只存在于局部实现、没有独立 schema 和 metadata 的代码，不应被当作
Skill - 一旦某项能力被定义为
Skill，就必须接受统一的注册、执行、监控和生命周期治理
2. Design Principles
Skill 设计必须遵循以下原则。
Skill 是能力单元，不是普通函数Skill应表达一项完整能力，而不是对现有函数做浅包装。Skill 必须可复用Skill不应只服务某一轮对话或某一个临时任务实例，而应可被不同 Agent 流程稳定复用。Skill 必须可组合Skill应能被更大 workflow、planner、router 或 sub-agent 编排。Skill 必须结构化可执行Skill必须具备明确的input_schema和output_schema。单纯自然语言说明不足以支撑工程化执行。Skill 必须具备明确执行语义side effects、权限、超时、异常、幂等性和资源边界必须可见，不能隐藏在实现细节中。Skill 应尽量减少隐式状态Skill不应依赖未声明的全局变量、隐式 context、神秘环境变量或不可见单例。Skill 应控制 side effects优先设计为纯能力；必须产生 side effects 时，应明确声明影响范围、权限要求和回滚策略。Skill 应支持 progressive disclosure在 routing 阶段，应优先使用name、description、tags 等轻量信息进行筛选，而不是一次性暴露全部实现细节。Skill 应可测试schema、handler、execution flow 必须能独立于完整 Agent 主循环进行测试。
强制性规范：
Must每个可执行Skill必须有稳定name、清晰description、显式handler、结构化input_schema、结构化output_schemaMust每个Skill必须能被独立注册、独立调用、独立测试Must每个存在 side effects 的Skill必须声明权限边界和影响范围Must NotSkill不得把核心输入隐藏在 prompt 文本、全局状态或隐式 context 中ShouldSkill应优先组合已有能力，而不是复制底层逻辑ShouldSkill应具备明确版本和 replacement 策略
3. Skill Definition
一个完整 Skill 通常包含两层定义：
External definition面向 portable packaging 的定义，例如SKILL.md、metadata、instruction、triggering information。Internal definition面向 runtime execution 的定义，例如 Python model、schema、registry entry、handler reference。
3.1 Core Fields
每个可执行 Skill 至少应包含以下核心字段。
name唯一标识。用于注册、查询、路由、监控与版本管理。description面向 routing 的简明描述，必须清楚表达“什么时候应该调用这个 Skill”。input_schema结构化输入契约，定义字段、类型、约束、默认值与校验规则。output_schema结构化输出契约，定义下游可以依赖的稳定结果结构。handler实际执行逻辑的 Python callable 或 entrypoint。metadata用于承载扩展配置，例如version、tags、required_permissions、timeout、owner、status等。
推荐扩展字段：
versionSkill版本号，建议使用 semver。tags可用于搜索、筛选和路由增强的标签集合。required_permissions执行前必须满足的权限集合。allowed_tools当前Skill允许调用的tool范围。entrypoint可被 runtime 解析的 Python import 路径，格式建议为module.submodule:function。examples输入示例、输出示例、触发示例与失败示例。
字段规范要求：
name必须全局唯一，必须稳定，禁止带用户信息、环境信息、随机后缀description必须描述触发条件、适用任务和边界，禁止写成空泛宣传语input_schema必须表达真实执行所需最小输入，禁止依赖“调用方自己知道还要传什么”output_schema必须表达下游可依赖结果，禁止返回无结构自由文本让下游自行猜测handler必须可解析、可测试、可追踪，禁止通过隐式脚本拼接执行metadata只应用于扩展属性，不得替代核心字段
一个合格的 Skill 定义必须同时满足：
Completeness足以支持 discovery、routing、execution、monitoringDeterminism在相同输入和依赖条件下，行为应尽量可预期Observability结果、错误和性能特征可追踪Governability可被 enable、disable、deprecate、replace、audit
3.2 推荐实现方式
推荐使用：
Pydantic用于input_schema、output_schema、输入校验和 JSON schema 导出dataclass用于运行时Skill记录对象、执行结果对象等Enum用于SkillCategory、SkillStatus、SideEffectLevelpathlib.Path用于文件、目录或资源定位
示例：
from __future__ import annotations
from dataclasses import dataclass, field
from enum import StrEnum
from typing import Any
from pydantic import BaseModel, Field
class SkillCategory(StrEnum):
TOOL = "tool"
WORKFLOW = "workflow"
KNOWLEDGE = "knowledge"
SYSTEM = "system"
class WebSearchInput(BaseModel):
query: str = Field(description="自然语言搜索请求。")
top_k: int = Field(default=5, ge=1, le=20, description="返回结果数量上限。")
class WebSearchOutput(BaseModel):
results: list[dict[str, Any]] = Field(description="标准化后的搜索结果列表。")
@dataclass(frozen=True, slots=True)
class RuntimeSkill:
name: str
description: str
input_schema: type[BaseModel]
output_schema: type[BaseModel]
handler: str
metadata: dict[str, str] = field(default_factory=dict)
实现规则：
- portable 定义负责 discovery 和 instruction packaging
- runtime 定义负责 typed execution
- 不要把 instruction contract 与 execution contract 混成同一层
3.3 Skill Contract Requirements
3.3.1 Routing Contract
Routing contract 决定 Agent 能否正确选中一个 Skill。
必须包含：
- 可区分的
name - 高辨识度
description - 必要的 tags 或 category 信息
要求：
description必须回答“什么时候用”description必须包含领域语义，而不是只写“处理任务”description不得同时覆盖多个无关任务
3.3.2 Execution Contract
Execution contract 决定系统能否稳定执行一个 Skill。
必须包含：
input_schemaoutput_schemahandler- side effect 说明
- permission 要求
要求：
handler的输入输出语义必须与 schema 一致- schema 变化必须受 version 管理
- 任何 breaking change 都必须通过 version 或 replacement 明确体现
3.3.3 Operational Contract
Operational contract 决定该 Skill 是否适合进入生产系统。
必须包含：
- owner 或责任归属
- version
- status
- monitoring 指标
- 失败语义说明
要求：
- 无 owner 的
Skill不应进入生产 - 无测试的
Skill不应进入默认启用状态 - 无 telemetry 的高风险
Skill不应进入自动调用链路
4. Skill Categories
可按能力性质将 Skill 划分为四类。
4.1 Tool Skills
Tool Skill 是对单一底层能力的稳定封装。
特点：
- 功能聚焦
- schema 清晰
- side effects 明确
- 常常直接对应一个
tool adapter或领域服务
适用场景：
web_searchfile_readdb_querysend_email
4.2 Workflow Skills
Workflow Skill 负责将多个步骤、多个 tool 或多个下层 Skill 组合成更高层能力。
特点：
- 包含多步 orchestration
- 复用价值高
- 通常包含 retry、fallback、post-processing
适用场景：
research_and_summarizeplan_and_execute_code_fixrobot_pick_and_place
4.3 Knowledge Skills
Knowledge Skill 封装领域知识、推理模板、知识检索策略或专家型 instruction。
特点：
- 副作用低
- routing 价值高
- 常与 retrieval 或 structured post-processing 结合
适用场景：
medical_guideline_lookuplegal_clause_explainerrobot_fault_diagnosis_guide
4.4 System Skills
System Skill 服务于 Agent 系统本身，而非直接面向业务任务。
特点：
- 偏内部运行时能力
- 常见于 planning、memory、safety、governance、recovery
适用场景：
context_compactionsafety_policy_checktask_routersession_recovery
5. Skill Lifecycle
Skill 生命周期通常包括以下阶段。
5.1 Define
开发者需要完成：
- 编写 portable definition
- 编写
handler - 定义
input_schema与output_schema - 补充
metadata - 补充示例与测试
定义阶段必须满足：
- 名称唯一
- 描述可用于 routing
- 可执行入口明确
- 输入输出结构明确
- 权限边界明确
定义验收标准：
- portable definition 可以被 loader 正确发现和解析
- runtime 定义可以被 registry 正确注册
handler可被 executor 正确调用- 输入输出 schema 至少有一组有效测试样例
- 失败路径至少有一组异常测试样例
5.2 Register
Skill 被构造成 runtime object 后，需要注册到 SkillRegistry。
注册阶段包括：
- 唯一性校验
- metadata 校验
- source 记录
- enabled 状态初始化
注册阶段禁止：
- 用重复名称覆盖现有
Skill而无显式 replace 策略 - 注册缺失核心字段的半成品
Skill - 把 schema 不完整或 discovery 失败对象写入 registry
5.3 Discover
SkillLoader 负责从配置 source 中发现 Skill。
discovery 阶段负责：
- 文件发现
- frontmatter 或 manifest 解析
- schema 校验
- runtime object 构建
discovery 规范：
- 解析失败必须可定位到文件路径与错误原因
- 无效
Skill必须被显式记录，不能静默吞掉 - source 与来源目录必须可追踪
5.4 Execute
执行阶段由 SkillExecutor 或等价执行层负责。
执行阶段至少应包括：
- 输入校验
- 权限校验
handler解析handler调用- 输出校验
- 异常归一化
执行阶段规范：
- 不允许绕过
input_schema直接执行handler - 不允许绕过权限检查执行高风险
Skill - 不允许把未校验输出直接交给下游 workflow
- 必须区分业务失败、系统失败、权限失败、依赖失败
5.5 Monitor
每次执行都应产出可观测数据。
建议最少记录：
skill_nameversion- latency
- success / failure
- error class
- source
- permission context
监控阶段规范：
- 每次调用都必须生成 execution record
- 高风险
Skill必须记录审计信息 - 监控数据必须足以支持问题回放与责任定位
5.6 Deprecate
过时 Skill 不应直接静默删除，而应进入 deprecated 状态。
下线规范：
- 在
metadata中标记status=deprecated - 指定 replacement skill
- 明确移除时间点
下线阶段禁止：
- 直接删除仍在生产链路中的
Skill - 不通知调用方就改变返回结构
- 不保留迁移路径就强制切换 replacement
6. Skill Management
推荐将 Skill 管理拆分为三层。
6.1 SkillRegistry
SkillRegistry 是运行时 Skill 的权威索引。
职责：
- register / unregister
- 唯一性控制
- enabled 状态维护
- 按名称获取
Skill - 列表查询与筛选
- 为 routing 提供轻量匹配能力
不应承担：
- 文件解析
handler执行- 复杂业务逻辑
6.2 SkillManager
SkillManager 是对外暴露的统一管理入口。
职责：
- 协调
SkillLoader与SkillRegistry - 提供
load、reload、enable、disable、select等统一 API - 作为 Agent 或 Router 对接
Skill子系统的入口
不应承担：
- 解析细节
handler执行逻辑- 具体业务能力实现
6.3 SkillExecutor
SkillExecutor 是执行边界层。
职责：
- 按
input_schema校验输入 - 解析
handler或entrypoint - 注入 runtime context
- 检查权限与 timeout
- 调用执行逻辑
- 按
output_schema校验输出 - 统一异常格式
- 记录 telemetry
建议接口：
from pydantic import BaseModel
class SkillExecutor:
async def execute(
self,
skill: "RuntimeSkill",
payload: dict,
*,
context: dict | None = None,
) -> BaseModel:
...
职责边界总结：
Loader负责加载Registry负责索引Manager负责编排与对外接口Executor负责执行
7. Skill Invocation Flow
标准调用链路如下：
User → Agent → Router → SkillManager → SkillExecutor → Result
步骤说明：
User用户提交自然语言请求或结构化任务。AgentAgent 解析任务意图，判断是否需要调用Skill。RouterRouter 根据name、description、tags、上下文状态与策略规则选出候选Skill。SkillManagerSkillManager解析目标Skill，并检查其是否可用、是否启用。SkillExecutorSkillExecutor对输入做 schema 校验，执行handler，处理权限、超时、异常和输出校验。Result结构化结果返回给 Agent，Agent 再决定是直接回答用户，还是继续规划后续步骤。
职责边界：
- Router 解决“选哪个”
- Manager 解决“拿到哪个定义”
- Executor 解决“怎么执行”
- Agent 决定“如何消费结果”
8. Input / Output Schema Design
可执行 Skill 必须使用结构化输入输出。
原因：
- 保证输入可校验
- 保证输出可消费
- 降低 prompt 歧义
- 支持 tool calling
- 支持 telemetry 与 tracing
- 支持 workflow 组合
- 支持自动生成文档和 JSON schema
推荐方案：
- 使用
Pydantic BaseModel - 使用
Field提供 description 与约束 - 避免公共接口直接暴露
dict[str, Any] - 保持字段最小但完整
示例：
from pydantic import BaseModel, Field
class ReadFileInput(BaseModel):
path: str = Field(description="绝对路径或工作区相对路径。")
encoding: str = Field(default="utf-8", description="文件读取编码。")
class ReadFileOutput(BaseModel):
content: str = Field(description="读取到的文本内容。")
size_bytes: int = Field(ge=0, description="文件大小，单位为 byte。")
Schema 设计规则：
- 输入字段必须最少但足够
- 输出字段必须稳定、可机读
- optional 字段必须有明确语义
- 有限类别应使用
Enum - 错误信息应在错误模型或异常语义中体现，不应隐藏在随意字符串里
Schema 强制规范：
- 输入字段命名必须自解释，禁止使用
data、info、payload2等含糊名称 - 输出字段必须面向消费方设计，而不是直接暴露内部中间变量
- 同一个
Skill的输出结构必须在同一 version 下保持稳定 - 当字段可为空时，必须说明“为空代表什么”
- 当字段有默认值时，默认值必须符合真实业务语义
9. Skill Naming Conventions
Skill 命名必须稳定、清晰、可扩展。
命名规则：
- 使用小写
- runtime Python 标识建议使用
snake_case - external portable package 名称可使用
kebab-case - 优先使用“动词 + 名词”或“领域 + 动作”
- 禁止使用
helper、misc、common_task这类语义模糊名称
推荐示例：
web_searchfile_readfile_writecode_executedocument_summarizerobot_plan_navigationrobot_execute_grasp
鼓励采用 domain-based naming：
web_searchbrowser_extract_contentfilesystem_read_textknowledge_retrieve_policyworkflow_research_and_summarize
命名一致性要求：
- external name 与 runtime name 的映射必须稳定
- registry key 必须统一归一化
- 同一语义能力不得出现多个近义重复命名
10. Best Practices
保持单一职责一个Skill只解决一类清晰能力。显式定义 schema每个可执行Skill都必须定义input_schema和output_schema。明确 side effects写文件、发网络请求、执行命令、修改状态都必须可见、可审计。优先组合而不是复制Workflow Skill应优先组合已有Skill或 service，而不是复制下层逻辑。description 为 routing 服务description应描述触发场景，而不是实现细节。handler 接口保持稳定非 breaking change 不应随意修改输入输出语义。可测试schema、handler、executor flow 应分别测试。可观测所有执行都应留下 logs、metrics 或 tracing 线索。输出结构稳定即使内部依赖 LLM，返回结果也必须符合稳定结构。版本管理严格输出语义变化、权限变化、行为变化应通过 version 明确体现。
Skill 交付检查清单：
- 是否有唯一
name - 是否有高辨识度
description - 是否定义
input_schema - 是否定义
output_schema - 是否有可执行
handler - 是否声明 side effects
- 是否声明 permissions
- 是否有示例输入输出
- 是否有单元测试
- 是否有失败测试
- 是否可被 registry 管理
- 是否可被 executor 监控
11. Anti-Patterns
以下写法属于明确禁止的错误模式。
把 Skill 当成普通函数只有函数实现，没有 schema、metadata、routing 信息和执行边界，不是合格Skill。没有 input_schema / output_schema只收一个松散dict，再返回一个松散dict，会使 orchestration 与 validation 失控。没有 docstring 或 operational description如果开发者无法判断“什么时候该用它”，说明这个Skill定义不完整。过度耦合 AgentSkill不能强依赖某个具体 Planner、Prompt 模板或内部单例。隐式依赖 context如果执行依赖 session、user identity、permission、env var，必须在 contract 或执行接口中显式体现。过于庞大的 mega-skill一个Skill中混入多个不相关能力，会导致职责失控。隐藏 side effects未声明就偷偷写文件、发请求、改数据库，是高风险设计。仅靠 LLM 自由生成输出需要 machine-consumable 结果时，必须用 schema 验证，而不能完全信任自由文本。description 过宽描述过宽会导致 routing 误触发，损害系统稳定性。不做 version 管理行为语义已变但 identifier 不变，会直接破坏下游调用。把 metadata 当垃圾桶任意字段都塞入metadata，会破坏 contract 清晰度与类型安全。输出依赖 prompt 偶然性如果output_schema要求结构化结果，但实现完全依赖 prompt“希望模型刚好返回正确格式”，这是不合格设计。没有治理状态无enabled、deprecated、replacement、status语义的Skill无法进入长期维护体系。
12. Example Skill
下面给出一个完整示例，演示 Skill 的定义、schema、handler、注册与调用。
12.1 Definition
SKILL.md
---
name: document-summarize
description: Summarize long text documents into a concise structured summary when the user asks for key points, abstract, or digest.
allowed-tools: llm.generate file.read
metadata:
version: 1.0.0
tags: summarization,document
required-permissions: tool:file.read tool:llm.generate
entrypoint: skills.document_summarize:run
---
Use this skill when the task is to summarize a document, article, report, or note.
Always preserve key conclusions, risks, and next actions.
12.2 Schema
from pydantic import BaseModel, Field
class DocumentSummarizeInput(BaseModel):
text: str = Field(description="待总结的完整文档内容。")
max_bullets: int = Field(default=5, ge=1, le=10, description="摘要要点数量上限。")
class DocumentSummarizeOutput(BaseModel):
summary: str = Field(description="高层摘要。")
key_points: list[str] = Field(description="提取出的关键结论列表。")
12.3 Handler
from __future__ import annotations
async def run(payload: DocumentSummarizeInput, context: dict | None = None) -> DocumentSummarizeOutput:
text = payload.text.strip()
sentences = [part.strip() for part in text.split(".") if part.strip()]
key_points = sentences[: payload.max_bullets]
summary = " ".join(key_points[:3])
return DocumentSummarizeOutput(summary=summary, key_points=key_points)
12.4 Register
registry = SkillRegistry()
registry.register(runtime_skill)
12.5 Invoke
executor = SkillExecutor()
result = await executor.execute(
runtime_skill,
{
"text": "Agent Skills package reusable capabilities for intelligent systems.",
"max_bullets": 3,
},
)
13. Integration with LLM / Tool Calling
Skill 是连接高层 Agent reasoning 与底层 tool execution 的中间层。
13.1 Skill 如何暴露给 LLM
在初始 routing 阶段，建议只暴露有限信息：
namedescriptiontagscategory
当某个 Skill 被选中后，再加载：
- 完整 instruction
input_schema- execution metadata
这样做符合 progressive disclosure 设计，也能避免上下文膨胀。
13.2 Skill 如何用于 function calling
在 LLM function calling 场景下，可做如下映射：
name对应 tool/function namedescription对应 tool descriptioninput_schema对应 JSON schema parametersoutput_schema用于执行后的结果校验
示例：
def skill_to_tool_schema(skill: RuntimeSkill) -> dict:
return {
"type": "function",
"function": {
"name": skill.name,
"description": skill.description,
"parameters": skill.input_schema.model_json_schema(),
},
}
13.3 运行时建议
- 不要一次性把所有已安装
Skill都暴露给 LLM - 应先由 Router 或 Manager 选出候选集
- 执行前必须校验 arguments
- 执行后必须校验 result
- 所有 model-triggered invocation 都必须可追踪
14. Future Extensions
Skill 系统后续可扩展到以下方向。
Plugin System把Skill打包为可安装插件，并支持隔离依赖。Remote Skills支持通过 RPC、HTTP、MCP、消息队列等方式远程执行Skill。Skill Marketplace支持 skill repository、签名校验、审核流程与 trust policy。Versioning提供更完善的 semver 与 migration 机制。Capability Policy Layer基于用户角色、环境与风险级别决定是否允许执行某个Skill。Skill Graph显式支持多SkillDAG 或 workflow graph 编排。Execution Sandbox对高风险Skill提供隔离执行环境，例如 shell、browser automation、code execution。