Agent Skills

Production-grade engineering skills for AI coding agents.

Skills encode the workflows, quality gates, and best practices that senior engineers use when building software. These ones are packaged so AI agents follow them consistently across every phase of development.

  DEFINE          PLAN           BUILD          VERIFY         REVIEW          SHIP
 ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐
 │ Idea │ ───▶ │ Spec │ ───▶ │ Code │ ───▶ │ Test │ ───▶ │  QA  │ ───▶ │  Go  │
 │Refine│      │  PRD │      │ Impl │      │Debug │      │ Gate │      │ Live │
 └──────┘      └──────┘      └──────┘      └──────┘      └──────┘      └──────┘
  /spec          /plan          /build        /test         /review       /ship

---

Commands

7 slash commands that map to the development lifecycle. Each one activates the right skills automatically.

What you're doing	Command	Key principle
Define what to build	/spec	Spec before code
Plan how to build it	/plan	Small, atomic tasks
Build incrementally	/build	One slice at a time
Prove it works	/test	Tests are proof
Review before merge	/review	Improve code health
Simplify the code	/code-simplify	Clarity over cleverness
Ship to production	/ship	Faster is safer

Skills also activate automatically based on what you're doing — designing an API triggers api-and-interface-design, building UI triggers frontend-ui-engineering, and so on.

---

Quick Start

# In the workspace you want to configure:
npx @chankov/agent-skills init
# Then open your coding agent in this directory and run:
#   /setup-agent-skills

That's it for guided setup. npx fetches the package, the CLI detects your coding agent (Claude Code, OpenCode, or pi), and /setup-agent-skills runs the full guided install — analysing the workspace, showing grouped menus, and confirming everything before writing a single file.

Three CLI commands:

Command	What it does
npx @chankov/agent-skills init	Materialize the package + hand off to /setup-agent-skills
npx @chankov/agent-skills doctor	Scan for broken symlinks and stale persona refs
npx @chankov/agent-skills update	Surface the version delta + hand off to /setup-agent-skills for the per-artifact diff

Versioned with semver; changelog in CHANGELOG.md; full docs in docs/npm-install.md.

Other install paths

/plugin marketplace add chankov/agent-skills
/plugin install agent-skills@nc-agent-skills

SSH errors? The marketplace clones repos via SSH. If you don't have SSH keys set up on GitHub, either add your SSH key or switch to HTTPS for fetches only:

git config --global url."https://github.com/".insteadOf "git@github.com:"

git clone https://github.com/chankov/agent-skills.git
cd agent-skills
# In Claude Code:
claude --plugin-dir .
# Then run /setup-agent-skills in your target workspace and pick "symlink" in Step 8.

Updates flow through git pull. Symlinks need Developer Mode on Windows.

Copy any SKILL.md into .cursor/rules/, or reference the full skills/ directory. See docs/cursor-setup.md.

Install as native skills for auto-discovery, or add to GEMINI.md for persistent context. See docs/gemini-cli-setup.md.

Install from the repo:

gemini skills install https://github.com/chankov/agent-skills.git --path skills

Install from a local clone:

gemini skills install ./agent-skills/skills/

Add skill contents to your Windsurf rules configuration. See docs/windsurf-setup.md.

Uses agent-driven skill execution via AGENTS.md and the skill tool.

The repo also ships optional OpenCode slash commands in .opencode/commands/ using an as- prefix as explicit lifecycle entry points (the agent will still invoke the same skills automatically from natural-language requests):

• /as-spec
• /as-plan
• /as-build
• /as-test
• /as-review
• /as-code-simplify
• /as-ship
• /as-design-agent

See docs/opencode-setup.md.

First-class pi package install:

pi install -l npm:@chankov/agent-skills

This includes the bundled pi-ask-user package, so the interactive ask_user tool and ask-user skill are available without a separate install.

pi has native Agent Skills support via AGENTS.md and discoverable skill directories like .agents/skills/. It can also expose the lifecycle commands (/spec, /plan, /build, /test, /review, /code-simplify, /ship) from .pi/prompts/, and pi extensions from .pi/extensions/ (currently: mcp-bridge, chrome-devtools-mcp, compact-and-continue; one-time npm ci required — see setup doc). For clone/symlink setup, install pi-ask-user separately with pi install -l npm:pi-ask-user unless it is already listed by pi list. See docs/pi-setup.md.

The repo also ships 15 selectable pi extension harnesses — agent orchestration, safety auditing, and Pi-to-Pi messaging — ported from disler's pi-vs-claude-code project (MIT). See the pi extension catalog for the full list, setup, and how to run each one.

Use agent definitions from agents/ as Copilot personas and skill content in .github/copilot-instructions.md. See docs/copilot-setup.md.

Skills are plain Markdown - they work with any agent that accepts system prompts or instruction files. See docs/getting-started.md.

