agent-skills-standard

Agent Skills Standard

The portable standards layer for AI coding agents. Sync once, then work in your own runtime.

Purpose

Agent Skills Standard provides a modular, version-controlled catalog of engineering guidelines and development workflows that synchronizes into native configurations for coding agents (Cursor, Claude Code, GitHub Copilot, Gemini CLI, Windsurf, Trae, Kiro, Roo, and more). It keeps engineering practices consistent across your team without packing thousands of instructions into system prompts.

Intended Developer

Built for developers and engineering teams who use AI coding assistants and want shared, auditable standards—such as architecture boundaries, strict type checking, security rules, and testing patterns—that stay portable across different tools and environments.

Note Specification & Runtime Boundary: This repository is an open-source catalog, distribution CLI, and MCP server. It provides skills conforming to the open Agent Skills format, but it does not own or govern the underlying specification, nor does it replace your existing agent runtime or IDE.

Concrete Use Case

When an agent creates or refactors an API endpoint, it can consult focused on-demand skill files matching the active file patterns and task concepts (such as NestJS controller conventions, TypeScript strict typing, and API response envelopes), providing structured domain guidance while reducing unnecessary prompt context compared to monolithic instructions.

Next Action: Quick Setup

Install globally and initialize in your project repository:

# Recommended: Global install and sync
npm install -g agent-skills-standard@latest
ags init
ags sync

Or run directly without global installation:

# Alternative: run via npx
npx agent-skills-standard@latest init
npx agent-skills-standard@latest sync

Not an engineer? You don't need to run any of the above — just describe your idea to your AI agent. See Getting Started: Product Owner.

The Problem

Every team has coding standards. But AI agents don't know them.

You end up repeating the same instructions: "Use OnPush change detection", "Always wrap errors with context", "No business logic in handlers". And every time, you face the same trade-off:

• Too many rules = AI forgets them, wastes tokens, gets confused
• Too few rules = AI writes generic code that doesn't match your standards
• Copy-paste .cursorrules = out of date in a week, doesn't scale to teams

The Solution

Agent Skills Standard turns your engineering rules into modular, version-controlled skills that any AI agent can load on demand.

Without Skills	With Skills
Large all-in-one architect prompt every chat	Focused skill loaded only when relevant
Rules drift across team members' prompts	Single source of truth, synced via CLI
Works in one AI tool, copy-paste to others	Works in Cursor, Claude, Copilot, Gemini, Windsurf, Trae, Kiro, Roo
One large instruction file consulted regardless of the edit	Hierarchical lookup narrows to the matching skill

Not Another Agent Runtime

Agent Skills Standard does not force you into a new daily command system. ags is for setup, sync, validation, MCP wiring, and updates. After sync, your AI tool receives native assets:

• Claude/Roo/OpenCode commands
• Codex/Cursor/Trae skills
• Gemini TOML commands
• Copilot prompts
• Antigravity/Kiro workflow files
• MCP tools for runtime instruction delivery, with load receipts — not a guarantee of routing, model, account, or task compliance

You keep the files in your repo, customize them with .skillsrc and custom_overrides, and run workflows inside the agent you already use.

How It Works

You run: npx agent-skills-standard sync

What your AI gets:

1. AGENTS.md (router)
   "Editing *.ts? Check typescript/_INDEX.md"

2. typescript/_INDEX.md (trigger table)
   File Match:  typescript-language  *.ts, *.tsx, tsconfig.json
   Keyword:     typescript-security  validate, sanitize, auth

3. typescript-language/SKILL.md (loaded on demand)
   The actual rules — only when needed.

The AI accesses matching skill files based on active file patterns and prompts, reducing token overhead compared to all-in-one prompts. Skill instructions provide structured guidance, though behavioral adherence remains model-dependent.

---

Architecture & Token Economy

This project follows a Zero-Trust architectural model inspired by Rust Token Killer (RTK). Instead of injecting every rule into every prompt, we use a hierarchical loading system that reads only the index rows and skills matching the current file and task.

Detailed documentation is available in ARCHITECTURE.md, covering:

• Hierarchical Resolution: Router Table (AGENTS.md) -> Category Index (_INDEX.md) -> Skill (SKILL.md).
• Integration Taxonomy: Multi-agent bridge support for Cursor, Claude, Copilot, Windsurf, Trae, Roo, etc.
• High-Density Design: All skills must be < 100 lines and optimized for token economy.

Quick Start

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 for full developer requirements (supported Node 22 LTS or newer supported LTS, pnpm 10+).

1. Initialize

Detects your tech stack and creates a .skillsrc configuration:

# Recommended: Install globally
npm install -g agent-skills-standard@latest
ags init

# Alternative: Run via npx without global installation
npx agent-skills-standard@latest init

2. Sync

Downloads skills into your configured AI agent directories, records ownership in .skills-lock.json v2, and generates the index:

# Recommended: Global CLI
ags sync

# Alternative: Via npx
npx agent-skills-standard@latest sync

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 if sync fails.

Tip Release & PATH Notes:

• Published version: read it from the npm package page badge or your installed binary (ags --version). That is the version consumers get from @latest.
• Source target: this checkout's CLI manifests and changelog target cli-v2.7.0 (see 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.

Safe Install & Local Edits

• Edit Protection: User-modified owned files are preserved and reported; they are never silently overwritten.
• ags sync --dry-run: Preview what would change without modifying files.
• ags sync --dry-run --verbose: List every affected file path.
• ags sync --dry-run --json: Output the install plan as JSON for CI or automation.
• ags sync --force <paths...>: Overwrite kept files after automatically backing them up.
• Scoped Backups: Pruned files and forced overwrites are saved to .ags/backups/ (latest 3 kept).
• Restore: Undo destructive changes with ags restore <id> or view backups with ags restore --list.
• Safe Uninstall: ags uninstall [--all] [--agent <agents...>] [--category <categories...>] removes only owned-unchanged files, preserving user edits and backing up first.

3. (Optional) Manage skill selections

Important ags skills exists in the current source target (cli-v2.7.0) and is not available in every published release. The published agent-skills-standard@2.6.6 package (installed from @latest during 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.

Add or remove guidance without editing YAML or looking up release tags:

# Using global CLI
ags skills

# Or via npx
npx agent-skills-standard@latest skills

Categories are checked from your current .skillsrc; newly enabled categories resolve their published release automatically, while existing pins stay untouched. Optionally customize nested skills (with search) or switch a category to its published release, review the full effect, then confirm once — the command saves the selection and installs it for every configured agent. Cancel or an unchanged selection writes nothing. On a real change the command records skills_mode: explicit, so a later ordinary sync will not silently re-add the categories or skills you removed.

4. Code

Your AI agent now reads AGENTS.md automatically. Skills activate based on what file you're editing and what you ask for.

Works instantly with Cursor, Claude Code, GitHub Copilot, Gemini CLI, Windsurf, Trae, Kiro, and Roo. No plugin or extension needed — the CLI generates each agent's native format.

5. (Optional) Enable MCP runtime delivery via the MCP server

The CLI distributes skills to disk. The companion MCP server serves them to your AI agent at runtime as explicit tool calls — closing the gap where agents read AGENTS.md but forget to load matched SKILL.md files (especially in sub-agents).

Consent model — you choose the scope

init and sync ask once whether to enable MCP and at what scope. Three choices, recommended in bold:

| Scope | What gets written | Touches $HOME? |