GitHub 项目转 AI Skill 避坑指南：Agent Skills 规范、工具横评与质量红线

最近这类视频很多：把任意一个 GitHub 仓库丢进去，五分钟吐出一个 AI Skill，以后你说一句话，AI 就按这个项目的用法帮你干活。

听着很爽。但我在把官方规范逐条读完、又翻了几个转换工具的实际产出之后，判断是：这件事能做，但九成人对”转出来的是什么”有误解。

转出来的不是”这个项目的 AI 版”，是一份说明书。说明书能不能用，取决于你补了多少东西。这篇把规范和工具都拆开讲，最后告诉你什么时候值得转、什么时候纯属浪费时间。

一、先说清楚：Skill 到底是个什么文件

很多人以为 Skill 是某种模型微调、某种插件、某种可执行程序。都不是。

一个 Skill 就是一个文件夹，核心只有一个 Markdown 文件。官方规范写得很直白：

skill-name/
├── SKILL.md          # 必需：元数据 + 指令
├── scripts/          # 可选：可执行脚本
├── references/       # 可选：参考文档
└── assets/           # 可选：模板、静态资源

SKILL.md 的结构是「YAML 头 + Markdown 正文」，最简单的可用版本只有六行：

---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
---

（这里写具体怎么用）

就这么点东西。所以”把项目转成 Skill”这件事，本质上是让 AI 读一遍仓库，然后帮你写这份说明书。它不改代码、不训练模型、不生成可执行文件。

二、规范只有三条硬要求，但每条都能卡人

官方 spec 对 frontmatter 的约束是明确的，我挑最容易踩的三条：

① name 必须和父目录名一致，且有字符限制。只能用小写字母、数字、连字符，最长 64 字符，不能以连字符开头或结尾，不能出现连续两个连字符。所以 PDF-Processing 不行（大写），pdf--processing 也不行（连续连字符）。

② description 是触发开关，不是介绍文字。上限 1024 字符，官方要求同时说清两件事：这个技能做什么、什么时候该用它。官方给的正面例子长这样：

description: Extracts text and tables from PDF files, fills PDF
forms, and merges multiple PDFs. Use when working with PDF
documents or when the user mentions PDFs, forms, or document
extraction.

反面例子是一句「Helps with PDFs」。这两种写法的区别在哪？模型是靠 description 判断”这个任务该不该调用这个技能”的。写得含糊，技能就永远躺在目录里没人调；写得准，一句话就能触发。这一栏写得好不好，直接决定技能是活的还是死的。

③ 可选字段别乱填。还有 license、compatibility（最长 500 字符，写环境依赖）、metadata（键值对）、allowed-tools（实验性，各家支持不一）。规范明确说”大多数技能不需要 compatibility 字段”，填了反而增加噪音。

三、真正关键的是那个”渐进式披露”

这一节是全文最该记住的。

官方规范里有个机制叫 progressive disclosure（渐进式披露），意思是技能不是一次性全读进上下文，而是分三层加载：

层级	内容	体量	何时加载
第一层	只有 name 和 description	约 100 tokens	启动时，所有技能全加载
第二层	SKILL.md 正文	建议 5000 tokens 以内	技能被激活时
第三层	scripts / references / assets	按需	真正用到时才读

为什么这个设计重要？因为上下文是有限的。如果你有二十个技能，每个都写五千字，光是”待命”状态就要吃掉两万 token。渐进式披露的意思是：平时只占那 100 tokens 的名字和描述，真触发才加载正文，细枝末节等你真的要用了才读。

规范给了一条硬指标：主 SKILL.md 控制在 500 行以内，超出就拆到 references 里去。

这条直接决定了转换工具的天花板——它们大多只会把 README 塞进 SKILL.md。README 动辄几千字、结构松散、没有”什么时候用”的描述、更没有分层，转出来的东西要么太胖、要么触发不了。这是转换工具质量参差的根本原因，不是模型不够聪明。