---

All 20 Skills

The commands above are the entry points. Under the hood, they activate these 20 skills — each one a structured workflow with steps, verification gates, and anti-rationalization tables. You can also reference any skill directly.

Define - Clarify what to build

Skill	What It Does	Use When
idea-refine	Structured divergent/convergent thinking to turn vague ideas into concrete proposals	You have a rough concept that needs exploration
spec-driven-development	Write a PRD covering objectives, commands, structure, code style, testing, and boundaries before any code	Starting a new project, feature, or significant change

Plan - Break it down

Skill	What It Does	Use When
planning-and-task-breakdown	Decompose specs into small, verifiable tasks with acceptance criteria and dependency ordering	You have a spec and need implementable units

Build - Write the code

Skill	What It Does	Use When
incremental-implementation	Thin vertical slices - implement, test, verify, commit. Feature flags, safe defaults, rollback-friendly changes	Any change touching more than one file
test-driven-development	Red-Green-Refactor, test pyramid (80/15/5), test sizes, DAMP over DRY, Beyonce Rule, browser testing	Implementing logic, fixing bugs, or changing behavior
context-engineering	Feed agents the right information at the right time - rules files, context packing, MCP integrations	Starting a session, switching tasks, or when output quality drops
source-driven-development	Ground every framework decision in official documentation - verify, cite sources, flag what's unverified	You want authoritative, source-cited code for any framework or library
frontend-ui-engineering	Component architecture, design systems, state management, responsive design, WCAG 2.1 AA accessibility	Building or modifying user-facing interfaces
api-and-interface-design	Contract-first design, Hyrum's Law, One-Version Rule, error semantics, boundary validation	Designing APIs, module boundaries, or public interfaces

Verify - Prove it works

Skill	What It Does	Use When
browser-testing-with-devtools	Chrome DevTools MCP for live runtime data - DOM inspection, console logs, network traces, performance profiling	Building or debugging anything that runs in a browser
debugging-and-error-recovery	Five-step triage: reproduce, localize, reduce, fix, guard. Stop-the-line rule, safe fallbacks	Tests fail, builds break, or behavior is unexpected

Review - Quality gates before merge

Skill	What It Does	Use When
code-review-and-quality	Five-axis review, change sizing (~100 lines), severity labels (Nit/Optional/FYI), review speed norms, splitting strategies	Before merging any change
code-simplification	Chesterton's Fence, Rule of 500, reduce complexity while preserving exact behavior	Code works but is harder to read or maintain than it should be
security-and-hardening	OWASP Top 10 prevention, auth patterns, secrets management, dependency auditing, three-tier boundary system	Handling user input, auth, data storage, or external integrations
performance-optimization	Measure-first approach - Core Web Vitals targets, profiling workflows, bundle analysis, anti-pattern detection	Performance requirements exist or you suspect regressions

Ship - Deploy with confidence

Skill	What It Does	Use When
git-workflow-and-versioning	Trunk-based development, atomic commits, change sizing (~100 lines), the commit-as-save-point pattern	Making any code change (always)
ci-cd-and-automation	Shift Left, Faster is Safer, feature flags, quality gate pipelines, failure feedback loops	Setting up or modifying build and deploy pipelines
deprecation-and-migration	Code-as-liability mindset, compulsory vs advisory deprecation, migration patterns, zombie code removal	Removing old systems, migrating users, or sunsetting features
documentation-and-adrs	Architecture Decision Records, API docs, inline documentation standards - document the why	Making architectural decisions, changing APIs, or shipping features
shipping-and-launch	Pre-launch checklists, feature flag lifecycle, staged rollouts, rollback procedures, monitoring setup	Preparing to deploy to production

---

Agent Personas

Pre-configured specialist personas for targeted reviews:

Agent	Role	Perspective
code-reviewer	Senior Staff Engineer	Five-axis code review with "would a staff engineer approve this?" standard. Read-only.
test-engineer	QA Specialist	Test strategy, coverage analysis, and the Prove-It pattern
security-auditor	Security Engineer	Vulnerability detection, threat modeling, OWASP assessment. Read-only.
planner	Architect	Produces numbered, step-by-step implementation plans. Read-only.
plan-reviewer	Plan Critic	Stress-tests plans for assumptions, gaps, ordering, and feasibility. Read-only.
builder	Implementer	Carries out an approved plan with minimal, idiomatic code.
scout	Recon	Fast codebase exploration — structure, patterns, entry points. Read-only.
documenter	Tech Writer	READMEs, inline docs, usage examples in the project's voice.

---

Reference Checklists

Quick-reference material that skills pull in when needed:

