v0.4.8

os-ask-simple

kharmanskyi@kharmanskyi⭐ 1.3k stars· last commit 1mo ago· 5 open issues

>-

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

7.2/10
Verified
Oct 12, 2026

// RATINGS

⭐GitHub Stars
⭐⭐⭐⭐⭐ 1.3k on GitHubGitHub ↗

Very popular

🟢ProSkills ScoreAI Verified
7.2/10
📍

Not yet listed on ClawHub or SkillsMP

// README

Open Steps

License: MIT

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.

Before and after

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

The same session reported two ways: a wall of engineering detail, and a short plain-language report with a verdict

Without the pack:

Hotfix deployed: session TTL misconfig in auth middleware caused 401 cascades after key rotation; patched the refresh path, invalidated stale JWTs, redeployed api+web. p95 back to 180ms. Root cause: env drift after the 09-14 rollout. Two flaky e2e specs quarantined (known, tracked)…

With it you get this:

People can sign in again. A bug was logging people out because their sessions expired far too early. The fix is live for everyone.

✅Response times are back to normal
⚠️Until this shipped, people were being logged out over and over.
Fully done?Yes
Anything needed from you?No
New debt?Two small ones, written down
Safe to close?Yes

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.

The skills

SkillWhat it doesWhen it fires
os-done-or-notA one-screen report with a verdict: done or not, anything needed from you, any new debt, safe to closeWork wraps up, or you ask how it went
os-step-by-stepNumbered steps a non-technical person can follow. The agent must first try everything itself and ask only for what truly needs youThe agent needs you to run, paste, click, approve or test something
os-ask-simpleThe question in plain words, what it costs later, and one marked recommendationThe agent has a question or options for you
os-what-could-go-wrongAssumes the decision already failed and works backwards to find out why, in a fresh agent that had no hand in it. Ends on one verdictSomething hard to undo is about to be agreed: a contract, a purchase, a migration, a launch
os-whats-nextMerges what is verified and ready, then recommends the next task and says why in plain wordsYou ask what is left or what to do next
os-check-workDoes not trust another session's report. Checks every claim against what actually happened, then says what to do about itAnother session says it is done
os-say-simpleRewrites any text in plain words without losing facts or bad news. Give it a number and you get exactly that many pointsAny text reads like engineering: a report, a comment, an error, the agent's own answer
os-big-pictureKeeps 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 useYou ask where the project stands, or a session report was just written

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/.

What it does on its own

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:

