Skip to main content
skill CX Codex

dx-audit · dotslashsimran — Claude Code skill: DX audit and install

dx-audit — a Claude Code skill audits the onboarding path for an SDK, API, CLI, or framework using its official docs. It follows one task in a clean environment and records friction, errors, and time to first success.

MIT ★ 541 updated 2026-11-09

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add dotslashsimran/simcraft --skill dx-audit -a claude-code
Open on GitHub

What dx-audit does

The skill tests a developer tool by following its official documentation in a clean environment. It records each action, elapsed time, errors, and page switches, then grades three error messages. The final teardown includes suggested changes to docs and error text.

The skill includes friction.py, snapshot.mjs, and reference.md with tag definitions and a grading rubric. Page snapshots need Node and the repository's playwright package; if the package does not resolve, the instructions call for npm install in ~/simcraft. friction.py uses Python's standard library. The audit runs in a separate temporary directory and an isolated environment.

If a task requires signup, an API key, payment card, or approval, the skill stops at that barrier and asks whether to continue once a key is available. It does not enter real credentials. Creating journey.mp4 is optional and requires ffmpeg or $FFMPEG.

What it helps with

  • test whether a newcomer can complete an SDK quickstart
  • log setup steps and failures for a CLI
  • find gaps in docs for a specific first task
  • grade error messages and draft replacements

Example prompts for the agent

  • Audit this SDK's onboarding by following the official docs in a clean environment.
  • Try this CLI as a new developer and log every failure.
  • Write a DX teardown of this API for its DevRel team, with documentation fixes.

How to install dx-audit

1Skills CLI (Vercel)

npx skills add dotslashsimran/simcraft --skill dx-audit -a claude-code

2Manually: put the files in place

~/.claude/skills/dx-audit/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/dx-audit/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about dx-audit

How do I install dx-audit in Claude Code?

Run npx skills add dotslashsimran/simcraft --skill dx-audit -a claude-code. The skill file is at ~/.claude/skills/dx-audit/SKILL.md.

What does dx-audit do?

It follows official docs through one developer task, logs steps and friction, and produces a teardown with proposed edits to documentation and error messages.

What does dx-audit need to run?

Page snapshots need Node and the repository's playwright package; if it does not resolve, run npm install in ~/simcraft. friction.py uses Python's standard library. Optional video generation needs ffmpeg or $FFMPEG.

Source text

SKILL.md · MIT
---
name: dx-audit
description: Audit the developer experience of a developer tool (SDK, API, CLI, framework) by trying it exactly like a brand-new developer, from the official docs only, in a fresh empty environment. Logs every step with timestamps and friction tags, measures time to first success, steps, page switches, errors and lines of code, finds where people would give up, grades three error messages, and writes a fair teardown with the top 5 fixes as ready-to-paste doc and error rewrites. Use when the user says "audit the developer experience of X", "DX teardown", "DX audit", "try this SDK like a new user", "onboarding friction", "time to first success", "how good are X's docs", or wants a teardown to send to a company's DevRel team.
---

# DX audit

You play a competent developer who has never seen this tool. You follow the official docs literally, write down everything that happens, and turn it into a teardown the company's DevRel team would want to read. The output is evidence, not opinion: every complaint has a timestamp, a URL, the exact output, and a fix.

