# Agent Native Cli > >- - **Type:** Skill - **Install:** `agentstack add skill-brettdavies-agentnative-skill-agentnative-skill` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [brettdavies](https://agentstack.voostack.com/s/brettdavies) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [brettdavies](https://github.com/brettdavies) - **Source:** https://github.com/brettdavies/agentnative-skill - **Website:** https://anc.dev/skill ## Install ```sh agentstack add skill-brettdavies-agentnative-skill-agentnative-skill ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Agent-Native CLI The standard for CLI tools designed to be operated by AI agents. Three artifacts work together: | Artifact | Role | | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`agentnative-spec`](https://github.com/brettdavies/agentnative) | Canonical text of the eight principles. Frontmatter `requirements[]` is the machine-readable contract. Vendored into [`spec/`](./spec/); snapshot refreshed each release. | | [`anc`](https://github.com/brettdavies/agentnative-cli) | The compliance auditor. Reads target source/binary, emits a JSON scorecard whose entries cite the spec requirement `id` (e.g. `p1-must-no-interactive`) and the probe `audit_id`. The runtime authority. | | **This skill** (`agent-native-cli`) | The agent-facing guide. Tells the agent how to invoke `anc`, how to navigate the spec when remediating findings, and where the implementation patterns and starter templates live. | The skill does **not** implement principles auditing. `anc` does. The skill teaches agents to use `anc` and supplies the surrounding context (spec, idioms, templates) that `anc`'s findings reference. ## First action: update check Run once per session before doing real work: ```bash bash "$(dirname "$0")/bin/check-update" ``` Empty output → continue. `UPGRADE_AVAILABLE ` → prompt the user via `AskUserQuestion` (Yes / Not now / Never). Full prompt text, snooze ladder, and state-file layout are in [`references/update-check.md`](./references/update-check.md). Exit code is always `0`; failures degrade silently. ## Start here → **[`getting-started.md`](./getting-started.md):** the three working loops (existing CLI / new Rust CLI / other language), the canonical `anc audit` invocations, the `anc skill install ` installer, and a "where things live" map. ## The eight principles Defined in [`spec/principles/`](./spec/principles/) (vendored from `agentnative-spec`, currently `v0.5.0`; see [`spec/README.md`](./spec/README.md) for resync instructions). One file per principle, each with machine-readable `requirements[]` frontmatter: | # | File | Subject | | --- | -------------------------------------------------------------------------------------------------------------------- | --------------------------------- | | P1 | [`p1-non-interactive-by-default.md`](./spec/principles/p1-non-interactive-by-default.md) | Non-Interactive by Default | | P2 | [`p2-structured-parseable-output.md`](./spec/principles/p2-structured-parseable-output.md) | Structured, Parseable Output | | P3 | [`p3-progressive-help-discovery.md`](./spec/principles/p3-progressive-help-discovery.md) | Progressive Help Discovery | | P4 | [`p4-fail-fast-actionable-errors.md`](./spec/principles/p4-fail-fast-actionable-errors.md) | Fail Fast, Actionable Errors | | P5 | [`p5-safe-retries-mutation-boundaries.md`](./spec/principles/p5-safe-retries-mutation-boundaries.md) | Safe Retries, Mutation Boundaries | | P6 | [`p6-composable-predictable-command-structure.md`](./spec/principles/p6-composable-predictable-command-structure.md) | Composable, Predictable Structure | | P7 | [`p7-bounded-high-signal-responses.md`](./spec/principles/p7-bounded-high-signal-responses.md) | Bounded, High-Signal Responses | | P8 | [`p8-discoverable-skill-bundle.md`](./spec/principles/p8-discoverable-skill-bundle.md) | Discoverable Skill Bundles | Do not paraphrase the principles inside this skill. Read the spec files directly; they are the source of truth. ## The anc loop: audit → fix → re-audit → claim badge Once `anc` is installed (one-line install in [`getting-started.md`](./getting-started.md)), the work is a four-step loop: **1. Audit.** `anc audit --output json . > scorecard.json`. The JSON envelope is schema `0.7` and contains: - `summary`: counter object covering the full status set (`total / pass / warn / fail / skip / error / opt_out / n_a`). Spans all three audit layers (behavioral, source, project). - `coverage_summary`: `must / should / may`, each with `total` + `verified`. **`verified` counts any verdict; `pass`, `warn`, `fail`, and `skip` all increment it.** "Was this MUST audited at all?" not "was it satisfied." The actual bar for "no MUST violations" is no `results[]` row where `tier == "must" && status == "fail"` (equivalently, every MUST row is `pass` / `warn` / `opt_out` / `skip` / `n_a`). - `badge.eligible` (bool), `badge.score_pct` (int), `badge.embed_markdown` (string or `null`), `badge.scorecard_url`, `badge.badge_url`, `badge.convention_url`. **70%** is the eligibility floor; below it, `embed_markdown` is `null` and the convention says do not advertise a badge. **The score is computed over behavioral-layer rows only.** Source- and project-layer audits do not affect `score_pct` or badge eligibility (`spec/principles/scoring.md` § "Scope: shipped-binary behavior only"). Under the current flat tier weights the formula reduces to a credit-weighted ratio: `pass = 1.0`, `warn = 0.5`, `fail` and `opt_out` = `0.0` (all in the denominator); `n_a`, `skip`, and `error` are excluded. The general form is tier-weighted (`w(must) · w(should) · w(may)`) but currently flat; see `spec/principles/scoring.md` for the formula and the cohort bands above the floor. - `results[]`: one entry per requirement-row. Each carries `id` (the spec requirement id matching `spec/principles/p-*.md` frontmatter, e.g. `p1-must-no-interactive`), `audit_id` (the probe that produced the row, e.g. `p1-non-interactive`), `tier` (`must` / `should` / `may`), `status`, `evidence`, `group`, `layer`, `confidence`, and `label`. A single probe like `p3-version` emits two rows (one tier-stamped `must`, one `should`), so you can attribute the verdict to a specific RFC 2119 level without joining the coverage matrix. - `audit_profile`: the exemption category in effect (or `null`). - `tool / anc / run / target` metadata: identifies the scored tool, the `anc` build, the invocation, and the resolved target. **Status set.** `pass` / `warn` / `fail` / `skip` / `error` are the live verdicts. `opt_out` marks a deliberate non-adoption (e.g. no `--output` flag → P2 schema-discovery rows collapse). `n_a` propagates from a conditional whose antecedent is `opt_out` or `n_a`; the `evidence` field names the antecedent so the chain is legible from JSON alone. The process exit code reflects live verdicts only: `n_a` from an `opt_out` antecedent does not force a non-zero exit. **2. Fix.** For each `fail`, look up the cited `id` (e.g. `p1-must-no-interactive`) in `spec/principles/p-*.md`'s `requirements[]` frontmatter. Apply the fix using the implementation references below. Re-run with `--principle ` to focus on one principle while iterating. **3. Re-audit.** Re-run `anc audit --output json .` until no MUST row is in `fail`. Query the JSON with `jq '[.results[] | select(.tier == "must" and .status == "fail")] | length'` and confirm it's `0`. Do not rely on `coverage_summary.must.verified == coverage_summary.must.total` as the satisfaction bar; the `verified` counter increments on any verdict, so it can equal `total` while MUST fails still exist. Use `--audit-profile ` to suppress audits that don't apply to the tool class: `human-tui` (TUIs that legitimately intercept the TTY), `file-traversal` (reserved), `posix-utility` (cat / sed / awk style), `diagnostic-only` (read-only tools). Suppressed audits emit `Skip` with structured evidence so readers see what was excluded. **4. Claim the badge.** Once `badge.eligible == true` (≥70%), copy `badge.embed_markdown` into the project's README. The `text` output appends an embed hint after the summary line whenever the floor is cleared; below the floor, nothing badge-related is printed (the convention's "do not nag" rule). ### Useful flags - `--principle `: filter the audit to one principle while iterating. - `--binary` / `--source`: scope to one layer (skip the other). - `--audit-profile `: suppress audits that don't apply (`human-tui`, `posix-utility`, `diagnostic-only`, `file-traversal`). - `--examples`: print a curated invocation block and exit (pair with `--output json` or `--json` for structured). - `--json`: short alias for `--output json` (the `p2-should-json-aliases` convention). - `--raw`: strip headers and summary, emit one `idstatus` line per audit. Pipe-friendly for `grep` / `awk`. - `--color ` (env `AGENTNATIVE_COLOR`): control ANSI styling; honors `NO_COLOR` in `auto` mode. - `-v` / `--verbose` (env `AGENTNATIVE_VERBOSE`): escalate diagnostic detail when debugging unexpected results. ### Get the scorecard JSON Schema The canonical JSON Schema for the scorecard envelope ships embedded in the binary. Extract it without a network round trip: ```bash anc emit schema # print to stdout anc emit schema | jq '.title' # inspect a field ``` The schema `$id` is `https://anc.dev/scorecard-v0.7.schema.json`. Pre-0.6 consumers treated `opt_out` / `n_a` as unknown, so feature-detect the status enum rather than pinning to an exact list. ## Implementation guidance (when fixing findings) Once `anc audit` reports a failure, the agent has the cited `id` (requirement-row id) and the spec text. The next question is "how do I write code that satisfies this requirement?" The references below answer that: | Need | File | | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | Rust/clap-specific patterns per principle | [`references/rust-clap-patterns.md`](./references/rust-clap-patterns.md) | | General Rust idioms (output, errors, dependency gating) | [`references/framework-idioms.md`](./references/framework-idioms.md) | | Idioms in Python, Go, JS, Ruby | [`references/framework-idioms-other-languages.md`](./references/framework-idioms-other-languages.md) | | Required project structure (modules, tests, AGENTS.md) | [`references/project-structure.md`](./references/project-structure.md) | ## Starter code Drop-in starting points for greenfield Rust CLIs. Each encodes the relevant principles by construction. | File | Encodes | | ---------------------------------------------------------------------- | -------------------------------------------------------------------- | | [`templates/clap-main.rs`](./templates/clap-main.rs) | `try_parse`, SIGPIPE fix, three-tier dependency gating, global flags | | [`templates/error-types.rs`](./templates/error-types.rs) | `thiserror` enum + `exit_code()` mapping | | [`templates/output-format.rs`](./templates/output-format.rs) | `OutputConfig`, `OutputFormat`, `diag!`, NO_COLOR / IsTerminal | | [`templates/agents-md-template.md`](./templates/agents-md-template.md) | Project-level AGENTS.md scaffold | ## Compliance auditing Use `anc`. Install once via Homebrew, cargo, or self-install: ```bash brew install brettdavies/tap/agentnative # binary is `anc` cargo install agentnative ``` To install **this skill bundle** into a host's canonical skills directory, use `anc`'s built-in installer: ```bash anc skill install claude_code # also: codex, cursor, factory, kiro, opencode anc skill install --all # install into every known host in one invocation anc skill install --dry-run claude_code # print resolved git command without spawning anc skill update claude_code # refresh an existing install (guards on SKILL.md marker) anc skill update --all # refresh every known host ``` Recommended `anc audit` invocations and the full agent loop are in [`getting-started.md`](./getting-started.md). Do not write shell scripts to grep for principle violations; `anc` already implements (and supersedes) every audit that approach could produce. ## Sources - [`agentnative-spec`](https://github.com/brettdavies/agentnative): canonical principle text (CC BY 4.0) - [`agentnative-cli`](https://github.com/brettdavies/agentnative-cli): `anc`, the canonical auditor (MIT / Apache-2.0) - [`agentnative-skill`](https://github.com/brettdavies/agentnative-skill): this repo (MIT) ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [brettdavies](https://github.com/brettdavies) - **Source:** [brettdavies/agentnative-skill](https://github.com/brettdavies/agentnative-skill) - **License:** Apache-2.0 - **Homepage:** https://anc.dev/skill Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-brettdavies-agentnative-skill-agentnative-skill - Seller: https://agentstack.voostack.com/s/brettdavies - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.