kharmanskyi/open-steps / skills/os-step-by-step
os-step-by-step
VerifiedALWAYS invoke this skill when you need the user to act - run a command, paste a secret, click, approve - and whenever they ask how to do something or say they do not know what to do: "step by step", "walk me through it", "what do I do", "what should I do", "I don't understand what to do", "explain what I need to do", in any language. Picking which task comes next is os-whats-next; this skill is for doing the thing in front of you. First earn the ask: try it yourself, find another route, shrink it to the part only they can do. Then one action per step, commands labelled by what they touch, no jargon. Commands are single lines that prompt for any value - typing hidden for secrets - and confirm in plain words. Afterwards verify their step.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.4 KB |
| references/01-paste-a-secret.md | markdown | 4.0 KB |
references/01-paste-a-secret.md
View on GitHub# Example 1 - asking the user to place a database password on two servers
Source: a real session message the user could not act on. Translated and
anonymised. This example is why rules 1, 3 and 8 exist.
## BEFORE - unreadable, though everything is technically present
The message opened with three paragraphs of what the agent had already tried:
a cloud CLI path that returned 403, a missing local database client, a second
attempt at the same workaround. Then, under a heading reading "What I need from
you - one command per host", it gave two nearly identical commands with
different IP addresses, separated by a sentence naming which database each one
wanted. It closed with a five-item plan mixing the agent's own next steps with
one item the user had to do, named mid-sentence.
**Defects**
| Defect | How it showed up |
|---|---|
| Ask buried behind diagnostics | Three paragraphs of failures before the request |
| Heading contradicts content | "one command per host" above two commands |
| Jargon inside the instruction | connection string, `sslmode`, Ctrl-D, `umask 077` |
| Two look-alike commands, unlabelled | Which address is the test server is only inferable from prose |
| No verification | Nothing said what success looks like |
| Agent's work mixed with the user's | "this one's on you" hidden inside a list item |
The fourth defect is not style. Swapping the order sends a live-environment
password to the test server.
## AFTER - os-step-by-step output
> **What I need from you: put the database password on two servers.**
>
> Why you and not me: it is a password. Passing through me, it would stay in the
> chat history and in the logs. And I have no database access - my key cannot
> see them.
>
> **Step 1. Get the first password.**
> In the hosting console, open Databases → the test database → Connection
> string. Copy the whole thing; it starts with `postgresql://`.
>
> **Step 2. Give it to the TEST server.**
> Paste this one line and press Enter - it will ask for the value, hide your
> typing, and confirm it saved:
> ```bash
> printf 'Paste the TEST connection string, then press Enter: '; IFS= read -rs V; echo; if [ ${#V} -lt 20 ]; then echo "Only ${#V} characters - looks truncated, nothing saved."; else printf '%s' "$V" | ssh root@<test-server> 'umask 077 && cat > /root/db_admin_dsn' && ssh root@<test-server> 'echo "Saved, $(wc -c < /root/db_admin_dsn) bytes"'; fi; unset V
> ```
>
> **Step 3. Repeat for the LIVE server.**
> A different password - take it from the live database. Do not mix them up:
> this one serves real users.
> ```bash
> printf 'Paste the LIVE connection string, then press Enter: '; IFS= read -rs V; echo; if [ ${#V} -lt 20 ]; then echo "Only ${#V} characters - looks truncated, nothing saved."; else printf '%s' "$V" | ssh root@<live-server> 'umask 077 && cat > /root/db_admin_dsn' && ssh root@<live-server> 'echo "Saved, $(wc -c < /root/db_admin_dsn) bytes"'; fi; unset V
> ```
>
> **How you'll know it worked.**
> Each command ends with "Saved, N bytes". "Only N characters" means the paste
> came in truncated - run it again. `Permission denied` - tell me.
>
> **What happens next, on my side.**
> Say "done with the passwords" - I grant the permissions, check that writing
> works and deleting is refused, then erase both password files.
## What this example fixed in the skill
1. Rule 1 - the ask moved to the top; the failed attempts were dropped entirely.
They were never information the user could use.
2. Rule 3 - each command now names its target in capital letters, with the
consequence of swapping them stated.
3. Rule 6 - "Saved, N bytes" is the check. Without it the user cannot tell a
successful step from a hung one.
4. The secrets section - "it would stay in the chat history and in the logs" is
the human version of "it does not pass through my context".
5. Rule 4 and the one-line commands - the first version of this very example
told the user to press Ctrl-D after `cat >`, exactly what the rule now
forbids. The command asks for the value itself and confirms by byte count.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |