agent-skills Documentation

1. Project Overview & Quickstart (addyosmani/agent-skills) Copy Chapter

File: README.md Copy Chapter

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 Copy Chapter

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

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 UI triggers frontend-ui-engineering, and so on.

Quick Start Copy Chapter

Fastest path — any agent, one command. The open skills CLI installs into 70+ agents (Claude Code, Cursor, Codex, Copilot, Cline, and more):

npx skills add addyosmani/agent-skills            # install all 24 skills
npx skills add addyosmani/agent-skills --list     # browse before installing

Or grab individual skills:

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? A per-skill npx install copies only
skills/<name>/, not the repo-level references/ directory. The skill still
works, but paths to supplementary shared checklists are unavailable. Use a
whole-repo integration, clone the repository, or copy the needed checklist into
a references/ directory inside the installed skill. This portability gap is
tracked in #361.

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 or use the full HTTPS URL to force HTTPS cloning during the marketplace-add step:

bash Copy

/plugin marketplace add https://github.com/addyosmani/agent-skills.git
/plugin install agent-skills@addy-agent-skills

If /plugin install still fails with [email protected]: 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 Copy

git config --global url."https://github.com/".insteadOf [email protected]:

Local / development:

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.

Antigravity CLI

Install as a native plugin for skills, subagents, and slash commands. See docs/antigravity-setup.md.

Install from the repo:

agy plugin install https://github.com/addyosmani/agent-skills.git

Install from a local clone:

git clone https://github.com/addyosmani/agent-skills.git
agy plugin install ./agent-skills

Gemini CLI

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/addyosmani/agent-skills.git --path skills

Install from a local clone:

gemini skills install ./agent-skills/skills/

Windsurf

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

OpenCode

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

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

**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+):

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 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/:

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.

Other Agents

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

Adoption Copy Chapter

Already installed? How you roll the pack out depends on your codebase. The Adoption Guide covers two paths: the full lifecycle from day one for a greenfield project, or an incremental, verification-first rollout for an established codebase.

All 24 Skills Copy Chapter

The commands above are entry points. The pack includes 24 skills total — 23 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.

Meta - Discover which skill applies Copy Section

Define - Clarify what to build Copy Section

Plan - Break it down Copy Section

Build - Write the code Copy Section

Verify - Prove it works Copy Section

Review - Quality gates before merge Copy Section

Ship - Deploy with confidence Copy Section

Agent Personas Copy Chapter

Pre-configured specialist personas for targeted reviews:

See docs/agents.md for the decision matrix, orchestration rules, and how personas compose with skills and slash commands.

Reference Checklists Copy Chapter

Quick-reference material that skills pull in when needed:

How Skills Work Copy Chapter

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 Copy Chapter

/* Detailed source-code truncated for AI context efficiency. */

Why Agent Skills? Copy Chapter

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.

How it compares Copy Chapter

Wondering how this stacks up against Superpowers or Matt Pocock's skills? See 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.

Contributing Copy Chapter

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.

Team Copy Chapter

agent-skills is built and maintained by:

License Copy Chapter

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

File: docs/copilot-setup.md Copy Chapter

Using agent-skills with GitHub Copilot

Setup Copy Chapter

Copilot Instructions Copy Section

Copilot supports creating agent skills using a .github/skills, .claude/skills, or .agents/skills directory in your repository.

mkdir -p .github/skills/test-driven-development .github/skills/code-review-and-quality

# Create files for essential skills
cat /path/to/agent-skills/skills/test-driven-development/SKILL.md > .github/skills/test-driven-development/SKILL.md
cat /path/to/agent-skills/skills/code-review-and-quality/SKILL.md > .github/skills/code-review-and-quality/SKILL.md

For more details, refer Creating agent skills for GitHub Copilot.

Agent Personas (*.agent.md) Copy Section

Copilot supports specialized agent personas. Use the agent-skills agents:

Important: GitHub Copilot requires custom agent files to be named *.agent.md.
Files named *.md are silently ignored by Copilot.
See VS Code custom agents docs for details.

# Create the agents directory and copy agent definitions
mkdir -p .github/agents
cp /path/to/agent-skills/agents/code-reviewer.md .github/agents/code-reviewer.agent.md
cp /path/to/agent-skills/agents/test-engineer.md .github/agents/test-engineer.agent.md
cp /path/to/agent-skills/agents/security-auditor.md .github/agents/security-auditor.agent.md

Invoke agents in Copilot Chat:

• @code-reviewer Review this PR
• @test-engineer Analyze test coverage for this module
• @security-auditor Check this endpoint for vulnerabilities

Custom Instructions (User Level) Copy Section

