Agent Skill on VvVzzz Blog

go-modern-guidelines：教 AI Agent 写现代 Go

Wed, 09 Sep 2026 20:30:00 +0800

收录于：开源仓库收藏夹

仓库：github.com/JetBrains/go-modern-guidelines · 许可：Apache-2.0 · 来源：JetBrains 官方项目

它是什么

给编码 Agent 用的现代 Go 写法指南。装上之后，Agent 会：

用 max(a, b) 而不是 if-else 取大
用 slices.Contains 而不是手写循环
用 cmp.Or(a, b, c) 而不是一串 nil 检查
知道 new(42) 取值指针、errors.AsType[T](err) 类型安全错误匹配（Go 1.26）

覆盖 Go 1.0 → 1.27 最有用的特性，包括 Go 官方 modernize analyzer 的全部目标。完整清单在 FEATURES.md。

Agent 行为约定：

从 go.mod 检测项目 Go 版本
只用 ≤ 该版本的语言/标准库特性
优先现代惯用法，而不是老写法

动机写得很准

Agent 生成「过时 Go」几乎必然，原因只有两个：

问题	含义
训练数据滞后	训练截止后加的 API（如 `errors.AsType[T]`）模型根本没见过
频率偏置	见过也不一定用：语料里 `for i := 0; i < n; i++` 远多于 `for i := range n`

指南的解法很直接：给 Agent 一份显式参考，而不是指望模型「自己想起来」。

这也和 Go 团队方向对齐：modernize 负责把旧代码改新，这份指南负责让新代码一开始就新。

形态：小 CLI + 多端插件

不是纯 Markdown 甩给模型——各 market 集成会在首次使用时 go install 一个小 CLI，装进本地缓存（如 ~/.cache/go-modern-guidelines），不改动你的项目。

要求：PATH 上有 Go toolchain，目标 Go 1.25+；更旧版本在 GOTOOLCHAIN=auto（默认）下也能拉兼容 toolchain。

支持面：

客户端	方式
Junie	`/extensions marketplace add JetBrains/go-modern-guidelines`
Claude Code	`/plugin marketplace add` + `modern-go-guidelines@goland-claude-marketplace`
Codex	`codex plugin marketplace add` + `goland-codex-marketplace`
Cursor	`cursor-agent plugin marketplace add …`
其他（OpenCode 等）	`npx skills add JetBrains/go-modern-guidelines`

Claude Code 装完后 Go 任务会自动触发；也可显式 /modern-go-guidelines:use-modern-go。

值得学的两个工程细节

1. 按 go.mod 探测版本
避免 Agent 在 Go 1.21 项目里写出 1.26 才有的 API——这是「知识」和「项目约束」分开的干净做法。

2. 构建脚本与 Agent 隔离
scripts/dev-install.sh 故意和面向 Agent 的 wrapper 分开：Agent 永远不能触发本地构建。本地调试靠 make dev-install + GO_MODERN_GUIDELINES_DEV=1，与 Claude Code / Codex / Cursor 走同一套缓存路径。

上手（Claude Code 示例）

/plugin marketplace add JetBrains/go-modern-guidelines
/plugin install modern-go-guidelines@goland-claude-marketplace

其他客户端安装与更新见仓库 README。

适合谁

用 Agent 写 Go，不想再 review「上古写法」
团队想统一「新项目直接用新惯用法」，而不是事后 modernize 改
在做 language-specific Agent guideline 时，可当范本看：动机、版本门控、多端分发、CLI 与 agent 隔离

和收藏夹里其他项目的关系

同为「给 Agent 的技能/指南」→ pptx-generator（产物向）vs 本文（语言向）
跑在各种 Harness 里 → Pi、Claude Code、Codex 等
指南/技能沉淀与检索 → OpenViking

最后更新：2026-09-09。信息基于公开 README 与仓库状态，使用前请以官方文档为准。

pptx-generator：给编码 Agent 用的 PPT 生成技能

