Agent Skills by Addy Osmani

Agent Skills 0.6.9 is a docs, hardening, and contributor-process release. No new skills this time; it sharpens the security and observability guidance in existing skills, adds setup and workflow docs, and lands a governance mechanism for the catalog's own development.

Highlights

• Advanced per-agent configuration guide (#316, @nucliweb). The canonical reference for keeping SKILL.md frontmatter portable and pushing vendor-specific runtime controls (model, tools, turn limits, thinking level) into metadata or a per-agent adapter, so the same skill file works across Claude Code, Cursor, Gemini, Antigravity, and other spec-conformant clients.
• Rejected skill-change ledger (#544, from #535). An append-only record of skill and description changes that were proposed and rejected, together with the eval score that rejected them, so the same idea does not get re-litigated in a new PR. Checking it is now a pre-flight step in CONTRIBUTING, and the ledger row lands on the default branch so closing the rejected PR cannot erase the record.

Hardening (existing skills)

• security-and-hardening: destructive path operations (delete, move, overwrite) now require symlink resolution, an allowlisted root, a minimum depth, and an ownership check read before the call (#547, @notbucki). And rate limiting must count in a shared store across instances, since a per-instance counter silently stops working the moment you run more than one instance (#536, @CahidArda).
• observability-and-instrumentation: when several entry points write to one log stream, stamp the entry point next to the correlation ID at the point the run starts. A correlation ID says which run; it does not say which code path started it (#546, @notbucki).

Docs

• Copilot: the standalone copilot CLI (plugin install) and Copilot inside VS Code are separate setups with different invocation models, now documented as such (#550, @DEOWL-kan, addressing #542).
• Lifecycle: the spec, plan, and task artifacts are the handoff between sessions. Run the whole lifecycle in one session for a small task; use a fresh session per phase for anything non-trivial (#549, @DEOWL-kan, from #513).
• Antigravity: the command-wrapper discoverability limitation is documented (#532, @ayobamiseun, from #445).
• Routing: database-migration and dependency-audit vocabulary added to the relevant skill descriptions (#537, @notbucki).

Thanks

Thanks to everyone who contributed this release: @nucliweb, @DEOWL-kan, @notbucki, @CahidArda, @ayobamiseun, @mvanhorn, and @federicobartoli.

Full Changelog: https://github.com/addyosmani/agent-skills/compare/0.6.8...0.6.9

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.

<a href="https://trendshift.io/repositories/25200" target="_blank"><img src="https://trendshift.io/api/badge/repositories/25200" alt="addyosmani%2Fagent-skills | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>

Addy's Agent Skills

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

---

Quick Start

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

<details>

<summary><b>Claude Code (recommended)</b></summary>

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

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

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

</details>

<details>

<summary><b>Cursor</b></summary>

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.

</details>

<details>

<summary><b>Antigravity CLI</b></summary>

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.

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

</details>

<details>

<summary><b>Gemini CLI</b></summary>

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

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/

</details>

<details>

<summary><b>Windsurf</b></summary>

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

</details>

<details>

<summary><b>OpenCode</b></summary>

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.

</details>

<details>

<summary><b>GitHub Copilot</b></summary>

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

Using the standalone copilot CLI? Install it as a plugin — see docs/copilot-cli-setup.md.

</details>

<details>

<summary><b>Kiro IDE & CLI </b></summary>

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/

</details>

<details>

<summary><b>Codex</b></summary>

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.

</details>

<details>

<summary><b>Command Code</b></summary>

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.

</details>

<details>

<summary><b>Other Agents</b></summary>

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

</details>

---

Adoption

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

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.

Meta - Discover which skill applies

| Skill | What It Does | Use When |

|-------|-------------|----------|

| using-agent-skills | 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 | 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 | Structured divergent/convergent thinking to turn vague ideas into concrete proposals | You have a rough concept that needs exploration |

| spec-driven-development | Write a PRD covering objectives, commands, structure, code style, testing, and boundaries before any code | Starting a new project, feature, or significant change |

| constraint-driven-development | 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 | Decompose specs into small, verifiable tasks with acceptance criteria and dependency ordering | You have a spec and need implementable units |

Build - Write the code

| Skill | What It Does | Use When |

|-------|-------------|----------|

| incremental-implementation | Thin vertical slices - implement, test, verify, commit. Feature flags, safe defaults, rollback-friendly changes | Any change touching more than one file |

| test-driven-development | Red-Green-Refactor, test pyramid (80/15/5), test sizes, DAMP over DRY, Beyonce Rule, browser testing | Implementing logic, fixing bugs, or changing behavior |

| context-engineering | Feed agents the right information at the right time - rules files, context packing, MCP integrations | Starting a session, switching tasks, or when output quality drops |

| source-driven-development | Ground every framework decision in official documentation - verify, cite sources, flag what's unverified | You want authoritative, source-cited code for any framework or library |

| doubt-driven-development | 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 | Component architecture, design systems, state management, responsive design, WCAG 2.1 AA accessibility | Building or modifying user-facing interfaces |

| api-and-interface-design | Contract-first design, Hyrum's Law, One-Version Rule, error semantics, boundary validation | Designing APIs, module boundaries, or public interfaces |

Verify - Prove it works

| Skill | What It Does | Use When |

|-------|-------------|----------|

| browser-testing-with-devtools | Chrome DevTools MCP for live runtime data - DOM inspection, console logs, network traces, performance profiling | Building or debugging anything that runs in a browser |

| debugging-and-error-recovery | Five-step triage: reproduce, localize, reduce, fix, guard. Stop-the-line rule, safe fallbacks | Tests fail, builds break, or behavior is unexpected |

Review - Quality gates before merge

| Skill | What It Does | Use When |

|-------|-------------|----------|

| code-review-and-quality | Five-axis review, change sizing (~100 lines), severity labels (Nit/Optional/FYI), review speed norms, splitting strategies | Before merging any change |

| code-simplification | Chesterton's Fence, Rule of 500, reduce complexity while preserv