Agent Skills Standard

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

Current release: v2.5.1 — trust-gated review workflows, markdown-first security handoff, expanded framework/database guidance, and a new Python backend skill pack for SDLC delivery.

280 ready-to-use coding standards for Cursor, Claude Code, GitHub Copilot, Gemini, Windsurf, Trae, Kiro, Roo and more — synced, versioned, and optimized to use 85% fewer tokens than traditional prompt engineering.

npx agent-skills-standard@latest init
npx agent-skills-standard@latest sync
# Done. Your AI now has portable team standards and SDLC workflows.

If ags -V still shows an old version after reinstalling, check your PATH order. ~/Library/pnpm must come before ~/Library/pnpm/bin, then run hash -r and verify with ags -V again.

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 | | :------------------------------------------ | :------------------------------------------------------------------ | | 3,600+ token architect prompt in every chat | ~500 token 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 | | AI scans all rules every time (slow, lossy) | Hierarchical lookup: ~25 lines scanned per edit |

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 enforcement

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 ~20 lines)
   "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 loads only the skills that match the file being edited and the task at hand. No wasted tokens. No forgotten rules.

---

Architecture & Token Economy

This project follows a Zero-Trust architectural model inspired by Rust Token Killer (RTK). Instead of injecting all rules into every prompt (which can cost 5,000+ tokens and cause "prompt loss"), we use a hierarchical loading system.

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

1. Initialize

Detects your tech stack and creates a .skillsrc config:

npx agent-skills-standard@latest init

2. Sync

Downloads skills into your AI agent's folders and generates the index:

npx agent-skills-standard@latest sync

3. 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.

4. (Optional) Enable runtime enforcement 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? | | --------------------------- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | | 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're not re-prompted on every sync.

Manage MCP integration with the mcp subcommand

ags mcp status                 # Show enabled, scope, and per-agent install state
ags mcp enable                 # Turn on (uses configured scope)
ags mcp disable                # Turn off (existing entries kept; use uninstall to clean)
ags mcp scope project          # Change scope: project | user | snippets-only | disabled
ags mcp install                # One-shot install at the configured scope
ags mcp uninstall --from=all   # Remove our entry from project + user configs
ags mcp snippets               # Regenerate ./mcp-config-snippets/ without touching configs

Or edit .skillsrc directly:

mcp:
  enabled: true
  scope: project # project | user | snippets-only | disabled
  prompted: true # set to false to be re-asked next sync

Manual install (if you prefer)

Add to your runtime's MCP config:

{
  "mcpServers": {
    "agent-skills-standard": {
      "command": "npx",
      "args": ["-y", "agent-skills-standard-mcp"],
    },
  },
}

Now any sub-agent in any runtime can call load_skills_for_files, audit_session_compliance, etc. Works in Claude Code, Cursor, Antigravity, Kiro, Continue, Gemini CLI — anywhere MCP is supported. Full setup: mcp/README.md.

CLI vs MCP — paired layers, not alternatives

| Layer | Tool | Runs when | Purpose | | ------------------------- | --------------------------------- | ------------------------------- | ---------------------------------------------------------------------- | | Distribution | agent-skills-standard (CLI) | Manually, before AI session | Fetches & writes SKILL.md files; generates AGENTS.md + _INDEX.md | | Runtime / Enforcement | agent-skills-standard-mcp (MCP) | Auto-launched by the AI runtime | Serves matched SKILL.md to live agents on demand; provides audit log |

Use both when you want enforcement receipts: the CLI installs the rules, the MCP makes sure agents load them.

---

SDLC Workflow Spine

The registry now ships a compact lifecycle that agents can run natively after sync:

| Stage | Synced Workflow | Output | | :--------- | :------------------------------ | :---------------------------- | | Route | sdlc | next workflow and blockers | | Brainstorm | brainstorm-feature | product-brief.md | | Plan | plan-feature | PRD, decisions, task slices | | Design | design-solution | architecture, contracts, ADR | | Readiness | implementation-readiness | go/no-go before code | | Build | implement-feature / dev-fix | implementation handoff | | Review | review-ticket | multi-lens PR/ticket verdict | | Verify | verify-work / verify-bug | walkthrough.md evidence | | Security | pentest / security-test | hacker report, PoC, SAST logs |

Session Telemetry

The registry now includes the common-telemetry skill and a companion MCP tool get_session_cost(). At the end of every workflow, the agent can now report MCP-observed session telemetry plus exact-or-estimated token cost when the host runtime supplies usage and pricing data.

See SDLC Workflow Quick Reference.

Default SDLC Support

ags init includes framework skills plus shared SDLC support categories when the registry provides them:

| Surface | How It Syncs | | :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | quality-engineering | Included as a skill category for BA review, Jira traceability, QA standards, browser/mobile verification, and Zephyr coverage | | specialists | Converted directly into native sub-agent files for Jira analysis, codebase scouting, architecture/security review, AC verification, test gaps, PR metadata, Zephyr/Confluence lookup, PR comments, integration tests, and TC creation |

External task