# agent-skills
**Repository Path**: blackcrystal/agent-skills
## Basic Information
- **Project Name**: agent-skills
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-28
- **Last Updated**: 2026-10-28
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# Fullstack Agent Skills
**Production-grade engineering workflows for AI coding agents.**
Fullstack Agent Skills is a collection of Markdown workflows that helps coding agents plan, implement, test, review, and ship software with consistent engineering discipline. This repository is the `vzwarbee` maintained/custom distribution, built from [Addy Osmani's upstream Agent Skills](https://github.com/addyosmani/agent-skills).
The upstream authorship and attribution are preserved. This distribution adds a public npm installer, adapters for selected agents, and customized workflows for full-stack engineering, UI planning, independent testing, browser acceptance, and mobile/Flutter work. Use this repository when you want the updated `vzwarbee` skill set; use the upstream repository when you specifically need the original upstream version.
## Start here
New to Agent Skills? Choose your coding agent below. Each option uses a documented discovery path or the package-managed installer; no undocumented agent command is assumed.
### Fastest: install in the current project
Open a terminal in your project and run:
```bash
npx fb-agent-skills@latest
```
The shorthand installs into the current project, auto-detects supported agents, and stores project state in `.agent-skills/state.json`. Select agents explicitly when needed:
```bash
npx fb-agent-skills@latest --agent codex,gemini
```
OpenCode
OpenCode discovers project skills from `.opencode/skills/`, `.agents/skills/`, or `.claude/skills/`. Install the maintained pack into its documented `.agents/skills/` compatibility path:
```bash
npx fb-agent-skills@latest --agent opencode
```
For a project-local manual setup, copy each skill directory into `/.agents/skills/`. OpenCode advertises matching skills through its native `skill` tool. The repository root `skills/` directory alone is not an OpenCode discovery path.
See [docs/opencode-setup.md](docs/opencode-setup.md) for project and global setup.
Codex
Codex CLI v0.122+ can install this maintained distribution as a native plugin:
```bash
codex plugin marketplace add https://github.com/vzwarbee/agent-skills.git
codex plugin add agent-skills@agent-skills
```
After installation, start a new Codex session and invoke a skill with `@`, for example `@spec-driven-development`. Codex uses the root `skills/` directory; Claude-specific slash commands are not copied into Codex.
For a local clone:
```bash
git clone https://github.com/vzwarbee/agent-skills.git
codex plugin marketplace add /path/to/agent-skills
codex plugin add agent-skills@agent-skills
```
See [docs/codex-setup.md](docs/codex-setup.md).
Claude Code
Install the maintained repository as a Claude Code plugin:
```text
/plugin marketplace add https://github.com/vzwarbee/agent-skills.git
/plugin install agent-skills@vzwarbee-agent-skills
```
After installation, use lifecycle commands such as `/spec`, `/plan`, `/build`, `/test`, `/review`, and `/ship`.
Cursor
Cursor's official portable instruction surface is `AGENTS.md`; project rules live in `.cursor/rules/`. Use the package-managed adapter for the maintained skill pack:
```bash
npx fb-agent-skills@latest --agent cursor
```
The package installs its adapter without claiming that `.cursor/skills/` is a documented Cursor-native installer. For a fully official manual fallback, place the routing instructions in the project-root `AGENTS.md` or create focused `.cursor/rules/*.mdc` files.
See [docs/cursor-setup.md](docs/cursor-setup.md).
Gemini CLI
Gemini CLI officially installs one skill from a URL/path and supports user or workspace scope. For the complete maintained pack, use the package-managed adapter:
```bash
npx fb-agent-skills@latest --agent gemini
```
For local development of an individual skill, use Gemini's documented link command:
```bash
git clone https://github.com/vzwarbee/agent-skills.git
gemini skills link ./agent-skills/skills/test-driven-development --scope user
```
Run `/skills reload`, then verify with `/skills list`. Use `/planning` rather than `/plan`, because `/plan` is reserved by Gemini CLI.
See [docs/gemini-cli-setup.md](docs/gemini-cli-setup.md).
### Global installation
Explicit `install` without `--scope` keeps the v1-compatible global behavior:
```bash
npx fb-agent-skills@latest install
npx fb-agent-skills@latest install --scope global --agent opencode,codex
```
Manage project and global installations independently:
```bash
npx fb-agent-skills@latest update --scope project
npx fb-agent-skills@latest doctor --scope project
npx fb-agent-skills@latest uninstall --scope project
npx fb-agent-skills@latest update --scope global
npx fb-agent-skills@latest doctor --scope global
npx fb-agent-skills@latest uninstall --scope global
```
Use `--project-dir ` with project scope for a different workspace or monorepo package. The custom CLI manages only package-owned files and instruction blocks, and `doctor` is read-only.
```
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
9 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 |
| Set the quality bar | `/constraints` | Decide it once, enforce it everywhere |
| Review before merge | `/review` | Improve code health |
| Audit web performance | `/webperf` | Measure before you optimize |
| Simplify the code | `/code-simplify` | Clarity over cleverness |
| Ship to production | `/ship` | Faster is safer |
Want fewer manual steps once the spec exists? **`/build auto`** generates the plan and implements every task in a single approved pass — you approve the plan once, then it runs autonomously. It removes the human stepping *between* tasks, not the verification: every task is still test-driven and committed individually, and it pauses on failures or risky steps.
Skills also activate automatically based on what you're doing — designing an API triggers `api-and-interface-design`, building web UI triggers `frontend-ui-engineering`, and building Flutter/React Native or Capacitor-native UI triggers `mobile-ui-engineering`.
---
## Upstream installation
The commands in this section install the original upstream repository, not this `vzwarbee` maintained distribution. Use them only when you intentionally want the upstream skill set.
The open [skills CLI](https://github.com/vercel-labs/skills) installs upstream skills into 70+ agents (Claude Code, Cursor, Codex, Copilot, Cline, and more):
```bash
npx skills add addyosmani/agent-skills # install upstream skills
npx skills add addyosmani/agent-skills --list # browse upstream skills
```
Or grab individual skills:
```bash
npx skills add addyosmani/agent-skills --skill code-review-and-quality # five-axis review before merge
npx skills add addyosmani/agent-skills --skill interview-me # requirements interrogation, one question at a time
npx skills add addyosmani/agent-skills --skill test-driven-development # red-green-refactor, enforced
```
> **Installing one skill?** Supporting documentation is colocated under each
> skill's own `references/` directory, so maintained skills remain self-contained
> when an installer copies only `skills//`.
Prefer a native integration? Pick your tool below.
Claude Code (recommended)
**Marketplace install:**
```
/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-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 use the full HTTPS URL to force HTTPS cloning during the marketplace-add step:
> ```bash
> /plugin marketplace add https://github.com/addyosmani/agent-skills.git
> /plugin install agent-skills@addy-agent-skills
> ```
>
> If `/plugin install` still fails with `git@github.com: Permission denied (publickey)` on Windows or macOS, the recommended workaround is to configure Git once to rewrite GitHub SSH URLs to HTTPS for subprocess clones:
> ```bash
> git config --global url."https://github.com/".insteadOf git@github.com:
> ```
**Local / development:**
```bash
git clone https://github.com/addyosmani/agent-skills.git
claude --plugin-dir /path/to/agent-skills
```
Cursor
Put workflow skills under `.cursor/skills/` (sync from `agent-skills/skills/`) and short policies in `.cursor/rules/*.mdc` — do not paste full skills into rules. See [docs/cursor-setup.md](docs/cursor-setup.md).
Antigravity CLI
Install as a native plugin for skills and subagents. In affected Antigravity CLI releases, legacy command TOMLs are reported as converted but their wrapper commands are not discoverable; invoke the underlying namespaced skills directly. See [docs/antigravity-setup.md](docs/antigravity-setup.md#lifecycle-workflows-and-command-compatibility).
**Install from the repo:**
```bash
agy plugin install https://github.com/addyosmani/agent-skills.git
```
**Install from a local clone:**
```bash
git clone https://github.com/addyosmani/agent-skills.git
agy plugin install ./agent-skills
```
Gemini CLI
Gemini's native CLI installs or links one skill at a time. For this upstream multi-skill repository, use a multi-agent skills installer rather than the unsupported `--path skills` option:
```bash
npx skills add addyosmani/agent-skills --agent gemini-cli
```
For local development, link one skill explicitly, then reload discovery:
```bash
gemini skills link ./agent-skills/skills/test-driven-development --scope user
# Run /skills reload inside Gemini CLI
```
See [docs/gemini-cli-setup.md](docs/gemini-cli-setup.md).
Windsurf
Add skill contents to your Windsurf rules configuration. See [docs/windsurf-setup.md](docs/windsurf-setup.md).
OpenCode
Copy skills to `.opencode/skills/` (or `~/.config/opencode/skills/`), add a project-local `AGENTS.md`, and use the built-in `skill` tool for agent-driven execution. Optional slash commands can be added under `.opencode/commands/`.
See [docs/opencode-setup.md](docs/opencode-setup.md).
GitHub Copilot
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).
Kiro IDE & CLI
Skills for Kiro reside under ".kiro/skills/" and can be stored under Project or Global level. Kiro also supports Agents.md. See Kiro docs at https://kiro.dev/docs/skills/
Codex
Install as a native Codex plugin (Codex CLI v0.122+):
```bash
codex plugin marketplace add addyosmani/agent-skills
codex plugin add agent-skills@agent-skills
```
The first command registers the marketplace; the second installs the plugin. Codex reads the root `skills/` directory directly through `.codex-plugin/plugin.json`. Once installed, invoke skills in chat using `@` (e.g., `@spec-driven-development`). See [docs/codex-setup.md](docs/codex-setup.md) for local installation and troubleshooting.
Command Code
Install natively with the built-in `cmd skills` command. Command Code clones the repo, discovers every `SKILL.md`, and installs into `.commandcode/skills/`:
```bash
cmd skills add addyosmani/agent-skills # pick skills to install (project)
cmd skills add addyosmani/agent-skills --global # install for all projects (~/.commandcode/skills/)
cmd skills add addyosmani/agent-skills -s spec-driven-development # install a specific skill
```
Installed skills show up in the TUI slash menu, e.g. `/spec-driven-development`. See [docs/commandcode-setup.md](docs/commandcode-setup.md).
Other Agents
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).
---
## Adoption
Already installed? How you roll the pack out depends on your codebase. The **[Adoption Guide](docs/adoption-guide.md)** covers two paths: the full lifecycle from day one for a greenfield project, or an incremental, verification-first rollout for an established codebase.
## Public distribution details
Use `--agent opencode,codex` for explicit selection. Updates touch only agents previously managed by this package, and global instruction files are changed only inside package-owned managed blocks. See [docs/distribution-cli.md](docs/distribution-cli.md) for supported adapters and safety details. Upstream synchronization and npm releases are maintainer-side.
---
## All 33 Skills
<<<<<<< HEAD
The commands above are entry points. The pack includes 33 skills total — 32 lifecycle skills plus the `using-agent-skills` meta-skill. The OpenCode-focused skills keep full-stack product work coherent, provide token-efficient browser and mobile acceptance, and provide a separate independent acceptance-testing session while reusing existing specialist skills. Each skill is a structured workflow with steps, verification gates, and anti-rationalization tables. You can also reference any skill directly.
### OpenCode - Main engineering session
| Skill | What It Does | Use When |
|-------|-------------|----------|
| [main-engineering-workflow](skills/main-engineering-workflow/SKILL.md) | Single-session request → plan → product/UI decisions → backend/frontend/integration → self-check → tester handoff workflow | Building or changing a product feature in OpenCode |
| [backend-planning](skills/backend-planning/SKILL.md) | Framework-neutral backend reasoning across domain rules, data integrity, authorization, failure, consistency, migrations, security, performance, and tests | A feature affects server behavior, data, persistence, or APIs |
| [ui-planning](skills/ui-planning/SKILL.md) | UI profile selection, feature-level layout decisions, and end-to-end UI planning without component implementation | Planning a frontend screen, flow, layout, or UI behavior |
| [ui-design-system](skills/ui-design-system/SKILL.md) | Applies a persisted UI profile through existing tokens and components without silent global redesign | Implementing UI after a profile exists or is selected |
| [agents-init](skills/agents-init/SKILL.md) | Initializes scoped instructions, task context, routing, assumptions, and verification for a coding-agent session | Starting or refreshing an agent session |
### OpenCode - Independent tester session
| Skill | What It Does | Use When |
|-------|-------------|----------|
| [independent-testing](skills/independent-testing/SKILL.md) | Requirement-first, black-box acceptance testing with risk-based regression, evidence reports, retesting, and optional white-box review | Starting a separate tester session from a completed feature handoff |
### OpenCode - Browser acceptance
| Skill | What It Does | Use When |
|-------|-------------|----------|
| [browser-acceptance](skills/browser-acceptance/SKILL.md) | Token-efficient black-box browser acceptance with functional defaults, limited visual checkpoints, and explicit project E2E → Playwright CLI → DevTools → BLOCKED fallback | Verifying browser-visible requirements or composing with `independent-testing` for a browser surface |
### OpenCode - Mobile acceptance
| Skill | What It Does | Use When |
|-------|-------------|----------|
| [mobile-acceptance](skills/mobile-acceptance/SKILL.md) | Token-efficient black-box acceptance for Flutter, React Native, and Capacitor native boundaries, preferring project E2E and using an available Maestro CLI only as a suitable fallback | Verifying native mobile behavior or composing with `independent-testing` for a Flutter, React Native, or native Capacitor surface |
=======
The commands above are entry points. The pack includes 25 skills total — 24 lifecycle skills plus the `using-agent-skills` meta-skill. Each skill is a structured workflow with steps, verification gates, and anti-rationalization tables. You can also reference any skill directly.
>>>>>>> upstream/main
### Meta - Discover which skill applies
| Skill | What It Does | Use When |
|-------|-------------|----------|
| [using-agent-skills](skills/using-agent-skills/SKILL.md) | Maps incoming work to the right skill workflow and defines shared operating rules | Starting a session or deciding which skill applies |
### Define - Clarify what to build
| Skill | What It Does | Use When |
|-------|-------------|----------|
| [interview-me](skills/interview-me/SKILL.md) | One-question-at-a-time interview that extracts what the user actually wants instead of what they think they should want, until ~95% confidence | The ask is underspecified, or the user invokes "interview me" / "grill me" |
| [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 |
| [constraint-driven-development](skills/constraint-driven-development/SKILL.md) | Interviews you for a quality bar with sane default thresholds, writes CONSTRAINTS.md, places each check by cost, and catches agents silencing checks or skipping tests to get green | No standards are written down, or an agent is producing more than anyone reads |
### 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 |
| [doubt-driven-development](skills/doubt-driven-development/SKILL.md) | Adversarial fresh-context review of every non-trivial decision in-flight - CLAIM → EXTRACT → DOUBT → RECONCILE → STOP, with optional user-authorized cross-model escalation | Stakes are high (production, security, irreversible), working in unfamiliar code, or a confident output is cheaper to verify now than to debug later |
| [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 |
| [mobile-ui-engineering](skills/mobile-ui-engineering/SKILL.md) | Flutter, React Native, and Capacitor-native UI engineering: adaptive layouts, touch, safe areas, keyboards, navigation, accessibility, and native boundaries | Building or debugging native mobile UI or Capacitor behavior that crosses the WebView/native boundary |
| [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-acceptance](skills/browser-acceptance/SKILL.md) | Functional browser acceptance by default, with limited visual checkpoints and explicit execution fallbacks | Verifying browser-visible requirements |
| [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 | Deep browser runtime diagnosis or requested console/network/performance evidence |
| [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 |
| [observability-and-instrumentation](skills/observability-and-instrumentation/SKILL.md) | Structured logging, RED metrics, OpenTelemetry tracing, symptom-based alerting - instrument as you build | Adding telemetry, or shipping anything that runs in production |
| [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 |
| [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 |
| [web-performance-auditor](agents/web-performance-auditor.md) | Web Performance Engineer | Core Web Vitals audit with Quick/Deep modes and a metric-honesty rule; run it via `/webperf` |
See [docs/agents.md](docs/agents.md) for the decision matrix, orchestration rules, and how personas compose with skills and slash commands.
---
## Reference Checklists
Quick-reference material that skills pull in when needed:
| Reference | Covers |
|-----------|--------|
| [definition-of-done.md](references/definition-of-done.md) | Project-wide standing bar every change clears, contrasted with per-task acceptance criteria |
| [testing-patterns.md](references/testing-patterns.md) | Test structure, naming, mocking, React/API/E2E examples, anti-patterns (JavaScript/TypeScript) |
| [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 |
| [observability-checklist.md](references/observability-checklist.md) | On-call questions, structured logging, RED/USE metrics, tracing, symptom-based alerting, pre-launch gate |
| [orchestration-patterns.md](references/orchestration-patterns.md) | Endorsed multi-persona orchestration patterns, anti-patterns, and the "personas don't invoke personas" rule |
---
## How Skills Work
Every skill follows a consistent anatomy:
```
┌─────────────────────────────────────────────────┐
│ SKILL.md │
│ │
│ ┌─ Frontmatter ─────────────────────────────┐ │
│ │ name: lowercase-hyphen-name │ │
│ │ description: Guides agents through [task].│ │
│ │ Use when… │ │
│ └───────────────────────────────────────────┘ │
│ 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.
---
## Project Structure
```
agent-skills/
<<<<<<< HEAD
├── skills/ # 33 skills (32 lifecycle + 1 meta)
│ ├── main-engineering-workflow/ # OpenCode main session
│ ├── backend-planning/ # OpenCode backend reasoning
│ ├── ui-planning/ # OpenCode UI planning
│ ├── ui-design-system/ # OpenCode UI profile application
│ ├── independent-testing/ # OpenCode independent tester session
│ ├── browser-acceptance/ # OpenCode browser acceptance
│ ├── mobile-acceptance/ # OpenCode mobile acceptance
│ ├── agents-init/ # Shared session initializer
│ ├── mobile-ui-engineering/ # Flutter/React Native/Capacitor UI
=======
├── skills/ # 25 skills (24 lifecycle + 1 meta)
>>>>>>> upstream/main
│ ├── interview-me/ # Define
│ ├── idea-refine/ # Define
│ ├── spec-driven-development/ # Define
│ ├── constraint-driven-development/ # Define
│ ├── planning-and-task-breakdown/ # Plan
│ ├── incremental-implementation/ # Build
│ ├── context-engineering/ # Build
│ ├── source-driven-development/ # Build
│ ├── doubt-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
│ ├── observability-and-instrumentation/ # Ship
│ ├── shipping-and-launch/ # Ship
│ └── using-agent-skills/ # Meta: how to use this pack
├── templates/ # Reusable global agent instruction templates
│ └── opencode-global-AGENTS.md # High-level global OpenCode policy
├── agents/ # 4 specialist personas
├── references/ # 7 supplementary checklists
├── hooks/ # Session lifecycle hooks
├── .claude/commands/ # 8 slash commands (Claude Code)
├── .gemini/commands/ # 8 slash commands (Gemini CLI)
├── commands/ # 8 slash commands (Antigravity CLI)
├── plugin.json # Antigravity plugin manifest
└── 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.
---
## How it compares
Wondering how this stacks up against [Superpowers](https://github.com/obra/superpowers) or [Matt Pocock's skills](https://github.com/mattpocock/skills)? See **[docs/comparison.md](docs/comparison.md)** for an honest, side-by-side look at how the three are shaped differently and when to reach for each — including a link to a controlled [head-to-head experiment](https://www.linkedin.com/pulse/superpowers-vs-agent-skills-faster-shipping-safer-reasoning-om-mishra-dzakf/).
---
## 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.
---
## Team
agent-skills is built and maintained by:
| | Name | GitHub | Role |
|---|------|--------|------|
| 
| **Addy Osmani** | [@addyosmani](https://github.com/addyosmani) | Creator |
| 
| **Federico Bartoli** | [@federicobartoli](https://github.com/federicobartoli) | Collaborator |
| 
| **Joan León** | [@nucliweb](https://github.com/nucliweb) | Collaborator |
---
## License
MIT - use these skills in your projects, teams, and tools.