For skills you want across all repositories:

1. Open VS Code → Settings → GitHub Copilot → Custom Instructions
2. Add your most-used skill summaries

Recommended Configuration Copy Chapter

.github/copilot-instructions.md Copy Section

GitHub Copilot supports project-level instructions via .github/copilot-instructions.md.

# Project Coding Standards

## Testing
- Write tests before code (TDD)
- For bugs: write a failing test first, then fix (Prove-It pattern)
- Test hierarchy: unit > integration > e2e (use the lowest level that captures the behavior)
- Run `npm test` after every change

## Code Quality
- Review across five axes: correctness, readability, architecture, security, performance
- Every PR must pass: lint, type check, tests, build
- No secrets in code or version control

## Implementation
- Build in small, verifiable increments
- Each increment: implement → test → verify → commit
- Never mix formatting changes with behavior changes

## Boundaries
- Always: Run tests before commits, validate user input
- Ask first: Database schema changes, new dependencies
- Never: Commit secrets, remove failing tests, skip verification

Specialized Agents Copy Section

Use the agents for targeted review workflows in Copilot Chat.

Usage Tips Copy Chapter

1. Keep instructions concise — Copilot instructions work best when focused. Summarize the key rules rather than including full skill files.
2. Use agents for review — The code-reviewer, test-engineer, and security-auditor agents are designed for Copilot's agent model.
3. Reference in chat — When working on a specific phase, paste the relevant skill content into Copilot Chat for context.
4. Combine with PR reviews — Set up Copilot to review PRs using the code-reviewer agent persona.

File: docs/cursor-setup.md Copy Chapter

Using agent-skills with Cursor

How to wire agent-skills into Cursor using current, supported project context — not legacy monolith files or Kaizen-specific layouts.

What Cursor supports today Copy Chapter

Cursor combines rules (short policies) and skills (full workflows):

Docs: Rules · Skills (URLs may redirect as Cursor updates docs).

Rules vs skills Copy Section

• Rules — concise, stable (“use conventional commits”, “type-annotate public Python APIs”). Prefer one concern per file; avoid large pasted guides.
• Skills — step-by-step processes from this repo (test-driven-development, code-review-and-quality, etc.). Do not copy entire SKILL.md bodies into rules; that duplicates .cursor/skills/ and wastes context.

Legacy (avoid for new setups) Copy Section

Recommended project layout Copy Chapter

your-project/
├── .cursor/
│   ├── rules/                    # Short .mdc policies (yours)
│   │   └── agent-skills.mdc      # Optional: “use project skills” pointer
│   └── skills/                   # What Cursor Agent loads
│       ├── using-agent-skills/
│       ├── test-driven-development/
│       ├── code-review-and-quality/
│       └── …                     # Synced from agent-skills + your own skills
└── agent-skills/                 # Optional: git submodule or vendor clone
    └── skills/                   # Upstream source only

Source of truth for the agent: .cursor/skills/.
Treat agent-skills/skills/ (or a cloned addyosmani/agent-skills) as upstream — sync into .cursor/skills/, do not edit only upstream and expect Cursor to see it.

Setup (any repository) Copy Chapter

1. Install skills into `.cursor/skills/` Copy Section

From a local clone of agent-skills (at project root or elsewhere):

mkdir -p .cursor/skills
rsync -a /path/to/agent-skills/skills/ .cursor/skills/

First-time copy without overwriting your custom skills:

rsync -a --ignore-existing /path/to/agent-skills/skills/ .cursor/skills/

After upstream updates:

rsync -a /path/to/agent-skills/skills/ .cursor/skills/

Each skill folder must contain SKILL.md with YAML frontmatter, at minimum:

---
name: test-driven-development
---

Cursor uses description (and related metadata) to decide when to apply a skill.

2. Add minimal project rules (optional but useful) Copy Section

Create .cursor/rules/agent-skills.mdc:

---
alwaysApply: true
---

Before non-trivial technical work:

1. Route via `.cursor/skills/using-agent-skills/SKILL.md`.
2. Read and follow the matching skill under `.cursor/skills/<name>/SKILL.md`.
3. Open `reference.md` in that folder when the skill links to it.
4. Prefer project skills over guessing; user does not need to say "read skill" each time.

Add separate .mdc files for repo-specific standards (style, language, stack), keeping each file focused.

Rule file format:

---
alwaysApply: false
globs: "**/*.{ts,tsx}"
---

# Your rule content

3. User-level skills (optional) Copy Section

Copy or install skills you want everywhere under ~/.cursor/skills/. Use for stack-wide guides (e.g. language patterns) that are not part of agent-skills.

