📒 学霸笔记：Agent Skills 行业标准与高阶编写心法
Agent Skills Industry Standard & Advanced Writing Techniques
课程名称 / Course Title: AI 原生开发工作流实战 / AI Native Development Workflow in Practice
章节 / Chapter: 前沿技术速递（加餐）/ Frontier Tech Express (Bonus)
讲师 / Instructor: Tony Bai
核心主题 / Core Topic: Agent Skills 规范化 + 高质量 Skill 编写心法
📌 一、宏观背景：从"私有方言"到"行业普通话" / From "Private Dialects" to "Industry Standard"
演进时间线 / Evolution Timeline
2025年底 2026年初 2026年春
│ │ │
▼ ▼ ▼
各工具各写各的 Prompt Anthropic 发布 OpenAI Codex / Gemini CLI /
(碎片化的"私有方言") agentskills.io 标准 Copilot / OpenClaw 全面兼容
("书同文，车同轨") (生态统一)
两大统一标准的关系 / Relationship of Two Unified Standards
| 标准 | 统一的层面 | 类比 |
|---|---|---|
| MCP（模型上下文协议） | AI 连接外部系统的 "物理接口" | USB 接口标准 |
| Agent Skills | AI 扩展自身能力的 "软性知识与逻辑" 标准 | Docker 镜像标准 |
🔑 关键信号 / Key Signal:
Skill 遵循 agentskills.io 规范 → 可像 Docker 镜像一样在不同 AI 智能体间 无缝流转和运行。
Skills following the standard can flow seamlessly across different AI agents, like Docker images.
📌 二、最新规范解析：Agent Skills Spec 升级要点 / Latest Spec Changes
核心结构不变 / Core Structure Unchanged
my-skill/
├── SKILL.md ← 核心文件（含 YAML Frontmatter + Markdown 正文）
├── scripts/ ← 确定性逻辑脚本
│ └── xxx.sh / xxx.py
└── references/ ← 按需加载的参考资料
└── advanced-guide.md
四大规范升级 / Four Major Spec Upgrades
升级 1：严格命名规范 / Strict Naming Convention (name)
# ❌ 旧式（随意）
name: My Cool Skill v2!
# ✅ 新规范
name: my-cool-skill-v2
| 规则 | 说明 |
|---|---|
| 长度 | 1-64 字符 |
| 允许字符 | 小写字母 + 数字 + 连字符 - |
| 禁止 | 不能以 - 开头/结尾，不能有连续 -- |
| 对标 | npm 包 / 容器镜像命名规范 |
| 目的 | 为未来的 "技能集市"（Skill Marketplace） 打基础 |
升级 2：新增 compatibility 兼容性字段
compatibility: 需要 Python 3.11+ 以及 jq 命令行工具，需要公网访问权限。
作用 / Purpose: Agent 调用前先评估环境是否满足 → 避免执行到一半报错。
升级 3：新增 license 和 metadata 字段
license: Apache-2.0
metadata:
author: tonybai
version: 1.2.0
作用 / Purpose: 支撑开源生态繁荣，为 Skill 的分发和归属提供元信息。
升级 4：正式确立"渐进式披露"机制 / Progressive Disclosure
┌─────────────────────────────────────────────────────────────┐
│ 三层渐进式披露 │
│ Three-Level Progressive Disclosure │
│ │
│ Layer 1: YAML Frontmatter (元数据) │
│ ────────────────────────────────── │
│ • name, description, allowed-tools │
│ • Agent 首先读取，决定是否"翻开"这个 Skill │
│ • 类比：书的封面和目录 │
│ │
│ Layer 2: SKILL.md 正文 (核心指令) │
│ ────────────────────────────────── │
│ • 执行步骤、核心逻辑、输出模板 │
│ • Agent 决定使用后加载 │
│ • ⚠️ 建议不超过 500 行！ │
│ • 类比：书的正文章节 │
│ │
│ Layer 3: references/ 目录 (参考资料) │
│ ────────────────────────────────── │
│ • 非高频使用的详细文档、示例、边缘场景处理 │
│ • Agent 按需"翻书"查阅 │
│ • 类比：书的附录和索引 │
└─────────────────────────────────────────────────────────────┘
⚠️ 铁律 / Iron Rule:
主SKILL.md不超过 500 行！过长 = 挤占上下文窗口 + AI 迷失在冗余信息中。
MainSKILL.mdshould NOT exceed 500 lines! Too long = wasting context window + AI gets lost.
📌 三、四大高阶心法 / Four Advanced Techniques ⭐⭐⭐
这是本讲的 核心精华 / Core Essence，真正拉开差距的地方！
🧠 心法一：同理心写法 — 解释"Why" / Empathy Writing — Explain "The Why"
核心原则：把 AI 当作聪明但缺乏业务上下文的新入职高级同事。
Core Principle: Treat AI as a brilliant senior colleague who just joined and lacks your business context.
| 维度 | ❌ 旧式"恐吓型" | ✅ 新式"共情型" |
|---|---|---|
| 语气 | "你必须（MUST）！绝不允许（NEVER）！" | "请采用…因为…曾引发过…" |
| 内容 | 只说 WHAT（做什么） | 说 WHAT + WHY（为什么） |
| 效果 | 边缘场景易崩溃/幻觉 | AI 理解核心价值观，能自主变通 |
| 类比 | 对新人大喊"照做！" | 向新人解释业务背景和历史教训 |
# ❌ 恐吓型
你必须（MUST）使用单例模式！绝不允许（NEVER）创建多个实例！
# ✅ 共情型
在处理数据库连接时，请采用单例模式。
**原因：** 我们的云函数环境并发量很大，频繁创建连接会导致
下游数据库连接池耗尽，曾引发过严重的线上故障。
💡 深层原理 / Deep Insight:
现代 LLM（Claude 4.6, GPT 5.x 等）具有极强的 心智理论能力（Theory of Mind）。
当你解释清楚 Why，模型能在 未定义的突发状况 中基于"核心价值观"做出最优变通。
🎯 心法二：攻击性 Description — 榨干触发潜能 / Aggressive Description — Maximize Trigger Rate
问题： LLM 存在 "触发不足"（Undertrigger） 倾向 — 倾向于用基础工具自己干，而不调用你的专业 Skill。
Solution: 像推销员一样，把触发场景定义到极致！
# ❌ 软弱的描述（低触发率）
description: 提取 PDF 文本并格式化数据。
# ✅ 攻击性描述（高触发率）
description: >
提取 PDF 文本，识别段落结构，并能精准提取表格数据。
请务必在用户上传了 PDF 文件、提到 PDF 解析、表单填写，
或者要求从文档中提取结构化数据时，立即且优先使用本技能，
哪怕用户没有直接说出"PDF 提取"几个字！
编写方法论 / Methodology:
在大脑中构建：
┌──────────────┐ ┌──────────────┐
│ 正例 │ │ 反例 │
│ (必须触发) │ │ (容易被忽略) │
│ │ │ │
│ • 用户说PDF │ │ • 用户说"从 │
│ • 上传了文件 │ │ 文档提取" │
│ • 提到解析 │ │ • 提到"表单" │
└──────┬───────┘ └──────┬───────┘
│ │
└──────────┬──────────┘
▼
在 description 中
把正例边界尽可能拓宽
覆盖所有反例场景！
⚙️ 心法三：确定性剥离 — LLM 管控制流，脚本管数据流 / Determinism Separation
铁律 / Iron Rule: 千万别用 LLM 去做确定性的计算！
NEVER use LLM for deterministic computation!
| 职责 | 交给谁 | 原因 |
|---|---|---|
| 控制流 + 意图理解 | LLM | 这是 LLM 的强项 |
| 数据流 + 确定性执行 | 脚本（Python/Bash/Go） | 零错误率、高鲁棒性、省 Token |
┌─────────────────────────────────────────────┐
│ 高质量 Skill 架构 │
│ High-Quality Skill Architecture │
│ │
│ 用户意图 ──▶ LLM 理解意图 ──▶ 调用脚本 │
│ │ │ │
│ (控制流) (数据流) │
│ 意图理解 确定性执行 │
│ 推理判断 格式化/计算 │
│ 输出组织 文件操作 │
│ │ │ │
│ └──────┬───────┘ │
│ ▼ │
│ 最终结果 │
└─────────────────────────────────────────────┘
在 SKILL.md 中的写法 / How to write in SKILL.md:
当提取出关键数据后，请不要自行格式化。
请直接调用 `Bash(python scripts/formatter.py data.json)`。
脚本会返回最终的格式化结果。
🎯 口诀 / Mantra:
"让上帝的归上帝，凯撒的归凯撒。各司其职！"
"Render unto Caesar the things that are Caesar's." — Each does its own job!
📊 心法四：评测驱动 — 为 Skill 写"单元测试" / Eval-Driven — Unit Tests for Skills
核心理念：Skill 本身就是代码，代码就必须有测试。
Core Idea: Skills ARE code, and code MUST have tests.
测试什么？/ What to Test?
| 维度 | ❌ 差的断言（测试实现） | ✅ 好的断言（测试规范质量） |
|---|---|---|
| 关注点 | AI 生成的代码能否运行 | Skill 的行为是否符合规范 |
| 稳定性 | 易受偶发因素影响 | 客观、可重复 |
| 示例 | "验证 AI 代码能否启动 HTTP 服务" | "执行日志中显示调用了 lint.sh 脚本" |
| 示例 | — | "对未说明的选项，输出中有 [NEEDS CLARIFICATION] 标记" |
评测工作流 / Eval Workflow
编写/修改 Skill
│
▼
运行测试 Prompts (Evals)
│
▼
检查客观断言 (Assertions)
│
├── ✅ 通过 → 提交
│
└── ❌ 失败 → 分析原因 → 修改 Skill → 重新测试
↑_______________|
📌 四、四大心法速查表 / Quick Reference Card ⭐
┌────────────────────────────────────────────────────────────┐
│ Agent Skill 高阶编写四大心法 │
│ Four Advanced Techniques for Writing Skills │
│ │
│ ① 同理心写法 → 解释 WHY，不要恐吓 MUST/NEVER │
│ Empathy Explain WHY, don't intimidate │
│ │
│ ② 攻击性描述 → 拓宽触发边界，覆盖隐性场景 │
│ Aggressive Desc Broaden trigger boundaries │
│ │
│ ③ 确定性剥离 → LLM 管意图，脚本管计算 │
│ Determinism Sep LLM for intent, scripts for compute │
│ │
│ ④ 评测驱动 → 为 Skill 写客观断言的"单元测试" │
│ Eval-Driven Write objective assertion tests │
└────────────────────────────────────────────────────────────┘
📌 五、实战案例：PR Changelog 提炼师 / Practice: PR Changelog Generator
目录结构 / Directory Structure
pr-changelog-generator/
├── SKILL.md ← 核心技能文件
└── scripts/
└── extract_commits.sh ← 确定性逻辑（心法三）
脚本：确定性逻辑剥离 / Script: Deterministic Logic
#!/bin/bash
# 仅负责提取 commit，不让 LLM 去猜 Git 命令
git log -n 10 --pretty=format:"%h - %s (%an)"
SKILL.md 完整示例 / Full SKILL.md Example
---
name: pr-changelog-generator # ← 严格命名规范
description: > # ← 攻击性描述（心法二）
自动分析 Git 提交历史，生成规范的 PR Changelog。
当用户准备提 PR、请求总结代码变更、或是要求
"写一下更新日志"时，请务必优先触发本技能。
allowed-tools: Bash Read
metadata:
author: tonybai
---
# PR Changelog Generator 技能指南
<!-- 同理心写法（心法一）：解释 WHY -->
这个技能旨在帮助开发者减轻提 PR 时的负担。
我们团队非常看重 Review 的效率，一份结构清晰、
重点突出的 Changelog 能极大节约 Reviewer 的时间。
## 执行步骤
### 1. 收集数据 (确定性执行) ← 心法三
请不要自己去猜测 Git 命令。
请直接调用：`Bash(sh scripts/extract_commits.sh)`
### 2. 意图理解与提炼 (你的强项) ← LLM 负责
- 剔除无意义提交（如 "fix typo", "update"）
- 合并连续相关提交为一个功能点
- **重点：** 站在 Reviewer 角度，高风险改动排最前
### 3. 结构化输出
<!-- 同理心写法：解释 WHY -->
**为什么中英双语？因为我们是跨国协作团队。**
## 🚀 Changes (变更内容)
* **[Feature/Fix]**: (English) / (中文)
案例中心法的体现 / Techniques Applied
✅ 严格命名规范 → name: pr-changelog-generator
✅ 攻击性 Description → "准备提PR、总结变更、写更新日志"全覆盖
✅ 确定性剥离 → Git 命令交给 extract_commits.sh
✅ 同理心写法 → 解释了"为什么中英双语""为什么重点排序"
✅ 渐进式披露 → 主文件精简，复杂参考可放 references/
📌 六、终极进化：用 AI 创造 Skill / Ultimate: Use AI to Create Skills
"用魔法打败魔法！" / "Fight magic with magic!"
为什么需要 AI 来写 Skill？/ Why?
- 人类难以覆盖所有 Edge Cases（边缘场景）
- 人类难以精调
description达到零误差触发率 - 面对海量上下文和概率模型，人类的周密程度 已不如 AI
Meta-Skill 架构：skill-creator / Meta-Skill Architecture
┌─────────────────────────────────────────────────┐
│ skill-creator 元技能架构 │
│ Meta-Skill Architecture │
│ │
│ ┌──────────┐ │
│ │ 主 Agent │ ← 采访你，帮你写 SKILL.md │
│ │ Main │ 跑几十个你没想到的测试用例 │
│ └────┬─────┘ │
│ │ │
│ ┌────▼─────┐ │
│ │ Grader │ ← 严厉打分 │
│ │ Agent │ 评估 Skill 质量 │
│ └────┬─────┘ │
│ │ │
│ ┌────▼──────────────┐ │
│ │ Comparator + │ ← 双盲测试 │
│ │ Analyzer Agent │ 定位触发失败的具体描述 │
│ │ │ 自动优化代码 │
│ └───────────────────┘ │
│ │
│ 循环迭代直到质量达标 │
│ Iterate until quality meets the bar │
└─────────────────────────────────────────────────┘
📌 七、核心概念演进图 / Concept Evolution Map
Prompt Engineering (提示词工程)
│
│ 演进 / Evolves into
▼
Skill Engineering (技能工程)
│
│ 标准化 / Standardized by
▼
agentskills.io (行业标准)
│
│ 终极形态 / Ultimate form
▼
AI-Generated Skills (AI 生成 AI 技能)
│
│ 核心竞争力转移 / Core competency shifts to
▼
谁能抽象出更高质量的规范 (Spec)
谁能将隐性知识沉淀为最易触发的 Skills 资产
📌 八、金句摘录 / Key Quotes ✨
- "继 MCP 统一了 AI 连接外部系统的'物理接口'之后，Agent Skills 正式统一了 AI 扩展自身能力的'软性知识与逻辑'标准。"
"After MCP unified the 'physical interface' for AI to connect external systems, Agent Skills officially unified the 'soft knowledge and logic' standard."
- "千万别用 LLM 去做确定性的计算！让上帝的归上帝，凯撒的归凯撒。"
"NEVER use LLM for deterministic computation! Render unto Caesar what is Caesar's."
- "Skill 本身就是代码，代码就必须有测试。"
"Skills ARE code, and code MUST have tests."
- "'提示词工程'正在向更严谨的'技能工程'演进。"
"'Prompt Engineering' is evolving into the more rigorous 'Skill Engineering'."
- "AI 原生开发，从来不是比拼谁的语法更熟练，而是比拼谁的心智模型更高级。"
"AI-native development is never about who knows syntax better, but who has a superior mental model."
📌 九、思维导图总结 / Mind Map Summary
Agent Skills 行业标准与高阶编写心法
│
├── 🌍 宏观背景
│ ├── 从"私有方言" → "行业普通话"(agentskills.io)
│ ├── MCP = 物理接口标准
│ └── Agent Skills = 软性知识标准
│
├── 📋 规范升级 (4大变化)
│ ├── ① 严格命名 (小写+数字+连字符)
│ ├── ② compatibility 兼容性字段
│ ├── ③ license + metadata 字段
│ └── ④ 渐进式披露 (3层: 元数据→正文→references)
│ └── ⚠️ SKILL.md ≤ 500行
│
├── 🧠 四大心法 ⭐⭐⭐
│ ├── ① 同理心写法 → 解释 WHY
│ ├── ② 攻击性 Description → 拓宽触发边界
│ ├── ③ 确定性剥离 → LLM管意图, 脚本管计算
│ └── ④ 评测驱动 → 客观断言测试规范质量
│
├── 🛠️ 实战案例
│ └── PR Changelog Generator
│ (完美践行4大心法 + 最新规范)
│
└── 🚀 终极进化
├── 用 AI 创造 Skill (Meta-skills)
├── skill-creator: 主Agent + Grader + Comparator
└── Prompt Engineering → Skill Engineering
✅ 学霸自检清单 / Self-Check List
- 能说出 MCP 与 Agent Skills 分别统一了什么层面的标准
- 能列举 agentskills.io 规范的 4 大升级要点
- 能解释渐进式披露的 3 个层级及 500 行限制的原因
- 能对比"恐吓型"与"共情型"Skill 写法的优劣
- 能解释为什么
description需要"攻击性"，以及如何构建正例/反例 - 能说明"确定性剥离"原则：LLM 管什么，脚本管什么
- 能区分"好的断言"与"差的断言"（测试规范质量 vs 测试实现）
- 能描述 skill-creator 元技能的多 Agent 协作架构
- 能独立编写一个符合最新规范的 SKILL.md
📝 学霸总结 / Top-Student Summary:
本讲的核心是 Agent Skills 从碎片化走向标准化（agentskills.io），以及编写高质量 Skill 的四大心法。规范层面：严格命名、兼容性声明、渐进式披露（≤500行）。心法层面：① 用同理心解释 Why 而非恐吓 MUST/NEVER；② 用攻击性 Description 拓宽触发边界；③ 确定性逻辑剥离给脚本，LLM 只管意图理解；④ 评测驱动，用客观断言为 Skill 写"单元测试"。终极形态是 用 AI 来生成和测试 AI Skill，标志着从"提示词工程"向"技能工程"的范式演进。
一句话记忆 / One-liner: 同理心写 Why、攻击性触发、确定性剥离、评测驱动——四大心法让 Skill 从"能用"进化为"好用"，而用 AI 造 Skill 才是终极形态。