kharmanskyi/open-steps

Plain-language agent skills for Claude Code, Codex, Cursor and Gemini CLI: honest session reports, straight verdicts, steps you can follow. MIT.

Open Steps – Claude Code、Codex、Cursor 和 Gemini 代理的通俗语言“技能”

这是什么

一组可重用的技能（小型提示模板和几个 shell 脚本），可以添加到 Claude Code、Codex CLI、Cursor CLI 或 Gemini CLI 中。
每个技能告诉 LLM 代理如何用通俗、非技术性的语言来组织其输出，以及如何与不是工程师的人类进行结构化交互。
该包还附带两个钩子，在每个代理会话的开始和结束时运行，自动插入路由表，并在完成实际工作后，要求代理生成简洁的“单屏”报告。

主要功能

技能	你得到什么	何时运行
`os‑done‑or‑not`	单屏判定：完成？是/否，任何必需的输入，新的技术债务，可安全关闭标志。	任务完成或你问“我们完成了吗？”时。
`os‑step‑by‑step`	供用户遵循的编号、非技术性说明；代理只要求用户执行它自己无法执行的操作。	当代理需要用户运行命令、点击、批准等时。
`os‑ask‑simple`	通俗语言的问题、预估成本以及单条高亮建议。	当代理面临决策点或需要澄清时。
`os‑what‑could‑go‑wrong`	事前分析：假设决策会失败，逆向推导，最后给出判定。	在承诺不可逆行动之前（合同、迁移、发布）。
`os‑whats‑next`	总结已验证的内容，并用日常语言建议下一个具体任务。	当你问“还剩下什么？”或报告撰写完毕后。
`os‑check‑work`	重新验证先前会话中的声明；报告任何不匹配之处和后续步骤。	当另一个会话声称工作已完成时。
`os‑say‑simple`	将任何文本块（报告、评论、错误）改写为通俗语言，同时保留事实。	当你需要现有文本的不太技术性的版本时。
`os‑big‑picture`	维护一个 `BIG‑PICTURE.md`，列出产品功能、其状态、未使用部分和积压工作；在你批准后可以在你的追踪器中开始工单。	当你询问整体项目状态或需要积压视图时。

工作原理

每个技能位于自己的文件夹中（skills/os-*），包含定义提示的 SKILL.md 和包含实际示例的 references/ 文件夹。
两个钩子（session-start.sh 和 stop-report.sh）是小型 shell 脚本。启动钩子将路由表（告诉代理何时触发每个技能的小型 Markdown 表）和最新报告注入 LLM 的上下文。停止钩子将会话结束时的仓库状态与启动时拍摄的快照进行比较，如果文件变化足够多，则要求代理生成报告。
对于 Claude Code，整个包被打包为插件，可自动连接技能和钩子。对于 Codex CLI、Cursor CLI 和 Gemini CLI，你将技能文件夹复制到 ~/.agents/skills/，并手动将路由块和钩子定义添加到各自的配置文件中。
该包还可以执行自主合并：如果 PR 有绿色检查并且有已批准的审查，代理会再次验证并合并它（使用 gh pr merge 或工具的本地合并命令）。权限通过 Claude Code 插件清单中的 allowed-tools 字段控制。

安装快速入门

git clone https://github.com/kharmanskyi/open-steps.git
Claude Code – claude plugin marketplace add ./open-steps && claude plugin install open-steps@open-steps
- 将路由块添加到 ~/.claude/CLAUDE.md（仓库提供了现成的代码片段）。
其他代理 – 复制技能文件夹：
```
mkdir -p ~/.agents/skills && cp -R open-steps/skills/os-* ~/.agents/skills/
```
- 将路由块插入工具特定的常设指令文件（~/.codex/AGENTS.md、Cursor 的项目根目录 AGENTS.md 或 ~/.gemini/GEMINI.md）。
- 按照 docs/other-agents.md 中的说明连接两个钩子。
运行 bash open-steps/doctor.sh 以验证技能、路由块和钩子是否正确安装。

评估

作者对 25 个代表性短语在三个 Claude 模型（Haiku 4.5、Sonnet 5.5、Opus 5.5）和三个其他代理上进行了冒烟测试。所有技能在主题相关的查询中都能正确触发，Haiku 的整体激活率为 89%，较新模型为 100%。未观察到主题外激活。
详细结果和测试工具在 evals/ 目录中（cases.md、results.md、run.sh）。

适用对象

许可与贡献

简而言之，Open Steps 是一套即插即用的提示模板和小型脚本，可将 LLM 编码代理的原始、技术性对话转变为简洁、人性化的状态报告和分步指导。