Record a workflow once, get a SKILL.md your agent can follow

What a skill file is

An agent skill is a folder with a SKILL.md file: Markdown with a small header holding a name and a description, followed by instructions. Agents that support skills read the description to decide when a skill applies, then load the rest. Because it is plain Markdown, other agents and people can read it too.

Why record instead of writing it

Writing instructions for a web task from memory leaves gaps. You forget the menu that has to be open first, the exact label on the button, the step that only appears for admins. A recording has no gaps because it is what you actually did, in order, on the real page.

• Exact names. Each step is named from the page’s accessible name: Click Invite member, not “click the blue button”.
• Order and URLs. Page changes and tab switches are steps, so the agent knows where to start.
• Locators. Each step keeps the ways to find that element again: test id, role and name, label, then text, with CSS only as a last resort.
• Nothing sensitive. Values typed into password and card fields are never stored, so credentials do not end up in a file you commit.

What Showsteps exports

---
name: "invite-a-teammate"
description: "Replay or walk through the \"Invite a teammate\" workflow recorded in a browser (6 steps, starting at app.acme.test). Use when the user wants to do this task, check that it still works, or run it with Playwright."
---

# Invite a teammate

Invite a teammate to the Acme workspace with the Editor role.

Recorded with Showsteps on 28 September 2026: 6 steps across 1 tab, starting at https://app.acme.test/settings.

## How to use this skill

- **Replay it:** run `npx playwright test replay.spec.ts` in this folder (needs `@playwright/test` and a browser: `npx playwright install chromium`). The test opens its own tab, and follows tabs the recording opened.
- **Do it by hand or with a browser tool:** follow the steps below in order. `steps.json` lists the same steps with every recorded locator, best first, for tools that drive a browser directly.
- **If a step fails:** the page probably changed. Re-locate the element from its name and role instead of the CSS selector, and update `replay.spec.ts`.

## Steps

1. Go to **Settings** on Acme
   - URL: https://app.acme.test/settings
2. Click **Team**
   - Find it by: role "link" named "Team"
3. Click **Invite member**
   - Find it by: role "button" named "Invite member"
4. Type "jane@example.com" in **Email**
   - Find it by: label "Email"
5. Select **Editor** in **Role**
   - Find it by: label "Role"
6. Click **Send invite**
   - Find it by: role "button" named "Send invite"

## Files

- `replay.spec.ts`: Playwright test for the whole flow.
- `steps.json`: machine-readable steps (format `showsteps-steps`, version 1).

From recording to a working skill

1. Record the task in Chrome, slowly, with test data.
2. In the editor, delete any wrong clicks. Rewrite titles that describe mechanics instead of intent, and add note steps for expected results (A green banner reads Invite sent). Agents use these to know they succeeded.
3. Export as an agent skill. You get a folder with the three files.
4. Put the folder where your agent reads skills. For Claude Code that is a folder under .claude/skills/ in your project or home directory. Other tools have their own location; the file is plain Markdown either way.
5. Run npx playwright test replay.spec.ts once to confirm the steps still work. Do it again after the app changes.

Limits to know about

• A skill describes the interface as it was on the day you recorded. When the app changes, re-record or edit the affected step.
• It replays actions, it does not judge results. Add expectations where success matters.
• Credentials are not in the file. Your agent needs its own way to sign in, such as an existing session.
• The recording is a human’s account of a task. Review it before an agent acts on your behalf, especially for anything that spends money or deletes data.

Agents can edit the recording too

The same recording is a file. A command line and a local MCP server let an agent list steps, rewrite titles, validate the file and export, and create a guide from a list of steps it wrote, with no network and no API key. See the agents page for commands and tool names.