Turn a recording you already have into an agent skill

The command

npx github:ykzeng-yale/skill-md convert recording.json

It prints the SKILL.md to your terminal. Add --out SKILL.md to write a file instead. It is a zero-dependency Node script under an MIT licence — it runs on your machine, reads one local file, and sends nothing anywhere. There is no key to get and nothing to sign up for.

It accepts two formats, and works out which one you gave it by looking at the contents rather than the file extension:

• Chrome DevTools Recorder — open DevTools, go to the Recorder panel, record your flow, then export as JSON.
• Selenium IDE — any saved .side project file.

What comes out

Here is a real conversion, not a mock-up. Input: an eight-step Chrome Recorder export of logging an expense. Output, verbatim:

---
name: log-expense-in-concur
description: Replay a www.concursolutions.com workflow recorded in Chrome DevTools
apps: [Chrome, www.concursolutions.com]
---

# Log expense in Concur

> Converted from a Chrome DevTools Recorder export by skill-md.

## Prerequisites

- Google Chrome
- Access to www.concursolutions.com

## Workflow Steps

### Step 1: Open www.concursolutions.com

Navigate to https://www.concursolutions.com/expense.

### Step 2: Click New Expense

Click "New Expense".

### Step 3: Fill in Expense name

Type "Client lunch" into "Expense name".

### Step 4: Fill in Amount

Type "42.50" into "Amount".

### Step 5: Click Save

Click "Save".

## Notes

3 browser-level steps (viewport, key-up, tab close) were omitted — they describe the browser rather than the task.

Eight recorded steps became five instructions. That reduction is the interesting part.

Why it reads in words, not selectors

A recording stores several ways to find each element. Chrome saves an accessibility label alongside the CSS selector, so the same click is available as both aria/New Expense and #new-exp-btn. The converter prefers the label, which is why a step says Click "New Expense" and not Click #new-exp-btn.

This matters more than it looks. A skill is read by a language model and by the person maintaining it. A list of CSS selectors is neither readable nor durable — it breaks the next time a developer renames a class, and when it breaks nobody can tell what it was supposed to do. A label survives a redesign more often, and when it does break the step still says what you were trying to achieve. Selenium locators are ranked the same way: link text and field names first, CSS and XPath only as a last resort.

What gets dropped, and why that is deliberate

Both converters remove things, and always report the count in a Notes section so the omission is visible rather than silent.

• Browser plumbing. Setting the viewport, releasing a modifier key, closing the tab. A person replaying your task does not "set viewport" — those steps describe the browser, not the work.
• Assertions, from Selenium only. This one is a judgement call worth stating plainly: assertText and friends are dropped, with a count. A test checks that something is true; a skill describes what to do. Turning an assertion into an instruction would invent a step nobody ever performed. If a check matters to you, add it back as a note in your own words.
• Test scaffolding. Stored variables, injected scripts, waits, frame switching.

Steps are renumbered after removals, because a gap in the sequence reads to an agent as a step it failed to load.

The converter also validates its own output before writing, so it cannot emit a file that the published validator would reject. You can check any skill yourself with npx github:ykzeng-yale/skill-md validate SKILL.md.

When this is the wrong tool

Three cases where you should not use it, and what to use instead:

• Your work is not in a browser, or you have not recorded anything yet. Chrome Recorder only captures one tab, and Selenium IDE only captures web pages. If the task spans a desktop application, a PDF, a spreadsheet and three tabs, there is no export to convert — record your screen instead, which is what SkillForge itself does.
• You want the skill to interpret a page rather than follow steps. This converter is deterministic: it maps recorded actions onto sentences and makes no guesses. If you want a model to watch a demonstration and infer intent, adaptive locators and verification steps, that is a different and genuinely useful approach — tools such as Playwriter's skill recorder do it, at the cost of needing an agent and an API key in the loop.
• You actually want a test. If you need pass/fail, assertions and CI reporting, keep your Selenium suite. Converting it to a skill throws away exactly the part that makes it a test.

Why we built this

We sell a screen recorder, so the honest admission is that this tool competes with our own funnel: it produces a SKILL.md without us. We built it anyway, because asking someone to grant screen-capture permission to a site they met a minute ago is a large request, and plenty of people have a recording already sitting on disk. The format is open and so is the converter. If it is all you need, use it and keep nothing from us.

FAQ

Does my recording get uploaded anywhere?
No. The converter is a local Node script with no network calls at all. It reads the JSON file you point it at and prints markdown. Nothing leaves your machine, and there is no account.

Do I need SkillForge to use this?
No. The converter and the SKILL.md spec are both MIT-licensed and work standalone. SkillForge is useful when there is no recording to convert because the work is not confined to a browser tab.

How do I export from Chrome DevTools Recorder?
Open DevTools, choose the Recorder panel, click Create a new recording, perform your flow, then stop and use the export button to save it as a JSON file. Pass that file to the convert command.

My Selenium project has several tests. Which one is converted?
The first one, and the command tells you the names of the others. Use --test followed by the test name to convert a specific one.

Why were my assertions removed?
Because a skill is a procedure, not a test. An assertion records something you wanted to be true, not an action you performed, so emitting it as a step would describe work that never happened. The count is reported in the Notes section so you can add the important checks back in your own words.