Scripts (Python is standard library only, Node uses the repo's `playwright`):
```
python3 ~/simcraft/skills/coding/dx-audit/scripts/friction.py   # written "friction.py" below
node ~/simcraft/skills/coding/dx-audit/scripts/snapshot.mjs      # written "snapshot.mjs" below
```
If `playwright` does not resolve, run `npm install` in `~/simcraft` once. Read `reference.md` for the tag definitions, grading rubric, time model and a worked example.

## 1. Set up (ask the user, one question at a time)

1. **The tool and ONE goal.** A real first task, such as "send my first traced LLM call", "deploy hello world", "create a project and add a package". Not "evaluate everything".
2. **Success, defined before you start.** One observable result: an exact output, an HTTP 200, a trace visible in a dashboard. Write it down. Do not change it halfway to make the run look better.
3. **The entry point.** Where a newcomer lands: usually the docs home or the "Quickstart" link on the homepage.

## 2. A clean environment

- A fresh empty temp folder, never inside a real project.
- Hide what this machine already has. The cheapest way: run every command with an empty home and a bare PATH, e.g. `env -i HOME=$SB/home PATH=/usr/bin:/bin TERM=dumb /bin/zsh -c '...'`. Use Docker (`docker run --rm -it python:3.12-slim`) or a new venv when the tool needs it. Never let an installer touch the user's real home folder or shell config.
- Write the environment down (OS, shell, runtime versions) with `--env` at init.
- Use only what the docs tell you. If you know a shortcut from training, don't use it; if the docs miss a step, that is a finding.

```
friction.py init <audit_dir> --tool "<name>" --goal "<goal>" --success "<exact result>" --docs <entry url> --env "<os, shell, versions, sandbox>" --redact "<sandbox path>=~"
```
`--redact` scrubs your sandbox path from everything saved. The home folder and login name are always scrubbed.

## 3. Follow the docs literally

For every page you open:
```
snapshot.mjs <url> <audit_dir> --links --copy --name 02-quickstart
```
It saves a screenshot, the page text (`snapshots/<name>.md`, read this instead of guessing), every code block, every link with dead ones re-checked in a real browser, and what each copy button really puts on the clipboard. Name snapshots in order (`01-`, `02-`) so the screenshots tell the story.

For every action, log it as you go, not afterwards:
```
friction.py step <dir> --url <page> --action "Open the quickstart from the home page" --shot screenshots/02-quickstart.png
friction.py run  <dir> --url <page> --action "Install the SDK" --cwd <work> --show "pip install foo" -- "<real wrapped command>"
friction.py step <dir> --url <page> --action "Write app.py from the docs snippet" --loc 6
friction.py run  <dir> --url <page> --action "Run the example" --cwd <work> --show "python app.py" --success-if-ok -- "<command>"
```
`run` executes the command, saves the output to `outputs/`, times it, and marks a non-zero exit as an error. `--show` is what the developer typed when your real command is wrapped in a sandbox.

When something goes wrong or feels wrong, tag it right away with a fix:
```
friction.py amend <dir> 4 --tag missing-step --sev 2 --note "what happened, quoting the output" --fix "the exact text or change that would have prevented it"
```
Tags: `missing-step`, `wrong-snippet`, `unclear-error`, `version-mismatch`, `auth-wall`, `naming-confusion`, `slow-feedback`, `dead-link`, `copy-paste-hazard`, `other`. Severity: 1 annoying, 2 costs real time, 3 likely to make people quit.

Rules while following:
- Do exactly what the page says, in order. When the docs are wrong, first log what happens when you follow them, then recover the way a newcomer would (reread the output, search the same docs) and log each recovery step. Leaving the docs for GitHub issues or a search engine is a context switch: log it with its URL.
- Copy code with what the copy button gives (the `--copy` result), not a cleaned-up version.
- Count lines of code you write or edit with `--loc`.

## 4. Walls: stop and ask

Never type real credentials, card details, or a phone number, and never create an account on the user's behalf. When the path needs a signup, an API key, a card, or an approval:
1. Log it: `friction.py step <dir> --url <page> --action "Needs an API key" --outcome blocked --tag auth-wall --sev <n> --note "..."` with a screenshot. Note what the wall asks for, whether there is a free tier or test mode, and how many steps it adds.
2. Ask the user whether they want to get a key themselves and put it in an env var for you, or whether the audit ends at the wall. A wall with no sandbox key or test mode is itself a top finding.

## 5. Break it on purpose: three error checks

After success (or at the wall), make three common mistakes and grade what the tool says. Pick the three most likely for this tool, usually: a wrong or expired key, a missing env var or config, and a wrong version (old runtime, incompatible package). For a tool without keys, use a typo in a name and a wrong file or path instead.
```
friction.py errcheck <dir> --mistake "Wrong API key" --cwd <work> --show "FOO_KEY=bad python app.py" -- "<command>"
friction.py grade <dir> 1 --what 2 --why 1 --fix 0 --note "what a newcomer would think" --better "a rewritten message that would score 6/6"
```
Each of what happened, why, and how to fix is scored 0 (missing or wrong), 1 (partly, or buried), 2 (clear and early). Test the fix the message suggests before you score it.

## 6. Write the teardown

```
friction.py metrics <dir>     # check the numbers
friction.py render <dir>      # audit.md skeleton, timeline.svg and timeline.png
friction.py reel <dir>        # optional: journey.mp4 from the step screenshots (ffmpeg, or $FFMPEG)
```
Look at `timeline.png` before using it. Then fill every TODO in `audit.md`:
- **Summary:** did a newcomer reach the goal, how long it took, where it hurt most, the one change that helps most.
- **The journey:** a few short paragraphs under the table, quoting exact output and linking screenshots.
- **Top 5 fixes:** ranked by impact over effort. Each has the current text, the problem in one sentence, and a rewritten doc snippet or error message ready to paste.
- **What they do well:** specific, with step numbers. Name what to keep so the fixes don't break it.

Deliverables in `<audit_dir>`: `audit.md`, `friction.json`, `timeline.png`, `screenshots/`, `snapshots/`, `outputs/`, and optionally `journey.mp4`. Do not publish `.redact.json`; it holds the private paths.

## Tone

Write for the company's DevRel team, so it can be published or sent as is. Be fair and specific. Credit what is good, and say it first if it is the bigger story. Every complaint comes with a fix. Quote output instead of describing it. No sarcasm, no "obviously", no guessing at internal reasons. Plain words, complete sentences. If the tool did well, say so plainly: a short teardown of a good tool is a good result.

## Before you hand it over

- Every number in the summary comes from `metrics`, and the time model is stated (render adds it).
- Every friction point has a URL, quoted output and a fix. Every error grade had its fix tested.
- No real keys, personal paths, or user names anywhere (`grep -r "$HOME" <dir>` finds nothing).
- Show the user `audit.md` and the timeline. Sending it to the company is the user's call.

© dotslashsimran · MIT · dotslashsimran/simcraft

Similar skills

SKILL.md skills catalog →

dx-audit by other authors comes first.

dx-audit mblode dx-audit reviews public APIs, error messages, CLI output and exported types against 38 rules. Handy before you ship a library or SDK. CX Codex +1 469installs minimal-run-and-audit lllllllama minimal-run-and-audit is a Claude Code skill that captures and standardizes evidence from deep learning reproduction runs, including inference, evaluation, and smoke tests. CX Codex +1 502,400installs seo-audit coreyhaines31 A skill for Claude Code, Codex, and Cursor that guides technical SEO audits. Diagnoses traffic drops, indexing issues, canonical tags, and multilingual setups. CX Codex +1 257,200installs browser-fingerprint-audit liarjsdev browser-fingerprint-audit audits browser fingerprints for internal contradictions using the liarjs CLI. It spots mismatches between browser JavaScript APIs and edge network data. CX Codex +1 132,900installs security-audit cloudflare security-audit reviews codebases and APIs for vulnerabilities using safe sandboxing. Fits pre-release security reviews, pen-test triage, and architecture checks. CX Codex +1 116,100installs audit-website squirrelscan audit-website is a Claude Code skill that audits a site and helps fix findings in its code. Start it to inspect a website or web app and work through the reported issues. CX Codex +1 75,200installs ponytail-audit DietrichGebert ponytail-audit is a Claude Code skill that audits a repository and ranks bugs, risks, and redundant code in a one-shot report without changing files. CX Codex +1 62,700installs

From the same set24

The whole set →
reverse-engineer-video The reverse-engineer-video Claude Code skill breaks down a reference clip into shots, camera moves and editing beats. Invoke it to inspect a cut, plan a remake or compare one with the original. CX Codex +1 ★ 541repo stars system-design-from-scratch system-design-from-scratch — a skill for Claude Code that builds minimal distributed architectures, verifies invariants under simulated node failures, and stress-tests them with real metrics. CX Codex +1 ★ 541repo stars paper-to-runnable The paper-to-runnable Claude Code skill turns a research paper into a minimal implementation of its central idea. It activates for requests to build or reproduce a paper, including from an arXiv link or local PDF. CX Codex +1 ★ 541repo stars codebase-map The codebase-map Claude Code skill maps an unfamiliar repository and traces a real request through it. Ask it to explain the project structure, locate a code path, or onboard a new teammate. CX Codex +1 ★ 541repo stars api-design-review api-design-review — a skill for Claude Code reviews HTTP APIs, SDKs, and CLIs. It runs when asked to assess an API design, inspect a spec, or judge whether a change is safe to ship. CX Codex +1 ★ 541repo stars code-loop The code-loop Claude Code skill turns three.js scenes and GLSL shaders into looping videos. It activates for requests to make generative animations or GIFs that repeat without a visible cut. CX Codex +1 ★ 541repo stars rough-cut This Claude Code skill builds a rough cut from talking footage. It kicks in for requests to trim pauses, filler words, repeats, or weak takes. CX Codex +1 ★ 541repo stars perspective-illusion This Claude Code skill creates looping illustrated 3D videos built around a perspective illusion. It activates for requests involving a dolly zoom, a flat-to-3D transition, or a similar optical-illusion clip. CX Codex +1 ★ 541repo stars

Project sponsors

Companies that keep this analytics open