Project skills in .cursor/skills/ take precedence for this repo’s workflows.

4. Verify Copy Section

1. Settings → Rules — project .mdc files listed.
2. Agent chat — skills from .cursor/skills/ appear in the skill list (if your Cursor build exposes it).
3. Run a task that maps to a skill (e.g. “add a feature with tests first”) without naming the file — agent should open test-driven-development when routing works.

How agents should use skills Copy Chapter

1. Discover — using-agent-skills maps task phase → skill name.
2. Read — full process in .cursor/skills/<name>/SKILL.md.
3. Deep dive — reference.md, references/*.md, or linked checklists when the skill says so.
4. Combine — e.g. incremental-implementation + api-and-interface-design for an API slice.

Explicit user phrases (“follow TDD”, “use code-review-and-quality”) still help if the agent drifts.

Phase → skill (quick map) Copy Section

Full tree: skills/using-agent-skills/SKILL.md in the repo.

What not to do Copy Chapter

Context tips Copy Chapter

• Keep always-on rules small (routing + 1–2 non-negotiables).
• Let skills carry long checklists and rationalization tables.
• Add phase-specific globs rules only when needed (e.g. **/*.py, **/components/**).
• Nudge by skill name if verification steps are skipped.

`agents/` directory Copy Chapter

Files under agent-skills/agents/ (e.g. code reviewer persona) are not loaded automatically by Cursor. Options:

• Reference the skill equivalent (code-review-and-quality).
• Paste agent markdown into the chat for one review.
• Extract a short checklist into a .mdc rule.

Troubleshooting Copy Chapter

Checklist (new project) Copy Chapter

• mkdir -p .cursor/skills and sync from agent-skills/skills/
• Optional: .cursor/rules/agent-skills.mdc with routing hint
• Add repo-specific rules as separate small .mdc files
• Commit .cursor/skills/ and .cursor/rules/ (team shares behavior)
• Skip giant .cursorrules unless required by legacy tooling

See also Copy Chapter

• getting-started.md
• ../README.md — Cursor quick blurb
• Upstream: github.com/addyosmani/agent-skills

File: docs/gemini-cli-setup.md Copy Chapter

Using agent-skills with Gemini CLI

Setup Copy Chapter

Option 1: Install as Skills (Recommended) Copy Section

Gemini CLI has a native skills system that auto-discovers SKILL.md files in .gemini/skills/ or .agents/skills/ directories. Each skill activates on demand when it matches your task.

Install from the repo:

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

Or install from a local clone:

git clone https://github.com/addyosmani/agent-skills.git
gemini skills install /path/to/agent-skills/skills/

Install for a specific workspace only:

gemini skills install /path/to/agent-skills/skills/ --scope workspace

Skills installed at workspace scope go into .gemini/skills/ (or .agents/skills/). User-level skills go into ~/.gemini/skills/.

Once installed, verify with:

/skills list

Gemini CLI injects skill names and descriptions into the prompt automatically. When it recognizes a matching task, it asks permission to activate the skill before loading its full instructions.

Option 2: GEMINI.md (Persistent Context) Copy Section

For skills you want always loaded as persistent project context (rather than on-demand activation), add them to your project's GEMINI.md:

# Create GEMINI.md with core skills as persistent context
cat /path/to/agent-skills/skills/incremental-implementation/SKILL.md > GEMINI.md
echo -e "\n---\n" >> GEMINI.md
cat /path/to/agent-skills/skills/code-review-and-quality/SKILL.md >> GEMINI.md

You can also modularize by importing from separate files:

# Project Instructions

@skills/test-driven-development/SKILL.md
@skills/incremental-implementation/SKILL.md

Use /memory show to verify loaded context, and /memory reload to refresh after changes.

Skills vs GEMINI.md: Skills are on-demand expertise that activate only when relevant, keeping your context window clean. GEMINI.md provides persistent context loaded for every prompt. Use skills for phase-specific workflows and GEMINI.md for always-on project conventions.

Recommended Configuration Copy Chapter

Always-On (GEMINI.md) Copy Section

Add these as persistent context for every session:

• incremental-implementation — Build in small verifiable slices
• code-review-and-quality — Five-axis review

On-Demand (Skills) Copy Section

Install these as skills so they activate only when relevant:

• test-driven-development — Activates when implementing logic or fixing bugs
• spec-driven-development — Activates when starting a new project or feature
• frontend-ui-engineering — Activates when building UI
• security-and-hardening — Activates during security reviews
• performance-optimization — Activates during performance work

Advanced Configuration Copy Chapter

MCP Integration Copy Section

Many skills in this pack leverage Model Context Protocol (MCP) tools to interact with the environment. For example:

• browser-testing-with-devtools uses the chrome-devtools MCP extension.
• performance-optimization can benefit from performance-related MCP tools.

To enable these, ensure you have the relevant MCP extensions installed in your Gemini CLI configuration (~/.gemini/config.json).

Session Hooks Copy Section

Gemini CLI supports session lifecycle hooks. You can use these to automatically inject context or run validation scripts at the start of a session.

To replicate the agent-skills experience from other tools, you can configure a SessionStart hook that reminds you of the available skills or loads a meta-skill.

Explicit Context Loading Copy Section

You can explicitly load any skill into your current session by referencing it with the @ symbol in your prompt:

Use the @skills/test-driven-development/SKILL.md skill to implement this fix.

This is useful when you want to ensure a specific workflow is followed without waiting for auto-discovery.

Slash Commands Copy Chapter

The repo ships 8 slash commands under .gemini/commands/: 7 lifecycle commands plus the /webperf specialist audit. Gemini CLI auto-discovers them when you run from the project root.

Each command invokes the corresponding skill automatically — no manual skill loading required.

Note: Use /planning instead of /plan — /plan conflicts with a Gemini CLI internal command name.

Usage Tips Copy Chapter

1. Prefer skills over GEMINI.md — Skills activate on demand and keep your context window focused. Only put skills in GEMINI.md if you want them always loaded.
2. Skill descriptions matter — Each SKILL.md has a description field in its frontmatter that tells agents when to activate it. The descriptions in this repo are optimized for auto-discovery across all supported tools (Claude Code, Gemini CLI, etc.) by clearly stating both what the skill does and when it should be triggered.
3. Use agents for review — Copy agents/code-reviewer.md content when requesting structured code reviews.
4. Combine with references — Reference checklists from references/ when working on specific quality areas like testing or performance.

File: docs/getting-started.md Copy Chapter

Getting Started with agent-skills

agent-skills works with any AI coding agent that accepts Markdown instructions. This guide covers the universal approach. For tool-specific setup, see the dedicated guides.

How Skills Work Copy Chapter

Each skill is a Markdown file (SKILL.md) that describes a specific engineering workflow. When loaded into an agent's context, the agent follows the workflow — including verification steps, anti-patterns to avoid, and exit criteria.

Skills are not reference docs. They're step-by-step processes the agent follows.

Quick Start (Any Agent) Copy Chapter

1. Clone the repository Copy Section

git clone https://github.com/addyosmani/agent-skills.git

2. Choose a skill Copy Section

Browse the skills/ directory. Each subdirectory contains a SKILL.md with:

• When to use — triggers that indicate this skill applies
• Process — step-by-step workflow
• Verification — how to confirm the work is done
• Common rationalizations — excuses the agent might use to skip steps
• Red flags — signs the skill is being violated

3. Load the skill into your agent Copy Section

Copy the relevant SKILL.md content into your agent's system prompt, rules file, or conversation. The most common approaches:

System prompt: Paste the skill content at the start of the session.

Rules file: Add skill content to your project's rules file (CLAUDE.md, .cursorrules, etc.).

Conversation: Reference the skill when giving instructions: "Follow the test-driven-development process for this change."

4. Use the meta-skill for discovery Copy Section

Start with the using-agent-skills skill loaded. It contains a flowchart that maps task types to the appropriate skill.

Recommended Setup Copy Chapter

Rolling out to a real project? The Adoption Guide covers two end-to-end paths: the full lifecycle from day one for a greenfield project, and an incremental, verification-first rollout for an established codebase. The setup below is the quick version.

Minimal (Start here) Copy Section

Load three essential skills into your rules file:

1. spec-driven-development — For defining what to build
2. test-driven-development — For proving it works
3. code-review-and-quality — For verifying quality before merge

These three cover the most critical quality gaps in AI-assisted development.

Full Lifecycle Copy Section

For comprehensive coverage, load skills by phase:

Starting a project:  spec-driven-development → planning-and-task-breakdown
During development:  incremental-implementation + test-driven-development
Before merge:        code-review-and-quality + security-and-hardening
Before deploy:       shipping-and-launch

Context-Aware Loading Copy Section

Don't load all skills at once — it wastes context. Load skills relevant to the current task:

• Working on UI? Load frontend-ui-engineering
• Debugging? Load debugging-and-error-recovery
• Setting up CI? Load ci-cd-and-automation

Skill Anatomy Copy Chapter

Every skill follows the same structure:

YAML frontmatter (name, description)
├── Overview — What this skill does
├── When to Use — Triggers and conditions
├── Core Process — Step-by-step workflow
├── Examples — Code samples and patterns
├── Common Rationalizations — Excuses and rebuttals
├── Red Flags — Signs the skill is being violated
└── Verification — Exit criteria checklist

See skill-anatomy.md for the full specification.

Using Agents Copy Chapter

The agents/ directory contains pre-configured agent personas:

Load an agent definition when you need specialized review. For example, ask your coding agent to "review this change using the code-reviewer agent persona" and provide the agent definition.

Using Commands Copy Chapter

The .claude/commands/ directory contains slash commands for Claude Code:

Note: When installed as a Claude Code plugin you may see a warning like
"Default commands/ folder is ignored because the manifest sets 'commands'".
This is expected. The root commands/ directory belongs to the Antigravity CLI
and is intentionally separate from .claude/commands/. All Claude Code slash
commands load correctly from .claude/commands/; the warning is cosmetic.

Using References Copy Chapter

The references/ directory contains supplementary checklists:

Load a reference when you need detailed patterns beyond what the skill covers.

If you install one skill with npx skills add ... --skill <name>, only the
selected skills/<name>/ directory is copied. The skill still works, but paths
to supplementary checklists in the repo-level references/ directory are
unavailable. Use a whole-repo integration, clone the repository, or copy the
needed checklist into a references/ directory inside the installed skill.
This portability gap is tracked in
addyosmani/agent-skills#361.

Spec and task artifacts Copy Chapter

The /spec and /plan commands create working artifacts (SPEC.md, tasks/plan.md, tasks/todo.md). Treat them as living documents while the work is in progress:

• Keep them in version control during development so the human and the agent have a shared source of truth.
• Update them when scope or decisions change.
• If your repo doesn’t want these files long‑term, delete them before merge or add the folder to .gitignore — the workflow doesn’t require them to be permanent.

Tips Copy Chapter

1. Start with spec-driven-development for any non-trivial work
2. Always load test-driven-development when writing code
3. Don't skip verification steps — they're the whole point
4. Load skills selectively — more context isn't always better
5. Use the agents for review — different perspectives catch different issues

File: docs/opencode-setup.md Copy Chapter

OpenCode Setup

This guide explains how to use Agent Skills with OpenCode in a way that closely mirrors the Claude Code experience (automatic skill selection, lifecycle-driven workflows, and strict process enforcement).

Overview Copy Chapter

OpenCode supports custom /commands, but does not have a native plugin system or automatic skill routing like Claude Code.

Instead, we achieve parity through:

• A strong system prompt (AGENTS.md)
• The built-in skill tool
• Consistent skill discovery from the /skills directory

This creates an agent-driven workflow where skills are selected and executed automatically.

While it is possible to recreate /spec, /plan, and other commands in OpenCode, this integration intentionally uses an agent-driven approach instead:

• Skills are selected automatically based on intent
• Workflows are enforced via AGENTS.md
• No manual command invocation is required

This more closely matches how Claude Code behaves in practice, where skills are triggered automatically rather than manually.

Installation Copy Chapter

1. Clone the repository:

git clone https://github.com/addyosmani/agent-skills.git

2. Open the project in OpenCode.

3. Ensure the following files are present in your workspace:

• AGENTS.md (root)
• skills/ directory

No additional installation is required.

How It Works Copy Chapter

1. Skill Discovery Copy Section

All skills live in:

skills/<skill-name>/SKILL.md

OpenCode agents are instructed (via AGENTS.md) to:

• Detect when a skill applies
• Invoke the skill tool
• Follow the skill exactly

2. Automatic Skill Invocation Copy Section

The agent evaluates every request and maps it to the appropriate skill.

Examples:

• "build a feature" → incremental-implementation + test-driven-development
• "design a system" → spec-driven-development
• "fix a bug" → debugging-and-error-recovery
• "review this code" → code-review-and-quality

The user does not need to explicitly request skills.

3. Lifecycle Mapping (Implicit Commands) Copy Section

The development lifecycle is encoded implicitly:

• DEFINE → spec-driven-development
• PLAN → planning-and-task-breakdown
• BUILD → incremental-implementation + test-driven-development
• VERIFY → debugging-and-error-recovery
• REVIEW → code-review-and-quality
• SHIP → shipping-and-launch

This replaces slash commands like /spec, /plan, etc.

Usage Examples Copy Chapter

Example 1: Feature Development Copy Section

User:

Add authentication to this app

Agent behavior:

• Detects feature work
• Invokes spec-driven-development
• Produces a spec before writing code
• Moves to planning and implementation skills

Example 2: Bug Fix Copy Section

User:

This endpoint is returning 500 errors

Agent behavior:

• Invokes debugging-and-error-recovery
• Reproduces → localizes → fixes → adds guards

Example 3: Code Review Copy Section

User:

Review this PR

Agent behavior:

• Invokes code-review-and-quality
• Applies structured review (correctness, design, readability, etc.)

Agent Expectations (Critical) Copy Chapter

For OpenCode to work correctly, the agent must follow these rules:

• Always check if a skill applies before acting
• If a skill applies, it MUST be used
• Never skip required workflows (spec, plan, test, etc.)
• Do not jump directly to implementation

These rules are enforced via AGENTS.md.

Limitations Copy Chapter

• No native slash commands (handled via intent mapping instead)
• No plugin system (handled via prompt + structure)
• Skill invocation depends on model compliance

Despite these, the workflow closely matches Claude Code in practice.

Recommended Workflow Copy Chapter

Just use natural language:

• "Design a feature"
• "Plan this change"
• "Implement this"
• "Fix this bug"
• "Review this"

The agent will automatically select and execute the correct skills.

Summary Copy Chapter

OpenCode integration works by combining:

• Structured skills (this repo)
• Strong agent rules (AGENTS.md)
• Automatic skill invocation via reasoning

This results in a fully agent-driven, production-grade engineering workflow without requiring plugins or manual commands.

File: docs/skill-anatomy.md Copy Chapter

Skill Anatomy

This document describes the structure and format of agent-skills skill files. Use this as a guide when contributing new skills or understanding existing ones.

File Location Copy Chapter

Every skill lives in its own directory under skills/:

skills/
  skill-name/
    SKILL.md           # Required: The skill definition
    scripts/           # Optional: Runnable helpers used by the skill workflow
    references/        # Optional: Skill-specific reference documentation
    supporting-file.md # Optional: Reference material loaded on demand

SKILL.md is the only required file. Add scripts/ or references/ only when the skill actually needs them, and omit them entirely for simpler skills.

SKILL.md Format Copy Chapter

Frontmatter (Required) Copy Section

---
name: skill-name-with-hyphens
---

Rules:

• name: Lowercase, hyphen-separated. Must match the directory name.
• description: Start with what the skill does in third person, then include one or more clear "Use when" trigger conditions. Include both what and when. Maximum 1024 characters.

Why this matters: Agents discover skills by reading descriptions. The description is injected into the system prompt, so it must tell the agent both what the skill provides and when to activate it. Do not summarize the workflow — if the description contains process steps, the agent may follow the summary instead of reading the full skill.

Standard Sections (Recommended Pattern) Copy Section

The frontmatter contract above is required. The section layout below is a recommended pattern, not a rigid template: equivalent headings are acceptable when they serve the same purpose clearly.

# Skill Title

## Overview
One-two sentences explaining what this skill does and why it matters.

## When to Use
- Bullet list of triggering conditions (symptoms, task types)
- When NOT to use (exclusions)

## [Core Process / The Workflow / Steps]
The main workflow, broken into numbered steps or phases.
Include code examples where they help.
Use flowcharts (ASCII) where decision points exist.

## [Specific Techniques / Patterns]
Detailed guidance for specific scenarios.
Code examples, templates, configuration.

## Common Rationalizations
| Rationalization | Reality |
|---|---|
| Excuse agents use to skip steps | Why the excuse is wrong |

## Red Flags
- Behavioral patterns indicating the skill is being violated
- Things to watch for during review

## Verification
After completing the skill's process, confirm:
- [ ] Checklist of exit criteria
- [ ] Evidence requirements

Section Purposes Copy Chapter

Overview Copy Section

The "elevator pitch" for the skill. Should answer: What does this skill do, and why should an agent follow it?

When to Use Copy Section

Helps agents and humans decide if this skill applies to the current task. Include both positive triggers ("Use when X") and negative exclusions ("NOT for Y").

Core Process Copy Section

The heart of the skill. This is the step-by-step workflow the agent follows. Must be specific and actionable — not vague advice.

Good: "Run npm test and verify all tests pass"
Bad: "Make sure the tests work"

Common Rationalizations Copy Section

The most distinctive feature of well-crafted skills. These are excuses agents use to skip important steps, paired with rebuttals. They prevent the agent from rationalizing its way out of following the process.

Think of every time an agent has said "I'll add tests later" or "This is simple enough to skip the spec" — those go here with a factual counter-argument.

Red Flags Copy Section

Observable signs that the skill is being violated. Useful during code review and self-monitoring.

Verification Copy Section

The exit criteria. A checklist the agent uses to confirm the skill's process is complete. Every checkbox should be verifiable with evidence (test output, build result, screenshot, etc.).

Supporting Files Copy Chapter

Create supporting files only when:

• Reference material exceeds 100 lines (keep the main SKILL.md focused)
• Code tools or scripts are needed
• Checklists are long enough to justify separate files

Keep patterns and principles inline when under 50 lines.

If a skill does not need runnable helpers, do not create an empty scripts/ directory just to mirror other skills. Empty directories add noise without changing how the skill works.

Shared References Copy Chapter

Checklists used by more than one skill — testing, security, performance, accessibility, definition-of-done — live in references/ at the repository root, deliberately not inside any skill directory.

This is a pack-level design choice. The Agent Skills spec describes a skill as a self-contained directory, but several skills here point at the same checklists. Colocating those would force one of two options: copy the checklist into every skill that uses it, or pick one skill to "own" it and have the others reach into that directory. Both drift over time. A single repo-root copy stays the source of truth.

The tradeoff is portability: a whole-repo install (such as the Claude Code marketplace plugin) carries references/ along, but a per-skill install that copies only skills/<name>/ leaves the repo-root sibling behind, and those links resolve to nothing. That gap is tracked in #361.

Current convention: material used by exactly one skill is a supporting file inside that skill's directory; material shared across skills goes in references/.

Context Efficiency Copy Chapter

Skills load on demand: only the skill name and description sit in context at startup. The full SKILL.md loads only when an agent decides the skill is relevant. To keep that load cheap:

• Keep SKILL.md under 500 lines. Move detailed reference material into supporting files.
• Write specific descriptions. A precise description helps the agent activate the skill at the right moment and skip it otherwise.
• Use progressive disclosure. Reference supporting files that are read only when the workflow reaches them.
• Prefer scripts over inline code. Executing a script consumes no context; only its output does. Inline code blocks are paid for on every load.
• Keep file references one level deep. Link directly from SKILL.md to supporting files rather than chaining through intermediate documents.

Script Requirements Copy Chapter

When a skill ships runnable helpers under scripts/, each script follows these conventions:

• Use a #!/bin/bash shebang.
• Use set -e for fail-fast behavior.
• Write status messages to stderr: echo "Message" >&2.
• Write machine-readable output (JSON) to stdout.
• Include a cleanup trap for temporary files.
• Reference the script path as skills/<skill-name>/scripts/<script>.sh (repo-relative).

Writing Principles Copy Chapter

1. Process over knowledge. Skills are workflows, not reference docs. Steps, not facts.
2. Specific over general. "Run npm test" beats "verify the tests".
3. Evidence over assumption. Every verification checkbox requires proof.
4. Anti-rationalization. Every skip-worthy step needs a counter-argument in the rationalizations table.
5. Progressive disclosure. Main SKILL.md is the entry point. Supporting files are loaded only when needed.
6. Token-conscious. Every section must justify its inclusion. If removing it wouldn't change agent behavior, remove it.

Naming Conventions Copy Chapter

• Skill directories: lowercase-hyphen-separated
• Skill files: SKILL.md (always uppercase)
• Supporting files: lowercase-hyphen-separated.md
• Shared references: stored in the root references/ directory, not inside skill directories (see Shared References for why).
• Skill-specific references: a single supporting doc can stay as a loose file in the skill directory (the Supporting files entry above); when several related docs travel with the skill, the emerging convention for self-contained, distributable skills is to group them in a references/ directory inside the skill directory, so the skill carries its own supporting docs.

Cross-Skill References Copy Chapter

Reference other skills by name:

Follow the `test-driven-development` skill for writing tests.
If the build breaks, use the `debugging-and-error-recovery` skill.

Don't duplicate content between skills — reference and link instead.

Required vs Recommended Copy Chapter

Required:

• A skills/<skill-name>/SKILL.md file
• Valid YAML frontmatter with name and description
• A description that includes both what the skill does and when to use it

Recommended:

• The standard section flow shown above
• Equivalent headings such as How It Works, Core Process, or Workflow when they read more naturally for the skill
• Supporting files only when they keep the main SKILL.md focused

File: docs/windsurf-setup.md Copy Chapter

Using agent-skills with Windsurf

Setup Copy Chapter

Project Rules Copy Section

Windsurf uses .windsurfrules for project-specific agent instructions:

# Create a combined rules file from your most important skills
cat /path/to/agent-skills/skills/test-driven-development/SKILL.md > .windsurfrules
echo "\n---\n" >> .windsurfrules
cat /path/to/agent-skills/skills/incremental-implementation/SKILL.md >> .windsurfrules
echo "\n---\n" >> .windsurfrules
cat /path/to/agent-skills/skills/code-review-and-quality/SKILL.md >> .windsurfrules

Global Rules Copy Section

For skills you want across all projects, add them to Windsurf's global rules:

1. Open Windsurf → Settings → AI → Global Rules
2. Paste the content of your most-used skills

Recommended Configuration Copy Chapter

Keep .windsurfrules focused on 2-3 essential skills to stay within context limits:

# .windsurfrules
# Essential agent-skills for this project

[Paste test-driven-development SKILL.md]

---

[Paste incremental-implementation SKILL.md]

---

[Paste code-review-and-quality SKILL.md]

Usage Tips Copy Chapter

1. Be selective — Windsurf's context is limited. Choose skills that address your biggest quality gaps.
2. Reference in conversation — Paste additional skill content into the chat when working on specific phases (e.g., paste security-and-hardening when building auth).
3. Use references as checklists — Paste references/security-checklist.md and ask Windsurf to verify each item.

2. Official Technical Reference & Guides (addyosmani/docs) Copy Chapter

Polymer docs are mostly in Markdown with some HTML. Jekyll is used to generate the static HTML for the site. The output is generated into a folder called _site and served from Google App Engine.

Prereqs and installation requirements Copy Chapter

We use Jekyll 1.4.2+ and Grunt to generate the documentation. You'll need to install the requirements before working on the docs (these instructions assume NPM is already installed):

sudo gem install jekyll
sudo gem install kramdown
sudo npm install grunt-cli
npm install

You'll also need the App Engine SDK to run the dev_appserver and preview the docs locally. Download the SDK.

Check out the documentation Copy Section

Checkout this repo:

git clone https://github.com/Polymer/docs.git --recursive

Create a directory polymer-all/projects and run the pull-all-projects.sh script in that directory:

cd docs/polymer-all
mkdir projects; cd projects
../tools/bin/pull-all-projects.sh

This populates projects with a bunch of repositories. You'll periodically need to re-run pull-all-projects.sh whenever the site is released.

Next, create a components folder in the top level docs directory and run pull-all-polymer.sh and pull-all-elements.sh in it:

cd ../..
mkdir components; cd components
../polymer-all/tools/bin/pull-all-polymer.sh
../polymer-all/tools/bin/pull-all-elements.sh

Note: these scripts can take some time to download.

You should now be able to build the docs successfully. Run this in the main folder:

grunt docs

Making edits and previewing changes Copy Chapter

This repo (Polymer/docs) is where the documentation source files live. To make a change:

1. First, up the App Engine dev server in this folder (dev_appserver.py .) to preview the docs.
2. Make your edits.
3. To build the docs, run grunt in base of the docs diretory you checked out. This starts up jekyll and watches for changes as you make edits. Be sure to run npm install in your docs directory if it's a new checkout. It can take some time for the docs to fully regenerate and be copied to the output folder...keep refreshing!

Jekyll generates the static site in a folder named _site. Note: If you're not running jekyll to rebuild the site, you won't see your changes in the dev server.

Once your changes look good, git commit them and push.

Building and pushing the docs Copy Chapter

Note: only project owners can publish the documentation.

If you have things checked out correctly in components and polymer-all, you should be able to generate the prodcution documentation using:

grunt docs

It's a good idea to do this before pushing the docs, as it runs a number of grunt tasks. Verify things went well.

Last step is to push the docs to App Engine. In your Polymer/docs directory, run:

./scripts/deploy_site.sh

This script builds the site, api docs, runs Vulcanizer over the imports, and deploys to App Engine.

Polymer release Copy Chapter

When we push a new version of Polymer, the site should be updated to use it. In addition,
the element reference and other projects will need updating.

First, update the submodules in /docs:

git submodule foreach git pull origin master
git submodule update

Update the projects:

cd polymer-all/projects
../tools/bin/pull-all-projects.sh

Then, update the elements and polyfills:

cd components
../polymer-all/tools/bin/pull-all-polymer.sh
../polymer-all/tools/bin/pull-all-elements.sh

Once these are updated, you need to update some versions for the docs:

• Increment the version in app.yaml;
• Update the Polymer release version in _config.yml.
• Add a link point link to the release notes in changelog.md.

Build the docs:

grunt docs

At this point, run the dev server and preview things locally to make sure nothing is terribly
broken after Polymer and the elements have been updated.

Lastly, run the deploy script:

./scripts/deploy_site.sh

Last thing is to switch the app version in the App Engine admin console. To make the docs live, hit up https://appengine.google.com/deployment?&app_id=s~polymer-project and select the version you just deployed.