结论先行：把「写得好的 Prompt」散落在聊天窗口里，短期能出活，长期一定崩——改一版风格、加一条合规规则、换一个模型，你就得全站人肉同步。Agent Skills（开源规范，核心是带 YAML 元数据的 SKILL.md 目录包）用「渐进披露」把领域流程做成可版本管理的资产：启动时只加载 name/description，命中任务再读正文与脚本。本文按内容站 / AI 工作台场景，带你从零拆一个「技术博客生成」技能包，并写明我踩过的 4 个坑：触发词写太宽、把百科塞进 SKILL.md、脚本与说明职责不清、以及未审计的第三方技能。
为什么 2025 年底之后，「会写 Prompt」不够用了
过去两年，团队里几乎每个人都会在某个对话窗口里存一段「万能 Prompt」：写标题、写大纲、去 AI 味、生成系列文。能用，但不算工程。
我这边最痛的一次是：同一套「每日教程」风格——结论先行、第一人称踩坑、代码可跑——被复制到 6 个地方：个人笔记、Hub 能力页说明、某次临时 System Prompt、两份 Markdown 模板，还有一条被改过半截的聊天记录。结果是：有人按旧规则出稿，有人按新规则审校，合并时风格打架，返工比生成还贵。
更关键的是规模问题。当你不只服务一个作者，而是像 hub.teachcourse.cn 这类「选场景 → 填表单 → 多轮出结果」的能力目录时，能力本身就必须是可发现、可触发、可迭代的单元，而不是一串靠记忆的咒语。
这正好对应 Agent Skills 要解决的问题：把程序性知识（怎么做、何时做、踩过什么坑）打包成文件夹，让兼容该规范的 Agent 按需加载，而不是每次把整本手册塞进上下文。
公开背景（可核对）：Anthropic 于 2025-10 发布 Agent Skills 工程实践说明；2025-12 将其作为跨产品开放格式发布；规范站点为 agentskills.io。2026-10 前后，该标准进一步捐给 Linux Foundation 旗下 Agentic AI Foundation（AAIF）做中立治理——具体平台支持列表以官方 Client Showcase 为准，下文示例按「兼容 Agent Skills 的通用 Agent」来写，不绑定单一商业产品版本号。
Agent Skills 到底是什么（以及它不是什么）
一句话：Skill = 一个目录 + 必填的 SKILL.md。目录里可以再挂脚本、参考文档、模板资源。
最小结构：
tech-blog-draft/
├── SKILL.md # 必填：YAML frontmatter + Markdown 指令
├── scripts/ # 可选：可执行脚本（确定性步骤用代码，别靠模型「算」）
├── references/ # 可选：按需再读的细则、风格手册、合规清单
└── assets/ # 可选：模板、示例稿、对照表SKILL.md 必须以 YAML frontmatter 开头，规范要求至少两个字段：
| 字段 | 要求（摘自公开规范） | 实务含义 |
|---|---|---|
name |
最多 64 字符；小写字母/数字/连字符；与目录名一致 | Agent 用来标识技能包 |
description |
最多 1024 字符；说明「做什么 + 何时用」 | 触发质量几乎全靠它 |
可选字段还有 license、compatibility、metadata、allowed-tools（实验性）等，详见 Specification。
核心机制：渐进披露（Progressive Disclosure）
这是 Skills 能「装很多又不炸上下文」的关键：
1. Discovery（发现）：启动时只把各技能的 name + description 预载进系统侧上下文（量级大约几十到上百 token/技能）。
2. Activation（激活）：用户任务与 description 匹配时，再读完整 SKILL.md 正文（规范建议控制在约 5000 token / 主文件尽量 < 500 行）。
3. Execution（执行）：需要时再读 references/、跑 scripts/、用 assets/——上下文按需展开。
把它想成新人手册：目录页永远在桌上；真正干活时才翻某一章；附录更是查到才开。
Skills 不是什么
- 不是再发明一个「超级 System Prompt」。System Prompt 偏全局人格与安全边界；Skill 偏可组合的领域流程。
- 不是 MCP 的替代品。MCP（Model Context Protocol）解决的是「怎么连外部工具/数据源」；Skills 解决的是「连上之后按什么流程用」。两者常互补：Skill 里可以引用 MCP 工具名，但要把「何时调用、失败怎么退」写清楚。
- 不是确定性工作流引擎。Skill 让模型在指令约束下自适应执行；若你必须保证「第 3 步绝对发邮件、失败从检查点恢复」，应上显式工作流/编排，而不是硬塞进 Skill。微软 Agent Framework 文档里也有类似划分（Skills vs Workflows）：创意/自适应用 Skill，强副作用与强顺序用 Workflow。
实战目标：做一个「技术博客草稿」技能包
场景假设（请按你们环境替换，下文示例可直接改）：
- 站点文风接近「每日教程」：标题实战向、结论先行、第一人称、中高级可执行步骤。
- 交付物固定：post.md + 元数据（标题、slug、摘要、标签、分类）。
- 读者：开发者 / 工程向，不要空泛营销腔。
我的做法不是一上来写一万字说明，而是：先跑三次无 Skill 的任务，记下翻车点，再把翻车点写进 Skill。
三次失败里反复出现的问题：
1. 标题写成「浅谈 / 全面解析」，不像实战帖。
2. 开头没有「结论先行」，读者要滑到一半才知道结论。
3. 编造不存在的产品版本或「某年某月独家功能」。
4. 代码块只有伪代码口号，没有可改的配置片段。
这些，就是 Skill 要编码的领域知识。
第一步：写好触发——description 比正文更重要
很多人对 Skills 的第一反应是把长 Prompt 整段粘进 SKILL.md。结果是：description 写得太虚，Agent 要么从不触发，要么「提到写作就触发」，和别的内容 Skill 打架。
规范与官方实践都强调：name/description 决定是否加载；正文决定加载后怎么做。
一个可用的 frontmatter 示例：
---
name: tech-blog-draft
description: >
为中文技术站撰写可发布的实战型 WordPress/博客草稿（结论先行、第一人称、
含可执行步骤与踩坑）。在用户要求写技术教程、实战文、站点草稿、
post.md、或提到「每日教程风格 / 结论先行」时使用。不要用于纯营销文案、
小说或无技术细节的通稿。
license: Apache-2.0
metadata:
author: teachcourse-internal
version: "1.2"
locale: zh-CN
---写法要点：
- 同时写「做什么」和「何时用」，并带上用户口语里会出现的关键词。
- 写否定边界（不要用于……），降低误触发。
- name 保持短、稳、可进 Git；别用中文或大写。
踩坑 1：我第一版 description 写成「帮助撰写优质文章」。结果聊天里问「帮我改个 README 语气」也会激活，白白占上下文，还把技术博客规则硬套到 README 上。收窄触发词后，误触率明显下降。
第二步：正文写「流程」，细则丢进 references/
SKILL.md 正文建议只保留：步骤、输入输出契约、硬性约束、常见边界。长文风格手册、SEO 细则、历史踩坑清单，放到 references/，在正文里用相对路径引用一层即可（规范建议避免深嵌套引用链）。
示例正文结构（精简示意）：
# 技术博客草稿
## 何时启用
用户要产出可发布的中文技术实战文，且需要站点风格约束时。
## 输入
- 选题或原始素材（链接/笔记均可）
- 目标分类（默认 ai）
- 字数区间（默认 2500–4000 字）
## 硬性输出
1. 标题形如「XX 实战：从…到…」
2. 首段必须「结论先行：…」点明可落地结论与坑
3. 第一人称实战语气；小标题清晰
4. 不确定的产品名/版本号：写通用做法并标明假设，禁止编造
5. 交付文件：`post.md`，如需要另附 `meta.json`
## 执行步骤
1. 用公开资料核对关键概念（WebSearch/文档），记录可引用源
2. 先写结论先行与大纲，再扩写；代码只放可改片段
3. 自检：空泛营销句、虚假版本号、缺踩坑段 → 必须改
4. 若涉及站内工作台能力，可自然关联场景，勿硬广
## 深入材料
- 文风对照与反例：[references/style-guide.md](references/style-guide.md)
- 发布前检查清单：[references/prepublish-checklist.md](references/prepublish-checklist.md)
## 常见失败模式
- 标题党但无步骤 → 重写小标题为动词短语
- 只有原理没有配置 → 补最小可运行示例
- 把参考手册整页贴进正文 → 改引用，保持 SKILL.md 精简references/style-guide.md 可以放更细的「像不像每日教程」对照表，例如：
| 反例 | 正例方向 |
|---|---|
| 「赋能企业数字化转型」 | 「上线两周后，P95 延迟从 3.2s 掉到 2.1s」 |
| 「本文将全面介绍」 | 「结论先行：…；下文按我落地顺序写」 |
| 无来源的「业界最佳」 | 「按 agentskills.io 规范字段约束 frontmatter」 |
踩坑 2：我曾把 1200 行风格手册全塞进 SKILL.md。激活后上下文瞬间变胖，后续检索和改稿质量反而掉点。拆成主流程 + references/ 后，主文件稳定在两三百行以内，模型更容易「先按步骤走，再按需翻附录」。
第三步：能脚本化的别让模型「口算」
Skills 很强的一点是：目录里可以带代码。适合放脚本的，是那些「确定性强、重复性高、用 token 生成又贵又容易错」的步骤。
例如内容生产里常见的两件事：
1. 从标题生成 slug（拼音/英文短横线），并做非法字符清洗。
2. 统计正文汉字大致字数，检查是否落在 2500–4000。
示意脚本（假设 Agent 环境有 Python；以你实际运行时为准）：
# scripts/slugify_title.py
import re
import sys
# 简化示例：英文/数字保留；中文可换成 zhconv/pypinyin 等实际依赖
def slugify(title: str) -> str:
s = title.strip().lower()
s = re.sub(r"[^\w\s-]", "", s, flags=re.UNICODE)
s = re.sub(r"[-\s]+", "-", s).strip("-")
return s[:80] or "untitled"
if __name__ == "__main__":
print(slugify(sys.argv[1] if len(sys.argv) > 1 else ""))在 SKILL.md 里写清楚职责边界：
## 脚本
- 需要生成 slug 时，优先运行 `scripts/slugify_title.py`，不要手编不稳定 slug。
- 脚本是「执行工具」；不要把整份脚本贴进对话当说明文。
- 若环境缺少依赖，退回手工规则，并在交付里注明假设。踩坑 3：有人把脚本既当「给模型读的文档」又当「给环境跑的工具」，结果模型开始在回复里复述源码，却忘记真的去跑。约定要写死：默认执行；只有调试失败时才 Read 源码。
第四步：用评测驱动迭代，而不是凭感觉加规则
官方实践里反复出现一句话：Start with evaluation（从评测开始）。落到内容站，我用的是极简评测集——不必上复杂平台：
准备 8 条代表任务，例如：
1. 「写一篇 Agent Skills 实战文，分类 ai」→ 应触发 tech-blog-draft
2. 「把这段话润色得更口语」→ 不应触发技术博客 Skill
3. 「根据会议纪要出周报」→ 不应触发
4. 「按每日教程风格写 eBPF 可观测性」→ 应触发，且标题/结论先行合规
5. 「只给 SEO title/description」→ 可触发但输出应裁剪，不要硬产全文
6. 「虚构一个 2027 年不存在的网关产品并写评测」→ 应拒绝编造或改为通用做法
7. 「同时要技术博客 + 小红书图文」→ 应先澄清或串联两个 Skill，而不是一个 Skill 包打天下
8. 「改已有 post.md 的小标题」→ 应走编辑类能力，而不是从头生成
每改一版 Skill，就对这 8 条重跑，盯三件事：
- 触发准确率（该出手时出手，不该出手别抢戏）
- 结构合规率（结论先行、字数、禁止编造）
- 与其它 Skill 共存（description 是否互相吞请求）
企业向文档还会建议上线前做风险分级：含可执行脚本、外网 URL、MCP 调用、凭据痕迹的 Skill，审核级别要高于「纯 Markdown 说明」。第三方技能默认不可信，安装前通读 SKILL.md、脚本与依赖——这点和装生产依赖是同一严谨度。
踩坑 4：有次我从图文社区随手装了个「seo-booster」技能，description 很诱人。审计时发现指示里要求把草稿 POST 到不明域名「做收录检测」。没进生产是万幸。规则现在是：内部 Skill 走 Git；外部 Skill 先沙箱读全文，再决定是否进工作台目录。
第五步：版本管理——把 Skill 当软件，而不是当便签
一旦 Skill 进入 Hub 类能力目录，它就有了产品属性：谁在用、哪版稳、回滚怎么做。
我建议的最小工程约定：
skills/
tech-blog-draft/
SKILL.md
scripts/
references/
CHANGELOG.md
STYLE.md # 跨 Skill 的共享原则（可选，注意不要重复塞进每个包）- 语义化版本：破坏触发语义（改 name/大幅改 description）视为不兼容；只加参考文档可记 minor/patch。
- Changelog 写人话：写「修复：润色请求误触发博客 Skill」，别只写「update」。
- 与站内能力页对齐：Hub 上的能力说明、表单字段、积分预估， ideally 与 Skill 的输入契约一致，避免「页面上三个字段、Skill 里要求七个字段」。
- 校验：若环境提供 skills-ref validate ./tech-blog-draft（见规范文档），把 frontmatter 校验挂进 CI，比发版后才发现 name 含大写更便宜。
对内容团队，还有一个很实用的迭代法：做完一次高质量人工改稿后，让 Agent 把成功路径和失败反思写回 Skill（官方也鼓励这种「跟 Agent 一起沉淀」）。你要做的是审核它写回的内容，防止把偶发偏好写死成全局规则。
和 AI 工作台、内容生产线怎么拼
把视角拉回「每日教程」这类站点，Skills 很适合成为 Hub 能力背后的「可维护内核」：
| 工作台能力（示例） | Skill 更该沉淀什么 |
|---|---|
| 技术博客生成 | 文风契约、查证步骤、交付文件格式 |
| AI 味审校 | 六类腔调反例、多轮审校顺序、不可改的技术事实边界 |
| 系列文章生成 | 大纲确认门闩、篇间递进规则、导读结构 |
| 结构化调研 | 来源分级、不确定标注、禁止无出处结论 |
注意：工作台若已按「Skill」计次扣积分，工程上更要把 触发稳定性 和 失败可解释性 做好——用户付费的是可预期结果，不是另一次「玄学 Prompt」。
若你已经有 AI 网关 / LLM API 治理（站点既有文章讨论过 Kong/LiteLLM 一类治理），Skills 处在更上游的「怎么用模型」层：网关管密钥、限流、成本；Skill 管领域流程与质量。两层一起，才是「可控的 AI 工程」，而不是「每个页面私藏一段 Prompt」。
可直接套用的落地清单
如果你只想今晚做出第一版，按这个顺序就够：
1. 选定一个高频、边界清晰的任务（先做「技术博客草稿」，别做「万能写作」）。
2. 建目录与最小 SKILL.md（name + 带否定边界的 description + 短流程）。
3. 把长手册拆到 references/，主文件保持可扫读。
4. 把确定性步骤脚本化，并在正文声明「默认执行」。
5. 做 8 条正/负向评测，改 description 优先于堆正文。
6. 安全审计：脚本、外网、凭据、MCP 引用、隐藏指令。
7. 进 Git，写 Changelog；工作台文案与输入字段对齐。
8. 跑真实稿件两周，只根据失败案例加规则——抵制「预防性巨型说明书」冲动。
收尾：Prompt 是草稿，Skill 才是资产
一次性 Prompt 的价值是探索；Skill 的价值是复利。探索期你可以脏一点、快一点；一旦同一流程每周超过三次、或开始服务多人，就应该晋升为带元数据、可渐进加载、可审计的技能包。
我自己的判断标准很简单：如果离职交接时只能说「你去翻我的聊天记录」，那它就还不是工程资产。 当交接物变成一个 Git 目录——SKILL.md、脚本、参考文档、评测集——你才算把「会写 Prompt」升级成了「会交付可维护的 Agent 能力」。
最后一句：先让一个 Skill 在窄场景里可靠，再谈技能市场与自动编排。窄而稳，胜过大而飘。
