如何贡献自己的技能到 kotlin-agent-skills？JetBrains 审核流程与评测（evals）编写完整指南-开发者社区

【免费下载链接】kotlin-agent-skills

A collection of AI agent skills useful for projects using Kotlin language

项目地址：https://gitcode.com/gh_mirrors/ko/kotlin-agent-skills

kotlin-agent-skills 是 JetBrains 官方发起的 AI Agent 技能（AI agent skills）合集仓库，收录专为 Kotlin 语言与 kotlinx 库打造的技能包。本文将带你完整走一遍向 kotlin-agent-skills 贡献自己的 Skill 的全流程：从提交 Issue 申请、通过维护者审核，到编写 SKILL.md 规范格式与 evals 评测文件，一份面向新手的完整贡献指南。

1️⃣ 先搞懂：Skill 在 kotlin-agent-skills 中是什么？

在动手贡献之前，先理解这个仓库的组织方式，能帮你少走很多弯路。

Skill = 一个自包含的文件夹：里面打包了指令、脚本和资源，供 AI 编码代理在特定场景下使用。
每个 Skill 文件夹都包含一个SKILL.md文件：开头是 YAML frontmatter（name和description等字段），后面是代理在技能激活时遵循的操作指导。
技能统一放在 skills/ 目录，仓库结构非常清晰：

kotlin-agent-skills/ ├── skills/ # 所有技能所在地 │ ├── kotlin-backend-jpa-entity-mapping/ │ ├── kotlin-tooling-agp9-migration/ │ └── ... ├── plugins/ # 插件市场清单（Claude Code / Codex 分发） ├── CATEGORIES # 权威分类清单 ├── CONTRIBUTING.md # 贡献指南（核心文件，必读！） └── README.md

📌 仓库的"宪法"是 CONTRIBUTING.md，本文所有流程都基于它整理。

命名规范：一步定生死

所有技能必须遵循kotlin-<category>-<functional-name>命名规则：

组成部分	规则	示例
`<category>`	必须是 CATEGORIES 中预定义的分类	`backend`、`tooling`
`<functional-name>`	短小、描述性强的 kebab-case 名称	`agp9-migration`
完整名称	组合后作为技能文件夹名	`kotlin-tooling-agp9-migration`

当前已预定义的两个分类：

backend— 服务端开发技能，如 Kotlin 中使用 Spring、JPA 等后端框架的正确姿势；
tooling— 各类工具链相关技能，例如构建工具迁移。

如果你的技能不属于任何现有分类，需要先在 Issue 中提议新增分类，而不是直接建 PR。

2️⃣ 贡献审核流程：先开 Issue，再开 PR

JetBrains 采用"Issue 先行"的审核模式，直接提交 PR 大概率会被拒绝。完整流程如下：

第 1 步：查重 🕵️

提交前先浏览现有技能目录 skills/。如果与已有技能功能重叠，维护者可能会建议你扩展现有技能而不是新建一个。

第 2 步：开 Issue，回答 5 个关键问题

根据 CONTRIBUTING.md 的要求，Issue 中必须提供以下描述：

问题与使用场景：为什么这必须是一个 Skill？
维护计划：你每月能投入多少小时维护它？
依赖风险：技能是否依赖可能使其被废弃的第三方依赖？
可用条件：需要哪些改动才能让技能真正可用？
更新承诺：什么时候应该重新审视/更新它？你能否承诺？

⚠️重要承诺：提交技能即意味着你承诺长期维护。如果你的贡献"过期"（未在新模型上测试、未跟进依赖升级），维护者会先联系你要求更新；若 30 天内没有回复，该技能将被归档（archived）。

另外，仓库原则也明确：不接收引入第三方依赖的技能（知名且广泛使用的库除外）。

第 3 步：获得批准后，按规范提交 PR

维护者会先审核 Issue，讨论范围与重叠问题，决定下一步（新建技能 or 扩展现有技能）。通过初始审批后，才进入 PR 阶段，技能必须符合下述格式与评测要求。

3️⃣ 编写 SKILL.md：通过审核的 frontmatter 模板

PR 阶段的硬性要求是SKILL.md的 YAML frontmatter 必须包含以下字段：

name: description: metadata: author: github:@your-handle version: 0.1.0 tested_models: provider: xxx model: xxx agent_version: xxx last_eval: 2026-06-10

几个容易踩坑的细节：

description 写"何时加载"，不是"做什么"

这是很多新手的误区。仓库明确说明：description 描述的是代理"什么时候"应该加载这个技能，而不是技能做什么或为什么需要它。官方推荐写法（参考 Perplexity Research 的风格指南）：

