kharmanskyi/open-steps

English · Español · Français · Русский · Українська · 한국어 · 中文

Plain-language agent skills for Claude Code, Codex, Cursor and Gemini CLI.

They keep development open to the person running it: the sessions, the decisions, the next steps, the whole picture.

By Pavlo Kharmanskyi.

I'm not an engineer. I'm a market-led builder: I look for where demand already exists and the infrastructure doesn't, then build the missing piece. Twenty years of building web and software products, always from the product side, and more than 50 developers at my company today.

Apart from the company, I started building a product on my own, just vibecoding. Partly to stay ahead of where all this is going, partly because I think the moment has arrived for people like me: you can now imagine a serious product and build it yourself, with no engineers or very few of them.

Then I ran straight into a wall. The agent does excellent work, then tells me about it in commit hashes and jargon, and I genuinely cannot tell whether we are done. Not because the work is unclear. Because nobody taught the agent to talk to someone who doesn't speak engineering.

So I built this pack. I'm sharing it here for anyone in the same position, and that's the whole idea behind the name: every step of building with an agent, kept open to the person doing the building. Right now it changes what the agent tells you. Where I want to take it next is the work itself, not just the reporting.

The whole idea in one screen. Work ends, you ask "are we done?".

Same facts. One screen. The bad news gets its own row instead of hiding in the middle of a paragraph. A second, longer example from a real session lives in this repository, with notes on what the rewrite changed: skills/os-done-or-not/references/01-prod-promote.md.

They work as a loop: os-whats-next picks the work, os-step-by-step walks you through your part, os-done-or-not reports the result, os-check-work accepts what other sessions did, os-ask-simple handles the questions on the way, os-what-could-go-wrong attacks anything hard to undo before it is agreed, and os-say-simple rescues any text that still reads like engineering. os-big-picture keeps the standing file whose queue os-whats-next reads as its backlog.

os-big-picture writes its file in plain words, so you get the whole picture without reading code. It measures from git how old each part is and whether anything still uses it, and it dates what it cannot measure. It opens tickets in your tracker only after you say yes. The file stays out of your commits unless you add it yourself. It never invents a task and never deletes anything. The rules and the reasons behind them are in skills/os-big-picture/.

The pack finishes finished work by itself. If a pull request has green checks and an approved review, the agent verifies it once more and merges it. On Claude Code that happens without a permission prompt. On Codex CLI, Cursor CLI and Gemini CLI the merge command goes through that tool's own permission settings, per their documentation. Whatever unblocks the most goes first.

Two things stop a merge: a claim that fails verification, or a note on the task saying merges happen on command only. Write that note on the task wherever another tool or person decides when to merge. To have merges on command only, put the same note in your standing instructions file: ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ~/.gemini/GEMINI.md, or the project's AGENTS.md on Cursor CLI.

On Claude Code a skill can also pre-approve tools for the turn it runs in, through its allowed-tools field. This pack keeps that list to what the skills use:

Other commands, and files outside your project and the reports folder, go through your own permission settings as usual. Other read-only git commands need no entry, because Claude Code runs them without asking. Codex CLI, Cursor CLI and Gemini CLI ignore the field, per their documentation, and ask the way they normally do. That part has not been tested.

The skills are the same folders on every tool. On Claude Code a plugin installs them and wires both hooks in one command. On Codex CLI, Cursor CLI and Gemini CLI one copy command installs the skills, and each tool takes a few lines of hook settings. What was run on each tool, and what comes from its documentation, is under What was run on each tool.

You need git to download the pack and to update it. Some skills, such as os-whats-next and os-check-work, also read project state through git and gh, GitHub's command-line tool. gh is optional. Without it, more of the output says "not checked".

Clone this repository:

git clone https://github.com/kharmanskyi/open-steps.git

Stay in the folder where you ran that command, the one that now holds open-steps/. The commands below run from there. Only git pull runs inside the clone.

On every tool you add one piece by hand: the routing block. The agent decides by itself whether to use a skill. The routing block is a short table that names the moments when it must use one, and which one. It goes in the file your tool reads as standing instructions, and each tool's part below names that file. Why the block matters.

The pack also has two hooks. One starts each session with the routing table and your last report. The other asks for a report when a session ends with real work done. How they work: The hooks.

Install the pack as a plugin. This wires the skills and both hooks:

claude plugin marketplace add ./open-steps && claude plugin install open-steps@open-steps

Check what you got:

claude plugin details open-steps

To check the whole install, not just the plugin, run /open-steps:os-install-check in Claude Code. It reports what is wired and what is not, and says "not checked" where it could not look.

The routing block goes in your own ~/.claude/CLAUDE.md, where it survives long conversations. One command, from the same folder, safe to re-run:

grep -q 'os-done-or-not' ~/.claude/CLAUDE.md 2>/dev/null || cat open-steps/docs/routing-block.md >> ~/.claude/CLAUDE.md

To update: git pull inside open-steps/, then claude plugin update open-steps@open-steps. Both steps are needed. The plugin updates from your clone, not from GitHub. Without the pull it says "already at the latest version" about an old copy. The installed copy changes only when the pack's version number does.

To remove: claude plugin uninstall open-steps, then take the block back out of your ~/.claude/CLAUDE.md.