再往深一层想：那 100 tokens 是什么？是整个技能系统里唯一”永远在线”的部分。你装二十个技能，启动时占的就是二十条 description。这意味着两件事——

第一，description 的质量直接决定技能能不能被找到。写得含糊，模型在一堆描述里挑不出来，技能等于没装。第二，description 之间还会互相干扰。两个技能都写”处理文档”，模型就会随机选一个，选中错的那个比找不到更麻烦。所以技能多了以后，写 description 的工作量会越来越大，这不是浪费时间，是必要的索引维护。

四、转换工具到底在做什么：四步拆解

不管哪家工具，流程都差不多这四步：

第一步，拉仓库元数据。拿仓库名、owner、默认分支、最新 commit hash、README 全文。有的工具用 git ls-remote，有的直接打 GitHub API，有的还会抓 package.json / pyproject.toml / Makefile 这类清单文件。

第二步，分析结构。看目录树、入口文件、命令行参数、依赖列表、CI 配置。目的是判断”这个项目对外暴露的能力是什么、怎么调用”。

第三步，生成骨架。建目录（SKILL.md + scripts/ + references/），把分析结果填进 SKILL.md，把 README 拆成 references 下的几个文件。有的工具还会塞一个 wrapper.py 模板占位。

第四步，注入溯源信息。把 source_url、source_hash、version 这些写进 metadata。这一步是给”技能版本管理”留钩子——仓库更新了，技能得知道自己是基于哪个 commit 生成的。

四步全是文本处理，没有任何”理解项目精髓”的魔法。所以质量上限就摆在那里：它能把文档搬过来，搬不动经验。

五、目前能用的几个方案

我按 GitHub 上的实际数据核了一遍，说几个有代表性的。先说明：这些项目的 star 数都很小，属于早期玩具阶段，别拿它跟成熟工具比稳定性。

方案一：github-skill-distiller

中文社区里传得比较广的一个，主打”5 分钟蒸馏”。仓库是 Shell 写的，MIT 协议，今年 4 月建仓、6 月后没再更新，目前 6 个 star。

用法是把它当作 Claude Code 的自定义命令：

git clone https://github.com/CN-big-cabbage/github-skill-distiller.git
cd github-skill-distiller
mkdir -p ~/.claude/commands
cp skills/generate-skill.md ~/.claude/commands/generate-skill.md

然后在 Claude Code 里 /generate-skill <仓库地址>。产出是 SKILL.md + 使用指南 + 故障排查 + 配置示例四件套，还带一个百分制质量评分，低于 70 分会尝试自动补两轮。

这个”自评分”的设计思路不错，但要注意：分数是模型自己打的，它觉得 85 分的技能，实际用起来可能根本触发不了。评分只能当参考，不能当验收。

方案二：repo2skill（Hhhkarimi）

TypeScript 写的，MIT，今年 8 月建仓，10 个 star。它最大的差异点是浏览器端运行、不需要任何 API key——分析在本地完成，仓库内容不上传到第三方服务器。对数据敏感的场景（比如公司内部仓库）这点很关键。

npm install -g repo2skill
repo2skill https://github.com/user/repo

它的输出结构比一般工具讲究：除了 SKILL.md，references 下面会分 architecture.md、code-map.md、testing-and-ci.md、implementation-playbook.md，还内置了任务评测（task evals）和正负触发查询。安全模型那块写了一句我觉得很对的话：仓库内容一律当作”不可信证据”，不把 secret 写进技能，破坏性操作（部署、迁移）必须显式确认。

支持 GitHub / GitLab / Gitee，界面有中文。

方案三：skill-factory（echoleesong）

Python 写的，MIT，4 个 star，1 月建仓、6 月后停更。它更像一个”脚手架生成器”：用 git ls-remote 拿 hash、HTTP 拿 README，然后建标准目录、注入 source_url / source_hash / version 这些溯源字段、再生成一个 wrapper.py 模板。

