# Agent Skills Standard CLI [![NPM Version](https://img.shields.io/npm/v/agent-skills-standard.svg?style=flat-square)](https://www.npmjs.com/package/agent-skills-standard) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://github.com/HoangNguyen0403/agent-skills-standard/blob/main/LICENSE) **Sync 242 AI coding standards to any project in one command.** Works with Cursor, Claude Code, GitHub Copilot, Gemini, Windsurf, Trae, Kiro, and Roo. **Current release:** `v2.7.0` — `ags sync` manifest-check fix for repo-root LICENSE/NOTICE; skill validator accepts package directories under `scripts/`; SkillSpector security scanning, pull request evaluation gates, and verified release tags. ```bash npx agent-skills-standard@latest init # detect your stack npx agent-skills-standard@latest sync # install skills ``` ## Prerequisites - **Consumer CLI (`ags`)**: Supported Node 22 LTS `>= 22.13` on the 22.x line, or a newer supported LTS. Supported means the exact declared dependency intersection `^22.13.0 || >= 23.5.0` (`commander` 15 declares `>= 22.12.0`, `inquirer` 14 declares `>= 23.5.0 || ^22.13.0 || ^20.17.0`); the CLI `package.json` declares no `engines` field of its own, so intermediate Node versions are not covered by a declared supported range. - **Repository Root & Tooling**: The root `package.json` _declares_ `node: ">= 20.0.0"` and `pnpm@10.0.0`. That is a manifest declaration for root scripts only, not evidence that the CLI or website build supports Node 20. - **Contributors & Website**: See [CONTRIBUTING.md](../CONTRIBUTING.md) for full developer requirements (supported Node 22 LTS or newer supported LTS, pnpm `10+`). ### Release and PATH Notes - **Published version:** Read it from the [npm package page](https://www.npmjs.com/package/agent-skills-standard) badge or your installed binary (`ags --version`). That is the version consumers get from `@latest`. - **Source target:** This checkout's CLI manifest (`cli/package.json`) is at `2.7.4` (see [CHANGELOG.md](../CHANGELOG.md)). A source version is a development target, not evidence that the same build is published to npm. - If `ags -V` still shows an older version after reinstalling, verify your shell's PATH order (e.g. `~/Library/pnpm` before `~/Library/pnpm/bin`), run `hash -r`, and verify with `ags -V` again. - **`ags skills` command availability:** `ags skills` exists in source (`cli-v2.7.0`+; `2.7.4` in this checkout) and is **not** available in every published release. The published `agent-skills-standard@2.6.6` package (installed from `@latest` during the 2026-11-03 verification) exposes `init`, `sync`, `verify`, and other commands, but no `skills` subcommand. Run `ags --help` against your installed build before relying on this step; if it is absent, edit `.skillsrc` directly. --- ## What It Does The CLI takes engineering standards from the [Agent Skills Standard registry](https://github.com/HoangNguyen0403/agent-skills-standard) and installs them into your AI agent's native format: ```bash npx agent-skills-standard sync - Updated .cursor/skills/ (Cursor) - Updated .claude/skills/ (Claude Code) - Updated .github/skills/ (Copilot) - Generated _INDEX.md for 8 categories. - AGENTS.md router index updated. ``` The result: your AI agent reads `AGENTS.md`, follows the router to the right category, and loads only the skills that match what you're editing. --- ## Commands | Command | What it does | | :--------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `init` | Detects your tech stack (Flutter, React, Go, etc.) and creates a `.skillsrc` config | | `sync` | Fetches skills from the registry, writes to agent folders, generates `_INDEX.md` + `AGENTS.md` | | `skills` | Category-first manager: pick categories (and optionally nested skills or a published category release), review once, then save and sync every configured agent | | `mcp` | Manage the optional MCP server integration (status / enable / disable / scope / via / install / upgrade / uninstall / snippets) — see [Optional: MCP Runtime Enforcement](#optional-mcp-runtime-enforcement) below | | `validate` | Checks your custom skills against format and token standards | | `feedback` | Submits improvement suggestions to the registry | | `upgrade` | Updates the CLI to the latest version | | `doctor` | Check installation health (config, agents, lock file, MCP, hooks, CLI version) with human or JSON output and safe repairs | | `restore` | List backups in `.ags/backups` or restore one (replace-only) | | `uninstall` | Remove files ags installed (keeps files you edited); backs up first | | `verify` | Check installed files against `.skills-lock.json` (`--strict`, `--attestation`) | | `policy` | Manage and check project agent policies (status, check, validate, compile, adopt) | | `hooks` | Manage pre-edit reminder hooks (status, install, install --enforce, uninstall) | ### Install Safety & Sync Options `ags sync` safely tracks owned files in `.skills-lock.json` v2 and preserves local user edits: - **User-Edit Preservation**: If you edited a synced skill, workflow, specialist, or bridge file, sync keeps your version and warns instead of overwriting it. - `--dry-run`: Preview additions, updates, kept edits, and prunes without writing anything to disk or modifying configs. - `--dry-run --verbose`: List every affected file path by status. - `--dry-run --json`: Emit the full install plan as machine-readable JSON (`schema_version: 1, kind: 'sync.plan'`). - `--force `: Overwrite specified user-edited files with upstream versions (a backup is created first). - **Automatic Backups**: Destructive changes (pruning or forced overwrites) automatically snapshot previous files into `.ags/backups//` (retaining the 3 most recent backups). > [!WARNING] > **First-use check, observed 2026-11-03:** `@latest` resolved to published `2.6.6`. An isolated global install and `ags init` (Next.js/Codex template, MCP disabled) succeeded, but the follow-up `ags sync` was rejected because the configured category refs `common-v2.9.3` and `quality-engineering-v1.6.2` were unavailable; no native agent assets or `.skills-lock.json` were installed, and the CLI exit code was not captured. Separately, the `specialists` ref `v1.5.2` was unavailable, and native export completeness is unverified. This is a dated record of that attempt, not a forecast for other releases: check `ags --version` on your install, and use [GitHub Issues](https://github.com/HoangNguyen0403/agent-skills-standard/issues) if sync fails. ### Category Manager: `ags skills` `ags skills` adds or removes guidance without editing YAML or remembering release tags, and without a second `sync` run. **Normal flow:** 1. Existing categories are checked; categories the current metadata cannot describe remain checked by default, are marked unavailable, and can be explicitly removed. 2. Pick categories. A new category uses its published release automatically; an existing pin is never changed. 3. Before the final Apply confirmation, the manager prepares the selection and reviews the exact source commits and effective selected packages. Existing revoked pins keep their ref and show the registry's advisory. 4. Confirm Apply once. The command uses that same prepared package set, saves `.skillsrc`, installs skills and managed indexes for every configured agent, and finalizes the lockfile. **Advanced flow (optional):** - `Customize skills in a category` opens that category at its effective ref with its nested skills checked according to the current selection. - Search matches skill names and descriptions. Selections outside the current view are never dropped. - Category-wide entries gain exact exclusions; allowlists only change their own members. Imported members are listed individually at the declaring category's ref: excluding one adds a qualified exclusion while the declared `category/*` expression stays, and an import already excluded with an exact id can be re-enabled. Qualified identities are never mixed with same-named local skills. - `Use the published category release` changes that category's ref explicitly; the full ref change appears in the review before saving. - New categories that use the Product Management category start with only the two foundation skills. **Write and failure behavior:** - Cancel, an unchanged selection, and non-TTY invocation write nothing. Non-TTY exits nonzero. - A real selection change sets `skills_mode: explicit`, so later ordinary `sync` will not re-add removed categories or excluded detected skills. - A preflight failure saves and installs nothing. - A failure after saving keeps the saved desired selection, reports the stage, and offers an in-command Retry. If `.skillsrc` changed on disk, the command reloads and asks you to review again instead of overwriting it. If saving failed, the attempted selection was not saved; reopen `ags skills`, review, and Apply again after fixing the reported failure. If installation failed after saving and you decline Retry, run `agent-skills-standard sync` after fixing the reported failure; when sync asks “Do you want to update .skillsrc with these versions?”, answer No to keep the saved refs. - Retained files (`custom_overrides`, `prune: false`, edited or unowned files) are reported as "applied with retained files", not as deleted. ### Restore & Uninstall - `ags restore [--list] [id]`: List backups or restore files from `.ags/backups/` (replace-only; does not delete newer files or modify lockfile). - `ags uninstall [--agent ] [--category ] [--all] [--dry-run] [-y, --yes]`: - Removes only manifest entries whose on-disk sha256 still matches (owned-unchanged). - Keeps user-edited files byte-identical. - Automatically creates a backup of removed files and `.skills-lock.json` before deleting. - `--all` removes all owned files, cleans MCP and hook registrations, clears `AGENTS.md` index block, and deletes `.skills-lock.json`. `CLAUDE.md` and `.skillsrc` are left unchanged. - Non-interactive environments without `--yes` exit 1 with a preview. ### Verification: `ags verify` Check installed files against `.skills-lock.json` to detect tampering, partial writes, or manual drift: - `ags verify`: Checks file integrity against the lockfile. - `ags verify --strict`: In addition to file integrity, fails (exit 1) if any locked ref now resolves to a different commit (moved tag) or cannot be resolved. - `ags verify --attestation`: Verifies build-provenance attestations using the GitHub CLI (`gh`). Requires `gh` on PATH; fails if any pinned source lacks `MANIFEST.json` or fails attestation. ### Policy Layer: `ags policy` Prevents mistakes by cooperating agents; not a security boundary. Manage and check deterministic project rules in `.ags/policy.json` (`protected_path`, `command`, `required_check`): - `ags policy status [--json]`: Show policy rules in force and built-in rules (identity/secret deny-list). - `ags policy check (--path

