GitSkills: A Dataset of Agent Skills on GitHub 精读

论文链接：arxiv.org/abs/2608.10906 发表时间：2026年8月（arXiv v1: 2026-08-11，cs.SE；MSR ‘27） 发表机构：伦敦大学学院（UCL）+ 霍恩海姆大学（斯图加特）+ 卡利亚里大学 数据集：Zenodo（SQLite） ｜ HuggingFace（Parquet） ｜ 样例仓库 领域标签：软件仓库挖掘（MSR）、LLM Agent、Agent Skills、数据集、软件工件

一、论文背景

1.1 Agent Skill 是什么：给智能体的"岗位操作手册"

一个 agent skill（智能体技能）是一个包含 SKILL.md 文件的文件夹，SKILL.md 里写着给语言模型智能体的操作指令，旁边可以附带脚本和参考文件。当智能体判断当前任务与技能描述匹配时，就自行加载这份技能。打个比方：如果说工具（tools）是智能体的"手"，那么技能就是智能体的"岗位操作手册"——新员工不需要重新培训，把手册放进抽屉，遇到对应场景自己翻出来照着做。

从结构上看（论文 Figure 2 给出了 Anthropic 官方 web-artifacts-builder 技能的原文开头）：SKILL.md 文件顶部是 YAML front matter，携带 name 和 description——这是智能体决定"要不要翻开这本手册"的唯一匹配依据；其后的 Markdown 正文则是具体的分步指令，常常引用文件夹里捆绑的可执行脚本（例如 scripts/init-artifact.sh）。

这个格式由 Anthropic 于 2025 年 10 月推出并作为开放规范发布（Apache-2.0 协议），任何智能体工具都可以支持该格式；Claude Code 是参考实现，.claude/skills/ 目录是其工具特定约定。（背景补充） 开放规范加上 Claude Code 的巨大装机量，使这一格式在 GitHub 上迅速形成大规模生态——技能靠复制文件夹在仓库间传播，没有 npm、没有 PyPI、没有编译器校验。

1.2 为什么技能是 SE 研究者没见过的"新物种"

论文开篇就点出了技能与传统软件工件的三个本质差异：

1. 主要用自然语言书写——不是代码，传统静态分析工具无从下手；
2. 由模型在运行时概率性选择——没有编译器或类型检查器验证"这次选对技能了吗"，描述模糊可能根本不被选中，指令含糊可能导致执行不完整却不报任何显式错误；
3. 没有中央注册表或包管理器——复用靠把文件夹从一个仓库复制到另一个仓库。

这三条合在一起意味着：开发者如何编写、复用、维护技能，是一个纯粹的实证问题——而此前没有任何数据集记录过这个种群。

1.3 软件供应链视角：无版本管理的复制传播

（背景补充） 传统软件供应链安全建立在"包管理器 + 版本锁定 + 签名/校验"的基础设施上。技能生态把这些全绕开了：一个技能从 A 仓库复制到 B 仓库，没有版本号、没有依赖声明、没有更新通知，B 仓库的主人甚至可能永远不知道 A 仓库的技能已经修复了某个危险指令。论文在研究问题部分直接把"被修改的广泛复用技能副本是否引入了原件中没有的命令执行或网络访问"称为**“无注册表生态中供应链攻击的类似物”**。这不是危言耸听——技能可以指示智能体运行命令、访问外部资源、执行捆绑脚本，而它们在仓库间被复制时没有经过任何正式审查。

1.4 为什么需要一个数据集

到 2026 年 7 月，GitHub 公开仓库里的技能文件已达数百万级，但生态爆发九个月来无人系统记录。生态正在形成惯例的关键窗口期（惯例与工具都还在发展中）一旦错过，后人就无法回答"一个新软件工件是如何传播的、通用实践如何涌现、这个格式会不会发展成跨工具的共享基础设施"。GitSkills 就是对这个窗口期的系统性快照。

二、论文定位与关联工作

2.1 软件仓库挖掘的数据集谱系

MSR（Mining Software Repositories）社区有构建大规模数据集的深厚传统，论文有意识地把 GitSkills 放进这条谱系：

2.2 与技能优化研究的分野

技能相关研究大多在"优化"侧：如何写好一个技能、如何让技能更省 token、如何自动生成技能。这些工作共同的前提是——你得先有技能可优化。GitSkills 回答的是更基础的问题：这个生态里到底有什么。两者是"林业学"与"一棵树的园艺学"的关系。没有生态级数据集，优化研究的对象选择本身就带有幸存者偏差。

2.3 采集方法论上的定位

