A tool that meets all six is agent-native.
1. Single binary, zero runtime deps
Ship one binary. Install means copy a file. Homebrew, curl | tar, or go install.
2. Deterministic behavior
Same input, same output. No ambient state, no implicit config.
3. Structured output
Support --format json for machine consumption. JSON output is the agent interface.
4. One bounded job
Each tool does one thing, produces output, and exits. No interactive modes.
5. SKILL.md
A machine-readable file at the repo root or docs/SKILL.md that declares the tool's full interface. The docs/ location avoids gitignore collisions and separates agent-facing contracts from developer-facing documentation.
6. Init command
Running tool init produces a valid config with sensible defaults.
Running tool doctor --format json checks health — config validity, dependencies, connectivity — and reports readiness in a standard schema.
Required sections: Install, Commands, What this does NOT do, Parsing examples.
# tool-name
One-line description.
## Install
```
brew install user/tap/tool-name
```
## Commands
### tool-name analyze
Analyzes input and produces a report.
**Flags:**
- `--format json` — output as JSON
**JSON output:**
```json
{
"status": "pass | fail | warn",
"items": [{"name": "...", "result": "..."}]
}
```
**Exit codes:**
- 0: success
- 1: failure
- 2: partial results
## Handoffs
- Output: structured JSON report. Next: a diagnostic tool for root cause.
- Refused questions: why did it fail, should we fix it.
## What this does NOT do
- Does not modify input files
- Does not manage database schemas
- Does not execute remediation — only reports state
## Failure Modes
- Network timeout: returns degraded status. Distrust: real-time fields.
- Config missing: returns exit code 1. Safe fallback: use defaults.
## Parsing examples
```bash
tool-name analyze --format json | jq '.status'
```Run ancc validate . to check all 30 conventions — 11 structural checks (fail), 4 semantic checks (warn), and 15 quality/ecosystem checks (warn). See Getting Started.
ANCC is a contract spec, not a runtime. It defines what a well-behaved tool looks like. It does not enforce behavior at runtime — that is delegated to CI gates (ancc validate in GitHub Actions), governance tooling, and the agent orchestration layer. Same separation as OpenAPI defining schemas while API gateways enforce them.
ANCC defines how tools advertise capabilities, not how they are found. Discovery is deliberately out of scope — and this is a design choice, not a gap.
Why ANCC does not define discovery. Discovery depends on deployment context. A single developer on a laptop finds tools differently than 500 autonomous agents in a fleet. A discovery protocol baked into the spec would either be too simple for fleet scale or too heavy for single-user. ANCC stays at the contract layer — the same SKILL.md works regardless of how the agent found the tool.
What agents do in practice. Three patterns, simplest to most structured:
What ANCC does not provide — and why:
A machine-readable list of all public ANCC-compliant tools is available at:
curl -s https://ancc.dev/catalog.json | jq '.tools[] | .name, .description'The catalog auto-updates weekly from GitHub. Any public repo with the ancc topic appears automatically — no registration, no approval, no gatekeeping. The catalog is a snapshot, not a registry. Tools self-declare compliance via SKILL.md; the catalog just makes them findable.
Agents use it for pre-creation search: before scaffolding a new tool, check if the capability already exists.
Every ANCC-compliant SKILL.md ends with a breadcrumb line that creates an organic discovery loop:
---
This tool follows the [Agent-Native CLI Convention](https://ancc.dev). Validate with: `ancc validate .`An agent reading any tool's SKILL.md sees the breadcrumb → discovers ANCC exists → installs the validator → runs ancc audit on its own environment → discovers gaps → searches for tools to fill them → each new tool has its own breadcrumb.
The result: every ANCC-compliant tool is an entry point to the ecosystem. No central registry needed — the tools themselves are the discovery network.
ANCC does not currently define a trust or signing model for tool artifacts. Install mechanisms (brew install, go install, curl | tar) carry the same supply chain risks as any CLI tool distribution. ANCC does not make this worse, but does not solve it yet.
Planned but not implemented: signed releases, provenance attestation, allowed install sources, and capability-scoped permissions. These layers become necessary when untrusted third parties publish ANCC-compliant tools. Until then, trust is established through source ownership and CI validation.