| --command | --diff) [--no-bypass] [--json]`: Evaluate a path, command executable, or git diff against active policy rules. - `ags policy validate [--fail-on-stale] [--json]`: Validate `.ags/policy.json` for schema errors, rule conflicts, and stale compiled rules. - `ags policy compile [--json]`: Scan `AGENTS.md` and `CLAUDE.md` to propose candidate rules into `.ags/policy-candidates.json`. Compiled rules can only warn or rewrite. - `ags policy adopt [--json]`: Activate candidate rules into `.ags/policy.json` after conflict validation. Set `AGS_POLICY_BYPASS=1` (or `AGS_POLICY_BYPASS=true`) to turn policy decisions into allow while reporting waived rules. ### Pre-Edit Hooks: `ags hooks` `sync` installs a `PreToolUse` hook that reminds your agent to call `load_skills_for_files` before every edit — advisory by default and never blocks work: ```bash ags hooks status # Show which hook files are installed per agent ags hooks install # (Re)install the reminder hook — advisory only ags hooks install --enforce # Claude also BLOCKS edits to SOUL.md, MEMORY.md, .env*, .ssh/, credentials*.json|yaml ags hooks uninstall # Deregister the hook (keeps the script file) ``` --- ## Configuration The `.skillsrc` file controls everything: ```yaml registry: https://github.com/HoangNguyen0403/agent-skills-standard agents: [cursor, copilot, claude] workflows_ref: workflows-v1.0.0 # pinned workflows release tag specialists_ref: specialists-v2.0.0 # pinned specialists release tag # skills_mode: explicit # set by `ags skills` on a real change: # # ordinary sync stops re-adding removed categories skills: react: ref: react-v1.3.1 golang: ref: golang-v1.3.1 exclude: ['golang-tooling'] # skip skills you don't need common: ref: common-v2.0.1 custom_overrides: ['common-tdd'] # protect your local edits # Local custom standalone skills indexed into AGENTS.md and _INDEX.md custom_skills: - path: "./.skills/my-custom-rule.md" triggers: ["*.ts", "keyword"] # Workflows synced to native agent surfaces (.agents/workflows/, .codex/skills/, etc.) workflows: - sdlc - brainstorm-feature - plan-feature - design-solution - implement-feature - verify-work - pentest - security-test - deploy-release - publish-notes - retro-learn # MCP consent and scope configuration mcp: enabled: true scope: project # project | user | snippets-only | disabled prompted: true # set to false to be re-asked next sync ``` A project without pins gets `workflows_ref` and `specialists_ref` written once to `.skillsrc` on first sync from the registry's latest releases (`--dry-run` never writes them). If the registry does not publish releases, sync falls back to the default branch with a warning. --- ## What Gets Generated After `sync`, your project contains: ```bash project/ AGENTS.md # Router table (~20 lines) .cursor/skills/ golang/_INDEX.md # Trigger table for Go skills golang/golang-language/SKILL.md # The actual skill golang/golang-testing/SKILL.md react/_INDEX.md # Trigger table for React skills react/react-hooks/SKILL.md ... ``` **`AGENTS.md`** maps file extensions to category indexes. **`_INDEX.md`** has two sections: **File Match** (auto-check against your file) and **Keyword Match** (activates when you mention a concept). **`SKILL.md`** is the skill itself — loaded on demand, averaging ~500 tokens. --- ## Optional: MCP Runtime Enforcement The CLI **distributes** skills as static files. The companion [`agent-skills-standard-mcp`](https://www.npmjs.com/package/agent-skills-standard-mcp) server **serves** them at runtime as MCP tool calls — closing the gap where sub-agents skip skill loading because they don't inherit `AGENTS.md`. `init` asks once whether to enable it and at what scope. Default is `project` (recommended). Change later with: ### Consent Model — You Choose the Scope `init` and `sync` ask once whether to enable MCP and at what scope. Recommended choice is in **bold**: | Scope | What gets written | Touches `$HOME`? | | --------------------------- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | | **`project`** (recommended) | `./mcp-config-snippets/*.json` + project-scoped runtime configs (`./.mcp.json`, `./.cursor/mcp.json`, etc.) | ❌ No | | `user` | All of `project` + user-home configs (`~/.cursor/mcp.json`, `~/.gemini/settings.json`) | ⚠️ Yes — sync prompts before each user-scope write | | `snippets-only` | Only `./mcp-config-snippets/*.json` — never edits any runtime config | ❌ No | | `disabled` | Nothing MCP-related | ❌ No | The CLI never reads or modifies user-home files unless you explicitly choose `user` scope AND confirm each write. All decisions are recorded in `.skillsrc` so you are not re-prompted on every sync. ```bash ags mcp status # Show current state + per-agent install ags mcp enable # Opt in; global launch mode installs agent-skills-standard-mcp@ and verifies it ags mcp disable # Clear consent (keeps existing registrations; use uninstall to clean) ags mcp scope project # Change scope: project | user | snippets-only | disabled ags mcp via auto # auto | npx | global launch mode (auto prefers a version-matched global ags-mcp) ags mcp install # Apply changes ags mcp upgrade # Move a detected global ags-mcp and enabled configs to this CLI's pin ags mcp uninstall --from=all # Remove our entry from project + user configs; siblings preserved ags mcp snippets # Regenerate ./mcp-config-snippets/ without touching runtime configs ``` Launch mode defaults to `auto`: the generated entry uses a globally installed `ags-mcp` only when its `--version` exactly matches the CLI pin, and otherwise falls back to `npx -y --prefer-offline agent-skills-standard-mcp@`. With `via: global` (saved mode, or `ags mcp enable --via global`), `ags mcp enable` installs `agent-skills-standard-mcp@` globally via npm, verifies the reported version, then writes the runtime configs; a failed install or mismatched probe exits `1` and leaves `.skillsrc` and the configs untouched. `--install-global` remains available as an explicit trigger for the same install. `ags mcp status` prints the resolved launch line, the pin, and the detected global version; `ags mcp install --via ` overrides the mode for that run without persisting it. `ags upgrade` does not rewrite runtime configs — run `ags sync` (or `ags mcp install`) to move them to the new pin; `ags mcp status` and `ags doctor` flag configured-vs-expected drift. The CLI **never** modifies user-home files (`~/.cursor/mcp.json`, `~/.gemini/settings.json`, etc.) unless you explicitly choose `scope: user` AND confirm each write. See [`mcp/README.md`](../mcp/README.md) for full details and [`mcp/ARCHITECTURE.md`](../mcp/ARCHITECTURE.md) for the threat model. `ags mcp upgrade [--dry-run] [--via auto|npx|global]` moves the whole integration to the effective pin — `mcp.version` when `.skillsrc` pins one, otherwise the version compiled into the running CLI, so `ags upgrade` is what moves that default. A detected stale global `ags-mcp` is replaced with `agent-skills-standard-mcp@` and re-probed (nonzero exit plus the manual `npm i -g` line on failure); enabled `project`/`user` configs are then rewritten at the configured scope, keeping configured `via` and the usual per-file user-scope prompts, and `--via` overrides the mode for that run only. With `via: global` (or `--via global`) and no readable global `ags-mcp`, it refuses to write configs that could not start: it prints the manual `npm i -g` line, exits `1`, and leaves existing configs untouched. `--dry-run` reports the plan and changes nothing, and is rejected (exit `1`) by every other `ags mcp` action; an absent global install is reported, never created implicitly; `.skillsrc` is never rewritten and nothing is published. Hosts pick up the new pin on their next MCP start. ## Installation Health: `ags doctor` Run read-only health checks across seven subsystems: configuration (`.skillsrc`), detected/configured agents, skill-content lockfile (`.skills-lock.json`), MCP server registrations, pre-edit hooks, legacy folder migrations, and CLI version. ```bash ags doctor # Human-readable health check report ags doctor --offline # Skip the network-backed CLI version check ags doctor --json # Emit a versioned JSON report (schema_version: 1, kind: 'doctor.report') ags doctor --exit-on-fail # Exit with code 1 when any check fails (default exit code is 0) ags doctor --fix # Apply available safe repairs interactively (prompts per fix) ags doctor --fix --yes # Apply repairs non-interactively ``` ### JSON Envelope When `--json` is supplied, `ags doctor` outputs a single JSON payload matching the `doctor.report` contract: ```json { "schema_version": 1, "kind": "doctor.report", "data": { "schema_version": 1, "checks": [ { "name": "config", "status": "ok", "evidence": ".skillsrc parsed", "fixable": false } ], "summary": { "total": 7, "ok": 7, "warn": 0, "fail": 0, "skip": 0 }, "healthy": true } } ``` ### Exit Behavior `ags doctor` always exits with code `0` by default so it never unexpectedly breaks pipelines. When `--exit-on-fail` is passed, it exits with code `1` if any check produces a `fail` status (`healthy: false`). --- ## Privacy & Security - **Text only** — the CLI downloads Markdown and JSON files, never binaries or scripts - **No telemetry by default** — zero data collection unless you opt into the local usage log (see docs/FRESHNESS.md) - **Transparent** — fetches from the [public registry](https://github.com/HoangNguyen0403/agent-skills-standard), nothing hidden - **Override protection** — `custom_overrides` prevents the CLI from touching your local modifications - **MCP consent model** — runtime configs in `$HOME` are only ever modified with explicit per-file consent --- ## Links - [Registry & Skills](https://github.com/HoangNguyen0403/agent-skills-standard) - [Architecture](./ARCHITECTURE.md) - [Report an Issue](https://github.com/HoangNguyen0403/agent-skills-standard/issues) ### 📜 Benchmark History | Version | Date | Skills | Avg Tokens | Savings (%) | Report | | --- | --- | --- | --- | --- | --- | | v2.6.0 | 2026-07-10 | 264 | 528 | 46% | [Report](../benchmarks/archive/v2.6.0.md) | | v2.4.7 | 2026-06-15 | 251 | 551 | 85% | [Report](../benchmarks/archive/v2.4.7.md) | | v2.4.6 | 2026-06-10 | 251 | 548 | 85% | [Report](../benchmarks/archive/v2.4.6.md) | | v2.4.1 | 2026-05-18 | 247 | 540 | 85% | [Report](../benchmarks/archive/v2.4.1.md) | | v2.4.0 | 2026-05-14 | 246 | 540 | 85% | [Report](../benchmarks/archive/v2.4.0.md) | | v2.3.0 | 2026-05-13 | 246 | 540 | 85% | [Report](../benchmarks/archive/v2.3.0.md) | | v2.2.2 | 2026-05-09 | 249 | 539 | 85% | [Report](../benchmarks/archive/v2.2.2.md) | | v2.2.0 | 2026-04-22 | 242 | 538 | 85% | [Report](../benchmarks/archive/v2.2.0.md) | | v2.1.2 | 2026-04-11 | 237 | 516 | 86% | [Report](../benchmarks/archive/v2.1.2.md) | | v2.1.1 | 2026-04-11 | 237 | 516 | 86% | [Report](../benchmarks/archive/v2.1.1.md) |