论文引用了第一作者 Destefanis 自己的前置工作《Authoring Agent Skills: A Software-Engineering Approach》（arXiv:2607.25032）——即"怎么写技能"；GitSkills 则是"生态里实际有什么"的实证基座。在数据工程层面，论文的核心贡献是把"对抗搜索 API 限制做完整采集"的工程实践（详见第四节）沉淀为可复用的管线。

三、问题定义

3.1 抽象问题：给"无形生态"做人口普查

把论文的工作抽象化，它回答的是：如何对一个无包管理器、无编译器校验、纯自然语言书写、靠复制传播的工件生态，做一次系统性快照？

这个问题对传统 SE 数据集构建是陌生的：代码数据集可以信任构建工具校验工件"成立"，包生态有注册表可枚举，而技能生态连"总共有多少技能"都无法从 API 直接得知。快照必须同时满足三个看似互相牵制的要求：完整（不能只采到方便采的）、可追踪（谁复制了谁要能看清）、有上下文（孤立的一个 md 文件研究价值有限）。

3.2 三个子问题

子问题一：完整采集——如何绕过搜索 API 的硬限制。 GitHub 代码搜索 API 每个查询最多返回 1,000 条结果，且其 total_count 总数估计被证明不可靠——文件名查询只报约 34.9 万条，而最终实际取回 380 万+ 文件，相差一个数量级。如果直接采，会拿到一个偏差未知的 9% 子样本，且研究者根本无从察觉。

子问题二：去重与传播追踪——如何既压缩存储又保留传播证据。 380 万文件中大量是逐字副本（最终测得 50.5%）。全部全文存储代价高昂且冗余；但若只留唯一内容、丢弃副本，“技能如何传播"这一最有研究价值的问题就永远无法回答。数据集必须同时持有"内容"与"出现"两个层面。

子问题三：富化上下文——给每个技能配上什么才有研究价值。 一个孤立的 SKILL.md 只是一段文本。要支撑采用、复用、维护、安全研究，需要：文本本身、解析后的 front matter、技能文件夹里的捆绑文件、所在仓库的元数据、以及（部分技能的）提交历史。富化 380 万个文件不现实也不必要——给谁做富化、做到什么程度，是一个采样设计问题。

四、问题解法

论文的解法是一条三阶段只读管线：Discovery → Deduplication → Enrichment（论文 Figure 1），每阶段在数据库中保存检查点、支持中断后恢复。所有请求只使用 GitHub REST/GraphQL API、代码搜索 API 和 raw 内容 CDN，不产生任何写入。

4.1 Discovery：按文件大小递归分区，绕过 1000 条上限

原理：代码搜索 API 的 1000 条上限是按"查询"计算的。如果把查询条件切得足够细，让每个子查询的结果都少于 1000 条，上限就形同虚设。文件大小是一个理想的切分维度：查询条件限定"文件大小在区间 [a,b) 内且文件名为 SKILL.md”，若结果超过 1000 条，就把该区间二分递归切下去，直到每个区间都能完整取回。

为什么不信任 total_count：论文实测文件名查询的 total_count 只报约 349,000，与最终取回的 380 万+ 相差十倍。如果依赖官方总数做外推，会严重低估生态规模。分区策略的价值不仅在于绕上限，更在于不依赖任何不可靠的总量估计——每个分区都被取尽，总数是"数出来的"而不是"估出来的"。

诚实处理噪声：搜索还会返回文件名只是包含 SKILL 字样的文件（如 coding-skill.md）以及早于该格式出现的全小写 skill.md。论文选择全部保留，每条记录携带精确文件名、位置分类、front matter 有效性和首次提交日期，把"采用更严格纳入标准"的自由留给后续研究者——采集与解释分离。

位置分类：每个结果按所在路径分类（标准位置 .claude/skills/ 与其他），为后续研究"厂商中立 vs 工具特定位置"的演化提供原始字段。

4.2 Deduplication：内容哈希分组 + 代表选择策略

所有文件按内容哈希分组——相同哈希意味着逐字节相同。每组选择一个代表（representative）做富化，选择时优先 .claude/skills/ 目录下的文件，并用确定性规则打破平局。两个关键设计决策：

• 代表不假定是原件：论文明确说"The representative is not assumed to be the original source"——哪份是源头是研究问题，不是数据集该预设的答案；
• 所有副本全部保留：每个副本都带着仓库、路径、位置分类留在数据集里，使得每种内容的传播范围都可以被直接测量。

4.3 Enrichment：给代表配齐上下文

对每个代表执行五类富化：

