1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | ruff-recursive-fix-github-awesome-copilot |
| 作者/维护者 | GitHub(github/awesome-copilot 合集);该技能由社区贡献者 MarcelloCuoghi 于 2026-03-27 提交并合并(PR #1183) |
| 来源链接 | https://github.com/github/awesome-copilot/tree/main/skills/ruff-recursive-fix |
| 许可证 | MIT(合集仓库,GitHub API) |
| GitHub Stars / Forks | 合集整体 39,825 / 5,084(GitHub API);该数字属整个合集,不代表本技能自身热度 |
| 技能自身热度 | skills.sh 安装量约 1.5K(站内搜索接口与详情页) |
| 最新版本 | 无独立版本号;技能文件最近一次提交 2026-03-27 |
| 安装方式 | npx skills add https://github.com/github/awesome-copilot --skill ruff-recursive-fix |
2. 功能介绍与亮点
这是一个单文件 skill(SKILL.md 约 6 KB),让 agent 用 Ruff 以“检查 → 修复 → 复核 → 再检查”的循环清理 Python 代码告警:
- 自动选择 Ruff 调用方式:按
uv run ruff、ruff、python -m ruff、pipx run ruff的顺序探测,全流程沿用同一前缀。 - 作用域与规则可调:可只处理某个目录,也可临时覆盖
--select/--ignore/--extend-select/--extend-ignore,默认沿用pyproject.toml。 - 先安全后不安全修复:先跑
--fix,仍有告警再跑--fix --unsafe-fixes(可关闭),每一轮都要求审阅 diff 并执行ruff format。 - 有明确的停止条件:检查干净、剩余项需要架构决策、已带理由抑制、或循环无进展时停下,并列出选项让用户选。
- 对
# noqa有约束:只允许窄范围、带规则号、带理由的抑制;存在多种合理做法时必须先问用户。 - 固定的结束汇报格式:迭代次数、已修复项、手动修复、抑制清单及理由、剩余问题。
3. 适用场景
分类:工程效率与代码质量。
- 接手一个 Ruff 告警成堆的 Python 项目,想让 agent 分批、可审阅地清理
- 给项目新启用一组 Ruff 规则后,批量消化存量告警
- 在 CI 失败于 Ruff 检查时,让 agent 按固定流程修到通过
受益人群:写 Python 的初中级开发者,以及希望把“跑 ruff、看 diff、再跑”这套手工循环交给 agent 的维护者。
4. 跨 Agent 兼容性
| Agent | 结论 | 依据 |
|---|---|---|
| Claude Code | 原生支持 | 标准 SKILL.md(name + description 前置信息),放入 skills 目录即可;需要本机能执行 Ruff |
| Codex | 需适配 | 同为 Agent Skills 格式,需手动引用或放入其 skills 路径;Ruff 需在其沙箱内可用 |
| OpenClaw | 未验证 | 未找到官方兼容说明 |
| Hermes Agent | 未验证 | 未找到官方兼容说明 |
5. 推荐理由
Ruff 自带的 --fix 只能一次性执行,真正耗时的是之后的人工环节:判断哪些 unsafe 修复会改变行为、哪些告警该抑制、什么时候该停下来问人。这个 skill 把这些判断写成了固定流程和停止条件,让 agent 的清理过程可审阅、可复现,不会悄悄加一堆 # noqa 了事。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | skills.sh 安装量约 1.5K;出自 GitHub 官方合集;暂无针对该技能的具名第三方评价 |
| 可用性 | 7 | 一条命令安装、MIT、流程与输出格式写得清楚;但需要本机已有 Ruff 并能执行命令,无脚本与示例项目,最近更新为 2026-03 |
| 安全性 | 9 | 纯提示词,无自带脚本、无联网、无凭据;仅指挥 agent 执行 Ruff 与格式化命令,unsafe 修复需审阅 diff 并向用户标注;skills.sh 上 Gen Agent Trust Hub、Socket、Snyk 三项审计均为 PASS |
安全检查清单:①会让 agent 执行 ruff check/format 与 --fix --unsafe-fixes,范围限于用户指定目录,修改后要求审阅 diff ②无外联 ③无凭据 ④未发现可疑指令 ⑤GitHub 官方合集 ⑥MIT ⑦合集仓库近日仍有提交。
7. 跟同类 Skills 相比的优势
| 方案 | 定位 | 差异 |
|---|---|---|
| 本 skill | Ruff 告警的迭代清理流程 | 专注“修到干净”这一件事,含 unsafe 修复审阅、noqa 约束与停止条件 |
| Trail of Bits 的 modern-python | 现代 Python 项目工具链规范(uv、ruff、ty 等) | 范围更宽,偏项目搭建与约定,不提供逐轮修复循环 |
直接运行 ruff check --fix |
Ruff 自带命令 | 一次执行、速度最快,但不替你审阅 unsafe 修复或决定抑制 |
| pre-commit 里的 ruff hook | 提交时自动检查与修复 | 适合防止新增告警,不适合批量消化存量 |
8. 用户评价
该技能目前在第三方平台尚无具名用户评价。
9. 其他补充
技能目录下只有 SKILL.md 一个文件,末尾附有四条提示词范例,可直接照抄使用。
10. 安装使用方式
- 确认项目环境里已有 Ruff(
uv add --dev ruff或pip install ruff) - 执行
npx skills add https://github.com/github/awesome-copilot --skill ruff-recursive-fix - 对 agent 说:“对 src/models 运行 ruff-recursive-fix,添加 noqa 前先问我”
- 安装后新开会话即可生效
11. 注意事项
--unsafe-fixes可能改变代码行为,建议在干净的 git 工作区使用,便于回退- 流程默认开启 unsafe 修复,不想动行为敏感代码时需在提示里明确关闭
- 只适用于 Python 项目,且依赖 Ruff 本身的规则覆盖