### Install Agent Skills from GitHub Repo

Source: https://github.com/addyosmani/agent-skills/blob/main/docs/gemini-cli-setup.md

Installs agent-skills from a GitHub repository into the default Gemini CLI skills directory. Use this for quick setup from a remote source.

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

--------------------------------

### Install agent-skills Plugin from Remote Repository

Source: https://github.com/addyosmani/agent-skills/blob/main/docs/antigravity-setup.md

Use this command to install the agent-skills plugin directly from its GitHub repository. This is the recommended method for quick setup.

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

--------------------------------

### Stack Detection Example

Source: https://github.com/addyosmani/agent-skills/blob/main/skills/source-driven-development/SKILL.md

Example output after detecting the project's stack and versions.

```text
STACK DETECTED:
- React 19.1.0 (from package.json)
- Vite 6.2.0
- Tailwind CSS 4.0.3
→ Fetching official docs for the relevant patterns.
```

--------------------------------

### SKILL.md Usage Example

Source: https://github.com/addyosmani/agent-skills/blob/main/AGENTS.md

Illustrates how to document the usage of runnable scripts within a skill, including command-line examples and argument descriptions.

```bash
bash /mnt/skills/user/{skill-name}/scripts/{script}.sh [args]
```

--------------------------------

### Project Structure Example

Source: https://github.com/addyosmani/agent-skills/blob/main/skills/spec-driven-development/SKILL.md

Illustrate the expected directory layout for your project, including the purpose of each top-level directory.

```text
src/           → Application source code
src/components → React components
src/lib        → Shared utilities
tests/         → Unit and integration tests
e2e/           → End-to-end tests
docs/          → Documentation
```

--------------------------------

### Build Commands Example

Source: https://github.com/addyosmani/agent-skills/blob/main/skills/spec-driven-development/SKILL.md

Define executable commands with flags for building, testing, linting, and development within your specification.

```text
Build: npm run build
Test: npm test -- --coverage
Lint: npm run lint --fix
Dev: npm run dev
```

--------------------------------

### List Installed Skills

Source: https://github.com/addyosmani/agent-skills/blob/main/docs/gemini-cli-setup.md

Verifies that skills have been successfully installed and are recognized by the Gemini CLI.

```bash
/skills list
```

--------------------------------

### Context-Aware Skill Loading Example

Source: https://github.com/addyosmani/agent-skills/blob/main/docs/getting-started.md

Load skills relevant to the current task to conserve context. Examples include loading frontend-ui-engineering for UI work, debugging-and-error-recovery for debugging, and ci-cd-and-automation for CI setup.

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

--------------------------------

### User Input Examples for Agent Skills

Source: https://github.com/addyosmani/agent-skills/blob/main/docs/opencode-setup.md

Examples of natural language user requests that trigger specific agent behaviors and skill invocations.

```text
Add authentication to this app
```

```text
This endpoint is returning 500 errors
```

```text
Review this PR
```

--------------------------------

### Install agent-skills Plugin from Local Clone

Source: https://github.com/addyosmani/agent-skills/blob/main/docs/antigravity-setup.md

Clone the agent-skills repository locally and then install it as a plugin using the specified path. This is useful for development or when working offline.

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

```bash
agy plugin install /path/to/agent-skills
```

--------------------------------

### Install Agent Skills from Local Clone

Source: https://github.com/addyosmani/agent-skills/blob/main/docs/gemini-cli-setup.md

Installs agent-skills from a local clone of the repository. This is useful when you have a local copy or are developing the skills.

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

--------------------------------

### Identify Project Dependencies

Source: https://github.com/addyosmani/agent-skills/blob/main/skills/source-driven-development/SKILL.md

Examples of dependency files used to detect project stack and versions.

```text
package.json    → Node/React/Vue/Angular/Svelte
composer.json   → PHP/Symfony/Laravel
requirements.txt / pyproject.toml → Python/Django/Flask
go.mod          → Go
Cargo.toml      → Rust
Gemfile         → Ruby/Rails
```

--------------------------------

### Recommended .windsurfrules configuration

Source: https://github.com/addyosmani/agent-skills/blob/main/docs/windsurf-setup.md

Example structure for a .windsurfrules file, keeping to 2-3 essential skills to respect context limits.

```text
# .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]
```

--------------------------------

### Install Agent Skills with Gemini CLI

Source: https://github.com/addyosmani/agent-skills/blob/main/README.md

Install agent-skills as native skills for Gemini CLI. Specify the path to the skills directory when installing from a local clone.

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

