dx-harness — Claude Code skill: audit and fix dev friction
dx-harness — a skill for Claude Code, Cursor, and other IDEs that finds and fixes developer-loop friction — slow onboarding, repeated manual steps, missing bootstrap and reset scripts.
MIT 141 installs ★ 227 updated 2026-08-15
npx skills add pproenca/dot-skills --skill dx-harness -a claude-codeWhat dx-harness does
dx-harness scans the repository, identifies dev-experience bottlenecks, and generates canonical scripts: bootstrap.sh, reset.sh, seed.sh, an AGENTS.md file with agent entry points, and task-runner entries. Runs on Claude Code, Cursor, GitHub Copilot, Codex, Gemini CLI, and OpenCode.
The workflow has seven stages: discover toolchain and conventions, audit the repo with scored findings, rank issues by impact, scaffold fixes into a scratch directory, show diffs for user approval, verify the harness end-to-end in an isolated git worktree, and log attrition history. All changes land in a sandbox first—the user picks what to apply.
Requires bash, git, node, and jq. Auto-detects npm, yarn, pnpm, bun, cargo, go modules, Python (uv, poetry, pip), just, make, docker compose, and Postgres. Default goal is 60-second bootstrap. Does not delete data or force-push.
What it helps with
- speed up developer onboarding to first commit
- eliminate repeated setup steps before work begins
- add missing bootstrap, reset, and seed scripts
- detect and track dev-practice drift over time
- make agent entry points explicit in AGENTS.md
Example prompts for the agent
- Audit dev friction: 'New developers take three hours to set up. Find the bottlenecks.'
- Close a manual-step gap: 'I always run these three commands first. Write me a script.'
- Measure time-to-first-commit: 'How long does a newcomer take to land a first PR? Check it against 60 seconds.'
How to install dx-harness
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill dx-harness -a claude-code2Manually: put the files in place
~/.claude/skills/dx-harness/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/dx-harness/
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill dx-harness -a codex2Manually: put the files in place
.agents/skills/dx-harness/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill dx-harness -a cursor2Manually: put the files in place
.cursor/skills/dx-harness/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install pproenca/dot-skills skills/.experimental/dx-harness2Manually: put the files in place
.github/skills/dx-harness/SKILL.md1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill dx-harness -a gemini-cli2Platform CLI
gemini skills install https://github.com/pproenca/dot-skills --path skills/.experimental/dx-harnessManually: put the files in place
.devin/skills/dx-harness/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill dx-harness -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about dx-harness
How do I install dx-harness in Claude Code?
Run npx skills add pproenca/dot-skills --skill dx-harness -a claude-code, then open ~/.claude/skills/dx-harness/SKILL.md. For other IDEs, use the matching flag: -a cursor for Cursor, -a codex for Codex, -a gemini-cli for Gemini CLI.
What does dx-harness do?
Scans your repo, finds dev-loop friction (slow setup, manual steps), generates bootstrap.sh, reset.sh, seed.sh, and AGENTS.md, then verifies everything in an isolated sandbox. It does not touch your code—all output lands in a scratch directory that you review and approve before applying.
What do I need installed to run it?
bash, git, node, and jq are required. The skill auto-detects npm, yarn, pnpm, bun, cargo, go modules, Python, just, make, docker compose, and Postgres—it adapts to whatever toolchain is in your repo.
Source text
SKILL.md · MIT
---
name: dx-harness
description: Developer-experience friction auditing and fixing — slow onboarding, repeated manual setup steps, missing bootstrap/reset/seed scripts, undiscoverable conventions. Audits the repo, scores findings, scaffolds canonical fixes (bootstrap.sh, reset.sh, seed.sh, AGENTS.md, task-runner entries), then verifies the harness end-to-end in a scratch worktree against a 60-second time-to-first-commit target. Triggers on phrases like "audit dx", "fix dev friction", "time to first commit", "set up the harness", "I keep doing X manually", "every time I reset the db I have to...", and on new-repo bootstrapping. Even if the user doesn't say "DX" — if they describe a repeated manual chore in their dev loop, this skill applies.
---
# DX Harness
Audits, scaffolds, and maintains the developer-experience harness of a repository. The harness is the meta-tooling that makes a dev loop fast: one-command bootstrap, one-command reset, one-command seed, discoverable conventions, agent-friendly entry points.
This skill exists because dev-experience attrition is real: harnesses rot, manual steps creep back in, conventions drift, and the cost is paid in micro-friction every day. The skill detects attrition systematically and applies canonical fixes.
## When to Apply
Trigger this skill when:
- A user describes a **repeated manual chore** ("every time I reset the db I have to re-register", "I always run these three commands before working")
- A user mentions **slow onboarding** or asks "how do I get this running"
- A new repo is being **bootstrapped** and needs a harness from day one
- A user explicitly asks to **audit DX** or **measure time-to-first-commit (TTFC)**
- A user asks to **fix** missing bootstrap/reset/seed scripts or AGENTS.md
- A periodic **maintenance pass** is needed (e.g., after a release, after onboarding a new engineer)
## Workflow Overview
```
┌────────────────────────────────────────────────────────────┐
│ 1. DISCOVER scripts/discover.sh → repo-fingerprint │
│ 2. AUDIT scripts/audit.sh → dx-audit.json │
│ 3. PRIORITIZE scripts/prioritize.sh → ranked findings │
│ 4. SCAFFOLD scripts/scaffold-*.sh → scratch dir │
│ 5. CONFIRM show diff to user; user picks what to apply│
│ 6. VERIFY scripts/verify.sh → assertions + timing │
│ 7. TRACK scripts/track-attrition.sh → audit log │
└────────────────────────────────────────────────────────────┘
```
All scaffolded edits land in a scratch directory first (`${TMPDIR}/dx-harness-<timestamp>/`). The user reviews the diff and chooses what to copy back into the repo. No surprise writes to the working tree.
## Tool Requirements
Required: `bash`, `git`, `node`, `jq`.
Detected at runtime (the skill adapts — it never forces a migration):
| Toolchain | Detection signal |
|-----------|------------------|
| npm/pnpm/yarn/bun | `package.json`, `pnpm-lock.yaml`, `yarn.lock`, `bun.lockb` |
| cargo | `Cargo.toml` |
| go modules | `go.mod` |
| Python (uv/poetry/pip) | `pyproject.toml`, `uv.lock`, `poetry.lock`, `requirements.txt` |
| just | `Justfile` or `justfile` |
| make | `Makefile` |
| docker compose | `docker-compose.yml`, `compose.yaml` |
| database (postgres) | `docker-compose.yml` services, `DATABASE_URL` env reference |
## Risk Level
**Write.** The skill writes files but does not delete user data, force-push, or run destructive ops. Default mode stages everything in a scratch directory; the user explicitly approves each application. Verification runs in a separate git worktree so timing measurements never touch the working tree.
## Setup
On first invocation, the skill checks `config.json` and prompts via `AskUserQuestion` for any empty required fields. See [config.json](config.json) for fields and defaults.
Key defaults:
- `ttfc_target_seconds: 60` — the time-to-first-commit goal in seconds
- `apply_mode: "scratch"` — scaffolded edits go to scratch dir first; user copies in
- `audit_log_path: "${CLAUDE_PLUGIN_DATA}/dx-harness/audits.log"` — persistent attrition history
## Quick Reference
### Run a full audit + scaffold pass
```bash
bash scripts/discover.sh > /tmp/fingerprint.json
bash scripts/audit.sh /tmp/fingerprint.json > /tmp/audit.json
bash scripts/prioritize.sh /tmp/audit.json
```
### Scaffold one specific harness piece
```bash
bash scripts/scaffold-bootstrap.sh /tmp/fingerprint.json
bash scripts/scaffold-reset.sh /tmp/fingerprint.json
bash scripts/scaffold-seed.sh /tmp/fingerprint.json
bash scripts/scaffold-agents-md.sh /tmp/fingerprint.json
bash scripts/scaffold-justfile.sh /tmp/fingerprint.json
```
### Verify the harness works end-to-end
```bash
bash scripts/verify.sh
# runs bootstrap in a scratch worktree, times it, asserts TTFC < target
```
### Track attrition over time
```bash
bash scripts/track-attrition.sh /tmp/audit.json
# appends to audits.log, prints diff vs previous run
```
## How to Use
The workflow scripts produce JSON between steps so they compose. The agent should read [references/workflow.md](references/workflow.md) for full step-by-step orchestration, including error handling and when to stop and ask the user.
For deeper context:
| File | Read When |
|------|-----------|
| [references/workflow.md](references/workflow.md) | Executing the workflow (always start here) |
| [references/audit-checklist.md](references/audit-checklist.md) | Understanding what `audit.sh` checks and why |
| [references/fix-recipes.md](references/fix-recipes.md) | Choosing which scaffold script applies for a finding |
| [references/attrition-patterns.md](references/attrition-patterns.md) | Reading git history for DX-rot signals |
## Gotchas
See [gotchas.md](gotchas.md) — accumulated failure points discovered over time. Always append new ones rather than rewriting.
## Related Skills
- `dev-skill:*` — for creating new agent-friendly skills (often the *output* of an AGENTS.md scaffolding pass references skills)
- `bug-review` — pairs naturally: bad DX often surfaces as repeat bug categories
© pproenca · MIT · pproenca/dot-skills