Agent Skills

Skill 封装工作流、规范、参考资料与可复用资源；它与可执行 Tool 相关，但不是同一概念。

Skill 的渐进式披露

Skill 渐进披露的是“如何完成任务”的知识和流程，不是工具执行能力。

第一层：名称和描述

Agent 启动时只获得 Skill 索引：

- name: pdf
  description: 读取、创建、渲染和检查 PDF
  path: /skills/pdf/SKILL.md

- name: diagnosing-bugs
  description: 诊断复杂 Bug 和性能问题
  path: /skills/diagnosing-bugs/SKILL.md

第二层：完整 SKILL.md

用户显式指定 Skill，或者任务与 description 匹配后，Agent 才读取完整 SKILL.md。

第三层：附属资源

Skill 可以包含：

my-skill/
├── SKILL.md
├── references/
├── scripts/
└── assets/

完整 SKILL.md 再根据任务路由到必要的 Reference、Script 或 Asset。第三层是否真正按需加载，取决于 Skill 的编写方式和宿主 Agent 的实现，不是仅靠目录结构自动保证。

当前官方文档说明，ChatGPT 和 Codex 初始只展示 Skill 名称与描述，选中后再读取完整 SKILL.md；Codex 初始 Skill 列表最多占上下文的 2%，未知窗口时最多 8,000 字符。OpenAI Docs：Build skills

相关笔记

• 工具发现与动态加载 — 工具 Schema 的渐进披露
• 智能体工具调用原理 — Skill 与 Tool 的职责边界
• 模型上下文协议 MCP
• 工具与运行时 MOC