dx
Audit developer experience and generate a DX health score. Evaluates devcontainer, git hooks, linting, build caching, environment setup, and release pipeline. Use when you want to check how easy it is
SKILL.mdproductivity/dx/SKILL.md
GitHubYou are in AUTONOMOUS MODE. Do NOT ask questions. Do NOT pause for confirmation. Execute every phase below in sequence, making decisions based on what you find.
============================================================ PHASE 0 — INPUT
$ARGUMENTS may contain:
--fix— automatically apply fixes and generate missing configs (default: report only)--focus=AREA— limit scan to a specific area:devcontainer,hooks,lint,env,monorepo,release--score-only— output just the numeric scores, skip recommendations
If no arguments are provided, run a full audit in report-only mode.
============================================================ PHASE 1 — STACK DETECTION
Detect the project stack by scanning for manifest files:
- Language:
package.json(Node/TS),pyproject.toml/requirements.txt(Python),go.mod(Go),Cargo.toml(Rust),pubspec.yaml(Flutter/Dart),Gemfile(Ruby) - Package manager:
package-lock.json(npm),yarn.lock(yarn),pnpm-lock.yaml(pnpm),bun.lockb(bun) - Framework: read dependencies for Next.js, Fastify, Django, FastAPI, etc.
- Monorepo:
turbo.json,nx.json,pnpm-workspace.yaml,lerna.json, rootworkspacesin package.json - CI provider:
.github/workflows/,.gitlab-ci.yml,.circleci/config.yml,Jenkinsfile,bitbucket-pipelines.yml
Record the detected stack — it drives all subsequent scoring.
============================================================ PHASE 2 — AUDIT SIX DX AREAS
Scan the project root and score each area on a 0-10 scale:
2.1 — Dev Container (0-10)
Check for:
.devcontainer/devcontainer.jsonexists (+3)Dockerfileorimagespecified in devcontainer config (+2)featuresorpostCreateCommandconfigured (+2)- VS Code
extensionslist present and matches detected stack (+1) forwardPortsconfigured for detected services (+1)- Docker Compose integration for multi-service setups (+1)
Score 0 if .devcontainer/ directory does not exist.
2.2 — Git Hooks (0-10)
Check for:
.husky/directory OR.lefthook.ymlOR.pre-commit-config.yamlexists (+3)- Pre-commit hook configured: lint + format (+2)
- Pre-commit hook runs type-check (+1)
- Commit-msg hook enforces conventional commits (+2)
- Lint-staged or equivalent for incremental checks (+1)
- Hook runner matches stack (husky for Node, pre-commit for Python, lefthook for polyglot) (+1)
Score 0 if no hook tooling is detected.
2.3 — Linting & Formatting (0-10)
Check for:
- Linter config exists:
.eslintrc.*/eslint.config.*/biome.json/ruff.toml/.golangci.yml/.rubocop.yml(+3) - Formatter config exists:
.prettierrc*/biome.json/pyproject.toml [tool.black](+2) - Editor config:
.editorconfig(+1) - VS Code settings:
.vscode/settings.jsonwith format-on-save (+1) - Lint script in package.json / pyproject.toml / Makefile (+1)
- No conflicting configs (e.g., ESLint + Biome overlapping) (+1)
- Config is current (ESLint 9 flat config, not deprecated
.eslintrc.json) (+1)
2.4 — Build Tooling & Caching (0-10)
Check for:
turbo.jsonornx.jsonwith task pipeline configured (+3)- Build caching enabled (local cache directory or remote cache config) (+2)
- Task graph defined with proper dependencies (+2)
tsconfig.jsonproject references (TypeScript composite builds) (+1)- Incremental builds configured (+1)
- Dev server script exists and uses watch mode (+1)
Score N/A if project is not a monorepo and has no build step.
2.5 — Environment Setup (0-10)
Check for:
.env.exampleor.env.templateexists with documented variables (+3)docker-compose.ymlfor local services (database, cache, etc.) (+2)- Setup script:
Makefile,scripts/setup.sh, orjust/tasktaskfile (+2) .tool-versionsor.nvmrcor.python-versionfor runtime pinning (+1)- Database migration tooling configured (Prisma, Alembic, goose, etc.) (+1)
- README has "Getting Started" section with fewer than 5 steps (+1)
2.6 — Release Pipeline (0-10)
Check for:
- Semantic-release or changesets or equivalent configured (+3)
- Conventional commits enforced (commitlint + husky or equivalent) (+2)
- CHANGELOG.md exists and appears auto-generated (+1)
- GitHub Actions / CI workflow for releases exists (+2)
- Version field in package.json / pyproject.toml / Cargo.toml is not
0.0.0placeholder (+1) - Git tags exist following semver pattern (+1)
============================================================ PHASE 3 — CALCULATE DX HEALTH SCORE
Compute the overall DX health score:
- Overall Score = average of all applicable area scores (skip N/A areas)
- Grade: A (9-10), B (7-8.9), C (5-6.9), D (3-4.9), F (0-2.9)
Classify each area:
- Strong (8-10): well-configured, no action needed
- Adequate (5-7): functional but has gaps
- Weak (2-4): partially set up, needs work
- Missing (0-1): not configured at all
============================================================ PHASE 4 — GENERATE RECOMMENDATIONS
For each area scored below 8, generate specific recommendations:
- What is missing and why it matters
- Estimated setup effort:
quick(< 5 min),medium(15-30 min),involved(1+ hr) - Which sub-skill to run:
/devcontainer,/git-hooks,/linter,/env-setup,/monorepo,/release - Priority:
critical(score 0-2),high(3-5),medium(6-7)
Sort recommendations by priority (critical first), then by effort (quick first).
If --fix was passed, automatically invoke the sub-skill for every critical and high priority area. Run them in sequence since some depend on others (e.g., /linter before /git-hooks).
============================================================ SELF-HEALING VALIDATION (max 2 iterations)
After completing, validate the output was produced correctly:
- Verify generated files exist and are syntactically valid.
- Run any available validation (lint, type-check, dry-run).
- If the skill produces configuration, verify it parses without errors.
IF VALIDATION FAILS:
- Diagnose from error context and re-generate the failing artifact
- Repeat up to 2 iterations
============================================================ OUTPUT
Print the DX Health Report:
## DX Health Report
### Project: {name}
### Stack: {language} / {framework} / {package-manager}
### Overall: {score}/10 ({grade})
| Area | Score | Status |
|------------------|-------|---------|
| Dev Container | X/10 | {status}|
| Git Hooks | X/10 | {status}|
| Lint & Format | X/10 | {status}|
| Build & Cache | X/10 | {status}|
| Environment | X/10 | {status}|
| Release Pipeline | X/10 | {status}|
### Recommendations (by priority)
1. {area} — {what's missing} — run `/sub-skill` ({effort})
2. ...
### Quick Wins (under 5 minutes)
- {actionable items that can be done immediately}
============================================================ NEXT STEPS
- Run individual sub-skills for areas that need improvement:
/devcontainer— generate dev container configuration/git-hooks— set up pre-commit and commit-msg hooks/linter— configure linting and formatting/env-setup— automate local environment bootstrap/monorepo— set up monorepo tooling and caching/release— configure automated release pipeline
- Re-run
/dxafter fixes to verify score improvement - Run
/dx --fixto auto-apply all critical and high priority fixes
============================================================ SELF-EVOLUTION TELEMETRY
After producing output, record execution metadata for the /evolve pipeline.
Check if a project memory directory exists:
- Look for the project path in
~/.claude/projects/ - If found, append to
skill-telemetry.mdin that memory directory
Entry format:
### /dx — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / {{N max}}
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}
Only log if the memory directory exists. Skip silently if not found. Keep entries concise — /evolve will parse these for skill improvement signals.
============================================================ DO NOT
- Do NOT modify any files unless
--fixwas explicitly passed - Do NOT score areas that are not applicable to the detected stack
- Do NOT recommend monorepo tooling for single-package projects
- Do NOT recommend tools that conflict with existing configs (e.g., Biome when ESLint is established)
- Do NOT inflate scores — be honest about gaps
- Do NOT skip the stack detection phase — every recommendation must be stack-appropriate