maplibre-skill-authoring

从会话中编写技能

对 maplibre-agent-skills 最有价值的输入，是这样一段会话：Agent 给出了错误的 MapLibre 答案，随后找到了正确答案，并交付了可运行的代码。这段会话保留着任何事后重建都无法恢复的内容：最初那个错误答案。 它是证明确实需要一项技能的证据，而且只会在上下文结束前存在。

这项技能讲的是如何收集这些内容。它不会重述如何贡献——AGENTS.md 中有针对 Agent 的规则，而 CONTRIBUTING.md 中有贡献方式，以及编写新技能的四步流程。交接时请阅读这两份文件；会话结束前请阅读本文，因为之后本文接下来要讲的大部分内容都无法恢复。

何时使用此技能

• 刚完成一项需要深入研究的 MapLibre 任务：查阅文档、源码、CHANGELOG 或问题讨论串
• 最初的做法是错的，或者对 Mapbox GL JS 是对的、对 MapLibre 却是错的
• 发现了文档没有明确说明的版本界限、易错点或故障模式
• 有人要求将这次会话记录为一项技能

先记录，后决定

趁会话还没结束，先把以下四项记在一个临时文件中：

1. 最初的错误答案，逐字记录。 在检查之前，你断言了什么、写了什么，或者本来会写什么。这是基准假设，也是这里唯一无法事后重建的内容——一旦正确答案进入上下文，模型就不会再按要求给出错误答案。只有在没有这项技能时模型会失败，这项技能才有存在的价值；因此，这正是让评测可编写的关键。
2. 你实际打开过的主要来源。 记录 URL，而不是回忆：样式规范页面、GL JS 文档页面、PR 或问题讨论串、CHANGELOG 条目。事后凭记忆重建的引用，只是一个伪装成链接的猜测。
3. 正确结论，用一两句话写明。 写成规则，而不是叙述你做了什么。
4. 版本和最小复现。 使用的是哪个 MapLibre 版本、哪个 SDK（GL JS 和 Native 并不相同），以及能展示该行为的最精简样式或代码。

将结论与项目分开

以上内容都与其来源代码库纠缠在一起。逐条检查：换到别人的项目中，这条内容还成立吗？

• 删除项目名称、文件路径、内部架构和业务逻辑。如果代码示例只有放在你的应用中才有意义，就改写成只需一个空白地图的示例。
• 保留版本界限。“在 X 之前有问题，之后可用”是判断；“它能用”则不是。
• 保留错误答案为何看似合理的原因。这是让技能拦住下一个 Agent 的关键，而且通常与 Mapbox GL JS 的使用习惯或过时的训练数据假设有关。
• 不要泄露任何私密信息。对报告进行匿名化；留下失败案例，不要带上雇主的代码。

编写前先确定规模

一次会话中的失败，只能支撑一项测试和一个章节——通常是在现有技能中新增内容。在认定需要新技能之前，请先查看可用技能和未解决的问题。

只有在该结论无处归属时，才需要新建技能：它既不是已发布技能的子主题，也不应归入任何现有技能。优先新增章节，其次在技能之间添加指引，最后才考虑新建技能。

根据会话编写评测，而不是根据草稿

先将捕获的材料转化为评测，再撰写内容；内容应基于实际发生的事情，而不是你打算说什么：

• 提示词是会话实际开始时的问题，去掉项目名称。
• 评分标准应编码正确的说法（材料 3），措辞应能用于评判陌生人的回答，而不是为了匹配你草稿中的措辞。
• icontains 触发项应是错误答案编造的名称（材料 1），并断言为 not-icontains；同时将真实名称断言为 icontains。如果某次会话虚构了 API 名称，你就有了最精准的触发项。

操作机制、提供方设置和基线运行说明见 evals/README.md。

诚实地交接

你正在起草的是一份提案，而不是经过验证的技能；交接时应明确说明这一点。说明哪些说法已通过一手来源核实，哪些无法核实。如果你无法运行评测——例如没有 API 密钥，或当前不在仓库的克隆副本中工作——请如实说明，不要省略；并将拉取请求及其描述留给将在评审中为其负责的人来撰写。

包含材料 1、2 和 4 的失败报告，本身就是一份完整的贡献。它比没有证据支撑的技能草稿更有价值。

不要

• 不要粘贴会话记录。 会话是素材，不是交付成果。
• 不要引用你没有打开过的来源。 拼凑出来的参考资料，是错误说法自信地蒙混过评审的最常见原因。
• 不要报告你没有运行过的评测结果，也不要编造运行评测所需的 API 密钥。
• 不要把项目特有的怪癖拔高为技能。 如果修复依赖于你的构建环境，那就不属于 MapLibre 的经验判断。
• 不要因为觉得答案显然缺失就跳过基线。 模型可能已经答对了；这个发现是值得报告的结果，不是死胡同。

相关技能

• maplibre-mapbox-migration — 这是一个常见的错误初始答案来源，因为沿用 Mapbox GL JS 的习惯可能会造成误导。

参考资料

• AGENTS.md — 本仓库中 Agent 的指南；也说明如何在仓库外报告失败
• CONTRIBUTING.md — 贡献途径及每种途径的要求
• evals/README.md — 提示词、评分标准、基线检查和提供方设置
• Agent Skills specification — SKILL.md 的约定

---

此技能只是一个快照。 如果一手来源与它相矛盾——包括上面的参考资料、MapLibre 当前文档，或运行 MapLibre 时的实际行为——应以该来源为准。遵循该来源，然后报告这一分歧，并注明来源和你的 MapLibre 版本：修改你安装的副本对其他人毫无帮助，而且会在下次更新时被覆盖。