Reference	Covers
testing-patterns.md	Test structure, naming, mocking, React/API/E2E examples, anti-patterns
security-checklist.md	Pre-commit checks, auth, input validation, headers, CORS, OWASP Top 10
performance-checklist.md	Core Web Vitals targets, frontend/backend checklists, measurement commands
accessibility-checklist.md	Keyboard nav, screen readers, visual design, ARIA, testing tools

---

How Skills Work

Every skill follows a consistent anatomy:

┌─────────────────────────────────────────────┐
│  SKILL.md                                   │
│                                             │
│  ┌─ Frontmatter ─────────────────────────┐  │
│  │ name: lowercase-hyphen-name           │  │
│  │ description: Use when [trigger]       │  │
│  └───────────────────────────────────────┘  │
│                                             │
│  Overview         → What this skill does    │
│  When to Use      → Triggering conditions   │
│  Process          → Step-by-step workflow   │
│  Rationalizations → Excuses + rebuttals     │
│  Red Flags        → Signs something's wrong │
│  Verification     → Evidence requirements   │
└─────────────────────────────────────────────┘

Key design choices:

• Process, not prose. Skills are workflows agents follow, not reference docs they read. Each has steps, checkpoints, and exit criteria.
• Anti-rationalization. Every skill includes a table of common excuses agents use to skip steps (e.g., "I'll add tests later") with documented counter-arguments.
• Verification is non-negotiable. Every skill ends with evidence requirements - tests passing, build output, runtime data. "Seems right" is never sufficient.
• Progressive disclosure. The SKILL.md is the entry point. Supporting references load only when needed, keeping token usage minimal.

---

Per-Project Overrides

A few skills produce files or need project-specific facts — where specs and plans are saved, how to start a dev server, whether the agent may create branches. Sensible defaults are built in, but any project can override them with a single file at .ai/agent-skills-overrides.md:

Skill	What you can override
spec-driven-development	Spec output directory and naming
planning-and-task-breakdown	Plan output directory, naming, embedded vs separate todo
browser-testing-with-devtools	Dev-server command, base URL, auth flow and roles (required — no default)
git-workflow-and-versioning	Whether the agent may create branches (default: never)

See docs/agent-skills-setup.md for the file format and a copy-paste template.

---

Project Structure

agent-skills/
├── skills/                            # 20 core skills (SKILL.md per directory)
│   ├── idea-refine/                   #   Define
│   ├── spec-driven-development/       #   Define
│   ├── planning-and-task-breakdown/   #   Plan
│   ├── incremental-implementation/    #   Build
│   ├── context-engineering/           #   Build
│   ├── source-driven-development/     #   Build
│   ├── frontend-ui-engineering/       #   Build
│   ├── test-driven-development/       #   Build
│   ├── api-and-interface-design/      #   Build
│   ├── browser-testing-with-devtools/ #   Verify
│   ├── debugging-and-error-recovery/  #   Verify
│   ├── code-review-and-quality/       #   Review
│   ├── code-simplification/          #   Review
│   ├── security-and-hardening/        #   Review
│   ├── performance-optimization/      #   Review
│   ├── git-workflow-and-versioning/   #   Ship
│   ├── ci-cd-and-automation/          #   Ship
│   ├── deprecation-and-migration/     #   Ship
│   ├── documentation-and-adrs/        #   Ship
│   ├── shipping-and-launch/           #   Ship
│   └── using-agent-skills/            #   Meta: how to use this pack
├── agents/                            # 3 specialist personas
├── references/                        # 4 supplementary checklists
├── hooks/                             # Session lifecycle hooks
├── .claude/commands/                  # 7 Claude slash commands
├── .pi/prompts/                       # 7 pi prompt-template commands
└── docs/                              # Setup guides per tool

---

Why Agent Skills?

AI coding agents default to the shortest path - which often means skipping specs, tests, security reviews, and the practices that make software reliable. Agent Skills gives agents structured workflows that enforce the same discipline senior engineers bring to production code.

Each skill encodes hard-won engineering judgment: when to write a spec, what to test, how to review, and when to ship. These aren't generic prompts - they're the kind of opinionated, process-driven workflows that separate production-quality work from prototype-quality work.

Skills bake in best practices from Google's engineering culture — including concepts from Software Engineering at Google and Google's engineering practices guide. You'll find Hyrum's Law in API design, the Beyonce Rule and test pyramid in testing, change sizing and review speed norms in code review, Chesterton's Fence in simplification, trunk-based development in git workflow, Shift Left and feature flags in CI/CD, and a dedicated deprecation skill treating code as a liability. These aren't abstract principles — they're embedded directly into the step-by-step workflows agents follow.

---

Contributing

Skills should be specific (actionable steps, not vague advice), verifiable (clear exit criteria with evidence requirements), battle-tested (based on real workflows), and minimal (only what's needed to guide the agent).

See docs/skill-anatomy.md for the format specification and CONTRIBUTING.md for guidelines.

---

License

MIT - use these skills in your projects, teams, and tools.