```bash
gemini skills install ./agent-skills/skills/
```

--------------------------------

### Sequential Pipeline Example

Source: https://github.com/addyosmani/agent-skills/blob/main/references/orchestration-patterns.md

Depicts a workflow where users execute a series of slash commands in sequence, with context passed between steps, simulating a pipeline.

```text
user runs:  /spec  →  /plan  →  /build  →  /test  →  /review  →  /ship
```

--------------------------------

### Clone Agent Skills Repository

Source: https://github.com/addyosmani/agent-skills/blob/main/docs/opencode-setup.md

Clone the agent-skills repository to your local machine to begin the setup process.

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

--------------------------------

### Install Agent Skills via Claude Marketplace

Source: https://github.com/addyosmani/agent-skills/blob/main/README.md

Use these commands to install agent-skills from the marketplace for Claude. If you encounter SSH errors, use the HTTPS URL instead.

```bash
/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills
```

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

--------------------------------

### Handling Documentation Conflicts

Source: https://github.com/addyosmani/agent-skills/blob/main/skills/source-driven-development/SKILL.md

Example of how to present a conflict between documentation and existing code to the user.

```text
CONFLICT DETECTED:
The existing codebase uses useState for form loading state,
but React 19 docs recommend useActionState for this pattern.
(Source: react.dev/reference/react/useActionState)

Options:
A) Use the modern pattern (useActionState) — consistent with current docs
B) Match existing code (useState) — consistent with codebase
→ Which approach do you prefer?
```

--------------------------------

### Dependency Graph Example

Source: https://github.com/addyosmani/agent-skills/blob/main/skills/planning-and-task-breakdown/SKILL.md

Illustrates the dependency relationships between different components of a project. Implementation order should follow this graph bottom-up.

```text
Database schema
    │
    ├── API models/types
    │       │
    │       ├── API endpoints
    │       │       │
    │       │       └── Frontend API client
    │       │               │
    │       │               └── UI components
    │       │
    │       └── Validation logic
    │
    └── Seed data / migrations
```

--------------------------------

### Minimal Skill Setup

Source: https://github.com/addyosmani/agent-skills/blob/main/docs/getting-started.md

Load these three essential skills for critical quality coverage in AI-assisted development: spec-driven-development, test-driven-development, and code-review-and-quality.

```text
spec-driven-development
test-driven-development
code-review-and-quality
```

--------------------------------

### Component File Structure Example

Source: https://github.com/addyosmani/agent-skills/blob/main/skills/frontend-ui-engineering/SKILL.md

Colocate all files related to a specific UI component for better organization and maintainability.

```treeview
src/components/
  TaskList/
    TaskList.tsx          # Component implementation
    TaskList.test.tsx     # Tests
    TaskList.stories.tsx  # Storybook stories (if using)
    use-task-list.ts      # Custom hook (if complex state)
    types.ts              # Component-specific types (if needed)
```

--------------------------------

### Standard Project README Template

Source: https://github.com/addyosmani/agent-skills/blob/main/skills/documentation-and-adrs/SKILL.md

A structured template for project README files to ensure consistent project setup and command documentation.

```markdown
# Project Name

One-paragraph description of what this project does.

## Quick Start
1. Clone the repo
2. Install dependencies: `npm install`
3. Set up environment: `cp .env.example .env`
4. Run the dev server: `npm run dev`

## Commands
| Command | Description |
|---------|-------------|
| `npm run dev` | Start development server |
| `npm test` | Run tests |
| `npm run build` | Production build |
| `npm run lint` | Run linter |

## Architecture
Brief overview of the project structure and key design decisions.
Link to ADRs for details.

## Contributing
How to contribute, coding standards, PR process.
```

--------------------------------

### Assumptions List Example

Source: https://github.com/addyosmani/agent-skills/blob/main/skills/spec-driven-development/SKILL.md

List your assumptions before writing a spec to ensure clarity and identify potential misunderstandings early.

```text
ASSUMPTIONS I'M MAKING:
1. This is a web application (not native mobile)
2. Authentication uses session-based cookies (not JWT)
3. The database is PostgreSQL (based on existing Prisma schema)
4. We're targeting modern browsers only (no IE11)
→ Correct me now or I'll proceed with these.
```

--------------------------------

### Define Project Context

Source: https://github.com/addyosmani/agent-skills/blob/main/skills/context-engineering/SKILL.md

Use this structured block at the start of a session to provide the agent with necessary project information and constraints.