它的定位很清醒——不假装能写出好技能，只保证结构合规。适合你已经想清楚要做什么，只是不想手动建目录的情况。

方案四：你手上可能已经有的那个

如果你用的是 WorkBuddy、Claude Code 这类带技能系统的客户端，它通常自带一个 skill-creator。这类内置工具不”读仓库”，而是跟你对话：问你技能要干什么、怎么触发、边界在哪，然后生成骨架，再做迭代评测。

区别在于：外部转换工具是”仓库 → 文档 → 技能”，内置的 skill-creator 是”人的意图 → 技能”。前者快，后者准。真要做一个长期用的技能，后者才是正路。

这四个方案共同的短板

不管选哪个，都会碰到同样三个问题，提前知道能少走弯路：

一是只读 README。几乎所有的转换工具都从 README 入手，因为它是入口文件、最好抓。但真正详细的用法通常在 docs/ 目录、wiki、或者示例代码里。README 只写了 20% 的信息，转出来的技能也只有 20% 的完整度。

二是不知道你的使用场景。同一个工具，运维用它排查故障，开发用它做本地调试，用法完全不同。转换工具不知道你是哪一类，只能给一份”通用说明”。而通用说明对具体场景往往是没用的。

三是没有实测。生成的技能里那些命令，没有任何工具会真的跑一遍验证。参数拼错了、版本不对了、权限不够了，它都不知道。所以你看完生成的技能，至少把里面的命令手动敲一遍，确认能跑通再用。

六、一个必须说的数据反差

我把几个仓库的 star 数拉出来对比，差距大得有点刺眼：

项目	定位	Star	最后更新
anthropics/skills	官方规范与技能集合	约 18.7 万	2026-10
obra/superpowers	技能框架	约 31 万	2026-11
github-skill-distiller	仓库转技能	6	2026-06
repo2skill（Hhhkarimi）	仓库转技能（浏览器端）	10	2026-08
skill-factory	技能脚手架生成	4	2026-06

技能生态本身很热——官方仓库十几万 star，框架类项目三十万 star，社区天天在讨论怎么写技能。但”把仓库自动转成技能”这一支，最好的也只有十个 star，而且大多几个月没动过。

这个反差说明一件事：大家真正需要的是”怎么写出好技能”，不是”怎么把仓库变成技能”。转换工具解决的是一个伪需求——你手上真有值得封装的仓库，你大概率比 AI 更懂它怎么用；你手上没有，转出来也没用。

七、转完之后，八成要手动补这四件事

如果你还是想试，那就把这几件事准备好。自动生成的技能，这四块基本都得重写。

① 重写 description。把自动生成的”这是一个 XX 项目的技能”删掉，换成”解决什么问题 + 什么场景触发”。判断标准很简单：你自己读一遍，能不能一眼看出什么时候该用它。看不出来就重写。

② 砍掉 README 里的废话。自动生成最常见的毛病是把 README 原样搬进来，里面塞满了”贡献指南””致谢””License””路线图”。这些对 AI 执行任务毫无价值，只占上下文。全部删掉，只留”怎么装、怎么调、参数有哪些”。

③ 补上真实用法示例。这是 AI 最缺的一环。README 通常写”支持 A、B、C 三种模式”，但不会写”我要把 A 和 C 组合起来做某件事，命令该怎么拼”。把你的实际操作写进去，技能才真的能用。

④ 把大段内容拆到 references。主 SKILL.md 控制在 500 行以内，超了就拆。参数表、API 清单、错误码对照这类”查得到但不必常驻”的内容，单独放 references，让 AI 按需读。

这四件事做完，才谈得上”一个能用的技能”。只做第一步生成，那就是个占位的空壳。

补完之后大概长这样

光说原则太虚，给一份完整的对照。假设你要封装公司内部的一个日志工具，转换工具自动生成的那版大概是”这是一个 log-tool 项目的技能，用于处理日志”，然后贴了半屏 README。手动改完应该变成这样：

