agent-dx

Files (4)

• SKILL.md
• sample-report.md · examples/
• agent-commands.md · references/
• tool-matrix.md · references/

SKILL.md (first lines)

# agent-dx — Agent Developer Experience Audit

Analyze a repo and generate a prioritized report of verification tools coding agents need to self-check their work. Report-only — recommends tools and commands, does not auto-install.

## How It Works

1. Detect project language, framework, and runtime
2. Scan for existing verification tools
3. Generate a Markdown report with prioritized recommendations
4. Include copy-paste install commands and agent-friendly run commands

## Step 1: Detect Project Context

Read these files to understand the project:

```
package.json                    # JS/TS: deps, devDeps, scripts, workspaces
tsconfig.json                   # TypeScript config
bun.lockb / bun.lock            # Bun runtime
pnpm-lock.yaml                  # pnpm
yarn.lock                       # Yarn
package-lock.json               # npm
pyproject.toml                  # Python: deps, tools
requirements.txt                # Python: deps
setup.py / setup.cfg            # Python: legacy
Cargo.toml                      # Rust
go.mod                          # Go
.github/workflows/*.yml         # CI configuration
CLAUDE.md                       # Project-level agent context
~/.claude/CLAUDE.md             # Global agent context
```

**Determine language:**
- `package.json` exists → JS/TS
- `pyproject.toml` or `requirements.txt` or `setup.py` → Python
- `Cargo.toml` → Rust
- `go.mod` → Go
- No manifest → scan file extensions as fallback

**Determine package manager / runtime** (JS/TS only):
- `bun.lockb` or `bun.lock` exists → already using Bun
- `pnpm-lock.yaml` exists → already using pnpm
- `yarn.lock` exists → already using Yarn
- `package-lock.json` exists → already using npm
- None of the above → recommend **Bun** (see `references/tool-matrix.md` for rationale)

**Determine framework** (from dependencies):
- `electron` → Electron (dual runtime: Node + Chromium)
- `react` → React
- `next` → Next.js
- `vue` → Vue
- `svelte` → Svelte
- `express` / `fastify` / `koa` → Node API server
- `django` / `flask` / `fastapi` → Python web framework

**Determine monorepo:**
- `workspaces` field in `package.json`
- `pnpm-workspace.yaml` exists
- `lerna.json` exists
- `nx.json` exists
- `turbo.json` exists

If monorepo detected, analyze root config + each workspace independently.

## Step 2: Scan Existing Tools

Use `references/tool-matrix.md` for the full lookup table of tools per language.

For each category in the tool matrix:
1. Check `devDependencies` in `package.json` (JS/TS) or `pyproject.toml` `[tool.*]` sections (Python)
2. Check for config files (e.g., `vitest.config.*`, `tsconfig.json`, `biome.json`)
3. Check `package.json` scripts for: `test`, `lint`, `typecheck`, `e2e`, `format`, `check`
4. **Scan `.github/workflows/*.yml` for CI steps** — if a tool already runs in CI, mark it as "CI-covered" not "Missing". Only recommend tools not already covered by CI.

## Step 2b: Audit CLAUDE.md Files

Check for agent context files at two levels:

**Project-level:** `CLAUDE.md` in the repo root (or `.claude/CLAUDE.md`)
**Global-level:** `~/.claude/CLAUDE.md`

### Project CLAUDE.md

Check if it exists. If it does, scan for these sections (doesn't need to match exactly — just check if the topics are covered):

| Topic | Why it matters for agents |
|-------|--------------------------|
| Project description / purpose | Agent understands what it's building |
| Tech stack / key dependencies | Agent picks the right tools and patterns |
| How to run the project (dev server, build) | Agent can test its changes |
| How to run tests | Agent knows the test command |
| How to lint / type check | Agent knows the verification commands |
| Code conventions / patterns | Agent follows the team's style |
| Directory structure overview | Agent finds files faster |
| Common gotchas / things to avoid | Agent avoids known pitfalls |

If project CLAUDE.md is missing, recommend creating one. If it exists but is **thin** (missing 3+ of the 8 topics above, or any topic covered in fewer than 50 words), note which topics are missing.

**Recommendation template for project CLAUDE.md:**
```markdown
# [Project Name]

[One-line description of what this project does]

## Tech Stack
- Runtime: [Bun / Node / Python / etc.]
- Framework: [React / Next / Django / etc.]
- Database: [Postgres / SQLite / etc.]

## Development
- `bun install` — install dependencies
- `bun dev` — start dev server
- `bun test` — run tests
- `bun run lint` — lint code
- `bun run typecheck` — type check

## Code Conventions
- [Key patterns, naming conventions, directory layout rules]

From seflless/dot-agents, MIT.

More from seflless/dot-agents