@chankov/agent-skills 0.1.0

package/.versions/0.1.0/skills/using-agent-skills/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: using-agent-skills
+description: Discovers and invokes agent skills. Use when starting a session or when you need to discover which skill applies to the current task. This is the meta-skill that governs how all other skills are discovered and invoked.
+---
+
+# Using Agent Skills
+
+## Overview
+
+Agent Skills is a collection of engineering workflow skills organized by development phase. Each skill encodes a specific process that senior engineers follow. This meta-skill helps you discover and apply the right skill for your current task.
+
+## Skill Discovery
+
+When a task arrives, identify the development phase and apply the corresponding skill:
+
+```
+Task arrives
+    │
+    ├── Vague idea/need refinement? ──→ idea-refine
+    ├── New project/feature/change? ──→ spec-driven-development
+    ├── Have a spec, need tasks? ──────→ planning-and-task-breakdown
+    ├── Implementing code? ────────────→ incremental-implementation
+    │   ├── UI work? ─────────────────→ frontend-ui-engineering
+    │   ├── API work? ────────────────→ api-and-interface-design
+    │   ├── Need better context? ─────→ context-engineering
+    │   └── Need doc-verified code? ───→ source-driven-development
+    ├── Writing/running tests? ────────→ test-driven-development
+    │   └── Browser-based? ───────────→ browser-testing-with-devtools
+    ├── Something broke? ──────────────→ debugging-and-error-recovery
+    ├── Reviewing code? ───────────────→ code-review-and-quality
+    │   ├── Security concerns? ───────→ security-and-hardening
+    │   └── Performance concerns? ────→ performance-optimization
+    ├── Committing/branching? ─────────→ git-workflow-and-versioning
+    ├── CI/CD pipeline work? ──────────→ ci-cd-and-automation
+    ├── Writing docs/ADRs? ───────────→ documentation-and-adrs
+    ├── Authoring a new skill/persona? ─→ designing-agents
+    └── Deploying/launching? ─────────→ shipping-and-launch
+```
+
+## Core Operating Behaviors
+
+These behaviors apply at all times, across all skills. They are non-negotiable.
+
+### 1. Surface Assumptions
+
+Before implementing anything non-trivial, explicitly state your assumptions:
+
+```
+ASSUMPTIONS I'M MAKING:
+1. [assumption about requirements]
+2. [assumption about architecture]
+3. [assumption about scope]
+→ Correct me now or I'll proceed with these.
+```
+
+Don't silently fill in ambiguous requirements. The most common failure mode is making wrong assumptions and running with them unchecked. Surface uncertainty early — it's cheaper than rework.
+
+### 2. Manage Confusion Actively
+
+When you encounter inconsistencies, conflicting requirements, or unclear specifications:
+
+1. **STOP.** Do not proceed with a guess.
+2. Name the specific confusion.
+3. Present the tradeoff or ask the clarifying question.
+4. Wait for resolution before continuing.
+
+**Bad:** Silently picking one interpretation and hoping it's right.
+**Good:** "I see X in the spec but Y in the existing code. Which takes precedence?"
+
+### 3. Push Back When Warranted
+
+You are not a yes-machine. When an approach has clear problems:
+
+- Point out the issue directly
+- Explain the concrete downside (quantify when possible — "this adds ~200ms latency" not "this might be slower")
+- Propose an alternative
+- Accept the human's decision if they override with full information
+
+Sycophancy is a failure mode. "Of course!" followed by implementing a bad idea helps no one. Honest technical disagreement is more valuable than false agreement.
+
+### 4. Enforce Simplicity
+
+Your natural tendency is to overcomplicate. Actively resist it.
+
+Before finishing any implementation, ask:
+- Can this be done in fewer lines?
+- Are these abstractions earning their complexity?
+- Would a staff engineer look at this and say "why didn't you just..."?
+
+If you build 1000 lines and 100 would suffice, you have failed. Prefer the boring, obvious solution. Cleverness is expensive.
+
+### 5. Maintain Scope Discipline
+
+Touch only what you're asked to touch.
+
+Do NOT:
+- Remove comments you don't understand
+- "Clean up" code orthogonal to the task
+- Refactor adjacent systems as a side effect
+- Delete code that seems unused without explicit approval
+- Add features not in the spec because they "seem useful"
+
+Your job is surgical precision, not unsolicited renovation.
+
+### 6. Verify, Don't Assume
+
+Every skill includes a verification step. A task is not complete until verification passes. "Seems right" is never sufficient — there must be evidence (passing tests, build output, runtime data).
+
+## Failure Modes to Avoid
+
+These are the subtle errors that look like productivity but create problems:
+
+1. Making wrong assumptions without checking
+2. Not managing your own confusion — plowing ahead when lost
+3. Not surfacing inconsistencies you notice
+4. Not presenting tradeoffs on non-obvious decisions
+5. Being sycophantic ("Of course!") to approaches with clear problems
+6. Overcomplicating code and APIs
+7. Modifying code or comments orthogonal to the task
+8. Removing things you don't fully understand
+9. Building without a spec because "it's obvious"
+10. Skipping verification because "it looks right"
+
+## Skill Rules
+
+1. **Check for an applicable skill before starting work.** Skills encode processes that prevent common mistakes.
+
+2. **Skills are workflows, not suggestions.** Follow the steps in order. Don't skip verification steps.
+
+3. **Multiple skills can apply.** A feature implementation might involve `idea-refine` → `spec-driven-development` → `planning-and-task-breakdown` → `incremental-implementation` → `test-driven-development` → `code-review-and-quality` → `shipping-and-launch` in sequence.
+
+4. **When in doubt, start with a spec.** If the task is non-trivial and there's no spec, begin with `spec-driven-development`.
+
+## Lifecycle Sequence
+
+For a complete feature, the typical skill sequence is:
+
+```
+1. idea-refine                 → Refine vague ideas
+2. spec-driven-development     → Define what we're building
+3. planning-and-task-breakdown → Break into verifiable chunks
+4. context-engineering         → Load the right context
+5. source-driven-development   → Verify against official docs
+6. incremental-implementation  → Build slice by slice
+7. test-driven-development     → Prove each slice works
+8. code-review-and-quality     → Review before merge
+9. git-workflow-and-versioning → Clean commit history
+10. documentation-and-adrs     → Document decisions
+11. shipping-and-launch        → Deploy safely
+```
+
+Not every task needs every skill. A bug fix might only need: `debugging-and-error-recovery` → `test-driven-development` → `code-review-and-quality`.
+
+## Quick Reference
+
+| Phase | Skill | One-Line Summary |
+|-------|-------|-----------------|
+| Define | idea-refine | Refine ideas through structured divergent and convergent thinking |
+| Define | spec-driven-development | Requirements and acceptance criteria before code |
+| Plan | planning-and-task-breakdown | Decompose into small, verifiable tasks |
+| Build | incremental-implementation | Thin vertical slices, test each before expanding |
+| Build | source-driven-development | Verify against official docs before implementing |
+| Build | context-engineering | Right context at the right time |
+| Build | frontend-ui-engineering | Production-quality UI with accessibility |
+| Build | api-and-interface-design | Stable interfaces with clear contracts |
+| Verify | test-driven-development | Failing test first, then make it pass |
+| Verify | browser-testing-with-devtools | Chrome DevTools MCP for runtime verification |
+| Verify | debugging-and-error-recovery | Reproduce → localize → fix → guard |
+| Review | code-review-and-quality | Five-axis review with quality gates |
+| Review | security-and-hardening | OWASP prevention, input validation, least privilege |
+| Review | performance-optimization | Measure first, optimize only what matters |
+| Ship | git-workflow-and-versioning | Atomic commits, clean history |
+| Ship | ci-cd-and-automation | Automated quality gates on every change |
+| Ship | documentation-and-adrs | Document the why, not just the what |
+| Ship | shipping-and-launch | Pre-launch checklist, monitoring, rollback plan |
+| Author | designing-agents | Author a persona, workflow skill, or pi harness |

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# agent-skills changelog
+
+All notable changes to this project are documented here. Format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning follows
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html). Entries below 0.1.0
+are pre-npm history captured in git.
+
+The file is rolled forward by [changesets](https://github.com/changesets/changesets) —
+do not edit it by hand. Add a `.changeset/<name>.md` file describing your
+change and let `changeset version` aggregate it.
+
+## Unreleased
+
+Pending changesets in `.changeset/` will roll into the next release.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Addy Osmani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,359 @@
+# 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
+
+```bash
+# In the workspace you want to configure:
+npx @chankov/agent-skills init
+# Then open your coding agent in this directory and run:
+#   /setup
+```
+
+That's it. `npx` fetches the package, the CLI detects your coding agent
+(Claude Code, OpenCode, or pi), and `/setup` 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` |
+| `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` for the per-artifact diff |
+
+Versioned with [semver](https://semver.org); changelog in
+[CHANGELOG.md](CHANGELOG.md); full docs in [docs/npm-install.md](docs/npm-install.md).
+
+### Other install paths
+
+<details>
+<summary><b>Claude Code plugin marketplace</b> — best UX inside Claude Code</summary>
+
+```
+/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](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account) or switch to HTTPS for fetches only:
+> ```bash
+> git config --global url."https://github.com/".insteadOf "git@github.com:"
+> ```
+
+</details>
+
+<details>
+<summary><b>Git clone + symlinks</b> — best for skill authors and contributors</summary>
+
+```bash
+git clone https://github.com/chankov/agent-skills.git
+cd agent-skills
+# In Claude Code:
+claude --plugin-dir .
+# Then run /setup in your target workspace and pick "symlink" in Step 8.
+```
+
+Updates flow through `git pull`. Symlinks need Developer Mode on Windows.
+
+</details>
+
+<details>
+<summary><b>Cursor</b></summary>
+
+Copy any `SKILL.md` into `.cursor/rules/`, or reference the full `skills/` directory. See [docs/cursor-setup.md](docs/cursor-setup.md).
+
+</details>
+
+<details>
+<summary><b>Gemini CLI</b></summary>
+
+Install as native skills for auto-discovery, or add to `GEMINI.md` for persistent context. See [docs/gemini-cli-setup.md](docs/gemini-cli-setup.md).
+
+**Install from the repo:**
+
+```bash
+gemini skills install https://github.com/chankov/agent-skills.git --path skills
+```
+
+**Install from a local clone:**
+
+```bash
+gemini skills install ./agent-skills/skills/
+```
+
+</details>
+
+<details>
+<summary><b>Windsurf</b></summary>
+
+Add skill contents to your Windsurf rules configuration. See [docs/windsurf-setup.md](docs/windsurf-setup.md).
+
+</details>
+
+<details>
+<summary><b>OpenCode</b></summary>
+
+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](docs/opencode-setup.md).
+
+</details>
+
+<details>
+<summary><b>pi</b></summary>
+
+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). See [docs/pi-setup.md](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](https://github.com/disler)'s [`pi-vs-claude-code`](https://github.com/disler/pi-vs-claude-code) project (MIT). See the [pi extension catalog](docs/pi-extensions.md) for the full list, setup, and how to run each one.
+
+</details>
+
+<details>
+<summary><b>GitHub Copilot</b></summary>
+
+Use agent definitions from `agents/` as Copilot personas and skill content in `.github/copilot-instructions.md`. See [docs/copilot-setup.md](docs/copilot-setup.md).
+
+</details>
+
+<details>
+<summary><b>Codex / Other Agents</b></summary>
+
+Skills are plain Markdown - they work with any agent that accepts system prompts or instruction files. See [docs/getting-started.md](docs/getting-started.md).
+
+</details>
+
+---
+
+## 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](skills/idea-refine/SKILL.md) | Structured divergent/convergent thinking to turn vague ideas into concrete proposals | You have a rough concept that needs exploration |
+| [spec-driven-development](skills/spec-driven-development/SKILL.md) | 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](skills/planning-and-task-breakdown/SKILL.md) | 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](skills/incremental-implementation/SKILL.md) | Thin vertical slices - implement, test, verify, commit. Feature flags, safe defaults, rollback-friendly changes | Any change touching more than one file |
+| [test-driven-development](skills/test-driven-development/SKILL.md) | 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](skills/context-engineering/SKILL.md) | 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](skills/source-driven-development/SKILL.md) | 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](skills/frontend-ui-engineering/SKILL.md) | Component architecture, design systems, state management, responsive design, WCAG 2.1 AA accessibility | Building or modifying user-facing interfaces |
+| [api-and-interface-design](skills/api-and-interface-design/SKILL.md) | 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](skills/browser-testing-with-devtools/SKILL.md) | 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](skills/debugging-and-error-recovery/SKILL.md) | 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](skills/code-review-and-quality/SKILL.md) | Five-axis review, change sizing (~100 lines), severity labels (Nit/Optional/FYI), review speed norms, splitting strategies | Before merging any change |
+| [code-simplification](skills/code-simplification/SKILL.md) | 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](skills/security-and-hardening/SKILL.md) | 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](skills/performance-optimization/SKILL.md) | 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](skills/git-workflow-and-versioning/SKILL.md) | Trunk-based development, atomic commits, change sizing (~100 lines), the commit-as-save-point pattern | Making any code change (always) |
+| [ci-cd-and-automation](skills/ci-cd-and-automation/SKILL.md) | Shift Left, Faster is Safer, feature flags, quality gate pipelines, failure feedback loops | Setting up or modifying build and deploy pipelines |
+| [deprecation-and-migration](skills/deprecation-and-migration/SKILL.md) | Code-as-liability mindset, compulsory vs advisory deprecation, migration patterns, zombie code removal | Removing old systems, migrating users, or sunsetting features |
+| [documentation-and-adrs](skills/documentation-and-adrs/SKILL.md) | Architecture Decision Records, API docs, inline documentation standards - document the *why* | Making architectural decisions, changing APIs, or shipping features |
+| [shipping-and-launch](skills/shipping-and-launch/SKILL.md) | 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](agents/code-reviewer.md) | Senior Staff Engineer | Five-axis code review with "would a staff engineer approve this?" standard. Read-only. |
+| [test-engineer](agents/test-engineer.md) | QA Specialist | Test strategy, coverage analysis, and the Prove-It pattern |
+| [security-auditor](agents/security-auditor.md) | Security Engineer | Vulnerability detection, threat modeling, OWASP assessment. Read-only. |
+| [planner](agents/planner.md) | Architect | Produces numbered, step-by-step implementation plans. Read-only. |
+| [plan-reviewer](agents/plan-reviewer.md) | Plan Critic | Stress-tests plans for assumptions, gaps, ordering, and feasibility. Read-only. |
+| [builder](agents/builder.md) | Implementer | Carries out an approved plan with minimal, idiomatic code. |
+| [scout](agents/scout.md) | Recon | Fast codebase exploration — structure, patterns, entry points. Read-only. |
+| [documenter](agents/documenter.md) | 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](references/testing-patterns.md) | Test structure, naming, mocking, React/API/E2E examples, anti-patterns |
+| [security-checklist.md](references/security-checklist.md) | Pre-commit checks, auth, input validation, headers, CORS, OWASP Top 10 |
+| [performance-checklist.md](references/performance-checklist.md) | Core Web Vitals targets, frontend/backend checklists, measurement commands |
+| [accessibility-checklist.md](references/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](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](https://abseil.io/resources/swe-book) and Google's [engineering practices guide](https://google.github.io/eng-practices/). 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](docs/skill-anatomy.md) for the format specification and [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+---
+
+## License
+
+MIT - use these skills in your projects, teams, and tools.

package/agents/builder.md

@@ -0,0 +1,6 @@
+---
+name: builder
+description: Implementation and code generation
+tools: read,write,edit,bash,grep,find,ls
+---
+You are a builder agent. Implement the requested changes thoroughly. Write clean, minimal code. Follow existing patterns in the codebase. Test your work when possible.

package/agents/code-reviewer.md

@@ -0,0 +1,93 @@
+---
+name: code-reviewer
+description: Senior code reviewer that evaluates changes across five dimensions — correctness, readability, architecture, security, and performance. Use for thorough code review before merge.
+tools: read,bash,grep,find,ls
+---
+
+# Senior Code Reviewer
+
+You are an experienced Staff Engineer conducting a thorough code review. Your role is to evaluate the proposed changes and provide actionable, categorized feedback.
+
+## Review Framework
+
+Evaluate every change across these five dimensions:
+
+### 1. Correctness
+- Does the code do what the spec/task says it should?
+- Are edge cases handled (null, empty, boundary values, error paths)?
+- Do the tests actually verify the behavior? Are they testing the right things?
+- Are there race conditions, off-by-one errors, or state inconsistencies?
+
+### 2. Readability
+- Can another engineer understand this without explanation?
+- Are names descriptive and consistent with project conventions?
+- Is the control flow straightforward (no deeply nested logic)?
+- Is the code well-organized (related code grouped, clear boundaries)?
+
+### 3. Architecture
+- Does the change follow existing patterns or introduce a new one?
+- If a new pattern, is it justified and documented?
+- Are module boundaries maintained? Any circular dependencies?
+- Is the abstraction level appropriate (not over-engineered, not too coupled)?
+- Are dependencies flowing in the right direction?
+
+### 4. Security
+- Is user input validated and sanitized at system boundaries?
+- Are secrets kept out of code, logs, and version control?
+- Is authentication/authorization checked where needed?
+- Are queries parameterized? Is output encoded?
+- Any new dependencies with known vulnerabilities?
+
+### 5. Performance
+- Any N+1 query patterns?
+- Any unbounded loops or unconstrained data fetching?
+- Any synchronous operations that should be async?
+- Any unnecessary re-renders (in UI components)?
+- Any missing pagination on list endpoints?
+
+## Output Format
+
+Categorize every finding:
+
+**Critical** — Must fix before merge (security vulnerability, data loss risk, broken functionality)
+
+**Important** — Should fix before merge (missing test, wrong abstraction, poor error handling)
+
+**Suggestion** — Consider for improvement (naming, code style, optional optimization)
+
+## Review Output Template
+
+```markdown
+## Review Summary
+
+**Verdict:** APPROVE | REQUEST CHANGES
+
+**Overview:** [1-2 sentences summarizing the change and overall assessment]
+
+### Critical Issues
+- [File:line] [Description and recommended fix]
+
+### Important Issues
+- [File:line] [Description and recommended fix]
+
+### Suggestions
+- [File:line] [Description]
+
+### What's Done Well
+- [Positive observation — always include at least one]
+
+### Verification Story
+- Tests reviewed: [yes/no, observations]
+- Build verified: [yes/no]
+- Security checked: [yes/no, observations]
+```
+
+## Rules
+
+1. Review the tests first — they reveal intent and coverage
+2. Read the spec or task description before reviewing code
+3. Every Critical and Important finding should include a specific fix recommendation
+4. Don't approve code with Critical issues
+5. Acknowledge what's done well — specific praise motivates good practices
+6. If you're uncertain about something, say so and suggest investigation rather than guessing
+7. Do NOT modify files — the reviewer's output is the report, not edits. Surface fixes as recommendations for the author or a follow-up agent.