Production-grade process and technology skills for AI agents — one command installs the discipline your AI agents are missing. Ships a full dev lifecycle: adversarial idea validation through to PR creation.

View Landing Page

Getting Started

npx agents-skills install   # one-time setup (role-based wizard)
agents-skills init          # generate project profile

Then use one command to build anything:

Workflow	When to use
`/build-feature`	New features — full lifecycle: validate → PRD → plan → implement → review → ship
`/build-quick`	Bug fixes & small tasks — fast loop: validate → implement → review → ship
`/refactor-workflow`	Refactoring existing code safely without changing behavior
`/build-feature-agent`	Non-technical team members — guided version of the full lifecycle

Invoking Slash Commands in Your IDE

IDE	How to invoke
Claude Code	Type `/build-feature` directly in the chat prompt
Cursor	Type `/build-feature` in the AI chat panel
VS Code (Copilot)	`@workspace /build-feature`
Antigravity	Type `/build-feature` in the prompt bar

What it does

agents-skills distributes a curated set of Core Skills, Optional Skills, Tech Skills, and workflow commands into any workspace. Every AI agent operating in that workspace follows a structured, quality-enforced development lifecycle — from adversarial idea validation through to PR creation.

Three layers. All IDEs served.

Three-Layer Architecture

┌────────────────────────────────────────────────────────────┐
│  LAYER 1: PROCESS SKILLS                                   │
│  Teach agents HOW TO THINK                                 │
│  Core Skills (12) + Optional Skills (5)                    │
│  Role-based install: Frontend / Backend / Fullstack / Full │
├────────────────────────────────────────────────────────────┤
│  LAYER 2: TECHNOLOGY SKILLS                                │
│  Teach agents HOW TO USE SPECIFIC TOOLS                    │
│  Optional — installed individually or via pack aliases     │
├────────────────────────────────────────────────────────────┤
│  LAYER 3: WORKFLOWS & COMMANDS                             │
│  Full lifecycle orchestration                              │
│  Master workflow (automated) + Slash commands (composable) │
└────────────────────────────────────────────────────────────┘
              ↑ All three layers distributed via CLI ↑

Key Features

🧠 Core Skills: 12 skills that teach agents how to think — from PRD writing to security hardening. Included in every role-based install bundle.
🚀 Multi-IDE: Antigravity, VS Code, Cursor, Claude Code — all from one command.
📦 Skill Versioning: Every skill has a version tracked in .version files. doctor catches outdated installs.
🔗 Dependency Resolution: Skills declare dependencies in frontmatter. Installing graphql-backend auto-installs backend-engineer.
📦 Pack Aliases: Install a curated pack with one command — react-pack, frontend-pack, graphql-pack, etc.
🔍 Project Auto-detection: agents-skills init scans your workspace and generates a project-profile.json with framework, language, testing, and token budget config.
🍳 Prompt Recipes: Parameterized prompt templates (add-auth, add-crud-page, setup-ci, etc.) assembled interactively and copied to clipboard.
📊 Token Budget Enforcement: Built-in 40% context budget rule. agents-skills tokens shows per-skill token costs. Workflows enforce this in Phase 0.
📸 Context Snapshots: agents-skills compact (human-driven) or agents-skills compact --auto (agent-driven via context-engineering skill) creates structured markdown snapshots for resuming long sessions.
⬆️ Smart Upgrade: agents-skills upgrade detects schema version changes, shows a full migration diff, and safely removes deprecated skills with explicit confirmation.
🛡️ Safety First: Automatic backups before global changes. Smart conflict resolution (overwrite / keep / merge / skip).

Quick Start

# Full install wizard (all skills, workflows, rules, hooks)
npx agents-skills install

# Install a single skill
npx agents-skills install react-query

# Install a pack (resolves to individual skills)
npx agents-skills install react-pack

# List everything installed
agents-skills list

# Check workspace health
agents-skills doctor

CLI Commands

Command	Description	v3?
`agents-skills install`	Full interactive install wizard	—
`agents-skills install <skill>`	Install one skill (dependency-aware)	—
`agents-skills install <pack>`	Install pack alias (resolves to individual skills)	NEW
`agents-skills list`	List installed skills	—
`agents-skills list --registry`	List all available skills in public registry	NEW
`agents-skills upgrade`	Smart migration: detect schema version, update/add/remove skills	NEW
`agents-skills upgrade --dry-run`	Show migration diff without executing	NEW
`agents-skills init`	Auto-detect tech stack → generate `project-profile.json` (adds model-agnostic default)	UPGRADE
`agents-skills recipe [name]`	Browse and run parameterized prompt recipes	—
`agents-skills tokens [--budget\|--skill\|--file]`	Token usage breakdown with 40% budget check	—
`agents-skills compact`	Interactive context snapshot (human-driven)	—
`agents-skills compact --auto`	Agent-driven context snapshot via JSON payload	NEW
`agents-skills doctor`	Workspace health check — surfaces upgrade prompt on schema mismatch	UPGRADE
`agents-skills telemetry [on\|off\|status\|report]`	Manage local telemetry	—