Wed, 09 Sep 2026 20:20:00 +0800

收录于：开源仓库收藏夹

技能路径：MiniMax-AI/skills · pptx-generator
所在仓库：MiniMax-AI/skills · 许可：MIT

它是什么

pptx-generator 是 MiniMax 官方 skills 集合里的一项 Agent Skill，覆盖 PowerPoint 全流程：

任务	做法
读 / 分析现有 PPT	`python -m markitdown presentation.pptx`
基于模板编辑	XML 工作流（见 `references/editing.md`）
从零创建	PptxGenJS，按页面类型生成 slide 模块再编译

它不是「让模型随便画几页」，而是一套有约束的生成规范：设计系统、五类页面、主题契约、页码规则、QA 流程都写死在 skill 里。

为什么值得看

1. 五类页面 + 视觉多样性

所有 slide 必须归入五种类型之一：

Cover 封面
TOC 目录
Section Divider 分节页
Content 内容页
Summary 总结页

并明确要求：不要连续多页用同一 layout——避免 Agent 生成「十页长得一样」的 PPT。

2. Theme 对象契约（强制）

编译脚本向每页传入固定五色主题：

Key	用途
`primary`	最深色，标题
`secondary`	深色强调、正文
`accent`	中间调强调
`light`	浅色强调
`bg`	背景

禁止自创 background / text / muted 等 key。Agent 被死死绑在统一主题模型上，多页并行生成时才不会各画各的。

3. 一页一文件，可并行

每页是独立可运行的 JS：

function createSlide(pres, theme) {
 const slide = pres.addSlide();
 // ...使用 theme.primary / theme.bg 等
 return slide;
}
module.exports = { createSlide, slideConfig };

函数必须同步（不能 async）
文件可单独 node slide-01.js 预览
有 subagent 时最多 5 页并发生成
最后 compile.js 统一写入 output/presentation.pptx

这是「结构化输出 + 模块化并行」在文档生成上的干净落地。

4. 设计系统不是空话

references/ 里拆得很细：

文件	内容
`slide-types.md`	五类页面 + 额外 layout 模式
`design-system.md`	色板、字体、Sharp/Soft/Rounded/Pill 风格配方、排版间距
`editing.md`	模板编辑、XML、常见坑
`pitfalls.md`	QA 流程、PptxGenJS 陷阱
`pptxgenjs.md`	完整 API 参考

中文固定 Microsoft YaHei，英文默认 Arial；16:9（10" × 5.625"）；页码徽章除封面外必有，且只显示当前页码（不是 3/12）。

5. 和「只会改 Markdown 的 Skill」不同

多数 Agent Skill 只动文本。这个 skill 管的是二进制办公文档：生成、改、读，还带 QA 门槛。属于 productivity 类 skill 里工程化程度较高的样本。

上手（Claude Code）

claude plugin marketplace add https://github.com/MiniMax-AI/skills
claude plugin install minimax-skills

依赖：

pip install "markitdown[pptx]" # 读 PPT
npm install -g pptxgenjs # 从零创建

Cursor / Codex / OpenCode 的安装方式见仓库 README。

触发词：PPT、PPTX、PowerPoint、presentation、slide、deck。

同仓库其他技能（顺带一提）

MiniMax skills 里还有同一思路的办公套件：minimax-pdf、minimax-xlsx、minimax-docx，以及前端/全端/移动端/shader 等开发技能。如果你要做「Agent 生成 Office 全家桶」，可以整包接入再按需挑。

适合谁

想让 Claude Code / Codex 直接产出结构稳定、风格统一的 PPT，而不是随机排版
需要「模板编辑 + 从零生成 + 读回分析」三条链路
在研究 Agent Skill 怎么管二进制产物、怎么做多页并行、怎么定 theme 契约

和收藏夹里其他项目的关系

Skill 被 Multica 等平台当作可复用剧本 → Multica
运行这些 Skill 的编码 Agent → Pi、Claude Code 等
Skill 本体的知识/记忆沉淀 → OpenViking