1. 全文与 front matter：下载 SKILL.md 全文，解析 YAML front matter（name/description 等字段）；
2. 文件夹内容：记录技能文件夹中捆绑的脚本与参考文档，在大小上限内下载文本文件——技能是否捆绑可执行内容（has_scripts、has_references）逐技能记录，这是供应链安全研究的直接素材；
3. 仓库元数据：owner、star 数、主语言、fork 状态、创建时间、最近推送时间；
4. 提交历史（抽样）：SKILL.md 的首末提交日期、提交数、作者账号（匿名化为用户/机器人标记）——覆盖标准位置的全部技能 + 其余技能的大小分层抽样，共 458,548 条；文件自身的提交历史为技能的加入时间提供断代依据；
5. 匿名化：提交信息中的邮箱（含 GitHub noreply 地址）用固定标记遮蔽并扫描确认无残留；作者账号与人名用带密钥的单向函数替换为稳定代码——不可逆、但同一账号在整个数据集中代码一致，作者身份可追踪而不可识别；机器人账号保留登录名；Co-authored-by 中的 AI 助手名保留（这本身就是"智能体写技能"研究的素材）。

4.4 数据封装：单个自包含 SQLite 文件

五张表、一个文件：

Zenodo 存 SQLite 原件，HuggingFace 提供按表分区的 Parquet 镜像，GitHub 提供样例仓库。采集与解释分离是贯穿封装的设计原则：每次文件名匹配都带着定义分析种群所需的全部属性被保留。

五、评估指标与实验证据

5.1 数据集统计全景

几个数字间的张力很值得玩味：380 万文件对 28 万仓库，平均每仓库约 13.4 个技能文件；28 万仓库对 19.6 万账号，平均每账号约 1.4 个仓库——扩散主要靠"更多人各建少量仓库"而非少数仓库堆满技能。

5.2 50.5% 逐字副本意味着什么

超过半数文件是逐字副本，这是全文最有分量的一个数字。它证明复制是这个生态的主流传播方式，同时暗示了一个分形结构：190 万个"唯一内容"里很可能还藏着大量"改几个字的近副本"（这正是论文提出的克隆谱系研究问题）。对安全研究而言，50.5% 意味着任何一个被广泛复制的技能一旦被恶意修改，其影响面都可能远超单一仓库——论文据此追问：被修改的副本是否引入了原件没有的命令执行或网络访问？

5.3 时间演化证据：提交历史做断代

458,548 条提交历史覆盖标准位置技能 + 其余的大小分层抽样，给出每个技能的首末提交时间。结合 2025 年 10 月格式发布这一时间锚点，月度队列分析可以回答：格式扩散速度、哪些项目先采用、语言与流行度与采用的关系、新写技能的文体是否正在收敛为"公式化模板"（论文特别指出：文体收敛预示一种新文类（genre）的诞生，多样性萎缩也可能反映机器作者比例上升）。

5.4 数据稳定性与边界诚实

7 次挖掘运行全程留痕（mining_runs 表记录每次的查询、时间戳与结果数），管线每阶段 checkpoint 可恢复，过程可审计。更重要的是论文对边界的诚实声明：数据集只覆盖公开仓库，且受 GitHub 代码搜索自身索引规则限制——只索引默认分支、384 KB 以下文件、近期活跃且少于 50 万文件的仓库、fork 仅当星数超过父仓库时收录。因此整个数据集应被读作真实种群的下界（lower bound）。

六、效果优势的根源解释

数据集论文的"优势"不在跑分而在完整性与可复用性。GitSkills 的四个根源：

根源一：分区搜索绕过 API 上限 → 覆盖 380 万+ 而非 34.9 万。 如果信了 total_count，这个领域的基础设施会建立在 9% 的偏差样本上且永不知情。按文件大小递归分区使每个子空间被取尽，总量是数出来的而非估出来的——这是整个数据集可信度的地基。

根源二：保留全量副本 → 传播研究从不可能变为直接可查。 大多数数据集会在去重时丢弃副本以省空间。GitSkills 反其道：文本按哈希只存一份，但每次出现（仓库+路径）全量保留。50.5% 这个数字、复用集中度分析、克隆谱系追踪，全都依赖这个"省存储但不省出现记录"的决策。

根源三：采集与解释分离 → 数据集的生命周期超越任何单一研究议程。 论文不替研究者决定"什么算真技能"——coding-skill.md、小写 skill.md、front matter 无效的文件全保留并打上可过滤标签。数据集因此不会被某个特定纳入标准绑架，后续十种不同的分析种群都能从中定义。加上管线可重跑、检查点可恢复，它是一个可持续更新的生态监测基座而非一次性快照。

根源四：诚实讨论局限 → 下界声明显著提升可信度。 论文不掩饰搜索索引的五种覆盖限制，反而把它们列清并主动给出"下界"解释框架。对数据集论文而言，坦白边界比宣称全覆盖更专业——使用者可以据此推断每类偏差的方向。

七、必要知识反推

要从这篇论文"偷师"，需要补三层知识：