✅ 以 "Load, when.." 开头
✅ 控制在50 个单词以内
✅ 描述用户的真实意图（来自真实查询）
❌ 不要总结工作流

仓库中的现有技能就是很好的范例，例如 skills/kotlin-tooling-agp9-migration/SKILL.md 的 description：

Migrates Kotlin Multiplatform (KMP) projects to Android Gradle Plugin 9.0+. … Use when upgrading AGP, when build fails due to KMP+AGP incompatibility, or when the user mentions AGP 9.0…

它以"做什么"开头，但关键落在 "Use when…" 触发条件上——这正是审核者想看到的。

metadata 中的 tested_models 不可省

provider、model、agent_version三项记录你在哪个模型/代理版本上验证过技能，last_eval则是最近一次评测日期。这两个字段直接关系到前面提到的"30 天归档规则"——没有评测记录的技能，过了一段时间就可能被归档。

💡 小技巧：动手前可以参考 Anthropic 的 skill-creator 技能来搭建骨架（CONTRIBUTING.md 中明确建议查阅），并用仓库内已有的成熟技能（如 skills/kotlin-tooling-java-to-kotlin/SKILL.md）作为结构参照。

4️⃣ 编写 evals：技能测试的必备环节

这是贡献流程中最容易被忽视、却最体现专业性的一步。

为什么需要 evals？

为了保证可复现性和可维护性，每个技能必须附带一组评测用例（evals）。评测让维护者能随时回归验证：当底层模型升级或依赖变更时，技能是否依然有效。

评测文件放哪里、写什么？

位置：放在你技能目录下的evals/evals.json中；
内容：提供基础测试用例，包含prompt（输入提示）、expected output（预期输出）、所需文件（如有）以及 assertions（断言）。

一个真实的评测示例可以参考 skills/kotlin-tooling-native-build-performance/evals/EVALUATION.md。该技能采用 A/B 评测方式：同一个任务分别在"有技能"和"无技能"两种状态下运行代理，再用加权评分标准（reward 0–1）打分：

任务	无技能	有技能	Δ	显著性
合成原生构建审计	0.74 ± 0.05	0.99 ± 0.02	+0.25	p = 0.031
KotlinProject 原生构建审计	0.59 ± 0.05	0.90 ± 0.02	+0.31	p = 0.031

加分项：with/without 对比

官方虽不强制，但强烈建议附上"有技能 vs 无技能"的对比数据（成功率或输出质量差异）。上面的表格就是标准范式——它用数据证明技能真实有效，而不是"感觉上"有用。这类对比数据会极大提升 PR 的通过概率。

5️⃣ 快速贡献检查清单 ✅

提交 PR 前，逐条对照 CONTRIBUTING.md 中的官方检查清单：

✅ 已先开 Issue 并获得维护者批准
✅ 与现有技能无重叠
✅ 技能遵循 Agent Skills 规范
✅ 命名符合kotlin-<category>-<functional-name>，分类正确
✅SKILL.md的 YAML frontmatter 合法：name、description、metadata（author、version、tested_models含 provider/model/agent_version、last_eval）
✅ description 说明"何时加载技能"，且不超过 50 词
✅ 文档清晰、使用场景明确
✅ 无安全漏洞或恶意代码
✅ 已包含evals/evals.json
✅ 列出技能测试过的项目清单（公开的附链接），可选附 with/without 对比数据

6️⃣ 上手操作：获取仓库并开始贡献

仓库是只读镜像场景下你无法直接推送，实际贡献需要在你的工作副本中操作。获取仓库：

git clone https://gitcode.com/gh_mirrors/ko/kotlin-agent-skills cd kotlin-agent-skills

然后按以下顺序推进：

阅读 CONTRIBUTING.md 和 README.md 中的命名规范；
查看 CATEGORIES 确认分类，浏览 skills/ 查重；
开 Issue，回答 5 个关键问题，等待维护者批准；
创建技能文件夹，编写SKILL.md（注意 frontmatter 与 description 规范）；
编写evals/evals.json并跑通评测，尽量准备 A/B 对比数据；
对照第 5 节检查清单逐项确认后，提交 PR。

写在最后

向 kotlin-agent-skills 贡献技能的核心可以浓缩为一句话：先 Issue 后 PR、frontmatter 规范、evals 必备、承诺长期维护。只要你的技能确实解决了 Kotlin 开发中的真实痛点，并且愿意为它的"保鲜"负责，通过 JetBrains 审核并不是难事。祝你的第一个 Skill 早日合入！🎉