---
name: log-triage
description: 按时间窗口、错误码、服务名过滤并聚合日志，定位异常首现时间与影响范围。当用户需要排查线上故障、分析报错日志、或询问某段时间的异常情况时使用。
license: Proprietary
metadata:
  source_url: https://github.com/your-org/log-tool
  source_hash: 9f2a1c7
  version: "1.4.0"
---

# 日志排查

## 何时使用
用户提到「报错」「异常」「挂了」「查下日志」「定位故障」时触发。

## 标准流程
1. 确认时间窗口，默认最近 1 小时，用户没说就按默认
2. 按服务名缩小范围，不知道服务名就先跑一次全量聚合
3. 按错误码聚合，取 Top 5
4. 查每个错误码的首次出现时间，这是判断影响起点的关键

## 常用命令
    logtool grep --since 1h --service api --level error
    logtool agg --by code --top 5
    logtool first-seen --code E5023

## 边界
- 只覆盖 app-* 服务，中间件日志在 mid-log 技能里
- 超过 7 天的日志已归档，需先申请解档
- 错误码含义见 references/error-codes.md

对比一下差别在哪：自动生成的那版通篇在说”这个项目是什么”，改完之后通篇在说”什么时候用它、按什么顺序做、哪里会踩空”。前者是产品介绍，后者是操作手册。AI 需要的是后者。

还有一点：上面这份只有三十几行，远低于 500 行的上限。但它的信息密度比自动生成的两千字高得多——每一行都是决策依据，没有一句废话。

八、什么项目值得转，什么一定白费

按我自己的判断，直接给结论。

值得转的：

• 命令行工具类。像 fzf、httpie、lazydocker 这种，用法是”一串参数”，文档齐全，转换效果最好。AI 学完就能帮你拼命令。
• 有稳定 API 的框架。FastAPI 这类，接口固定、文档规范，转出来能当查询手册用。
• 公司内部工具。价值最大——因为外部 AI 不知道它怎么用，你把用法沉淀成技能，团队里谁都能调。
• 你自己的项目。你比谁都清楚边界和坑，转完补几句就能用。

不值得转的：

• 纯代码库、没有使用文档的。AI 只能从源码猜用法，猜出来的东西不敢信。
• 大型框架（几万行以上）。五千 token 装不下，硬塞进去全是噪音。这类应该做的是”按功能切成多个技能”，而不是一锅端。
• 读一遍就懂的小工具。转技能的时间比你自己记下来还长。
• 文档里全是截图、没有文字的。AI 读不到图里的信息，转出来是空的。

如果拿不准，问自己三个问题，全答得上来才值得动：

1. 这个工具的用法，你自己能一口气说清楚吗？说不清说明你对它还不够熟，转出来你也判断不了对错。先去用熟，再谈封装。
2. 你希望 AI 帮你做的，是”记得命令”还是”判断该用哪条命令”？前者转换工具能给你，后者只有你自己写进去。
3. 这个项目半年后还会用吗？半年就淘汰的工具，做完技能的收益还不够抵消维护成本。

九、六个坑，踩过就知道

坑一：把 README 当文档。README 是给”要不要用这个项目”的人看的，不是给”已经决定用它”的人看的。里面一半是营销、一半是贡献指南，真正的用法可能藏在 docs 目录或者 wiki 里。转换工具只抓 README，天生残缺。

坑二：忽略版本漂移。技能生成时基于某个 commit，仓库一升级，命令参数变了，技能还在教旧用法。这是自动生成技能最大的长期风险。生成时把 source_hash 记进 metadata，定期核对，是最低成本的防御。

坑三：description 写名字不写场景。「用于操作 Docker」这种描述，AI 判断不了该不该触发。要写成「管理 Docker 容器与镜像，在用户需要查看容器状态、清理镜像、排查启动失败时使用」。

坑四：脚本直接抄仓库里的。有的工具会把仓库里的脚本抄进 scripts/。这些脚本可能带硬编码路径、需要特定依赖、甚至有破坏性操作。抄进来的脚本一定要逐个看一遍，别让 AI 拿着一把没保险的枪。

