Agent skill

Dx Harness

by pproenca in pproenca/dot-skills

Developer-experience friction auditing and fixing — slow onboarding, repeated manual setup steps, missing bootstrap/reset/seed scripts, undiscoverable conventions.

MITAuto-check passedDevelopment

Install Dx Harness

skills CLI
$ npx skills add pproenca/dot-skills --skill dx-harness -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install pproenca/dot-skills dx-harness --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/pproenca/dot-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/.experimental/dx-harness .claude/skills/dx-harness && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
dx-harness
GitHub stars
215
Token cost
~1.5k tokens
SKILL.md length
482 words
Files
28 (incl. scripts, references, assets)
Skills in repo
41
Repo updated
First seen
Licence
MIT

At a glance

Developer-experience friction auditing and fixing — slow onboarding, repeated manual setup steps, missing bootstrap/reset/seed scripts, undiscoverable conventions.

  • Phrases like audit dx
  • SKILL.md covers When to Apply, Workflow Overview, Tool Requirements and Risk Level, plus 5 more sections
  • Runs Shell scripts from its folder; calls bash
  • Fix dev friction

What it does

Dx Harness is an agent skill from pproenca/dot-skills. 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…

Its SKILL.md is about 1.5k tokens, which your agent loads only when the skill is triggered. The skill folder holds 31 other files, including scripts, reference files and assets (for example `config.json`, `gotchas.md` and `metadata.json`).

It sits in Development, covering Project scaffolding, Git worktrees and End-to-end testing. It works with Docker. The repository describes itself as: A collection of AI agent skills following the Agent Skills open format. The licence is MIT.

When your agent uses it

  • Phrases like audit dx
  • Fix dev friction
  • Time to first commit
  • Set up the harness

Example prompts

  • “audit dx”
  • “fix dev friction”
  • “time to first commit”
  • “/dx-harness”

Requirements

  • Python 3
  • A Bash shell
  • Docker

What it can do on your machine

Read from SKILL.md and the folder at commit cf93c57. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 3 files in scripts/ (Shell, from the files we listed), which the agent can run.

    Shell commands in SKILL.md call:

    • bash

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Dx Harness loads about 1.5k tokens when it runs, and up to ~8.1k if it reads all its reference files. Until then it costs about 182 tokens; SKILL.md has 482 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~182
When it runs · the whole SKILL.md, loaded when a task matches
~1.5k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~8.1k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from pproenca/dot-skills at commit cf93c57, republished under its MIT licence (© pproenca). 482 words, ~1,516 tokens.

Download SKILL.mdSave it as .claude/skills/dx-harness/SKILL.md (or your agent's skills folder). This skill also uses 27 other files; get the full folder from GitHub.
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):

ToolchainDetection signal
npm/pnpm/yarn/bunpackage.json, pnpm-lock.yaml, yarn.lock, bun.lockb
cargoCargo.toml
go modulesgo.mod
Python (uv/poetry/pip)pyproject.toml, uv.lock, poetry.lock, requirements.txt
justJustfile or justfile
makeMakefile
docker composedocker-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.

Show full SKILL.md (185 more words)Show less

Setup

On first invocation, the skill checks config.json and prompts via AskUserQuestion for any empty required fields. See 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 for full step-by-step orchestration, including error handling and when to stop and ask the user.

For deeper context:

FileRead When
references/workflow.mdExecuting the workflow (always start here)
references/audit-checklist.mdUnderstanding what audit.sh checks and why
references/fix-recipes.mdChoosing which scaffold script applies for a finding
references/attrition-patterns.mdReading git history for DX-rot signals

Gotchas

See gotchas.md — accumulated failure points discovered over time. Always append new ones rather than rewriting.

  • 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. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 27 other files (scripts, references, assets) in skills/.experimental/dx-harness of pproenca/dot-skills.

  • SKILL.md
  • assets/templates/AGENTS.md.tmpl
  • assets/templates/Justfile.tmpl
  • assets/templates/Makefile.tmpl
  • assets/templates/bootstrap.sh.tmpl
  • assets/templates/reset.sh.tmpl
  • assets/templates/seed.sh.tmpl
  • config.json
  • gotchas.md
  • metadata.json
  • references/attrition-patterns.md
  • references/audit-checklist.md
  • references/fix-recipes.md
  • references/workflow.md
  • scripts/audit.sh
  • scripts/discover.sh
  • scripts/lib
  • … and 11 more

Open the folder on GitHubat commit cf93c57

Compare with similar skills

Dx Harness next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Dx Harness compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Dx Harness this skillpproenca/dot-skills215—~1.5kAutomated safety check: PassMIT
Superset Project Setupsuperset-sh/superset15k—~577Automated safety check: NotesCustom licence
Start Tempsgotempsh/temps826—~5.4kAutomated safety check: PassApache-2.0
Build Px4 macOSPX4/PX4-Autopilot13k—~1.1kAutomated safety check: PassBSD-3-Clause
Development WorkflownelsonPires5/herdr-board170—~2.4kAutomated safety check: PassNone
Tnr Dev Serverstudie-tech/TheNinjaRPG104—~2.5kAutomated safety check: NotesNone

