Showsteps for agents

What you can do

• Validate and inspect a guide file.
• Rewrite step titles and descriptions, hide steps, regenerate titles.
• Export Markdown, self-contained HTML, PDF, DOCX, a Playwright script, or a replayable agent skill.
• Create a guide from steps you write (no screenshots needed), then hand the file to a person to open in the extension.

Everything works offline on local files. Passwords and other sensitive fields are never stored in a guide: typed values in those fields are masked as ••• and no tool prints them.

Files

A guide is either:

• something.showsteps: a zip with guide.json and images/<stepId>.png, or
• a bare guide.json. Screenshots are picked up from an images/ folder next to it, if present.

Every command and tool accepts both. The schema is versioned (v1). Key fields: title, and steps[] withid, action, target (name, role, locators), title, description,page.url and skipped. The steps.json written by the skill export follows a JSON Schema served at /schema/steps.schema.json.

CLI

npx -y @showsteps/cli --help

Rules you can rely on

• --json prints exactly one JSON object on stdout and nothing else. It always has "ok": true|false. Failures look like {"ok": false, "error": {"code": "invalid|usage|io", "message": "...", "errors": [...]}}.
• Human messages and errors go to stderr.
• Exit codes: 0 ok, 1 invalid input (bad guide, unknown step id, bad steps file), 2 usage error, 3 file error (missing or unwritable path).
• Relative paths resolve against the current directory.
• SOURCE_DATE_EPOCH fixes timestamps written by new and by edits, for reproducible output.

Export layout

--json returns {"ok": true, "files": ["/abs/path", ...]}. Steps with skipped: true are left out of every export.

Worked example

Every block below marked as runnable is executed by our checks, in this order, in an empty folder, and its output is compared with the command line's own golden files. Run them yourself in an empty folder and you get the same results. Paths in the output are absolute, so yours will differ.

1. Write a guide from scratch

steps.json can be an array, or an object with a title and steps:

{
  "id": "g_from_steps",
  "title": "Reset a password",
  "description": "Written by an agent.",
  "steps": [
    { "action": "navigate", "url": "https://app.example.test/login", "page": { "url": "https://app.example.test/login", "title": "Sign in" } },
    { "action": "click", "target": "Forgot password" },
    { "action": "type", "target": "Email", "value": "jane@example.test" },
    { "action": "type", "target": "New password", "masked": true },
    { "action": "click", "target": "Reset password" },
    { "action": "note", "title": "Check your inbox for the confirmation email.", "description": "It arrives within a minute." }
  ]
}

showsteps new --from-steps steps.json --out made.showsteps --json

Step fields: action (navigate, click, type, select, check,press, scroll, hover, note), title (generated when omitted, required fornote), description, target, url, value, optionText, key,checked, masked, page and skipped. Later steps inherit the last URL. Titles you give are treated as hand-edited and survive regen-titles. Every problem in the file is reported at once, so fix them in one pass.

Guides made this way have no screenshots. Exports still work, and a person can open the file in the extension to review it.

2. Check and inspect it

showsteps validate made.showsteps --json

showsteps info made.showsteps --json

showsteps steps made.showsteps --json

3. Fix wording, then export

showsteps edit-step made.showsteps --id s3 --title "Enter your work email" --description "Use the address you signed up with." --out reviewed.showsteps --json

showsteps regen-titles reviewed.showsteps --out regenerated.showsteps --json

showsteps export reviewed.showsteps --format md,skill --out out --json

4. What a failure looks like

A steps file is not a guide, so validating it fails. Exit code 1, one JSON object on stdout, the reasons on stderr:

showsteps validate steps.json --json

showsteps --help

MCP server

showsteps-mcp speaks MCP over stdio. It needs no network and no keys. Files are passed by absolute path.

claude mcp add showsteps -- npx -y @showsteps/mcp

{
  "mcpServers": {
    "showsteps": { "command": "npx", "args": ["-y", "@showsteps/mcp"] }
  }
}

Results are JSON in both the text content and structuredContent. Invalid guide content is reported as data byvalidate_guide. Everything else that fails (missing file, unknown step id, relative path, malformed steps) returnsisError: true with an error.code of invalid, usage or io and the list of problems.

edit_step and regenerate_titles overwrite the file unless you pass out_path. Preferout_path when a person has not asked you to change the original.

Working with people

The recording is a human’s account of a task. A sensible split: you fix wording, structure and exports; the person reviews screenshots and redactions in the extension (.showsteps files open there directly) before sharing. Send them the file path, not the contents.

See also: record a workflow as an agent skill and convert clicks to a Playwright test.