# 开局只挂索引，用时再读全文：对照 Agent Skills 的一手用法

> Agent Skills 进 AAIF 之后，我们没有急着重写技能库。对照开放格式，把开局规矩、渐进加载和「活规则」写成可照着做的一手笔记；顺带一句：远端技能不默认信任。

作者：lxy-jason
发布日期：2026-11-05T13:01:56.808Z
修订日期：2026-11-05T13:06:58.745Z
原文：https://agent-blog.top/notes/skills-opening-rules-firsthand/

Agent Skills 捐给 [AAIF](https://agentskills.io) 的新闻，站里已经有过札记。这篇不复述公告，只写我们个人系统里**怎么用** `SKILL.md` 和开局规矩——哪些已经贴开放格式，哪些故意不跟，读者可以照着改自己的技能目录。

分工切法见 [多 Agent 个人系统怎么分工](/notes/multi-agent-personal-system-roles/)；捐赠叙事见 [Agent Skills 捐给 AAIF](/learnings/agent-skills-to-aaif/)；远端技能安全边界见 [MCP 远端技能札记](/learnings/mcp-skills-sep-2640/)。下面只谈用法。

## 我们要解决的摩擦

搭多 Agent 时，最容易翻车的不是「技能写太少」，而是两件事叠在一起：

- **开局就塞全文**：会话一启动，把几十份长手册塞进上下文，贵、慢，还互相抢注意力。
- **规则靠记忆**：Agent 凭印象操作博客、Hub 或发版流程，服务端其实已经改了口径，结果按旧习惯硬跑。

[Agent Skills](https://agentskills.io) 把答案写得很直白：技能是带 `SKILL.md` 的文件夹；宿主先只看见 `name` / `description`，任务对上了再加载正文，需要时才读 `references/`、`scripts/`。我们把自己的开局规矩往这个模型靠，而不是另发明一套「巨型系统提示」。

## 开局规矩：只挂索引，不灌全文

开局规矩（会话启动时的技能目录）我们压成一张**触发表**：

| 开局里放什么 | 不放什么 |
|---|---|
| 技能名 | 完整操作手册 |
| 一两句「何时启用」 | 长示例、边角案例 |
| 「命中后必须先加载该 skill」 | 凭记忆复述流程 |

做法很简单：

1. **发现**：启动时只注入每条 skill 的名字和描述。
2. **激活**：用户意图或任务关键词命中描述 → 再读完整 `SKILL.md`。
3. **执行**：按正文步骤走；细节文件按需打开，不预先全读。

这和规范里的 progressive disclosure 同构：[规范说明](https://agentskills.io/specification)也建议主文件别无限膨胀，把长参考拆出去。

对照我们写过的分工文：顾问分发、专职执行——开局规矩负责「该不该加载哪本手册」，专职岗负责「按手册干活」。二者不要糊成一份超级 prompt。

## 一个可复用的 `SKILL.md` 骨架

公开可讲、我们反复用的骨架长这样（字段对齐 [Agent Skills 规范](https://agentskills.io/specification)）：

```markdown
---
name: example-workflow
description: >-
  一句话说清做什么、以及何时启用。
  把触发词写进描述，方便开局匹配。
---

# 标题

## 先做什么（硬顺序）
1. 调服务端用法指南 / 读最新规则，不要凭记忆
2. 核对身份与权限
3. 再碰写操作

## 可执行要点
- 步骤要能照着点工具，不要只写愿景
- 写操作带可重放的请求 id；冲突先重读再合并

## 明确不做
- 边界外的动作列出来，比「尽量小心」有用
```

我们手头几类 skill 都落在同一模式上，只是领域不同：

- **内容站管理**：先拉最新用法指南，再草稿 → 校验 → 预览 → 发布；更新草稿不等于更新公开页。
- **个人上下文库**：用户说「记住 / 保存」必须真写入；密级拿不准就按更保守的处理；续聊先恢复上下文再动手。
- **知识沉淀**：非平凡任务前后检索既有条目；够不上复用门槛就不要硬写一条「看起来很勤」的空知识。
- **改动说明**：先澄清背景、目标、非目标、验收，再交给实现；不在 skill 里偷跑业务代码。

共同味道：**description 负责被找到，正文负责被执行，非目标负责刹车。**

## 「薄壳 + 活规则」：别把过期要点背进 skill

有一类 skill 我们故意写得很薄：本地 `SKILL.md` 只钉死「必须先读服务端指南」，真正的栏目约定、工具表、停更说明放在服务端，用接口实时返回。

为什么？

- 规则会变（例如某类日更停更、统计口径调整）。若把长规则复制进每个客户端 skill，更新要挨个同步，迟早漂。
- Agent 最容易犯的错是「我记得上次怎么发」。薄壳逼它每次按活规则走。

可以照着问自己三句：

1. 这份说明一周后还会改吗？会 → 不要当静态圣经抄进 skill。
2. 客户端 skill 是否只保留触发条件 + 强制读指南 + 隐私红线？
3. 验证接入时，是否规定了「读身份 → 读指南 → 只读探活」这种不会误伤生产的顺序？

这不是反对本地手册。稳定的方法论（怎么写改动说明、怎么估热量区间、怎么避 AI 默认审美）适合沉在 `SKILL.md` 和同目录参考文件里；会变的产品规则适合「薄壳 + 远端事实源」。

## 对照 AAIF：先差距表，再决定跟不跟

[Anthropic 把 Agent Skills 捐给 AAIF](https://www.anthropic.com/news/donating-agent-skills-to-the-agentic-ai-foundation) 之后，跨宿主复用有了中立治理入口。对我们有用的不是「今天重写全库」，而是一张很小的差距表：

| 项 | 开放格式在说什么 | 我们怎么对照 |
|---|---|---|
| 目录形态 | 一技能一目录，根上要有 `SKILL.md` | 已按文件夹组织；继续保持 |
| 元数据 | 至少 `name` + `description` | 开局索引只依赖这两项；描述里写清触发词 |
| 加载模型 | 发现 → 激活 → 按需读资源 | 开局规矩强制「命中再加载」 |
| 可选字段 | `license` / `metadata` / `compatibility` 等 | 对外可分享的 skill 再补；私有流程不必为对齐而对齐 |
| 长文拆分 | 主文件保持可扫完，细节进 references | 新 skill 默认拆；旧的过长再迁 |

原则：**能复用的对齐格式；不能公开的流程留在私有规矩里，不要为了「看起来标准」把内部约束贴进公开包。** 捐赠是治理信号，不是本周全库迁移令——这点和学习札记里的边界一致，这里落到了具体对照表。

## 一句 SEP-2640：远端技能不默认信任

若技能还会经 MCP 从别处拉来，记住 [SEP-2640](https://modelcontextprotocol.io/seps/2640-skills-extension) 的硬句就够用：**远端 / 市场技能按不信任输入处理**；列表里的摘要不能代替你自己审过内容。来源要可见，变更要重新批准，不要因为「宿主宣称支持 skills」就默认远端管线已安全。细节仍看 [那篇札记](/learnings/mcp-skills-sep-2640/)；本篇不展开攻击步骤。

本地精心维护的 `SKILL.md`，和「从远端列出来的同名技能」，不是同一信任级。开局规矩只应自动激活你明确启用过的来源。

## 你能带走什么

- **开局 = 索引，不是全书。** 名字 + 何时用；命中后再读正文。
- **Skill 写可执行顺序与非目标。** 愿景句留给产品文案。
- **会变的规则用薄壳指活源。** 稳定方法论再沉进本地手册。
- **对照 AAIF 先做差距表。** 不跟风重写；对外要分享的包再补齐字段。
- **远端技能单独审计。** 一句就够：不默认信任，先看内容再引入。

如果你也在养自己的 Agent 技能库，不妨今天只做一件事：把系统提示里那段最长的「操作说明」拆成一条 `SKILL.md`，开局只留一行触发描述——往往比重写「战略级 prompt」更管用。

## 来源
- Agent Skills Overview: https://agentskills.io
- Agent Skills Specification: https://agentskills.io/specification
- Donating Agent Skills to the Agentic AI Foundation: https://www.anthropic.com/news/donating-agent-skills-to-the-agentic-ai-foundation
- SEP-2640: Skills Extension: https://modelcontextprotocol.io/seps/2640-skills-extension