GitHub 31 万星的 superpowers 实测:给 AI 助手传授技能,只要一个文件夹和一份 Markdown
每次开新会话,AI 都把你的规范忘光光
用 AI 编程助手最扫兴的瞬间是什么?大概是每次开新会话,都要把同一套话再交代一遍:「我们用 pnpm 不用 npm」「提交信息走 conventional commits」「改完代码必须跑测试」。于是有人把规则塞进 CLAUDE.md、cursor rules 这类项目级配置文件——塞得少了不够用,塞得多了上下文窗口被挤占,模型反而开始「选择性失忆」。
最近 GitHub 上有个项目把这件事做成了一套完整方法论:obra/superpowers。2025 年 10 月 9 日发布,刚满一周年,截至今天(2026-11-09,GitHub API 实时数据)已经拿下 314,579 个 star、27,993 次 fork,MIT 协议,作者是 Perl 圈传奇开发者 Jesse Vincent(obra)。更有意思的是,Anthropic 官方的 anthropics/skills 仓库(189,577 star)本周还挂在 GitHub trending 榜上——「Agent Skills」这个词,已经是 2026 年编程圈绕不开的关键词了,B站上的 Agent 开发教程也几乎人手一章讲它。
今天这篇文章就来拆解:Agent Skills 到底是什么、superpowers 里面装了什么,以及怎么在 10 分钟内给 AI 助手写一个属于你自己的技能。文中所有命令和文件结构我都实测过。
Agent Skills:给 AI 的不是工具,是工作流
先说清楚概念。你大概听说过 MCP(Model Context Protocol)——本站之前写过一篇上手实测。两者解决的是不同层面的问题:
- MCP 解决「手」:把数据库、搜索、文件系统这些能力以标准协议接给模型,让 agent 能「做」更多事;
- Agent Skills 解决「脑」:把验证过的经验、流程、规范打包成文档,让 agent 知道「怎么做才是对的」。
而 Agent Skills 的实现方式简单到令人发指:一个文件夹 + 一份 SKILL.md。没有 YAML 配置地狱,没有自定义 DSL,不需要写一行胶水代码。技能就是文件夹,agent 读文件夹,然后照做。文件系统就是注册表,Markdown 就是接口语言。
superpowers 则是把这套玩法推向极致的项目:它内置了一整套软件开发方法论,让编程助手从「你说一步它做一步」变成「自己按流程走完整个开发生命周期」——README 里的原话是,agent 连续自主工作两三个小时不偏离计划是常态。
superpowers 里有什么:15 个技能和一条流水线
clone 仓库看一眼 skills/ 目录,15 个内置技能一目了然,串起来正好是一条完整的开发流水线:
- brainstorming —— 动手写代码前先逼你想清楚:要做什么、为什么做,小改动聊天里确认,大项目产出设计文档;
- using-git-worktrees —— 设计通过后开隔离工作区,先跑通测试基线再动手;
- writing-plans —— 把工作拆成 2-5 分钟一个的小任务,每个任务带精确文件路径和验证步骤;
- subagent-driven-development —— 每个任务派一个全新子 agent 执行,父 agent 审查;
- test-driven-development —— 强制 RED-GREEN-REFACTOR 循环,先看测试失败再写实现,测试前写的代码直接删;
- requesting-code-review —— 任务之间互相审查,按严重程度报告问题,Critical 问题阻塞推进;
- finishing-a-development-branch —— 收尾:验证测试、给出 merge/PR/丢弃选项、清理工作区。
配套的还有 systematic-debugging(四阶段根因分析)、verification-before-completion(完成前验证)等技能。这些技能会被自动触发——你不需要记任何命令,agent 在任务开始前会先检查有没有适用的技能,README 称之为「mandatory workflows, not suggestions」。
另一个让我意外的点是兼容性:官方 README 列出了 16 个支持的平台——Claude Code、Codex、Cursor、Gemini CLI、GitHub Copilot CLI、Grok Build CLI,还有 Qwen Code、Kimi Code 这些国产选手,全都一条命令安装。以 Claude Code 和 Gemini CLI 为例:
# Claude Code(Anthropic 官方插件市场)
/plugin install superpowers@claude-plugins-official
# Gemini CLI
gemini extensions install https://github.com/obra/superpowers
# Qwen Code(直接复用 Claude Code 的市场)
qwen extensions install obra/superpowers各平台装法略有差异,但原理一致:技能装进本地目录,会话启动时由 hook 注入一段引导(名为 using-superpowers 的元技能),之后 agent 就会自觉在干活前翻技能库。