```text
PROJECT CONTEXT:
- We're building [X] using [tech stack]
- The relevant spec section is: [spec excerpt]
- Key constraints: [list]
- Files involved: [list with brief descriptions]
- Related patterns: [pointer to an example file]
- Known gotchas: [list of things to watch out for]
```

--------------------------------

### Parallel Fan-out with Merge Example

Source: https://github.com/addyosmani/agent-skills/blob/main/references/orchestration-patterns.md

Illustrates a pattern where multiple personas process the same input concurrently, with their results merged into a single output.

```text
                    ┌─→ code-reviewer    ─┐
/ship → fan out  ───┼─→ security-auditor ─┤→ merge → go/no-go + rollback
                    └─→ test-engineer    ─┘
```

--------------------------------

### Configure Parallel CI Jobs with Caching

Source: https://github.com/addyosmani/agent-skills/blob/main/skills/ci-cd-and-automation/SKILL.md

Example YAML configuration for running lint, typecheck, and test jobs in parallel using npm caching.

```yaml
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '22', cache: 'npm' }
      - run: npm ci
      - run: npm run lint

  typecheck:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '22', cache: 'npm' }
      - run: npm ci
      - run: npx tsc --noEmit

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '22', cache: 'npm' }
      - run: npm ci
      - run: npm test -- --coverage
```

--------------------------------

### Feature Flag Implementation

Source: https://github.com/addyosmani/agent-skills/blob/main/skills/ci-cd-and-automation/SKILL.md

A simple TypeScript example demonstrating a feature flag pattern. This allows for decoupling deployment from release, enabling features dynamically.

```typescript
// Simple feature flag pattern
if (featureFlags.isEnabled('new-checkout-flow', { userId })) {
  return renderNewCheckout();
}
return renderLegacyCheckout();
```

--------------------------------

### Simplicity Check Examples

Source: https://github.com/addyosmani/agent-skills/blob/main/skills/incremental-implementation/SKILL.md

Illustrates the principle of choosing the simplest working solution over premature abstraction. Use simple function calls and direct component creation when possible.

```text
SIMPLICITY CHECK:
✗ Generic EventBus with middleware pipeline for one notification
✓ Simple function call

✗ Abstract factory pattern for two similar components
✓ Two straightforward components with shared utilities

✗ Config-driven form builder for three forms
✓ Three form components
```

--------------------------------

### CI Failure Pattern Examples

Source: https://github.com/addyosmani/agent-skills/blob/main/skills/ci-cd-and-automation/SKILL.md

Provides examples of common CI failure types and the corresponding agent actions for resolution. These patterns guide the agent's debugging and recovery skills.

```text
Lint failure → Agent runs `npm run lint --fix` and commits
Type error  → Agent reads the error location and fixes the type
Test failure → Agent follows debugging-and-error-recovery skill
Build error → Agent checks config and dependencies
```

--------------------------------

### Deprecation Notice Example

Source: https://github.com/addyosmani/agent-skills/blob/main/skills/deprecation-and-migration/SKILL.md

A markdown template for announcing deprecation. Include status, replacement, removal date, reason, and a migration guide.

```markdown
## Deprecation Notice: OldService

**Status:** Deprecated as of 2025-03-01
**Replacement:** NewService (see migration guide below)
**Removal date:** Advisory — no hard deadline yet
**Reason:** OldService requires manual scaling and lacks observability.
            NewService handles both automatically.

### Migration Guide
1. Replace `import { client } from 'old-service'` with `import { client } from 'new-service'`
2. Update configuration (see examples below)
3. Run the migration verification script: `npx migrate-check`
```

--------------------------------

### Set up Agent Skills for Local Development with Claude

Source: https://github.com/addyosmani/agent-skills/blob/main/README.md

Clone the repository and point Claude to the plugin directory for local development.

```bash
git clone https://github.com/addyosmani/agent-skills.git
claude --plugin-dir /path/to/agent-skills
```

--------------------------------

### Import agent-skills from Gemini CLI

Source: https://github.com/addyosmani/agent-skills/blob/main/docs/antigravity-setup.md

If agent-skills is already installed in a legacy Gemini CLI setup, you can import it into Antigravity CLI. This command facilitates migration.

```bash
agy plugin import gemini
```

--------------------------------

### Install Agent Skills with Antigravity CLI

Source: https://github.com/addyosmani/agent-skills/blob/main/README.md

Install agent-skills as a native plugin using the Antigravity CLI. You can install from a remote repository or a local clone.

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

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