Core Skills (12)

Included in all role-based install bundles (Frontend, Backend, Fullstack, Full).

Skill	Phase	Description
`grill-me`	Phase 0	Adversarial plan stress-testing. Attacks assumptions, resolves every branch of the decision tree before a line of code is written.
`context-engineering`	Phase 0	Teaches agents how to pack context efficiently. Upgrades `compact` CLI to be agent-driven.
`write-a-prd`	Phase 1	Produces a full PRD: user stories, success criteria, scope boundaries. Submitted as a GitHub issue.
`source-driven-development`	Phase 1	Grounds every framework decision in official docs. Agent must cite sources, never hallucinate APIs.
`prd-to-plan`	Phase 2	Turns a PRD into a tracer-bullet implementation plan. Each bullet = thin end-to-end vertical slice.
`incremental-implementation`	Phase 2	Implement → Test → Verify → Commit cycle discipline.
`code-reviewer`	Phase 4	Critique against project standards. Anti-rationalization table and verification gate.
`test-writing`	Phase 4	Vitest unit + Playwright E2E. TDD process guidance.
`security-and-hardening`	Phase 4	OWASP Top 10, auth patterns, secrets management, dependency auditing.
`git-workflow`	Phase 5	Branch naming, conventional commits, PR creation.
`ci-cd-and-automation`	Phase 5	Shift Left, quality gate pipelines, feature flags.
`skill-creator`	Meta	Generates new skills. Enforces 7-section anatomy output.

Optional Skills (5)

Installed on demand or with the Full bundle. Available as opt-in gates in /build-feature.

Skill	Trigger	Description
`performance-optimization`	Pre-ship	Core Web Vitals, bundle analysis, profiling.
`documentation-and-adrs`	Pre-ship	Architecture Decision Records, API docs, inline doc standards.
`debug-investigator`	On-demand	Root cause analysis, structured multi-step investigation.
`deprecation-and-migration`	On-demand	Code-as-liability mindset, migration patterns, zombie code removal.
`context-health-check`	On-demand	Pre-load cost estimation and forward-planning for context budget.

Technology Skills

All tech skills upgraded to 7-section anatomy. Installed individually or via pack aliases.

Individual Skills

Skill	Pack	Description
`firebase-setup`	`firebase-pack`	Firebase Auth, Firestore, and Storage conventions (v9 SDK)
`graphql-backend`	`graphql-pack`, `backend-pack`	Apollo Server, DataLoaders, schema design, N+1 prevention
`graphql-frontend`	`graphql-pack`	Apollo Client, fragments, cache management, code generation
`react-query`	`react-pack`	TanStack Query conventions, key factories, mutations
`rtk-query`	`react-pack`	RTK Query data-fetching, cache tags, optimistic updates
`react-native`	`react-pack`, `mobile-pack`	Expo, React Navigation, native modules, styling, performance
`react-component-scaffolder`	`react-pack`, `frontend-pack`	Boilerplate for strict React/Vite components
`frontend-design`	`frontend-pack`	Production-grade UI/UX with premium design quality
`payload-cms`	standalone	PayloadCMS v3 + Next.js: collections, blocks, media, email
`api-integration`	`frontend-pack`	Frontend ↔ Redux/Firebase endpoint connection
`backend-engineer`	`backend-pack`	Node.js, TypeScript, MongoDB, REST APIs, Microservices
`playwright`	`testing-pack`	Full Playwright E2E: selectors, POM, assertions, mocking, CI
`post-pr-review`	standalone	Post code review feedback as inline GitHub PR comments

Pack Aliases

Packs are install-time shortcuts — resolved to individual skill installs.

Pack	Resolves To
`react-pack`	react-query, rtk-query, react-native, react-component-scaffolder
`frontend-pack`	react-component-scaffolder, frontend-design, api-integration
`graphql-pack`	graphql-backend, graphql-frontend
`backend-pack`	backend-engineer, graphql-backend
`firebase-pack`	firebase-setup
`mobile-pack`	react-native
`testing-pack`	playwright, test-writing

7-Section Skill Anatomy

Every first-party skill implements all 7 sections:

