ANCC

Agent-Native CLI Convention

ANCC is a contract for CLI tools that agents can run and compose with declared behavior. It standardizes install, JSON output, readiness checks, scope boundaries, and handoffs — so tools don't bloat into god-objects as agents evolve them.

Before and after

A normal CLI tool that an agent tries to use:

# Agent guesses flags from --help
$ mytool check --output json
unknown flag: --output

# Agent tries another guess
$ mytool check -f json
{"ok": true, "msg": "all good"}

# Agent has no idea what "ok" means structurally
# No exit code contract. No schema. No way to know what this tool won't do.
# Agent wraps it in a retry loop and hopes.

The same tool, ANCC-compliant:

# Agent reads SKILL.md — knows exact flags, output schema, exit codes
$ mytool check --format json
{
  "status": "healthy",
  "checks": [
    {"name": "config", "status": "pass", "message": "valid"},
    {"name": "database", "status": "pass", "message": "reachable"}
  ]
}
# Exit code 0 = all checks pass. Exit code 1 = failures found.
# SKILL.md declares: "Does not remediate — diagnosis only."
# Agent knows exactly what it got, what to trust, and what to hand off.

The difference: the agent never guesses. It reads the contract, runs the command, parses structured output, and acts. No plugins. No SDKs. One markdown file.

What ANCC is NOT

• Not dashboards. Agents cannot squint at Grafana. They need structured output with exit codes.
• Not AIOps. No ML anomaly detection. Deterministic tools with declared behavior.
• Not agent tracing. This is not about observing agents. It is about building tools agents can observe with.
• Not a framework. No runtime, no library, no dependency. A convention — six requirements and a markdown file.
• Not unbounded self-improvement. Tools evolve under governed conventions with explicit scope boundaries.

What it prevents

Without scope constraints, agents optimize locally: nearest tool, cheapest modification, fastest path to green tests. After five iterations, your focused diagnostic tool also deploys, manages databases, sends alerts, and runs backups. That is uncontrolled growth — and it is the default outcome when agents modify tools.

ANCC prevents this structurally:

• "What this does NOT do" is a required section with minimum 3 boundary statements. Enforced by ancc validate — the tool fails validation without it.
• Scope pressure detection flags tools with 10+ commands — automatic signal that a tool needs splitting.
• Handoff contracts force tools to declare where they stop and what comes next. Composition by design, not by accident.
• Enforcement provenance separates advisory guardrails from enforcing boundaries. See Advisory vs Enforcing Guardrails.
• 33 validation checks run in CI on every push. Structural checks fail the build; quality checks warn.

Quick start

# Install
brew install ppiankov/tap/ancc

# Create a complete tool project in 30 seconds
ancc scaffold my-scanner --type scanner
cd my-scanner && go mod tidy && make build

# Validate — must pass before the tool enters the ecosystem
ancc validate .
# 30 pass, 0 fail, 3 warn

The scaffolded project includes: Go binary, Makefile, CI workflows, docs/SKILL.md, tests, README with badge. It builds, tests pass, and validates on first run.

See Getting Started for the full walkthrough, or Tool Genesis for the full creation loop.

Tools

28+ tools following this convention across security, diagnostics, enforcement, and investigation.

See Ecosystem for the full tool inventory, or Lifecycle for how tools are created, versioned, and retired.