SkillPre-approved on Claude Code
Every skillReading its reports folder, ~/.claude/open-steps/
os-done-or-notWriting its report in that folder, and gh pr view and gh pr checks
os-whats-next, os-check-workgh 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
os-big-pictureEditing 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
os-what-could-go-wrongIts premortem prompt script
/open-steps:os-install-checkdoctor.sh

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 docume

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/os-ask-simple/SKILL.md5.3 KBupstream ↗
    ---
    name: os-ask-simple
    description: >-
      ALWAYS invoke this skill before asking the user any technical question or
      offering options, and whenever they ask to be asked in plain words - "ask
      simple", "ask me simply", "ask me in plain words" - in any language. ALWAYS
      invoke it too when the user asks for your view on a technical choice:
      whether it is worth doing, more than the problem needs, or replaceable by
      something simpler, and which option you would take. Invoke it even when the
      code makes the answer look obvious: the checks are what make the answer more
      than a guess. Rewrites the question in plain words and always ends with one
      marked recommendation. A structural choice first passes six checks, shown as
      a table: effort now, simpler substitute, extra work later, lock-in,
      over-engineering, easy to undo. Doing nothing is always weighed.
    allowed-tools:
      - "Read(~/.claude/open-steps/**)"
    ---
    
    # os-ask-simple
    
    Two jobs. Ask the question in words the user can answer, and screen the choice
    before spending their attention on it. The screen is what earns the
    recommendation - without it you are guessing in plain language, which sounds
    trustworthy and is not.
    
    ## Language
    
    Write in the language the user speaks in this session. Detect it from the
    conversation. Keep code, file names and identifiers in English.
    
    ## When to use
    
    - You are about to ask the user a technical question.
    - You are about to offer options.
    - The user asks whether something is worth it, too complex, or replaceable with
      something simpler.
    - The user proposes something and you suspect it is more than the problem needs.
    
    ## Before anything: is this even a question for them?
    
    Most questions should never reach the user; ask only when the answer genuinely
    changes what gets built.
    
    - **Can you answer it by looking?** Read the code, the config, the last report.
      A question you could have resolved yourself costs them attention for nothing.
    - **Is there a conventional default?** Take it and say you took it.
    - **Would both answers lead to the same work?** Then it is not a fork.
    
    ## Light form - every question
    
    ```
    <The question in one plain sentence. No jargon; if a term is unavoidable, give a
    three-to-five word analogy.>
    
    Why it matters: <one line, in terms of the product, not the code>
    What changes later: <one line>
    Easy to undo: <yes, and how - or no, and why>
    ```
    
    Then the options, through your tool's question picker where it has one (in
    Claude Code, AskUserQuestion). Offer two to four, each with a one-line
    trade-off in plain words, the recommended one first and marked `(Recommended)`.
    
    Keep the heading to 12 characters or fewer and each label to one to five
    words. Claude Code's picker has the same limits, and short labels read well as
    plain text too. Where there is no picker, write the same question and options
    as plain text, the recommended one first and marked.
    
    ## Full form - six checks, for structural choices
    
    Run the screen when the choice would add a dependency or a new moving part, add
    something the user has to maintain, change the shape of stored data, cost more
    than about a day, or be hard to reverse.
    
    Show it as a table. Answer every row - "not checked" is allowed and honest;
    silence is not.
    
    | Check | What goes in the answer |
    |---|---|
    | How long now | Real effort, in hours or days, plus what has to be touched |
    | Simpler substitute | The simplest thing that would also work - or "none found", having looked |
    | Extra work for you later | Anything the user must do repeatedly afterwards: approvals, manual steps, watching a dashboard |
    | Harder to change later | What this locks in, and what would be expensive to move afterwards |
    | Over-engineering | Say yes when it is yes. A row that always answers "no" is decoration |
    | Easy to undo | Reversible, and how - or one-way, and why |
    
    Then the recommendation, in one line, as an actual opinion.
    
    ## Hard rules
    
    1. **Always weigh doing nothing.** "Change nothing" is a real candidate, often
       the winner. If it lost, say in one line why.
    2. **A recommendation is required.** Never lay out options and stop. "It depends"
       is not a recommendation - if it truly depends, say what it depends on and pick
       the option that is right under the more likely condition.
    3. **Recommend against the user's own idea when the screen says so.** Plainly, in
       one sentence, with the simpler substitute named. They asked for a filter, not
       for agreement.
    4. **Never recommend what you have not screened.** If the six checks were skipped
       because the choice looked small, say the choice looked small.
    5. **One question at a time.** Two questions in one message means the second gets
       a careless answer.
    6. **Watch your own bias.** The most interesting thing to build is not the
       recommendation. If an option is more fun to implement, that is a reason for
       suspicion, not for preference.
    
    ## Known gotchas
    
    - **Two options that end in the same place are one option.** Do not pad the
      picker to look thorough.
    - **"Over-engineering: no" answered reflexively kills the whole screen.** The row
      exists to be answered yes sometimes.
    - **Effort estimates are guesses.** Say "roughly" and give a range. A confident
      number that turns out wrong costs more trust than a range ever does.
    - **The user may pick the option you did not recommend.** That is the point of
      asking. Do it their way without re-arguing, and note the trade-off once.
    
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/kharmanskyi-open-steps-skills-os-ask-simple.md

// REPO STATS

1.3k stars
5 open issues
Last commit: 1mo ago