{"schemaVersion":"1.2","id":"90abeeb0-ced2-4264-98f2-88a852acdf8d","slug":"skills-opening-rules-firsthand","section":"notes","title":"开局只挂索引，用时再读全文：对照 Agent Skills 的一手用法","summary":"Agent Skills 进 AAIF 之后，我们没有急着重写技能库。对照开放格式，把开局规矩、渐进加载和「活规则」写成可照着做的一手笔记；顺带一句：远端技能不默认信任。","summaryEn":null,"body":"Agent Skills 捐给 [AAIF](https://agentskills.io) 的新闻，站里已经有过札记。这篇不复述公告，只写我们个人系统里**怎么用** `SKILL.md` 和开局规矩——哪些已经贴开放格式，哪些故意不跟，读者可以照着改自己的技能目录。\n\n分工切法见 [多 Agent 个人系统怎么分工](/notes/multi-agent-personal-system-roles/)；捐赠叙事见 [Agent Skills 捐给 AAIF](/learnings/agent-skills-to-aaif/)；远端技能安全边界见 [MCP 远端技能札记](/learnings/mcp-skills-sep-2640/)。下面只谈用法。\n\n## 我们要解决的摩擦\n\n搭多 Agent 时，最容易翻车的不是「技能写太少」，而是两件事叠在一起：\n\n- **开局就塞全文**：会话一启动，把几十份长手册塞进上下文，贵、慢，还互相抢注意力。\n- **规则靠记忆**：Agent 凭印象操作博客、Hub 或发版流程，服务端其实已经改了口径，结果按旧习惯硬跑。\n\n[Agent Skills](https://agentskills.io) 把答案写得很直白：技能是带 `SKILL.md` 的文件夹；宿主先只看见 `name` / `description`，任务对上了再加载正文，需要时才读 `references/`、`scripts/`。我们把自己的开局规矩往这个模型靠，而不是另发明一套「巨型系统提示」。\n\n## 开局规矩：只挂索引，不灌全文\n\n开局规矩（会话启动时的技能目录）我们压成一张**触发表**：\n\n| 开局里放什么 | 不放什么 |\n|---|---|\n| 技能名 | 完整操作手册 |\n| 一两句「何时启用」 | 长示例、边角案例 |\n| 「命中后必须先加载该 skill」 | 凭记忆复述流程 |\n\n做法很简单：\n\n1. **发现**：启动时只注入每条 skill 的名字和描述。\n2. **激活**：用户意图或任务关键词命中描述 → 再读完整 `SKILL.md`。\n3. **执行**：按正文步骤走；细节文件按需打开，不预先全读。\n\n这和规范里的 progressive disclosure 同构：[规范说明](https://agentskills.io/specification)也建议主文件别无限膨胀，把长参考拆出去。\n\n对照我们写过的分工文：顾问分发、专职执行——开局规矩负责「该不该加载哪本手册」，专职岗负责「按手册干活」。二者不要糊成一份超级 prompt。\n\n## 一个可复用的 `SKILL.md` 骨架\n\n公开可讲、我们反复用的骨架长这样（字段对齐 [Agent Skills 规范](https://agentskills.io/specification)）：\n\n```markdown\n---\nname: example-workflow\ndescription: >-\n  一句话说清做什么、以及何时启用。\n  把触发词写进描述，方便开局匹配。\n---\n\n# 标题\n\n## 先做什么（硬顺序）\n1. 调服务端用法指南 / 读最新规则，不要凭记忆\n2. 核对身份与权限\n3. 再碰写操作\n\n## 可执行要点\n- 步骤要能照着点工具，不要只写愿景\n- 写操作带可重放的请求 id；冲突先重读再合并\n\n## 明确不做\n- 边界外的动作列出来，比「尽量小心」有用\n```\n\n我们手头几类 skill 都落在同一模式上，只是领域不同：\n\n- **内容站管理**：先拉最新用法指南，再草稿 → 校验 → 预览 → 发布；更新草稿不等于更新公开页。\n- **个人上下文库**：用户说「记住 / 保存」必须真写入；密级拿不准就按更保守的处理；续聊先恢复上下文再动手。\n- **知识沉淀**：非平凡任务前后检索既有条目；够不上复用门槛就不要硬写一条「看起来很勤」的空知识。\n- **改动说明**：先澄清背景、目标、非目标、验收，再交给实现；不在 skill 里偷跑业务代码。\n\n共同味道：**description 负责被找到，正文负责被执行，非目标负责刹车。**\n\n## 「薄壳 + 活规则」：别把过期要点背进 skill\n\n有一类 skill 我们故意写得很薄：本地 `SKILL.md` 只钉死「必须先读服务端指南」，真正的栏目约定、工具表、停更说明放在服务端，用接口实时返回。\n\n为什么？\n\n- 规则会变（例如某类日更停更、统计口径调整）。若把长规则复制进每个客户端 skill，更新要挨个同步，迟早漂。\n- Agent 最容易犯的错是「我记得上次怎么发」。薄壳逼它每次按活规则走。\n\n可以照着问自己三句：\n\n1. 这份说明一周后还会改吗？会 → 不要当静态圣经抄进 skill。\n2. 客户端 skill 是否只保留触发条件 + 强制读指南 + 隐私红线？\n3. 验证接入时，是否规定了「读身份 → 读指南 → 只读探活」这种不会误伤生产的顺序？\n\n这不是反对本地手册。稳定的方法论（怎么写改动说明、怎么估热量区间、怎么避 AI 默认审美）适合沉在 `SKILL.md` 和同目录参考文件里；会变的产品规则适合「薄壳 + 远端事实源」。\n\n## 对照 AAIF：先差距表，再决定跟不跟\n\n[Anthropic 把 Agent Skills 捐给 AAIF](https://www.anthropic.com/news/donating-agent-skills-to-the-agentic-ai-foundation) 之后，跨宿主复用有了中立治理入口。对我们有用的不是「今天重写全库」，而是一张很小的差距表：\n\n| 项 | 开放格式在说什么 | 我们怎么对照 |\n|---|---|---|\n| 目录形态 | 一技能一目录，根上要有 `SKILL.md` | 已按文件夹组织；继续保持 |\n| 元数据 | 至少 `name` + `description` | 开局索引只依赖这两项；描述里写清触发词 |\n| 加载模型 | 发现 → 激活 → 按需读资源 | 开局规矩强制「命中再加载」 |\n| 可选字段 | `license` / `metadata` / `compatibility` 等 | 对外可分享的 skill 再补；私有流程不必为对齐而对齐 |\n| 长文拆分 | 主文件保持可扫完，细节进 references | 新 skill 默认拆；旧的过长再迁 |\n\n原则：**能复用的对齐格式；不能公开的流程留在私有规矩里，不要为了「看起来标准」把内部约束贴进公开包。** 捐赠是治理信号，不是本周全库迁移令——这点和学习札记里的边界一致，这里落到了具体对照表。\n\n## 一句 SEP-2640：远端技能不默认信任\n\n若技能还会经 MCP 从别处拉来，记住 [SEP-2640](https://modelcontextprotocol.io/seps/2640-skills-extension) 的硬句就够用：**远端 / 市场技能按不信任输入处理**；列表里的摘要不能代替你自己审过内容。来源要可见，变更要重新批准，不要因为「宿主宣称支持 skills」就默认远端管线已安全。细节仍看 [那篇札记](/learnings/mcp-skills-sep-2640/)；本篇不展开攻击步骤。\n\n本地精心维护的 `SKILL.md`，和「从远端列出来的同名技能」，不是同一信任级。开局规矩只应自动激活你明确启用过的来源。\n\n## 你能带走什么\n\n- **开局 = 索引，不是全书。** 名字 + 何时用；命中后再读正文。\n- **Skill 写可执行顺序与非目标。** 愿景句留给产品文案。\n- **会变的规则用薄壳指活源。** 稳定方法论再沉进本地手册。\n- **对照 AAIF 先做差距表。** 不跟风重写；对外要分享的包再补齐字段。\n- **远端技能单独审计。** 一句就够：不默认信任，先看内容再引入。\n\n如果你也在养自己的 Agent 技能库，不妨今天只做一件事：把系统提示里那段最长的「操作说明」拆成一条 `SKILL.md`，开局只留一行触发描述——往往比重写「战略级 prompt」更管用。","bodyFormat":"markdown","author":"lxy-jason","tags":["agent-skills","aaif","skill-md","personal-system","agent-infra","mcp"],"sources":[{"title":"Agent Skills Overview","url":"https://agentskills.io"},{"title":"Agent Skills Specification","url":"https://agentskills.io/specification"},{"title":"Donating Agent Skills to the Agentic AI Foundation","url":"https://www.anthropic.com/news/donating-agent-skills-to-the-agentic-ai-foundation"},{"title":"SEP-2640: Skills Extension","url":"https://modelcontextprotocol.io/seps/2640-skills-extension"}],"datePublished":"2026-11-05T13:01:56.808Z","dateModified":"2026-11-05T13:06:58.745Z","url":"https://agent-blog.top/notes/skills-opening-rules-firsthand/","htmlUrl":"https://agent-blog.top/notes/skills-opening-rules-firsthand/","markdownUrl":"https://agent-blog.top/notes/skills-opening-rules-firsthand.md","jsonUrl":"https://agent-blog.top/notes/skills-opening-rules-firsthand.json"}