agent-native-dx

Files (26)

• SKILL.md
• agent-readiness-template.md · assets/
• AGENTS.md · assets/agent-sample/
• README.md · assets/agent-sample/
• core.py · assets/agent-sample/app/
• test_core.py · assets/agent-sample/tests/
• SKILL.md · assets/mcp-sample/.claude/skills/demo/
• .mcp.json · assets/mcp-sample/
• README.md · assets/mcp-sample/
• llms.txt · assets/mcp-sample/
• package.json · assets/mcp-sample/
• smoke.json · assets/
• trial-log.example.json · assets/
• trial-log.unregistered.json · assets/
• agent-audit.md · references/
• agent-entry-files.md · references/
• automation-safety.md · references/
• discoverability.md · references/
• machine-surfaces.md · references/
• standards.md · references/
• trial-protocol.md · references/
• agent_trial_driver.py · scripts/
• agent_trial_scorer.py · scripts/
• check_agent_readiness.py · scripts/
• check_decision_rule.py · scripts/
• check_protocol_example.py · scripts/

SKILL.md (first lines)

# Agent-Native DX

## Mission

Developers increasingly work through coding agents, not only terminals. Agent UX is product UX: an agent that cannot build, run, verify, or debug your product is a product defect, not a documentation footnote.

Treat every agent-visible surface — entry files, schemas, structured output, error codes, scripts, tests, repository structure — as part of product design. Audit it as a product, and recommend product changes rather than documenting around friction.

Read `references/standards.md` for the canonical thresholds, severity vocabulary, and release gates.

## Two audiences, one corpus

Humans and agents read the same repository. The corpus has two first-class audiences:

- **Humans** read prose, examples, and explainers.
- **Agents** read the same prose plus machine-readable complements: AGENTS.md/CLAUDE.md entry files, OpenAPI and JSON Schema, structured CLI output, stable error codes, MCP servers, Agent Skills, deterministic scripts, and discoverable tests.

Do not fork the corpus. Write one set of facts, and add machine-readable surfaces that state the same facts in agent-usable form. When prose and machine surface disagree, both lose to implementation truth — and the contradiction is a P1 finding.

For the human-facing documentation use the `developer-docs` skill if available. This skill audits and improves the agent-facing surfaces.

## Agent-native DX workflow

### 1. Score the repository and report

Start here on every invocation. Run the inventory, then read the gaps back to the user in
plain language before doing anything else.

```
python3 scripts/check_agent_readiness.py /path/to/repo
```

It scores 19 surfaces grouped by the three questions that decide whether an agent can work
in a repository at all, and prints a readiness percentage with a band:

- **Can an agent find its way around**: an entry file, machine-readable schemas, documented
  structured output and exit codes, discoverable tests, a README, a build manifest.
- **Can an agent operate the product**: an exposed MCP server, MCP documented for users,
  shipped agent skills, `llms.txt`.
- **Can an agent do the work**: a setup command that works from a clean clone, a
  discoverable test command, a declared lint or format tool, CI configuration, whether CI
  runs the same test command the docs give, a pinned toolchain, an architecture document,
  a documented destructive-operation guardrail.

The score is an inventory signal, never a verdict. Add `--strict` to exit non-zero on any
gap, which is the form to use in CI.

Measured across fifteen public repositories in six ecosystems, scores ran from 79 percent
to 21 percent, so a low score is a real signal rather than an artifact of a harsh checklist.
The most common substantive gap was CI parity: thirteen of fifteen gave no way to tell that
a green local run predicts a green CI run, which is the property an agent depends on most
because without it the agent cannot know whether its change is finished.

### 2. Audit agent entry points

Read `references/agent-entry-files.md` when auditing or writing AGENTS.md/CLAUDE.md entry files.

Read `references/agent-audit.md` when planning the audit, defining simulated agent tasks, and recording tool-use traces.

Verify:

- an entry file exists at the repository root
- it names the commands to build, test, run, and verify
- invariants and gotchas an agent cannot infer are stated
- commands are complete, copy-pasteable, and current
- the entry file is the single source for agent guidance, not a duplicate of the docs

### 3. Audit machine-readable surfaces

Read `references/machine-surfaces.md` when auditing OpenAPI, JSON Schema, structured CLI output, stable error codes, MCP servers, or Agent Skills.

Verify:

- canonical machine schemas exist for public interfaces and match implementation
- CLIs emit structured output (`--json` or equivalent) for the operations agents automate
- error codes are stable, documented, and machine-distinguishable from prose messages
- MCP and Agent Skills surfaces exist where they pay off, per the reference

### 4. Audit automation safety

Read `references/automation-safety.md` when auditing determinism, idempotency, non-interactive modes, destructive-operation guardrails, or secrets handling.

Verify:

- scripts and commands are deterministic and idempotent
- every interactive prompt has a non-interactive equivalent
- destructive operations require explicit opt-in; nothing destructive is the default
- secrets never appear in output, logs, or example commands

### 5. Audit test discoverability

Read `references/discoverability.md` when auditing repository structure, test discoverability, command discovery, or state inspectability.

Verify:

- the repository layout is conventional enough for an agent to map
- tests are discoverable by name and location, and runnable with one documented command
- commands are discoverable through complete `--help` output
- state is inspectable without mutation (status/describe/dry-run commands)

### 6. Recommend agent-native improvements

For each gap, produce a prioritized improvement:

1. Name the surface and the finding.
2. Assign severity using the canonical severity vocabulary.
3. State the exact product change, never a documentation workaround.
4. State how to verify the change with an agent-visible signal.

Do not recommend prose that merely describes the gap. Recommend the product change that removes it.

## Agent trials

Auditing the surfaces is not the same as observing an agent fail. A trial runs an
agent against a target repository and records what actually happened, so findings rest
on observation rather than inspection.

Read `references/trial-protocol.md` before running or scoring a trial. It defines
pre-registration, the coverage corpus, the classification codebook, the second-rater

From devarispbrown/devex-skills, MIT.

More from devarispbrown/devex-skills