从零到一 Agent Skills：概念、结构与建立教程

前言

因为大模型能力的不断进化，我们正从“模型会不会回答”转向“模型能不能稳定完成一类任务”。Agent Skills 作为一种开放格式，正在成为 AI Agent 工程化落地的关键一环。

这篇文章基于当前公开的 Agent Skills 规范。结合 Codex、VS Code、Claude Code 及自研 Agent 的工程实践，程序性地梳理 Skill 的概念、目录结构、加载机制、建立方法及落地实现。话说回来，无论你是 Agent 开发者、业务工程师，还是技术决策者。这篇文章都将帮你建立起对 Agent Skills 的完整认知框架。

使用者痛点 #1：Skill 目录结构不清晰。导致项目维护成本高

很多团队在第一次接触 Agent Skills 时发现文件夹层级繁杂，难以快速定位必需文件与可选文件。缺少统一的目录约定，让新人上手慢，并频繁出现误删或漏加文件。

使用者痛点 #2：Skill 与 Tool 的混淆导致功能拆分不清晰

初学者常把 Skill 当成直接可调用的 API，忽略了它是对工具链与流程的包装。结果导致代码耦合度高，可复用性差。

一个形象的类比

Skill 更像是 Agent 的 "可装载工作手册"

• 告诉 Agent 什么时候应该使用这个能力
• 告诉 Agent 按什么步骤执行
• 告诉 Agent 可以调用哪些脚本
• 告诉 Agent 遇到异常如何处理
• 告诉 Agent 最终应该如何验证结果

Agent 能力的四层架构

为了更清晰地理解 Skill 在整个程序中的位置，可以把 Agent 的能力拆解为四个层次：

什么时候应该沉淀一个 Skill？话说回来，

A practical rule of thumb:

Cautionary note: With powerful base models,overly complex skills can become bottlenecks. Tailor skills to vertical domains—this is where generic agents fall short.

二、当前公开规范的主要结构——痛点三：缺乏标准化配置导致团队协作受阻

完整目录结构

三层理解 `


# 第一层：Main spec – required SKILL.md + optional scripts/references/assets.

# 第二层：User interface extensions like agents/openai.yaml.

# 第三层：A quality folder evals/。not loaded at runtime.
`
`
`

各目录职责摘要 `

`
`

`**scripts/** – deterministic operations 
`
`

`**references/** – long knowledge bases 
`
`

`**assets/** – static resources 
`
`

`**evals/** – quality verification cases `
` `