做 Agent 开发一段时间后，大部分人都会遇到同一个问题：

Prompt 越写越长，模型执行越来越飘。

你把所有规范、流程、示例一股脑塞进系统 Prompt，token 蹭蹭涨，模型的注意力却被稀释了——它在"同时看着"几十件事，结果每件事都做得不够准。

Agent Skill 就是在解决这个问题。

---

核心思路：按需加载

把不同能力拆成独立的"技能包"，Agent 根据当前任务，只加载需要的那一个。

就像你电脑装了几十个软件，但你只打开当前要用的那个，其他的不占内存。

Context Window 就是 Agent 的"内存"，留给当前任务的空间越干净，执行越稳定。

---

一个 Skill 的三层结构

第一层：Metadata（元信息）

技能的"身份证"——叫什么、能干什么、什么时候触发。

name: code-review
description: 审查代码，识别安全风险、逻辑问题、性能瓶颈
triggers:
  - "帮我看一下这段代码"
  - "review 一下"
input:
  - code_snippet: string
output:
  - review_report: string

Metadata 很轻，系统可以把所有技能的 Metadata 一起加载，让 Agent 先选用哪个技能，而不需要把完整内容全暴露出来。

---

第二层：Instruction（执行指令）

真正告诉 Agent "这件事怎么做"，只在执行这个技能时才加载进上下文。

## Code Review 执行指南

按优先级审查以下维度：
1. 安全性：SQL 注入、XSS、敏感信息硬编码 → 标记 [HIGH]
2. 逻辑正确性：边界条件、空值处理、并发问题
3. 性能：循环内重复计算、不必要的数据库查询
4. 可读性：命名是否清晰，复杂逻辑是否有注释

每条问题注明 [HIGH/MEDIUM/LOW]，说明位置、问题、修改建议。

---

第三层：Resources（外部资源）

有些技能执行时还需要额外的东西：规则库、模板、脚本、外部工具调用等。这些放在 Resources 层，Agent 按需拉取，用完即走。

/skills/code-review/
  metadata.yaml          ← 索引，常驻
  instruction.md         ← 执行时加载
  resources/
    security_rules.json  ← 按需拉取
    review_template.md

---

三层各司其职

层级	作用	加载时机
Metadata	技能索引，用于路由选择	始终在上下文
Instruction	执行指南，指导 Agent 行为	技能被选中时
Resources	外部数据/脚本/模板	执行过程中按需

这就是所谓的渐进式披露——信息随执行进度逐步展开，而不是一开始全部堆在上下文里。

---

设计 Skill 时最容易踩的坑

粒度问题。 一个技能对应一个完整的用户意图，不要太粗也不要太细。

code-review ✅ 对应"帮我 review 代码"这个完整意图
backend-development ❌ 太粗，一个技能管了太多事
check-variable-naming ❌ 太细，组合起来很麻烦

描述要精准。 Agent 靠 Metadata 的 description 来判断用不用这个技能，描述模糊就容易选错。

---

举例

比如我们现在需要生成一个视频，但是并不知道怎么做，这时候可以借助这个skill，https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices，我们把这个 skill 安装到本地

然后直接向ai提问，ai会自动寻找这个skill，并利用这个skill生成视频

帮我生成一个前端行业报告，使用remotion-best-practices这个skill

可以看到ai最后直接帮我创建了一个前端项目

执行看看效果，为了较少大小，我调整为4倍速，可以看到效果还不错，如果不借助skill，很难实现这个效果

最后

Agent Skill 的本质是对执行能力的结构化管理。

三层结构解决的问题很实际：让 Context Window 里只出现当前任务需要的内容，让模型更专注，执行更稳定，技能库更好维护。