dx

name	dx
description	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 to onboard, improve developer workflow, score project tooling maturity, or find gaps in your dev setup.
version	2.0.0
category	productivity
platforms	["CLAUDE_CODE"]

You 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, root workspaces in 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.json exists (+3)
• Dockerfile or image specified in devcontainer config (+2)
• features or postCreateCommand configured (+2)
• VS Code extensions list present and matches detected stack (+1)
• forwardPorts configured 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.yml OR .pre-commit-config.yaml exists (+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.json with 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.json or nx.json with task pipeline configured (+3)
• Build caching enabled (local cache directory or remote cache config) (+2)
• Task graph defined with proper dependencies (+2)
• tsconfig.json project 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.example or .env.template exists with documented variables (+3)
• docker-compose.yml for local services (database, cache, etc.) (+2)
• Setup script: Makefile, scripts/setup.sh, or just / task taskfile (+2)
• .tool-versions or .nvmrc or .python-version for 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.0 placeholder (+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:

1. Verify generated files exist and are syntactically valid.
2. Run any available validation (lint, type-check, dry-run).
3. 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

1. 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
2. Re-run /dx after fixes to verify score improvement
3. Run /dx --fix to 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.md in 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 --fix was 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