--------------------------------

### Install Agent Skills for Specific Workspace

Source: https://github.com/addyosmani/agent-skills/blob/main/docs/gemini-cli-setup.md

Installs agent-skills scoped only to the current workspace. This keeps skills local to a project and avoids global installation.

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

--------------------------------

### Modularize GEMINI.md with Skill Imports

Source: https://github.com/addyosmani/agent-skills/blob/main/docs/gemini-cli-setup.md

Demonstrates how to modularize project instructions in GEMINI.md by importing skills from separate files using a specific markdown syntax.

```markdown
# Project Instructions

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

--------------------------------

### ADR Template Example

Source: https://github.com/addyosmani/agent-skills/blob/main/skills/documentation-and-adrs/SKILL.md

An example of an Architecture Decision Record (ADR) template. Store ADRs in `docs/decisions/` with sequential numbering.

```markdown
# ADR-001: Use PostgreSQL for primary database

## Status
Accepted | Superseded by ADR-XXX | Deprecated

## Date
2025-01-15

## Context
We need a primary database for the task management application. Key requirements:
- Relational data model (users, tasks, teams with relationships)
- ACID transactions for task state changes
- Support for full-text search on task content
- Managed hosting available (for small team, limited ops capacity)

## Decision
Use PostgreSQL with Prisma ORM.

## Alternatives Considered

### MongoDB
- Pros: Flexible schema, easy to start with
- Cons: Our data is inherently relational; would need to manage relationships manually
- Rejected: Relational data in a document store leads to complex joins or data duplication

### SQLite
- Pros: Zero configuration, embedded, fast for reads
- Cons: Limited concurrent write support, no managed hosting for production
- Rejected: Not suitable for multi-user web application in production

### MySQL
- Pros: Mature, widely supported
- Cons: PostgreSQL has better JSON support, full-text search, and ecosystem tooling
- Rejected: PostgreSQL is the better fit for our feature requirements

## Consequences
- Prisma provides type-safe database access and migration management
- We can use PostgreSQL's full-text search instead of adding Elasticsearch
- Team needs PostgreSQL knowledge (standard skill, low risk)
- Hosting on managed service (Supabase, Neon, or RDS)

```

--------------------------------

### Initialize Ideas Directory

Source: https://github.com/addyosmani/agent-skills/blob/main/skills/idea-refine/SKILL.md

Optional command to initialize the ideas directory before using the skill. This script sets up the necessary environment for the idea refinement process.

```bash
# Optional: Initialize the ideas directory
bash /mnt/skills/user/idea-refine/scripts/idea-refine.sh
```

--------------------------------

### Migration Steps for Consumers

Source: https://github.com/addyosmani/agent-skills/blob/main/skills/deprecation-and-migration/SKILL.md

A checklist for migrating consumers incrementally. Focus on identifying touchpoints, updating to the replacement, and verifying behavior.

```text
1. Identify all touchpoints with the deprecated system
2. Update to use the replacement
3. Verify behavior matches (tests, integration checks)
4. Remove references to the old system
5. Confirm no regressions
```

--------------------------------

### Install Chrome DevTools MCP Globally

Source: https://github.com/addyosmani/agent-skills/blob/main/agents/web-performance-auditor.md

Install the Chrome DevTools MCP globally to use its commands directly. This is an alternative to running commands via npx.

```bash
npm i -g chrome-devtools-mcp
```

--------------------------------

### List Active Antigravity Plugins

Source: https://github.com/addyosmani/agent-skills/blob/main/docs/antigravity-setup.md

Verify that the agent-skills plugin (or any other plugin) is correctly installed and active in your Antigravity CLI environment. Run this command after installation or import.

```bash
agy plugin list
```

--------------------------------

### Claude Code Skill Installation

Source: https://github.com/addyosmani/agent-skills/blob/main/AGENTS.md

Command to install a skill locally using Claude Code. This copies the skill directory to the user's local Claude skills directory.

```bash
cp -r skills/{skill-name} ~/.claude/skills/

```

--------------------------------

### Initialize OpenTelemetry SDK for Node.js

Source: https://github.com/addyosmani/agent-skills/blob/main/skills/observability-and-instrumentation/SKILL.md

Import this before any other code to enable automatic instrumentation for HTTP, gRPC, and database clients. Configure the service name for tracing.

```typescript
// tracing.ts — must be imported before anything else
import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';

