Table of Contents
一份面向工程落地的渐进式加载与模块化能力实践手册
0. 为什么 Agent Skills 重要：从“理解”到“执行”
大语言模型（LLM）擅长理解与生成文本，但现代 AI 系统越来越需要行动：调用工具、遵循流程、协同多步工作流，并在有限的上下文窗口中，以更确定、更安全、更高效的方式完成真实任务。
这就是 Agent Skills（智能体技能） 的价值所在。
Agent Skills 通过“可复用、可模块化”的方式，把通用模型升级为“能干活的专家”，将以下内容打包起来：
- 程序性知识（流程、最佳实践、决策规则）
- 业务上下文（注意事项、合规约束、适用边界）
- 可选自动化资产（脚本、模板、参考资料）
并支持按需加载（on-demand），避免每次对话重复交代同一套 SOP。
一句话理解：
- LLM 解决“能答”
- Agent Skills 解决“能做成事”
1. 核心概念：工具、技能、插件与子智能体
在工程实践中，“工具（Tool）”“技能（Skill）”“插件（Plugin）”常被混用。建立清晰术语能显著提升系统设计质量与治理能力。
1.1 工具（Tool）：Can-Do（原子执行）
工具是智能体的“手”，典型表现为：
- API 调用
- Shell 命令
- 数据库查询函数
- 文件读写操作
工具关注：
- 可行性（能不能做）
- 确定性（做出来是否稳定可复现）
- 权限边界（允许访问什么）
例子：execute_sql_query(sql)
它让智能体“能执行 SQL”，但不会教“怎样写安全高效 SQL”。
欢迎加入我们的TG群组交流：
https://t.me/+IuIEVyJ2STQ3ZDAx
1.2 技能（Skill）：Know-How（程序性胜任力）
技能是 SOP/剧本/手册，指导智能体如何正确使用工具，具备“胜任力”。
技能关注：
- 任务胜任力（怎么做更好）
- 合规性（必须遵守哪些规范）
- 决策逻辑（不同情况下怎么选）
例子：“数据库优化技能”可能会要求：
- 先用 EXPLAIN 分析执行计划
- 再根据结果调整索引/SQL
- 回归验证性能
- 最后才执行正式查询
1.3 插件（Plugin）：能力打包与分发
插件通常是一个容器，把一组相关工具与技能打包，便于整体启用/禁用（企业场景常见）。
例子：“办公插件”可能包含：
- 邮件工具
- 日程工具
- 写作与汇总技能（周报、纪要、报告）
1.4 子智能体（Sub-Agent）：隔离上下文的专家分工
当任务需要独立状态、长链路推理、或复杂执行时，系统会把它实例化为子智能体：
- 独立上下文
- 独立工具集
- 避免污染主智能体上下文
- 强化关注点分离（Separation of Concerns）
2. Agent Skills 在实践中长什么样？
大多数实现都遵循开放标准的形态：
一个 Skill = 一个文件夹 + 一个 SKILL.md（必需）+ 可选 scripts/resources/templates
你可以把 Skill 文件夹理解为给新员工的“入职手册”：
- 什么时候用这个技能
- 具体步骤怎么做
- 用哪些模板/脚本
- 如何验收质量与边界情况
3. 渐进式披露（Progressive Disclosure）：核心架构模式
3.1 上下文窗口限制（Context Window Problem）
上下文窗口是稀缺资源。把数百工具定义与长篇手册一次性塞进系统提示词会导致：
- 成本高
- 延迟大
- 推理精度下降（上下文饱和）
- 幻觉风险上升
3.2 三层加载模型：只在需要时加载需要的内容
Agent Skills 的关键是渐进式披露，典型分为三层：
Level 1：发现（Discovery）——只加载元信息
会话开始时，智能体只看到每个 Skill 的：
- name
- description
这非常轻量，允许挂载很多技能而不挤占上下文。
Level 2：激活（Activation）——加载指令主体
当用户请求与 skill 的 description 匹配时，智能体才读取：
- SKILL.md 的正文（流程、规范、决策树）
这一步将“操作手册”动态注入上下文，做到“用时再学”。
Level 3：执行（Execution）——按需读取资源/执行脚本
如果 Skill 引用了脚本、模板或参考资料，智能体才会：
- 读取相关文件
- 在沙箱/VM 中运行脚本
- 只消费脚本输出（不必把源码塞进上下文）
这使得确定性操作更可靠，也大幅节省 token。
4. 一个直观类比：技能加载像浏览器加载
Agent Skills 的加载方式可以类比现代 Web 应用：
- Level 1 元信息 ≈ Manifest / 路由表 / 模块索引
- Level 2 指令主体 ≈ 路由级代码分包 + 动态 import
- Level 3 脚本执行与资源读取 ≈ 懒加载资源 + Worker/WASM 计算只返回结果
浏览器不会一次加载整个站点，智能体也不应一次加载全部技能内容。
5. 高质量
SKILL.md
的结构与写法
5.1 YAML Frontmatter：触发路由的核心信号
最少要写：
---
name: pdf-processing
description: Extracts text and tables from PDF files, fills forms, merges documents. Use when the user mentions PDFs, forms, or document extraction.
---关键点：description 决定“会不会被用上”。
✅ 好的 description 应该包含：
- 明确动词：extract / review / generate tests
- 明确产物：CSV / PR feedback / summary report
- 触发关键词：PR、diff、PDF、pytest、forms 等
❌ 坏的 description：
- “Helps with tasks”
- “Useful for productivity”
- “Does data work”
5.2 指令主体：写成可执行 SOP，而不是散文
推荐结构：
- When to use / When not to use（适用与禁用边界）
- Inputs required（缺什么就问什么）
- Output format（输出格式固定化）
- Workflow steps（编号步骤）
- Decision tree（可选但非常有效）
- Quality checklist（减少遗漏与幻觉）
6. 把脚本与资源打包进 Skill
一个更完整的目录可能是：
pdf-skill/
├── SKILL.md
├── FORMS.md
├── REFERENCE.md
└── scripts/
└── extract_tables.py最佳实践：脚本当黑盒用
而不是读源码。建议智能体：
- 先运行 –help
- 再按参数执行
- 只基于输出做判断与汇总
这样上下文更干净，执行更确定。
7. Skills + MCP：胜任力与连接层的协同
Skills 负责“怎么做”，但智能体还需要“连上世界”（数据源与工具），这就是 MCP 的价值。
MCP 一句话
MCP 是“AI 的 USB-C”：为智能体访问外部工具与数据源提供统一协议。
分工非常清楚
- MCP 提供能力（Capabilities / Tools）：例如 query_database、read_drive_file
- Skills 提供胜任力（Competence / Instructions）：教你何时、如何、安全地用这些工具
成熟架构通常同时使用二者：
- MCP 解决连接碎片化
- Skills 解决流程与合规
8. 动态工具发现：突破“工具列表爆炸”
大企业可能有成千上万内部工具，不可能全部塞进系统提示词。
动态工具发现的典型流程：
- 智能体使用“工具搜索工具”向注册中心查询
- 注册中心返回相关工具 schema
- 智能体只把这些工具注入上下文
- 再由 Skill 的流程引导调用这些工具
这把“工具数量上限”从硬限制变成了“按需加载”。
9. 不同框架的实现范式
不同框架对工具/技能编排有不同工程哲学：
LangChain：函数式灵活性
- 工具就是函数
- agent 循环选择调用
- 原型快，但工具链大时容易变“面条代码”
Semantic Kernel：企业级插件与治理
- 强类型与结构化
- planner/规划器更适合长期维护
- 但相对厚重
CrewAI：角色分工（多智能体）
- 按角色分配工具与任务
- 复杂任务成功率更高，降低上下文混淆
AutoGen：对话驱动的代码执行
- 强调生成代码→执行→反馈→自我修正的闭环
- 探索性任务很强
经验总结：
- 小规模工具链 → 灵活框架更快
- 企业落地 → 结构化与治理更重要
- 多阶段复杂任务 → 角色分工更稳
10. 安全与治理：技能像“安装软件”
Skill 的能力越强，攻击面越大，因为它可能引导：
- 执行代码
- 操作文件系统
- 调用敏感工具
10.1 典型威胁
- 间接提示注入（网页、PDF、文档隐藏指令）
- 蜜罐文件（仓库里埋恶意指令）
- 工具滥用（危险命令、破坏性 SQL）
- 数据外泄风险
10.2 核心防线
A) 沙箱执行：容器/VM/WASM，避免在宿主机直接执行
B) 最小权限（RBAC）：只给必要权限
C) 人机回环（HITL）：高风险操作必须审批后执行
10.3 信任模型
只使用可信来源的技能；第三方技能必须审计：
- scripts 是否有异常网络请求
- 是否读取敏感路径
- 是否存在与 description 不一致的行为
11. Skill 工程化最佳实践清单
设计
- 单一职责：一个 skill 只做一件事
- description 写成“路由关键词”
- 适当提供 few-shot 示例
- SKILL.md 过长就拆分为子文件引用
执行
- 确定性逻辑交给脚本
- 尽量减少网络依赖
- 输入校验、错误信息明确
维护
- 建议加版本/所有者字段（即使不是强制）
- 规范更新要同步 examples
- 跟踪误触发与安全事件
12. 示例：高信号 Code Review Skill
---
name: code-review
description: Reviews PR diffs for correctness, edge cases, style, performance, and security. Use when the user provides a diff, PR link, or asks for a review.
---
# Code Review Skill
## When to use
- Reviewing pull requests or code diffs
- Checking code quality before merging
## Output format
Return feedback grouped by severity:
- Must-fix (bugs, correctness, security)
- Should-fix (maintainability, clarity)
- Nice-to-have (refactors, polish)
## Workflow
1) Understand the change objective
2) Correctness: verify logic meets requirements
3) Edge cases: nulls, errors, retries, boundaries
4) Style: naming, consistency, conventions
5) Performance: obvious inefficiencies
6) Security: validation, injection, secrets exposure
## Checklist
- [ ] Tests cover key paths
- [ ] Errors are handled safely
- [ ] No sensitive data leaks
- [ ] Code remains readable13. 团队落地的最小可行路线（Playbook）
- 先做 5–10 个高价值技能（code-review、pdf-processing、data-summary、weekly-report、incident-triage）
- 做工具治理RBAC 权限 + 沙箱 + HITL 审批点
- 建技能注册与规范命名、版本、owner、review 流程
- 度量结果时间节省、误触发率、安全事件、质量提升
- 逐步扩展技能库就是“数字员工资产库”
最后的结论
Agent Skills 是从：
- 拥有知识 → 拥有胜任力
- 会聊天 → 能交付
- 单体 Prompt → 模块化工作系统
的关键工程化桥梁。
通过结合：
- 渐进式披露
- MCP 动态工具发现
- 安全沙箱
- 人机回环治理
你可以把通用模型变成可信赖的“数字员工”。