The pack also has an optional output style for Claude Code, Answer first. It makes the agent put the answer in the first line and stop narrating its checks. It is off by default, because turning it on would replace a style you already chose. Turning it on takes two lines, in docs/output-style.md. Output styles are a Claude Code setting, so the pack does not wire it on Codex CLI, Cursor CLI or Gemini CLI.

These three tools read ~/.agents/skills/, so one command installs the skills for all of them:

mkdir -p ~/.agents/skills && cp -R open-steps/skills/os-* ~/.agents/skills/

The rest is set per tool:

The routing block command for each tool, safe to re-run, is in docs/other-agents.md. So are the hook settings, in The hooks there, and everything that was run rather than read.

doctor.sh reads the shared skills folder and each tool's own, the routing block, and the hook settings of each tool it finds, down to the event each hook sits under. It says "not checked" for what it cannot look at.

The skills are a copy, so they stay as they were until you run the copy command again. The remove steps have not been run yet.

If you also use Claude Code in a project where the block sits in AGENTS.md for Cursor CLI: Claude Code 2.1.277 and later reads a project's AGENTS.md when the project has no CLAUDE.md, per its changelog. So the block reaches Claude Code in that project too.

The pack tells the agent to separate what it measured from what it assumed. Same rule for me. Twenty-five phrases a person would actually say, each asked three times with no one at the keyboard, on three Claude models: did the right skill switch on by itself? Three off-topic questions, asked the same way, checked the opposite. Three runs per phrase is a smoke test, not a benchmark.

The chart and the table are Claude Code. The same phrases were run on Codex CLI, Cursor CLI and Gemini CLI by contributors, and what each tool counts as "switched on", what was run on every tool, and what the misses show are in evals/README.md.

Measured on 2026-10-05.

Everything is in evals/: cases.md is every phrase we ask, results.md is what came back, phrase by phrase. The scorer writes that file; I don't type it. Scoring is a plain script reading tool calls, with no AI judging anything. Re-run it with bash evals/run.sh; EVAL_AGENT picks the tool, and a script for another tool follows the contract in Measuring another agent.

Also easy to check yourself: the pack's descriptions are always on, and Claude Code estimates their cost itself. Run claude plugin details open-steps for the current figure. The session-start hook adds its text on top: the routing table, and the last report, capped by OPEN_STEPS_MAX_REPORT_LINES.

Each skill is one folder with one SKILL.md inside: a short header, then the rules. Each also has a worked example in its references/ folder.

What runs on your machine is plain shell:

• The two hooks, short enough to read in a minute. On Cursor CLI and Gemini CLI they run through hooks/adapter.sh.
• Two small scripts, which os-big-picture and os-what-could-go-wrong call. The second is loaded through a ! command, which is a Claude Code feature. How other tools handle that line is in docs/other-agents.md.
• The install check, doctor.sh, when you run it.

The skills also have the agent run git and gh commands, including merges, as What it does on its own says.

Two hooks ship with the pack. The Claude Code plugin connects them for you. On Codex CLI, Cursor CLI and Gemini CLI you wire them by hand, as docs/other-agents.md shows.

session-start.sh puts the routing table and the last report in front of a new session. It also quietly records what your repositories looked like at that moment. stop-report.sh compares against that when the session ends, and asks for a report if real work landed. That is also how work you finished inside a single reply still gets one. Neither hook can loop: reports are written outside your repositories, so writing one changes nothing they look at. The stop hook costs nothing when it stays quiet. The start hook does add its text to your context, with the report part capped by the setting below. Their settings:

Reports are saved outside your repositories, in ~/.claude/open-steps/reports/<project>/. So they stay out of your commits and survive uninstalling the pack. Each tool is pointed at this one folder, so all your tools share one history. The .claude in the path is only a name.

These shape everything here:

1. Descriptions are commands, not summaries. The skill descriptions open with "ALWAYS invoke this skill…". With this form the skills switched on in the test runs shown under Numbers. The evals do not compare it with other wordings.
2. A skill cannot force itself to run. Anything that must hold in each reply lives in the tool's standing instructions file (CLAUDE.md, AGENTS.md, GEMINI.md) or, on Claude Code, the output style instead. The pack says which layer each piece belongs to.
3. Measured and assumed stay apart. A "yes" has to name its proof. Anything unchecked says "not checked". This is also why the reports are short: the agent stops narrating its checks and states the result.

The plain-language rules borrow from ASD-STE100, the simplified English written for aerospace manuals: short sentences, active voice, one idea per sentence. Borrow is the word. Nothing here is certified against the standard.

• Answer quality and the premortem's fresh agent are measured on Claude Code only. What was run on each tool is under What was run on each tool.
• The output style does not reach subagents. So os-what-could-go-wrong carries its rules inside the handover to its fresh agent, and its plain language rests on references/premortem-prompt.md.

Free, MIT licensed. Take it, use it at work, change it, fork it.

I keep building this pack for my own work, so it moves on its own. Pull requests are welcome and I read them; the rules are in CONTRIBUTING.md.

If it helped, a star makes it easier for other people to find.

MIT. See LICENSE. © 2026 Pavlo Kharmanskyi.

Open Steps is an independent open-source project, not affiliated with or endorsed by the makers of the tools it runs on. Claude and Claude Code are trademarks of Anthropic. All other trademarks, including Codex, Cursor and Gemini, are the property of their respective owners.