kharmanskyi/open-steps

Open Steps – Plain‑language agent “skills” for Claude Code, Codex, Cursor and Gemini

What it is

• A collection of reusable skills (small prompt‑templates plus a few shell scripts) that you can add to Claude Code, Codex CLI, Cursor CLI or Gemini CLI.
• Each skill tells the LLM‑agent how to phrase its output in plain, non‑technical language and how to structure the interaction with a human who isn’t an engineer.
• The pack also ships two hooks that run at the start and end of every agent session, automatically inserting a routing table and, when real work has been done, asking the agent to generate a concise “one‑screen” report.

Key capabilities

Skill	What you get	When it runs
os‑done‑or‑not	One‑screen verdict: Done? Yes/No, any required input, new technical debt, safe‑to‑close flag.	When a task finishes or you ask “are we done?”.
os‑step‑by‑step	Numbered, non‑technical instructions for the user to follow; the agent only asks for actions it truly can’t perform itself.	When the agent needs the user to run a command, click, approve, etc.
os‑ask‑simple	Plain‑language question, estimated cost, and a single highlighted recommendation.	When the agent has a decision point or needs clarification.
os‑what‑could‑go‑wrong	Premortem analysis: assumes a decision will fail, works backwards, ends with a verdict.	Before committing to irreversible actions (contracts, migrations, launches).
os‑whats‑next	Summarises what’s verified and suggests the next concrete task, explained in everyday words.	When you ask “what’s left?” or after a report is written.
os‑check‑work	Re‑verifies claims from a previous session; reports any mismatches and next steps.	When another session claims a job is finished.
os‑say‑simple	Rewrites any block of text (report, comment, error) into plain language while preserving facts.	Whenever you need a less‑technical version of existing text.
os‑big‑picture	Maintains a BIG‑PICTURE.md that lists product features, their status, unused parts and a backlog; can open tickets in your tracker after you approve.	When you ask for an overall project status or need a backlog view.

How it works

• Each skill lives in its own folder (skills/os‑*) with a SKILL.md that defines the prompt and a references/ folder with a worked example.
• The two hooks (session‑start.sh and stop‑report.sh) are tiny shell scripts. The start hook injects the routing table (a tiny markdown table that tells the agent when to fire each skill) and the most recent report into the LLM’s context. The stop hook compares the repository state at the end of the session with the snapshot taken at start and, if enough files changed, asks the agent to produce a report.
• For Claude Code the whole thing is packaged as a plugin that automatically wires the skills and hooks. For Codex CLI, Cursor CLI and Gemini CLI you copy the skill folders into ~/.agents/skills/ and manually add the routing block and hook definitions to the respective configuration files.
• The pack can also perform autonomous merges: if a PR has green checks and an approved review, the agent verifies it again and merges it (using gh pr merge or the tool’s native merge command). Permissions are controlled via the allowed‑tools field in Claude Code’s plugin manifest.

Installation quick‑start

1. git clone https://github.com/kharmanskyi/open-steps.git
2. Claude Code – claude plugin marketplace add ./open-steps && claude plugin install open-steps@open-steps
   • Add the routing block to ~/.claude/CLAUDE.md (the repo provides a ready‑made snippet).
3. Other agents – copy the skill folders:

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

   • Insert the routing block into the tool‑specific standing‑instructions file (~/.codex/AGENTS.md, project‑root AGENTS.md for Cursor, or ~/.gemini/GEMINI.md).
   • Wire the two hooks as described in docs/other‑agents.md.
4. Run bash open-steps/doctor.sh to verify that the skills, routing block and hooks are correctly installed.

Evaluation

• The author ran a smoke‑test of 25 representative phrases across three Claude models (Haiku 4.5, Sonnet 5.5, Opus 5.5) and three other agents. All skills fired correctly on‑topic queries, with an overall activation rate of 89 % on Haiku and 100 % on the newer models. No off‑topic activation was observed.
• Detailed results and the test harness are in the evals/ directory (cases.md, results.md, run.sh).

Who it’s for

• Product builders, project managers, or anyone who wants to use LLM agents for code‑related work without having to interpret dense engineering reports.
• Teams that already use Claude Code, Codex CLI, Cursor CLI or Gemini CLI and need a consistent, plain‑language layer on top of the agent’s output.

License & contribution

• MIT‑licensed, free to use, modify and redistribute.
• Contributions are welcomed; see CONTRIBUTING.md for the process.

---

In short, Open Steps is a plug‑and‑play set of prompt‑templates and tiny scripts that turn the raw, technical chatter of LLM coding agents into concise, human‑friendly status reports and step‑by‑step guidance.