agent-use

Use this skill to make work easier for AI agents to use: easier to discover, easier to understand in a small context window, easier to operate safely, easier to verify, and easier to recover.

Audit mode reviews existing work and produces an evidence-backed score, gap list, and remediation plan. Build mode guides new work so the agent contract is designed before implementation ossifies.

The doctrine: agents need action parity, context parity, safe primitives, structured outputs, durable state, explicit completion signals, and recovery paths. Prose helps, but agent-useful systems also provide inspectable contracts, examples, commands, schemas, evals, and stable entry points.

Audit workflow

1. Classify the target: website/docs, app UI, repository, CLI/TUI, HTTP API, SDK, MCP server, A2A agent, Agent Skill, file/workspace system, mobile app, or mixed product.
2. Gather evidence from applicable surfaces. For repositories, run scripts/audit_agent_use.py --root <path> --markdown. For UI/app repos, also run scripts/action_parity_inventory.py <path> --output action-parity-inventory.md --csv-output capability-map.csv. For websites, run scripts/web_agent_readiness.py <url> --markdown --profile auto. For Agent Skills, run scripts/validate_agent_assets.py --skill-dir <skill-dir> --run-help --py-compile --markdown.
3. Build a capability map. List the important things a capable human can see, decide, and do; then map agent-readable context, agent action path, verification path, safety tier, and recovery path.
4. Run the noun test. For every important domain object, ask whether the agent can discover it, identify it, read it, mutate it when appropriate, verify results, and recover from failure.
5. Score only dimensions that apply using references/scoring-rubric.md. Mark non-applicable dimensions explicitly rather than penalizing them.
6. Write findings with file paths, URLs, commands, response snippets, schemas, or screenshots. Avoid generic advice that cannot be patched.
7. Prioritize fixes into quick wins, medium work, and structural work. Include evals that prove the improvements help agents complete tasks.

Recommended audit output is in references/report-template.md.