Skip to content
Back to search

open-steps

MarketplaceWorks with Claude CodeGitHub

Plain-language skills for Claude Code by Pavlo Kharmanskyi. One plugin: open-steps.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/kharmanskyi/open-steps with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/kharmanskyi/open-steps'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kharmanskyi-open-steps/badge.svg)](/listings/kharmanskyi-open-steps)

HTML

<a href="/listings/kharmanskyi-open-steps"><img src="/api/listings/kharmanskyi-open-steps/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](evals/README.md#what-was-run-on-each-tool).

First, for any 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](docs/claude-md.md).

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](#the-hooks).

Claude Code

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`](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.

<a id="other-agents-codex-cursor-gemini-cli"></a>

Codex CLI, Cursor CLI and 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:

| | Codex CLI | Cursor CLI | Gemini CLI | |---|---|---|---| | Routing block goes in | `~/.codex/AGENTS.md` | `AGENTS.md` in the project root | `~/.gemini/GEMINI.md` | | Hooks go in | `~/.codex/config.toml`. Per Codex's docs, it then asks once to trust them | `~/.cursor/hooks.json`, through `hooks/adapter.sh` | `~/.gemini/settings.json`, through `hooks/adapter.sh`, with the stop hook on `AfterAgent` | | Check | `bash open-steps/doctor.sh` | `bash open-steps/doctor.sh` | `bash open-steps/doctor.sh` |

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 16 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "open-steps",
  3. "description": "Open Steps by Pavlo Kharmanskyi: plain-language skills for coding agents.",
  4. "owner": {
  5. "name": "Pavlo Kharmanskyi"
  6. },
  7. "plugins": [
  8. {
  9. "name": "open-steps",
  10. "source": "./",
  11. "description": "Plain-language skills for coding agents, for the person running development who does not read code: session reports, decisions, next steps and the whole picture.",
  12. "homepage": "https://opensteps.ai",
  13. "repository": "https://github.com/kharmanskyi/open-steps"
  14. }
  15. ]
  16. }
README.md · README · 420 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Open Steps
  2. [![License: MIT](https://img.shields.io/badge/License-MIT-black.svg)](LICENSE)
  3. **English** · [Español](README.es.md) · [Français](README.fr.md) · [Русский](README.ru.md) · [Українська](README.uk.md) · [한국어](README.ko.md) · [中文](README.zh.md)
  4. **Plain-language agent skills for Claude Code, Codex, Cursor and Gemini CLI.**
  5. They keep development open to the person running it: the sessions, the
  6. decisions, the next steps, the whole picture.
  7. By [Pavlo Kharmanskyi](https://github.com/kharmanskyi).
  8. I'm not an engineer. I'm a market-led builder: I look for where demand already
  9. exists and the infrastructure doesn't, then build the missing piece. Twenty
  10. years of building web and software products, always from the product side, and
  11. more than 50 developers at my company today.
  12. Apart from the company, I started building a product on my own, just
  13. vibecoding. Partly to stay ahead of where all this is going, partly because I
  14. think the moment has arrived for people like me: you can now imagine a serious
  15. product and build it yourself, with no engineers or very few of them.
  16. Then I ran straight into a wall. The agent does excellent work, then tells me
  17. about it in commit hashes and jargon, and I genuinely cannot tell whether we
  18. are done. Not because the work is unclear. Because nobody taught the agent to
  19. talk to someone who doesn't speak engineering.
  20. So I built this pack. I'm sharing it here for anyone in the same position, and
  21. that's the whole idea behind the name: every step of building with an agent,
  22. kept open to the person doing the building. Right now it changes what the agent
  23. tells you. Where I want to take it next is the work itself, not just the
  24. reporting.
  25. ## Before and after
  26. The whole idea in one screen. Work ends, you ask "are we done?".
  27. ![The same session reported two ways: a wall of engineering detail, and a short plain-language report with a verdict](assets/before-after.svg)
  28. <details>
  29. <summary>The same thing as text, if the picture does not load</summary>
  30. Without the pack:
  31. > Hotfix deployed: session TTL misconfig in auth middleware caused 401
  32. > cascades after key rotation; patched the refresh path, invalidated stale
  33. > JWTs, redeployed api+web. p95 back to 180ms. Root cause: env drift after
  34. > the 09-14 rollout. Two flaky e2e specs quarantined (known, tracked)…
  35. With it you get this:
  36. > People can sign in again. A bug was logging people out because their
  37. > sessions expired far too early. The fix is live for everyone.
  38. >
  39. > | | |
  40. > |---|---|
  41. > | ✅ | Response times are back to normal |
  42. > | ⚠️ | Until this shipped, people were being logged out over and over. |
  43. >
  44. > | Fully done? | Yes |
  45. > |---|---|
  46. > | **Anything needed from you?** | No |
  47. > | **New debt?** | Two small ones, written down |
  48. > | **Safe to close?** | Yes |
  49. </details>
  50. Same facts. One screen. The bad news gets its own row instead of hiding in
  51. the middle of a paragraph. A second, longer example from a real session lives
  52. in this repository, with notes on what the rewrite changed:
  53. [`skills/os-done-or-not/references/01-prod-promote.md`](skills/os-done-or-not/references/01-prod-promote.md).
  54. ## The skills
  55. | Skill | What it does | When it fires |
  56. |---|---|---|
  57. | [`os-done-or-not`](skills/os-done-or-not/) | A one-screen report with a verdict: done or not, anything needed from you, any new debt, safe to close | Work wraps up, or you ask how it went |
  58. | [`os-step-by-step`](skills/os-step-by-step/) | Numbered steps a non-technical person can follow. The agent must first try everything itself and ask only for what truly needs you | The agent needs you to run, paste, click, approve or test something |
  59. | [`os-ask-simple`](skills/os-ask-simple/) | The question in plain words, what it costs later, and one marked recommendation | The agent has a question or options for you |
  60. | [`os-what-could-go-wrong`](skills/os-what-could-go-wrong/) | Assumes the decision already failed and works backwards to find out why, in a fresh agent that had no hand in it. Ends on one verdict | Something hard to undo is about to be agreed: a contract, a purchase, a migration, a launch |
  61. | [`os-whats-next`](skills/os-whats-next/) | Merges what is verified and ready, then recommends the next task and says why in plain words | You ask what is left or what to do next |
  62. | [`os-check-work`](skills/os-check-work/) | Does not trust another session's report. Checks every claim against what actually happened, then says what to do about it | Another session says it is done |
  63. | [`os-say-simple`](skills/os-say-simple/) | Rewrites any text in plain words without losing facts or bad news. Give it a number and you get exactly that many points | Any text reads like engineering: a report, a comment, an error, the agent's own answer |
  64. | [`os-big-picture`](skills/os-big-picture/) | Keeps one `BIG-PICTURE.md`: what the product is, every feature with how far it got, which parts nobody uses any more, and what is queued. It offers to open the queue as tickets in a tracker you already use | You ask where the project stands, or a session report was just written |
  65. They work as a loop: `os-whats-next` picks the work, `os-step-by-step` walks
  66. you through your part, `os-done-or-not` reports the result, `os-check-work`
  67. accepts what other sessions did, `os-ask-simple` handles the questions on the
  68. way, `os-what-could-go-wrong` attacks anything hard to undo before it is
  69. agreed, and `os-say-simple` rescues any text that still reads like
  70. engineering. `os-big-picture` keeps the standing file whose queue
  71. `os-whats-next` reads as its backlog.
  72. `os-big-picture` writes its file in plain words, so you get the whole picture
  73. without reading code. It measures from git how old each part is and whether
  74. anything still uses it, and it dates what it cannot measure. It opens tickets
  75. in your tracker only after you say yes. The file stays out of your commits
  76. unless you add it yourself. It never invents a task and never deletes
  77. anything. The rules and the reasons behind them are in
  78. [`skills/os-big-picture/`](skills/os-big-picture/).
  79. ## What it does on its own
  80. **The pack finishes finished work by itself.** If a pull request has green
  81. checks and an approved review, the agent verifies it once more and merges it.
  82. On Claude Code that happens without a permission prompt. On Codex CLI, Cursor
  83. CLI and Gemini CLI the merge command goes through that tool's own permission
  84. settings, per their documentation. Whatever unblocks the most goes first.
  85. Two things stop a merge: a claim that fails verification, or a note on the
  86. task saying merges happen on command only. Write that note on the task
  87. wherever another tool or person decides when to merge. To have merges on
  88. command only, put the same note in your standing instructions file:
  89. `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, `~/.gemini/GEMINI.md`, or the
  90. project's `AGENTS.md` on Cursor CLI.
  91. On Claude Code a skill can also pre-approve tools for the turn it runs in,
  92. through its `allowed-tools` field. This pack keeps that list to what the
  93. skills use:
  94. | Skill | Pre-approved on Claude Code |
  95. |---|---|
  96. | Every skill | Reading its reports folder, `~/.claude/open-steps/` |
  97. | `os-done-or-not` | Writing its report in that folder, and `gh pr view` and `gh pr checks` |
  98. | `os-whats-next`, `os-check-work` | `gh pr list`, `gh pr view`, `gh pr checks` and `gh pr diff`, which read a pull request, and `gh pr merge`, for the merges above |
  99. | `os-big-picture` | Editing its own `BIG-PICTURE.md`, its census script, `git rev-parse --git-dir` to find the repository folder, `gh repo view`, `gh issue list`, and `gh issue create`, which opens tickets after you say yes |
  100. | `os-what-could-go-wrong` | Its premortem prompt script |
  101. | `/open-steps:os-install-check` | `doctor.sh` |
  102. Other commands, and files outside your project and the reports folder, go
  103. through your own permission settings as usual. Other read-only `git` commands
  104. need no entry, because Claude Code runs them without asking. Codex CLI, Cursor
  105. CLI and Gemini CLI ignore the field, per their documentation, and
  106. ask the way they normally do. That part has not been tested.
  107. <a id="quick-start"></a>
  108. ## Install
  109. The skills are the same folders on every tool. On Claude Code a plugin
  110. installs them and wires both hooks in one command. On Codex CLI, Cursor CLI
  111. and Gemini CLI one copy command installs the skills, and each tool takes a few
  112. lines of hook settings. Antigravity takes a copy command of its own and the
  113. same kind of hook settings. What was run on each tool, and what comes from its
  114. documentation, is under
  115. [What was run on each tool](evals/README.md#what-was-run-on-each-tool).
  116. ### First, for any tool
  117. You need `git` to download the pack and to update it. Some skills, such as
  118. `os-whats-next` and `os-check-work`, also read project state through `git` and
  119. `gh`, GitHub's command-line tool. `gh` is
  120. optional. Without it, more of the output says "not checked".
  121. Clone this repository:
  122. ```bash
  123. git clone https://github.com/kharmanskyi/open-steps.git
  124. ```
  125. Stay in the folder where you ran that command, the one that now holds
  126. `open-steps/`. The commands below run from there. Only `git pull` runs inside
  127. the clone.
  128. On every tool you add one piece by hand: the routing block. The agent decides
  129. by itself whether to use a skill. The routing block is a short table that
  130. names the moments when it must use one, and which one. It goes in the file
  131. your tool reads as standing instructions, and each tool's part below names
  132. that file. [Why the block matters](docs/claude-md.md).
  133. The pack also has two hooks. One starts each session with the routing table
  134. and your last report. The other asks for a report when a session ends with
  135. real work done. How they work: [The hooks](#the-hooks).
  136. ### Claude Code
  137. Install the pack as a plugin. This wires the skills and both hooks:
  138. ```bash
  139. claude plugin marketplace add ./open-steps && claude plugin install open-steps@open-steps
  140. ```
  141. Check what you got:
  142. ```bash
  143. claude plugin details open-steps
  144. ```
  145. To check the whole install, not just the plugin, run
  146. `/open-steps:os-install-check` in Claude Code. It reports what is wired and
  147. what is not, and says "not checked" where it could not look.
  148. The routing block goes in your own `~/.claude/CLAUDE.md`, where it survives
  149. long conversations. One command, from the same folder, safe to re-run:
  150. ```bash
  151. grep -q 'os-done-or-not' ~/.claude/CLAUDE.md 2>/dev/null || cat open-steps/docs/routing-block.md >> ~/.claude/CLAUDE.md
  152. ```
  153. To update: `git pull` inside `open-steps/`, then
  154. `claude plugin update open-steps@open-steps`. Both steps are needed. The
  155. plugin updates from your clone, not from GitHub. Without the pull it says
  156. "already at the latest version" about an old copy. The installed copy changes
  157. only when the pack's version number does.
  158. To remove: `claude plugin uninstall open-steps`, then take the block back out
  159. of your `~/.claude/CLAUDE.md`.
  160. The pack also has an optional output style for Claude Code, Answer first. It
  161. makes the agent put the answer in the first line and stop narrating its
  162. checks. It is off by default, because turning it on would replace a style you
  163. already chose. Turning it on takes two lines, in
  164. [`docs/output-style.md`](docs/output-style.md). Output styles are a Claude
  165. Code setting, so the pack does not wire it on Codex CLI, Cursor CLI or Gemini
  166. CLI.
  167. <a id="other-agents-codex-cursor-gemini-cli"></a>
  168. ### Codex CLI, Cursor CLI and Gemini CLI
  169. These three tools read `~/.agents/skills/`, so one command installs the skills
  170. for all of them:
  171. ```bash
  172. mkdir -p ~/.agents/skills && cp -R open-steps/skills/os-* ~/.agents/skills/
  173. ```
  174. The rest is set per tool:
  175. | | Codex CLI | Cursor CLI | Gemini CLI |
  176. |---|---|---|---|
  177. | Routing block goes in | `~/.codex/AGENTS.md` | `AGENTS.md` in the project root | `~/.gemini/GEMINI.md` |
  178. | Hooks go in | `~/.codex/config.toml`. Per Codex's docs, it then asks once to trust them | `~/.cursor/hooks.json`, through `hooks/adapter.sh` | `~/.gemini/settings.json`, through `hooks/adapter.sh`, with the stop hook on `AfterAgent` |
  179. | Check | `bash open-steps/doctor.sh` | `bash open-steps/doctor.sh` | `bash open-steps/doctor.sh` |
  180. | Update | `git pull` inside `open-steps/`, then the copy command again | `git pull` inside `open-steps/`, then the copy command again | `git pull` inside `open-steps/`, then the copy command again |
  181. | Remove | Delete the `os-*` folders from `~/.agents/skills/`, the block from `~/.codex/AGENTS.md`, and the two hook entries from `~/.codex/config.toml` | Delete the `os-*` folders from `~/.agents/skills/`, the block from `AGENTS.md`, and the two hook entries from `~/.cursor/hooks.json` | Delete the `os-*` folders from `~/.agents/skills/`, the block from `~/.gemini/GEMINI.md`, and the two hook entries from `~/.gemini/settings.json` |
  182. The routing block command for each tool, safe to re-run, is in
  183. [`docs/other-agents.md`](docs/other-agents.md#the-routing-block). So are the
  184. hook settings, in [The hooks](docs/other-agents.md#the-hooks) there, and
  185. everything that was run rather than read.
  186. `doctor.sh` reads the shared skills folder and each tool's own, the routing
  187. block, and the hook settings of each tool it finds, down to the event each
  188. hook sits under. It says "not checked" for what it cannot look at.
  189. The skills are a copy, so they stay as they were until you run the copy
  190. command again. The remove steps have not been run yet.
  191. If you also use Claude Code in a project where the block sits in `AGENTS.md`
  192. for Cursor CLI: Claude Code 2.1.277 and later reads a project's `AGENTS.md`
  193. when the project has no `CLAUDE.md`, per its changelog. So the block reaches
  194. Claude Code in that project too.
  195. ### Antigravity
  196. Antigravity does not read `~/.agents/skills/`. Its app, its IDE and its CLI
  197. read `~/.gemini/config/skills/`:
  198. ```bash
  199. mkdir -p ~/.gemini/config/skills && cp -R open-steps/skills/os-* ~/.gemini/config/skills/
  200. ```
  201. The routing block goes in `AGENTS.md` in the project root. The hooks go in
  202. `~/.gemini/config/hooks.json`, through `hooks/adapter.sh`, with the stop hook
  203. on `Stop`, as [Antigravity](docs/other-agents.md#antigravity) shows. Check
  204. with `bash open-steps/doctor.sh`. To update, run `git pull` inside
  205. `open-steps/`, then the copy command again. To remove, delete the `os-*`
  206. folders from `~/.gemini/config/skills/`, the block from `AGENTS.md`, and the
  207. `open-steps` entry from `~/.gemini/config/hooks.json`. Both hooks were run in
  208. a project's own `.agents/` folder. The skills folder for your user and the
  209. session-start hook from `~/.gemini/config/hooks.json` were run too; the stop
  210. hook from that file, the app and the IDE come from Antigravity's
  211. documentation.
  212. ## Numbers
  213. The pack tells the agent to separate what it measured from what it assumed.
  214. Same rule for me. Twenty-five phrases a person would actually say, each asked
  215. three times with no one at the keyboard, on three Claude models: did the right
  216. skill switch on by itself? Three off-topic questions, asked the same way,
  217. checked the opposite. Three runs per phrase is a smoke test, not a benchmark.
  218. The chart and the table are Claude Code. The same phrases were run on Codex
  219. CLI, Cursor CLI and Gemini CLI by contributors, and what each tool counts as
  220. "switched on", what was run on every tool, and what the misses show are in
  221. [evals/README.md](evals/README.md#what-was-run-on-each-tool).
  222. ![Activation per skill on Haiku 4.5, Sonnet 5.5 and Opus 5.5](assets/activation.svg)
  223. <!-- numbers: score.py writes this table, edit the prose but not these rows -->
  224. Measured on 2026-10-05.
  225. | Skill | Haiku 4.5 | Sonnet 5.5 | Opus 5.5 |
  226. |---|---|---|---|
  227. | `os-done-or-not` | 12/12 | 12/12 | 12/12 |
  228. | `os-whats-next` | 9/9 | 9/9 | 9/9 |
  229. | `os-check-work` | 9/9 | 9/9 | 9/9 |
  230. | `os-ask-simple` | 9/9 | 9/9 | 9/9 |
  231. | `os-what-could-go-wrong` | 9/9 | 9/9 | 9/9 |
  232. | `os-big-picture` | 9/9 | 9/9 | 9/9 |
  233. | `os-say-simple` | 7/9 | 9/9 | 9/9 |
  234. | `os-step-by-step` | 3/9 | 9/9 | 9/9 |
  235. | **All 25 phrases** | **89%** | **100%** | **100%** |
  236. | Fired on an off-topic question | 0/9 | 0/9 | 0/9 |
  237. <!-- numbers: end -->
  238. Everything is in [`evals/`](evals/): [`cases.md`](evals/cases.md) is every
  239. phrase we ask, [`results.md`](evals/results.md) is what came back, phrase by
  240. phrase. The scorer writes that file; I don't type it. Scoring is a plain
  241. script reading tool calls, with no AI judging anything. Re-run it with
  242. `bash evals/run.sh`; `EVAL_AGENT` picks the tool, and a script for another
  243. tool follows the contract in
  244. [Measuring another agent](evals/README.md#measuring-another-agent).
  245. Also easy to check yourself: the pack's descriptions are always on, and Claude
  246. Code estimates their cost itself. Run `claude plugin details open-steps` for
  247. the current figure. The session-start hook adds its text on top: the routing
  248. table, and the last report, capped by `OPEN_STEPS_MAX_REPORT_LINES`.
  249. ## How the pack is built
  250. Each skill is one folder with one `SKILL.md` inside: a short header, then the
  251. rules. Each also has a worked example in its `references/` folder.
  252. What runs on your machine is plain shell:
  253. - The two hooks, short enough to read in a minute. On Cursor CLI and Gemini
  254. CLI they run through `hooks/adapter.sh`.
  255. - Two small scripts, which `os-big-picture` and `os-what-could-go-wrong` call.
  256. The second is loaded through a `!` command, which is a Claude Code feature.
  257. How other tools handle that line is in
  258. [`docs/other-agents.md`](docs/other-agents.md).
  259. - The install check, `doctor.sh`, when you run it.
  260. The skills also have the agent run `git` and `gh` commands, including merges,
  261. as [What it does on its own](#what-it-does-on-its-own) says.
  262. ### The hooks
  263. Two hooks ship with the pack. The Claude Code plugin connects them for you. On
  264. Codex CLI, Cursor CLI, Gemini CLI and Antigravity you wire them by hand, as
  265. [`docs/other-agents.md`](docs/other-agents.md#the-hooks) shows.
  266. [`session-start.sh`](hooks/session-start.sh) puts the routing table and the
  267. last report in front of a new session. It also quietly records what your
  268. repositories looked like at that moment.
  269. [`stop-report.sh`](hooks/stop-report.sh) compares against that when the
  270. session ends, and asks for a report if real work landed. That is also how work
  271. you finished inside a single reply still gets one. Neither hook can loop:
  272. reports are written outside your repositories, so writing one changes nothing
  273. they look at. The stop hook costs nothing when it stays quiet. The start hook
  274. does add its text to your context, with the report part capped by the setting
  275. below. Their settings:
  276. | Setting | Default | What it does |
  277. |---|---|---|
  278. | `OPEN_STEPS_COOLDOWN` | 900 | seconds of quiet between report requests |
  279. | `OPEN_STEPS_MIN_FILES` | 1 | changed files before a report is asked for |
  280. | `OPEN_STEPS_MAX_REPOS` | 25 | started in a folder of repositories, how many get checked |
  281. | `OPEN_STEPS_DISABLE` | unset | set to anything to switch the stop hook off |
  282. | `OPEN_STEPS_MAX_REPORT_LINES` | 80 | cap on the last report the start hook shows |
  283. | `OPEN_STEPS_NO_SESSION_START` | unset | set to anything to switch the start hook off |
  284. Reports are saved outside your repositories, in
  285. `~/.claude/open-steps/reports/<project>/`. So they stay out of your commits
  286. and survive uninstalling the pack. Each tool is pointed at this one folder, so
  287. all your tools share one history. The `.claude` in the path is only a name.
  288. ### Three decisions
  289. These shape everything here:
  290. 1. **Descriptions are commands, not summaries.** The skill descriptions open
  291. with "ALWAYS invoke this skill…". With this form the skills switched on in
  292. the test runs shown under [Numbers](#numbers). The evals do not compare it
  293. with other wordings.
  294. 2. **A skill cannot force itself to run.** Anything that must hold in each
  295. reply lives in the tool's standing instructions file (`CLAUDE.md`,
  296. `AGENTS.md`, `GEMINI.md`) or, on Claude Code, the output style instead.
  297. The pack says which layer each piece belongs to.
  298. 3. **Measured and assumed stay apart.** A "yes" has to name its proof.
  299. Anything unchecked says "not checked". This is also why the reports are
  300. short: the agent stops narrating its checks and states the result.
  301. The plain-language rules borrow from ASD-STE100, the simplified English
  302. written for aerospace manuals: short sentences, active voice, one idea per
  303. sentence. Borrow is the word. Nothing here is certified against the standard.
  304. ## Limits
  305. - Answer quality and the premortem's fresh agent are measured on Claude Code
  306. only. What was run on each tool is under
  307. [What was run on each tool](evals/README.md#what-was-run-on-each-tool).
  308. - The output style does not reach subagents. So `os-what-could-go-wrong`
  309. carries its rules inside the handover to its fresh agent, and its plain
  310. language rests on
  311. [`references/premortem-prompt.md`](skills/os-what-could-go-wrong/references/premortem-prompt.md).
  312. ## Open source
  313. Free, MIT licensed. Take it, use it at work, change it, fork it.
  314. I keep building this pack for my own work, so it moves on its own. Pull
  315. requests are welcome and I read them; the rules are in
  316. [CONTRIBUTING.md](CONTRIBUTING.md).
  317. If it helped, a star makes it easier for other people to find.
  318. ## License
  319. MIT. See [LICENSE](LICENSE). © 2026 Pavlo Kharmanskyi.
  320. Open Steps is an independent open-source project, not affiliated with or
  321. endorsed by the makers of the tools it runs on. Claude and Claude Code are
  322. trademarks of Anthropic. All other trademarks, including Codex, Cursor and
  323. Gemini, are the property of their respective owners.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.