const sdk = new NodeSDK({
  serviceName: 'checkout-service',
  instrumentations: [getNodeAutoInstrumentations()],
});
sdk.start();
```

--------------------------------

### Run Lighthouse Audit with Installed MCP CLI

Source: https://github.com/addyosmani/agent-skills/blob/main/agents/web-performance-auditor.md

Execute a Lighthouse audit using the globally installed Chrome DevTools MCP CLI. The output is directed to a JSON file.

```bash
chrome-devtools lighthouse_audit --output-format=json > report.json
```

--------------------------------

### Structure Commit Messages

Source: https://github.com/addyosmani/agent-skills/blob/main/skills/git-workflow-and-versioning/SKILL.md

Provides examples of descriptive commit messages and the standard format for commit headers.

```text
# Good: Explains intent
feat: add email validation to registration endpoint

Prevents invalid email formats from reaching the database.
Uses Zod schema validation at the route handler level,
consistent with existing validation patterns in auth.ts.

# Bad: Describes what's obvious from the diff
update auth.ts
```

```text
<type>: <short description>

<optional body explaining why, not what>
```

--------------------------------

### Create Agent Skills Directory and Copy Files

Source: https://github.com/addyosmani/agent-skills/blob/main/docs/copilot-setup.md

Use this command to create the necessary directory structure for agent skills and copy essential skill definitions into your repository. Ensure the source path to `agent-skills` is correct.

```bash
mkdir -p .github

# 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
```

--------------------------------

### Create .windsurfrules file

Source: https://github.com/addyosmani/agent-skills/blob/main/docs/windsurf-setup.md

Concatenate multiple skill files into a single .windsurfrules configuration file for project-specific agent instructions.

```bash
# 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
```

--------------------------------

### Project Conventions for Simplification

Source: https://github.com/addyosmani/agent-skills/blob/main/skills/code-simplification/SKILL.md

Steps to follow to ensure simplifications align with project standards and existing patterns.

```text
1. Read CLAUDE.md / project conventions
2. Study how neighboring code handles similar patterns
3. Match the project's style for:
   - Import ordering and module system
   - Function declaration style
   - Naming conventions
   - Error handling patterns
   - Type annotation depth
```

--------------------------------

### Direct Invocation Example

Source: https://github.com/addyosmani/agent-skills/blob/main/references/orchestration-patterns.md

Represents a simple, single-persona workflow where a user directly invokes a persona for a specific task.

```text
user → code-reviewer → report → user
```

--------------------------------

### Agent Interaction Example with interview-me

Source: https://github.com/addyosmani/agent-skills/blob/main/skills/interview-me/SKILL.md

Demonstrates how an agent interacts with a user using the interview-me skill to clarify a request. It shows the agent making hypotheses, asking clarifying questions, and updating its understanding based on user responses.

```text
User:  build me a dashboard for our metrics
Agent: <starts proposing chart libraries and layouts>
```

```text
User: build me a dashboard for our metrics

Agent:
HYPOTHESIS: You want a way to answer "how are we doing?" in standup, and "dashboard" came to mind because that's the conventional answer.
CONFIDENCE: ~30% — missing: who it's for, what "metrics" are, and what success looks like

Q:     When you say "how are we doing?", who's asking — you alone, the engineering team in standup, or up the chain (e.g., your manager, an exec, a board)?
GUESS: engineering team in standup, because "we" usually scopes that way and standups are where this question gets asked. If it's for execs the metrics and the framing change a lot.

User: It's actually for me. I keep losing track of which experiments are running and what their early signal looks like.

Agent:
Updated read: not a team dashboard at all. It's a personal experiment tracker. Confidence: ~60% — still missing: what "early signal" means and what done looks like.

Q:     Is the gap that you don't know which experiments exist, or that you can't see their results in one place?
GUESS: the second one. You have a list of experiments somewhere, but their results live in five different tools, and reconciling them by hand is what you're tired of.

User: First one actually. I literally don't have a list. They're spread across different docs.

Agent: <continues>
```

--------------------------------

### Single-Persona Slash Command Example

Source: https://github.com/addyosmani/agent-skills/blob/main/references/orchestration-patterns.md

A slash command that encapsulates a single persona and its associated skills, simplifying repeated invocations.

```text
/review → code-reviewer (with code-review-and-quality skill) → report
```

--------------------------------

### Example of Good vs. Bad Process Description

Source: https://github.com/addyosmani/agent-skills/blob/main/docs/skill-anatomy.md

Illustrates how to write specific and actionable steps for a skill's core process, contrasting vague advice with precise commands.

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