Similar skills

  • Superset Project Setup

    superset-sh/superset

    Makes a repository Superset-ready by writing .superset/config.json with setup, teardown and run scripts, then proving it with a real throwaway workspace.

    15k GitHub stars~577 tokensUpdated today
    DevelopmentAuto-check: notes
  • Start Temps

    gotempsh/temps

    Start (or restart) a local Temps control plane built from this checkout, and the web dev server (bun dev) in <checkout/web.

    826 GitHub stars~5.4k tokensUpdated today
    DevelopmentAuto-check passed
  • Build Px4 macOS

    PX4/PX4-Autopilot

    Build PX4 board firmware on macOS in the px4-dev Docker container, including git worktrees, and stage commit-labeled artifacts without flashing hardware.

    13k GitHub stars~1.1k tokensUpdated today
    DevelopmentAuto-check passed
  • Development Workflow

    nelsonPires5/herdr-board

    Default sandbox-first developer workflow for herdr-board. An agent skill from nelsonPires5/herdr-board.

    170 GitHub stars~2.4k tokensUpdated yesterday
    Testing & QAAuto-check passed
  • Tnr Dev Server

    studie-tech/TheNinjaRPG

    Run a TheNinjaRPG dev server locally from any git worktree, provision disposable test users, and call tRPC endpoints as those users.

    104 GitHub stars~2.5k tokensUpdated today
    DevelopmentAuto-check: notes
  • Agents Generator

    sickn33/agentic-awesome-skills

    Generate project-specific AGENTS.md and companion rules by analyzing a codebase.

    47k GitHub starsUsed in 1 repo~2.3k tokens
    DevelopmentAuto-check: notes

More from pproenca/dot-skills

All 41 skills in this repo
  • Audio Voice Recovery

    pproenca/dot-skills

    Audio forensics and voice recovery guidelines for CSI-level audio analysis.

    215 GitHub stars~3.3k tokensUpdated 1 mo ago
    Auto-check passed
  • Codemod React Pipeline

    pproenca/dot-skills

    Guided, scripted pipeline for running JSX/TSX/React codemods safely across large legacy codebases.

    215 GitHub stars~1.6k tokensUpdated 1 mo ago
    Auto-check passed
  • Dev Rfc

    pproenca/dot-skills

    Create well-structured RFCs and technical proposals for software projects.

    215 GitHub stars~3.8k tokensUpdated 1 mo ago
    Auto-check passed
  • Language Spec Author

    pproenca/dot-skills

    Turn a rough idea for a language into a complete, implementable specification — a DSL, query, config/data, template, or protocol language — by interviewing the author dimension by dimension until…

    215 GitHub stars~2.4k tokensUpdated 1 mo ago
    Auto-check passed
  • Python Pep Author

    pproenca/dot-skills

    Drafting Python Enhancement Proposals (PEPs) — proposing a Python language feature, a standard library change, an interoperability standard, or an informational/process document for the Python…

    215 GitHub stars~2.1k tokensUpdated 1 mo ago
    Auto-check passed
  • Designs new features, extensions, or modifications to Uncle Bob's Acceptance Pipeline Specification — new mutation strategies, Gherkin syntax support, report formats, pipeline stages, IR fields, or…

    215 GitHub stars~1.5k tokensUpdated 1 mo ago
    Auto-check passed

Works with

Questions about Dx Harness

What does Dx Harness do?

Developer-experience friction auditing and fixing — slow onboarding, repeated manual setup steps, missing bootstrap/reset/seed scripts, undiscoverable conventions. Dx Harness is an agent skill from pproenca/dot-skills. Developer-experience friction auditing and fixing — slow onboarding, repeated manual setup steps, missing bootstrap/reset/seed scripts, undiscoverable conventions.

When should I use Dx Harness?

Dx Harness fits situations like: phrases like audit dx; fix dev friction; time to first commit; set up the harness.

How do I install Dx Harness in Claude Code?

Run `npx skills add pproenca/dot-skills --skill dx-harness -a claude-code`. Or copy the skill folder (skills/.experimental/dx-harness in pproenca/dot-skills) into .claude/skills/dx-harness in your project. Claude Code loads it when a task matches its description.

How do I install Dx Harness in Codex?

Run `npx skills add pproenca/dot-skills --skill dx-harness -a codex`. Or copy the skill folder (skills/.experimental/dx-harness in pproenca/dot-skills) into .agents/skills/dx-harness in your project. Codex loads it when a task matches its description.

Can I use Dx Harness in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add pproenca/dot-skills --skill dx-harness -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/dx-harness, .gemini/skills/dx-harness, .github/skills/dx-harness and .opencode/skills/dx-harness in your project.

What does Dx Harness need to run?

Going by SKILL.md and its folder, Dx Harness needs a shell for the scripts in its folder and the command-line tools its instructions call (bash). Our summary lists: Python 3; A Bash shell; Docker.

Does Dx Harness access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Dx Harness safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Dx Harness use?

Dx Harness is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Dx Harness use?

About 1.5k tokens (SKILL.md is roughly 6.1k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 6.5k tokens, read only when the agent opens those files.

What are the alternatives to Dx Harness?

Skills that share tags, products or a category with Dx Harness: Superset Project Setup (superset-sh/superset, 15k stars), Start Temps (gotempsh/temps, 826 stars), Build Px4 macOS (PX4/PX4-Autopilot, 13k stars) and Development Workflow (nelsonPires5/herdr-board, 170 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Dx Harness?

pproenca (a GitHub user) maintains it in pproenca/dot-skills, which has 215 GitHub stars. The repository holds 41 skills in this directory. The repository was last updated on August 15, 2026.

Source: pproenca/dot-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.