坑五：一个技能装下整个项目。违背渐进式披露的设计。正确做法是按任务切：一个技能管”安装配置”，一个管”日常操作”，一个管”故障排查”，各自控制在五百行内。

坑六：不验证触发。技能做完了，从来没测过”说一句话能不能触发它”。这是最常见也最致命的疏漏——技能写得再好，触发不了等于不存在。至少准备五个真实句子试一遍，看它是否被正确调用。

十、常见问题

Q1：转换需要 API key 吗？

看工具。github-skill-distiller 走的是 Claude Code 的自定义命令，用你客户端本身的额度；repo2skill 是浏览器端本地分析，不需要任何 key；skill-factory 只用 git 和 HTTP 抓元数据，也不需要。但”分析 README 生成内容”这一步要模型参与，本地跑就吃你自己的算力或额度。

Q2：转出来的技能能直接用吗？

能跑，但大概率不好用。它更像一份”初稿”，需要你按第七节补四件事。指望它开箱即用，通常会失望。

Q3：支持私有仓库吗？

浏览器端工具（如 repo2skill）主打公开仓库，因为要从前端直接拉数据，没法带凭证。私有仓库得用本地跑的方案，配 token 或者直接读本地 clone 的目录。

Q4：技能和 MCP 有什么区别？

MCP 是”给 AI 装一个能调用的服务接口”，技能是”给 AI 一份操作手册”。前者扩能力边界，后者补领域知识。同一个需求，用 MCP 是让 AI 能执行命令，用技能是让 AI 知道命令该怎么拼。两者不冲突，很多场景要一起用。

Q5：一个项目应该拆几个技能？

按”任务”拆，不按”模块”拆。判断标准：如果一个技能的 description 需要写”以及”，那多半该拆成两个。

Q6：怎么验证技能写得对不对？

官方提供了校验工具，能检查 frontmatter 是否符合规范（name 格式、description 长度这些）。但格式合规只是及格线，真正的验收是”给五个真实句子，看它能不能正确触发、触发后输出的东西对不对”。这一步没有工具能替你做。

Q7：技能应该放在哪个目录？

不同客户端不一样，但规则相通：全局目录放常用技能，项目目录放这个项目专用的技能。以 Claude Code 为例，项目内的技能放 .claude/skills/，全局的放 ~/.claude/skills/，项目内的优先级更高。WorkBuddy 的全局目录是 ~/.workbuddy/skills/。

有个坑要注意：目录名必须和 frontmatter 里的 name 完全一致，规范写明的。你从别处拷过来一个技能目录，改了个名字，模型就找不到它了——因为它按 name 去找目录。这个错误没有任何报错提示，只能靠手动核对。

十一、结语

回到开头那个问题：五分钟把 GitHub 项目转成 Skill，值不值得试。

我的判断是：值得试，但别把它当终点。

这类工具真正的价值不在”省时间”，而在帮你把项目的结构梳理一遍。它抓元数据、拆目录、整理参数，这些机械活确实省事。但它替代不了”你到底想让 AI 干什么”这个判断，也替代不了你踩过的那些坑。

更现实的一点是：这些转换工具现在都还是个人项目，六个 star、十个 star 的量级，几个月不更新是常态。用它做一次性的事可以，别把工作流建在上面。

真正值得投入的方向，是把你自己反复做的那件事写成一个技能——不是转别人的仓库，是沉淀自己的方法。仓库会升级、工具会失效，但”这件事该怎么做”是你的，搬不走。

顺带说一句，技能这件事最容易犯的错是”为了做而做”。看到别人分享一个技能仓库，自己也去搭一套，最后装了一堆技能，常用的还是那两个。工具是给具体问题准备的，手头没有问题，就别急着造工具。

如果你手上有正在用的项目，不确定值不值得转成技能，可以在评论区说一句它是干什么的、你想让 AI 帮你做到哪一步，我看到会回。