领域层：GitHub API 与软件生态测量。 需要了解代码搜索 API 的行为特性（1000 条上限、total_count 语义、索引覆盖规则：默认分支/384KB/50 万文件/fork 星数规则），以及"API 报告的总数是估计值"这一容易被忽视的陷阱。更广地说，需要对目标平台的可枚举性做工程侦察：注册表类生态（npm/PyPI）可完整枚举，而 GitHub 这种无注册表生态只能靠搜索分区逼近——数据集设计前先回答"这个生态能被完整测量吗"。

方法论层：去重与采样设计。 内容哈希去重是基本功（逐字节相同 = 哈希相同）；真正体现功力的是代表选择策略（优先标准位置 + 确定性平局规则 + 明确不假定代表是原件）与分层抽样（提交历史：标准位置全采 + 其余按大小分层），用最小富化成本覆盖最有代表性的子集。匿名化设计也值得学：带密钥单向函数让"同一账号稳定同码、全程可追踪但不可识别"，兼顾伦理与研究需求。

工程层：大规模只读爬取管线。 三阶段管线、每阶段数据库检查点、中断恢复、运行留痕（mining_runs）、只读原则（对目标平台零副作用）、raw CDN 与 API 的配合——这些是任何大规模采集项目的通用骨架。

融合节点：这篇论文最大的方法论启发是把软件仓库挖掘（MSR）的成熟方法论迁移到自然语言工件。哈希去重来自代码克隆检测，提交断代来自软件演化考古，分层抽样来自实证 SE，供应链分析框架来自依赖研究——工具箱没换，换的是测量对象。自然语言工件生态的测量学，可以大量复用 SE 数十年积累的方法。

八、通用性灵感

灵感一：自然语言工件生态需要自己的"测量学"。 核心思想：当一种新工件类型出现（技能、提示、工作流定义、agent 配置），第一件事不是优化它，而是测量它——人口、分布、传播、演化。论文证据：GitSkills 在格式发布仅九个月即完成 380 万文件快照，抢在惯例固化前建立实证基线。推广场景：MCP 服务器生态、agent 提示词库、开源 workflow YAML——任何正在爆发的新工件类型都值得一张"人口普查表"。

灵感二：复制传播 + 无版本管理 = 供应链风险温床。 核心思想：没有包管理器意味着没有更新通道、没有锁定机制、没有审计入口，修复不传播、篡改不可发现。论文证据：50.5% 逐字副本 + 论文提出的"被修改副本是否引入原件没有的命令执行"研究问题。推广场景：企业内部流转的提示词/技能模板需要"影子注册表"——不改变复制传播的习惯，但提供内容寻址（哈希）与来源追踪能力。

灵感三：API 的自我报告不可信，完整采集要靠分区穷举。 核心思想：平台 API 给的总量估计（total_count）可能是数量级错误的，任何依赖它的采样设计都建立在流沙上；按可枚举维度递归分区直到每个子空间可取尽，才能得到"数出来"的完整集合。论文证据：报 34.9 万 vs 实取 380 万+，相差十倍。推广场景：一切有 per-query 上限的搜索 API（GitHub、邮件归档、应用商店）在做数据采集时都适用此策略。

灵感四：采集与解释分离是数据集长寿的关键设计。 核心思想：数据集构建者不预设"什么算数"，把边界判断的原始字段（精确文件名、位置分类、有效性标记）全量留给使用者，数据集就能服务多个互相冲突的研究议程并支持更严格的再分析。论文证据：noise 文件（coding-skill.md 等）全保留 + 可过滤字段设计。推广场景：任何语料库构建——存"观测"而非"结论"，是数据工程与数据分析的职责分界线。

灵感五：数据集是领域奠基设施，短期看是论文，长期看是基础设施。 核心思想：一个领域从"手工艺研究"走向"系统科学"的标志，是出现一个被共同引用的人口级数据集（如 ImageNet 之于视觉、World of Code 之于 MSR）。GitSkills 的 SQLite 单文件 + Parquet 镜像 + 样例仓库 + 可重跑管线的组合，是按"社区公共设施"标准设计的。推广场景：新领域研究者的入场策略——与其挤进优化赛道的红海，不如为领域构建第一块测量基石，引用与影响会随生态增长复利。

结语

这篇 3 页的 MSR ‘27 短文做了一件"小而重"的事：在 Agent Skill 格式诞生九个月的窗口期，用一套对抗 API 限制的分区搜索管线，为 380 万文件、28 万仓库的生态留下第一份完整快照。它不提出模型、不刷榜单，却定义了后续所有技能生态研究的实证起点——包括那个最让人不安的数字：一半的技能文件是复制品，在无注册表、无版本管理的世界里静静扩散。

本文基于论文全文逐页阅读撰写。