---
name: skill-name
description: One-line trigger description
version: 1.0.0
category: process | technology
optional: true | false
dependencies: []
---

## 1. Trigger Conditions
## 2. Prerequisites
## 3. Steps
## 4. Anti-Rationalization Table
## 5. Red Flags
## 6. Verification Gate
## 7. References

Workflows

`/build-feature` — Master Workflow

Chains all Core Skill phases with gate conditions:

Phase 0: Core Skills Check (binary — no NLP)
  └── Are Core Skills installed? If not → print install command → exit

Phase 1: Grill  [/grill-me]
  └── Adversarial validation → resolved decision tree

Phase 2: PRD  [/write-a-prd]
  └── User stories, success criteria, scope → GitHub issue

Phase 3: Plan  [/prd-to-plan]
  └── Tracer-bullet vertical slices → ./plans/*.md

Phase 4: Implement  [/implement]
  └── Load tech skills → Implement → Test → Verify → Commit

Phase 5: Quality  [/review] [/secure] [/test]
  └── Code review → Security audit → Test suite

Phase 5a: Optional Gates (user opt-in)
  └── [/perf]  Performance audit
  └── [/docs]  Documentation + ADRs

Phase 6: Ship  [/ship]
  └── Branch → Commit → PR

`/build-quick` — Fast Loop

For bug fixes and small tasks — 4 phases, no PRD or plan:

Phase 1: Grill      [/grill-me]   (lightweight — scope validation only)
Phase 2: Implement  [/implement]
Phase 3: Review     [/review]
Phase 4: Ship       [/ship]

Individual Slash Commands

Command	Skill	Output
`/grill-me`	grill-me	Resolved decision tree
`/write-a-prd`	write-a-prd	PRD → GitHub issue
`/prd-to-plan`	prd-to-plan	`./plans/*.md`
`/implement`	incremental-implementation + tech skills	Working vertical slice
`/review`	code-reviewer	Review report
`/secure`	security-and-hardening	Security audit
`/test`	test-writing	Test suite
`/ship`	git-workflow + ci-cd-and-automation	Branch, commit, PR
`/perf`	performance-optimization	Performance audit
`/docs`	documentation-and-adrs	ADRs + docs
`/compact`	context-engineering	Agent-driven context snapshot
`/debug`	debug-investigator	Root cause report

Skill Gap Detection

Phase 0 of /build-feature runs a binary Core Skills check — no NLP parsing:

OUTCOME A — Core Skills installed:
  "Core Skills are installed. Proceeding."

OUTCOME B — Core Skills missing:
  "Core Skills are not fully installed.
   Run: npx agents-skills install
   Then re-run /build-feature."

To browse and install tech skills: agents-skills list --registry

Upgrade Command

Minor upgrade (same schema version)

agents-skills upgrade
  → Detect outdated skills → overwrite with latest → update .version files
  → "3 skills updated: code-reviewer v1.1, git-workflow v1.2"

Major upgrade (v2 → v3 schema change)

agents-skills upgrade
  STEP 1 — Show migration diff (read-only):
    ✓ Will UPDATE (12 skills): code-reviewer, git-workflow...
    + Will ADD (8 new skills): grill-me, write-a-prd...
    ✗ Will REMOVE (2 skills): app-architect, doc-coauthoring

  STEP 2 — Confirm destructive changes:
    "2 skills will be removed. Proceed? [y/N]"

  STEP 3 — Execute after confirmation

  STEP 4 — Summary + "Run agents-skills doctor to verify"

Use agents-skills upgrade --dry-run to preview without executing.

Context Engineering Upgrade

Human-driven (still available)

agents-skills compact

Interactive prompts → snapshot in .agents/context-snapshots/.

Agent-driven (new in v3)

agents-skills compact --auto '{"goal":"...","completed":[...],...}'

The context-engineering skill teaches agents to auto-fill all snapshot fields from session state — no human prompts needed.

Token Budget System

Model-agnostic default

Conservative default: 128k context → 51,200 token budget (40%)

Config file override (`agents-skills.config.json`)

{
  "model": "claude-sonnet-4-20250514",
  "contextWindow": 200000,
  "budgetPercent": 40
}

# See live breakdown per skill
agents-skills tokens

# Quick budget check
agents-skills tokens --budget

Skill Dependencies

Skills declare dependencies in their SKILL.md frontmatter:

---
name: graphql-backend
dependencies:
  - backend-engineer
---

Current dependency graph:

graphql-backend   → backend-engineer
frontend-design   → react-component-scaffolder
post-pr-review    → code-reviewer

Project Profile

Running agents-skills init scans your workspace and writes .agents/project-profile.json:

{
  "generated_at": "2026-04-14T...",
  "framework": "next-app-router",
  "language": "typescript",
  "styling": "tailwindcss",
  "stateManagement": "react-query",
  "testing": { "unit": "vitest", "e2e": "playwright" },
  "packageManager": "pnpm",
  "detectedSkills": ["frontend-design", "react-query", "playwright", "test-writing"],
  "tokenBudget": {
    "model": "model-agnostic",
    "contextWindow": 128000,
    "budgetPercent": 40,
    "budgetTokens": 51200
  }
}

IDE Output Mapping

Source (`.agents/`)	Antigravity	VS Code / Copilot	Cursor	Claude Code
`rules/project-standards.md`	`.agents/rules/project-standards.md`	`.github/copilot-instructions.md`	`.cursorrules`	`CLAUDE.md`
`rules/*.md` (rest)	`.agents/rules/`	`.github/rules/`	`.cursor/rules/*.mdc`	`.claude/rules/`
`skills/`	`.agents/skills/`	`.github/skills/`	`.cursor/skills/`	`.claude/skills/`
`commands/`	`.agents/commands/`	`.github/instructions/`	`.cursor/commands/`	`.claude/commands/`
`workflows/`	`.agents/workflows/`	`.github/agents/`	`.cursor/agents/`	`.claude/agents/`
`hooks/`	`.agents/hooks/`	`.github/hooks/`	`.cursor/rules/*.mdc` (alwaysApply)	`.claude/hooks/`
`recipes/`	`.agents/recipes/`	`.github/recipes/`	`.cursor/recipes/`	`.claude/recipes/`

Project Structure

.agents/                  # Canonical agent source files
├── rules/                # Style guides & AI instructions
├── skills/               # Capability-specific prompt snippets
│   ├── <process-skill>/  # Mandatory + optional process skills
│   └── <tech-skill>/     # Technology skills
├── commands/             # Thin slash command stubs (10-20 lines each)
│   ├── grill-me.md       # /grill-me
│   ├── write-a-prd.md    # /write-a-prd
│   ├── prd-to-plan.md    # /prd-to-plan
│   ├── implement.md      # /implement
│   ├── ship.md           # /ship
│   └── compact.md        # /compact
├── workflows/            # Full orchestration docs
│   ├── build-feature.md         # Master workflow (full lifecycle)
│   ├── build-quick.md           # Fast loop (bug fixes, small tasks)
│   ├── build-feature-agent.md   # Non-technical user variant
│   └── refactor-workflow.md     # Safe refactoring workflow
├── hooks/                # AI-powered event handlers
├── recipes/              # Parameterized prompt templates
├── context-snapshots/    # Auto-generated session resumption files
└── project-profile.json  # Generated by `agents-skills init`

bin/
└── cli.js                # CLI entry point + subcommand router

src/
├── adapters/             # IDE-specific mapping logic
├── commands/             # CLI command implementations
│   ├── list.js
│   ├── doctor.js
│   ├── init.js
│   ├── recipe.js
│   ├── tokens.js
│   ├── compact.js
│   ├── upgrade.js        # NEW: smart migration command
│   └── telemetry.js
└── core/                 # Core engine modules
    ├── skill-registry.js
    ├── dependency-resolver.js
    ├── project-detector.js
    ├── token-counter.js
    ├── context-compactor.js
    ├── recipe-engine.js
    └── telemetry.js

skills.json               # Registry manifest (v3 schema)
docs/                     # Landing page (GitHub Pages)

`skills.json` Registry Manifest

{
  "version": "3.0.0",
  "skills": [
    {
      "name": "grill-me",
      "version": "1.0.0",
      "category": "process",
      "optional": false,
      "description": "Adversarial plan stress-testing",
      "packs": [],
      "dependencies": []
    }
  ],
  "packs": [
    {
      "name": "react-pack",
      "description": "All React-related skills",
      "skills": ["react-query", "rtk-query", "react-native", "react-component-scaffolder"]
    }
  ]
}

agents-skills list --registry fetches this manifest from GitHub and diffs against locally installed skills.

Requirements

Node.js 16+
npm 7+ (for npx support)

Development

# Link locally for testing
npm link
agents-skills help

# Unlink when done
npm unlink -g agents-skills

Publishing

npm login
npm version patch   # or minor/major
npm publish --access public

The prepublishOnly script automatically copies .agents/skills → skills/ and .agents/recipes → recipes/ before publish.

License

MIT

Keywords

FAQs

What is agents-skills?

Is agents-skills popular?

Is agents-skills well maintained?

Package last updated on 17 Apr 2026

agents-skills

agents-skills v3