最后更新：2026-09-09。信息基于公开 SKILL.md 与仓库 README，使用前请以官方为准。

从 skill-creator 看 Agent Skill 的 7 个设计原则

Tue, 18 Aug 2026 00:00:00 +0800

Agent Skill 可以理解为一份给智能体使用的领域工作手册：它不仅告诉模型“做什么”，还提供判断原则、操作步骤、参考资料和可重复执行的脚本。

一个 Skill 是否好用，通常不取决于篇幅，而取决于三个问题：模型能否在正确的场景发现它、加载后能否迅速找到需要的信息、遇到新情况时能否做出合理判断。

结合 skill-creator 的组织方式，我把其中最值得复用的思路整理成七条设计原则。

用三层结构实现渐进式加载

Skill 不应该把所有背景知识一次性塞进上下文。更合适的结构是按需逐层加载：

flowchart TD
 A["第一层：name + description
用于发现与路由"] --> B["第二层：SKILL.md
核心流程与判断原则"]
 B --> C["第三层：references / scripts / assets
只在具体任务需要时加载"]

第一层要足够短，让系统能在大量 Skill 中快速判断相关性；第二层包含完成任务所需的主流程；第三层承载较长的文档、模板、示例和确定性工具。

这种分层解决了两个相反的问题：信息太少时模型无法完成工作，信息太多时关键指令又容易被淹没。

一个实用的目录可以是：

my-skill/
├── SKILL.md
├── references/
│ ├── api.md
│ └── style-guide.md
├── scripts/
│ └── validate.py
└── assets/
 └── template.md

SKILL.md 负责导航，不必复制所有细节。需要 API 时读 references/api.md，需要校验时运行 scripts/validate.py，需要产物骨架时复用 assets/template.md。

把 description 当作路由规则

很多 Skill 写得很完整，却经常不触发，问题通常出在 description。

description 不是给人看的宣传语，而是智能体判断“此刻是否应该加载这个 Skill”的路由规则。它至少要回答：

这个 Skill 能完成什么任务；
用户会在什么场景下需要它；
哪些相近场景不属于它。

不够有效的写法：

description: Helps with documents.

更清楚的写法：

description: >-
 Create, edit, redline, and review Word documents.
 Use when the user asks to produce or modify a .docx file,
 preserve document styles, or inspect tracked changes.
 Do not use for PDFs or spreadsheets.

前者只提供一个模糊主题，后者给出了能力、触发场景和边界。模型不需要猜“documents”究竟指什么。

与其堆积关键词，不如描述用户真实会提出的请求。关键词覆盖不到表达方式的变化，场景描述更容易表达意图。

解释 Why，给模型留下判断空间

Skill 需要约束，但不能只有 MUST 和 NEVER。当规则背后没有原因时，模型只能机械匹配；一旦遇到作者没写过的场景，它就不知道应该坚持还是变通。

例如：

优先复用现有模板，因为模板已经包含品牌字体、页边距和层级规范。
只有当模板无法表达用户明确要求的版式时，才创建新结构。

这段话同时给出了默认动作、原因和例外条件。模型面对新任务时，仍然可以沿着目标做判断。

原则不等于宽泛口号。好的原则应包含：

想保护的目标；
推荐的默认行为；
允许偏离的条件；
偏离后仍需满足的底线。

同时测试“用了 Skill”和“没用 Skill”

只验证最终答案看起来是否不错，无法证明 Skill 真正带来了价值。更有效的测试是为同一任务保留两组结果：

with_skill：加载 Skill 后执行；
without_skill：不加载 Skill，作为基线。

比较时可以同时使用两类检查：

可程序化断言

适合验证确定性条件，例如：

目标文件是否生成；
front matter 是否包含必填字段；
输出中是否泄露敏感路径；
指定命令是否退出成功；
产物能否通过构建或格式校验。

人工或模型评审

适合评估更主观的质量，例如：

结构是否清楚；
结论是否有足够证据；
是否出现无意义的重复；
风格是否符合目标读者；
面对异常场景时判断是否合理。

如果两组结果没有稳定差异，说明 Skill 可能只是增加了上下文，并没有真正改变决策或产物质量。

防止测试驱动出过拟合规则

测试发现问题后，最直接的反应是再加一条特殊规则。但如果每个失败案例都对应一条补丁，Skill 很快会变成长而脆弱的条件列表。

假设一个图表生成 Skill 在测试中遇到折线重叠。过拟合的修复可能是：

当图表类型是折线图并且系列数大于 4 时，把线高改成 40px。

更具泛化能力的原则是：

为标签和连线预留与内容密度相匹配的空间；
当画布尺寸变化时，优先使用可自适应的间距和最小尺寸。

前者只处理已知测试，后者解释了问题的原因，也能覆盖柱状图、流程图和新的画布尺寸。

每次准备加规则时，可以先问三个问题：

失败背后的共同原因是什么？
这个规则能否覆盖尚未见过的相邻场景？
如果未来删除测试用例，这条规则本身是否仍有价值？

把重复且确定的操作交给脚本

语言模型适合理解意图、做取舍和生成内容，不适合反复手工完成严格、机械的转换。

适合写成脚本的工作包括：

检查目录和必填字段；
批量转换文件格式；
解析稳定的数据结构；
运行构建、测试和静态检查；
对产物执行可重复的安全扫描。

适合留给模型的工作包括：

判断用户真正想解决的问题；
在多个合理方案之间权衡；
根据上下文调整表达和结构；
解释失败原因并提出下一步。

脚本应该小而明确：写清输入、输出、依赖和失败方式。不要把一个新的复杂系统藏进 Skill；否则维护成本只是从提示词转移到了代码。

按领域拆分参考资料，并明确加载条件

当参考资料越来越多，简单地把它们全部放进一个大文件，会破坏渐进式加载的意义。

更好的方式是按领域拆分：

references/
├── authentication.md
├── content-model.md
├── deployment.md
└── troubleshooting.md

然后在 SKILL.md 中明确路由：

- 认证、授权或 token 问题：读取 `references/authentication.md`
- 数据结构和字段约束：读取 `references/content-model.md`
- 发布与回滚：读取 `references/deployment.md`
- 常见失败和恢复步骤：读取 `references/troubleshooting.md`

文件名应该表达内容，加载条件应该可以由任务直接判断。避免让模型为了找到一条信息，先遍历整个 references 目录。

七条原则之间不是彼此独立的技巧，而是共同围绕“发现、执行、验证、维护”构成一套设计方法：

mindmap
 root((Agent Skill))
 容易发现
 渐进式加载
 description 路由
 能够判断
 解释 Why
 保留例外条件
 可以验证
 with skill
 without skill
 防止测试过拟合
 稳定执行
 确定操作脚本化
 便于维护
 参考资料按领域拆分
 明确加载条件

一张表总结

原则	解决的问题	落地方式
渐进式加载	上下文过载	元数据、主流程、资源分层
description 路由	Skill 漏触发或误触发	写能力、场景和边界
解释 Why	规则无法适应新情况	给目标、默认行为和例外
对照测试	无法判断 Skill 是否有效	比较 with / without Skill
防止过拟合	规则越来越碎	从失败案例提炼共同原因
脚本化确定性工作	重复操作不稳定	用小脚本完成校验与转换
按领域拆参考资料	找不到真正需要的信息	拆文件并写清加载条件

结语

一个可靠的 Skill 不是越长越好，也不是规则越多越好。它更像一套分层的决策支持系统：入口负责发现，正文负责流程和原则，参考资料负责深度，脚本负责确定性。

写 Skill 时始终围绕三个目标取舍：容易触发、按需加载、能够泛化。 做到这三点，Skill 才能从一次性的提示词，变成可测试、可复用、可维护的能力模块。