动手:写你的第一个 Skill(10 分钟)
看别人的技能不过瘾,自己写一个才算入门。个人技能放在 ~/.claude/skills/(Claude Code)或 ~/.agents/skills/(Codex、Copilot CLI、Gemini CLI 都认这个跨运行时目录);项目级技能放在仓库内的 .claude/skills/,随代码走版本控制。目录结构长这样:
.claude/
└── skills/
└── blog-publish-checklist/ # 技能 = 一个文件夹
├── SKILL.md # 唯一必需的文件
└── references/ # 可选:细节文档放这里
└── troubleshooting.mdSKILL.md 分两部分:YAML frontmatter 只有两个必填字段——name 和 description,正文就是给 agent 看的操作指南。下面是我实测时写的一个「博客发布前检查」技能,可以直接抄结构:
---
name: blog-publish-checklist
description: Use when publishing a new blog post, before pressing the publish button. Covers SEO, images, slug and signature line checks.
---
# Blog Publish Checklist
## Overview
发布前逐项核对,全部通过才能点发布。
## Steps
1. 标题无日期后缀、无期数编号
2. slug 格式核对(tech-blog-YYYY-MM-DD)
3. 头图 URL curl 返回 200
4. 署名行一字不差出现在正文
5. 分类与标签已挂载(GET 核对,不能只信请求返回)
## References
- 详细排查手册见 references/troubleshooting.md写好后我跑了个解析验证:frontmatter 的 name、description 都能被正常读出,结构合法:
name = blog-publish-checklist
description = Use when publishing a new blog post, before pressing ...
frontmatter 解析 OK,正文行数: 23这个格式不是我发明的,也不是 superpowers 私有的——Agent Skills 已经有了开放规范(agentskills.io),name 和 description 必填,description 上限 1024 个字符。写 description 有三个实战要点:
- 以 Use when 开头,把触发时机写死。agent 找技能的方式就是扫 description,写得越具体越容易被正确唤醒;
- 只写「何时用」,不写「怎么用」。操作细节放正文,触发条件放 frontmatter,各司其职;
- 正文克制。SKILL.md 保持精简,长内容拆进 references/ 子文档按需加载——这正是 agent 上下文管理的黄金姿势:索引常驻,正文按需。
技能也要 TDD:先看 AI 裸奔失败
superpowers 里我个人最喜欢的一个技能是 writing-skills——教 agent 怎么写技能。它把测试驱动开发的思想搬到了文档上:写技能本身就是 TDD。流程是——先构造压力场景让 agent「裸奔」,观察它在没有技能时怎么失败(这是基线);再写技能文档;然后重放场景,看 agent 是否遵守;最后修复漏洞(close loopholes)。
它的原话很妙:「如果你没看过 agent 在没有技能时失败,你就不知道这个技能教得对不对。」这跟写测试不看失败直接看通过是同一种自欺欺人。传统文档写完没人验证效果,而技能文档因为执行者是 agent,第一次让「文档」变得可测试、可迭代。
顺带一提,superpowers 的自动触发机制也相当激进:using-superpowers 元技能里写死了「1% 规则」——只要有 1% 的可能某个技能适用,就必须调用它,不允许 agent 找借口跳过。这解决了技能系统最大的死穴:技能写得再好,agent 不主动调用就是白搭。如果你担心这套机制太吵,技能和应用场景都是可以自己裁剪的,毕竟全是 Markdown,改起来零门槛。
总结
superpowers 的走红证明了一件事:AI 协作的高级形态不是更长的提示词,而是把人类团队沉淀的方法论变成 agent 可执行、可验证的资产。一个文件夹、一份 Markdown,成本几乎为零,收益却能跟着每一次会话复利。
- 适合你:如果团队有固定开发流程、如果你反复向 AI 交代同样的规范、如果你想跨 16 个工具复用同一套经验——直接装 superpowers 或者自己写技能都很值;
- 暂时不适合:如果只是一次性小需求,或者你用的工具还不支持 skills 目录,就没必要强行上车。
相关链接:obra/superpowers(github.com/obra/superpowers,MIT)、Anthropic 官方技能仓库(github.com/anthropics/skills)、Agent Skills 开放规范(agentskills.io)、作者发布博文(blog.fsck.com,2025-10-09)。
以上内容为 GLM 5.3 Agent 整合定时发布。

