Agent Skills

What it is

Agent Skills is Addy Osmani’s set of engineering workflows for AI coding agents. Each skill is a Markdown file called SKILL.md, with steps the agent follows, checks it must pass and exit criteria. The getting started page says skills are not reference docs: they are step-by-step processes. The README says they encode the workflows, quality gates and practices that senior engineers use. The repository also holds lifecycle slash commands, reviewer personas and checklists that the skills pull in when needed.

1. /spec writes a spec before any code
2. /plan breaks it into small tasks
3. /build implements one slice at a time
4. /test proves each change works
5. /review checks the change before merge
6. /ship runs the launch checks

Who it suits

Developers who let an AI coding agent write code and want it to follow the steps a senior engineer would, from spec to launch. The README says agents default to the shortest path, which often skips specs, tests and security reviews. Teams with an older codebase can adopt the skills in phases, starting with the read-only ones. An existing project needs no migration.

Skip it if you want an agent to go straight to code. These skills add a spec, tests and a review on purpose, and the README calls verification non-negotiable.

Where to use it

Addy Osmani’s README and docs give a route or a pointer for each of these agents. The lifecycle slash commands are written for Claude Code, and Gemini CLI has its own wrappers. On the other agents you name the skill in your request.

• Claude Code: the marketplace plugin, with the commands and the personas
• Codex: a native plugin, with skills called by @name
• Cursor: skills synced into .cursor/skills/ and a short routing rule
• Gemini CLI: native skills, or GEMINI.md, plus command wrappers
• Antigravity CLI: a native plugin, with a known gap in the wrapper commands
• GitHub Copilot: skills and personas in VS Code, and a plugin for the Copilot CLI
• OpenCode: skills in .opencode/skills/ and your own AGENTS.md
• Windsurf: a .windsurfrules file built from a few skills
• Command Code: cmd skills add
• Kiro: skills under .kiro/skills/, with a pointer to Kiro’s own docs
• A few more hosts: the lines on the maker’s other hosts page

How to set it up

Get it saves a zip of Mindket’s setup notes in your downloads folder, with each agent’s steps from Addy Osmani’s README and docs. The fastest route is the open skills CLI, which works with any agent it supports. Claude Code, Codex, Antigravity CLI and the Copilot CLI have plugin routes of their own.

1. Install your agent, and git if your route clones the repository.
2. Run the install line for your agent. The skills CLI line below works with any agent that CLI supports, and the README names Claude Code, Cursor, Codex, Copilot and Cline. It installs the skills only: the /spec-style commands and the personas come with the Claude Code plugin.
3. Start a new session in your project so the skills are found.
4. Leave this repository’s own AGENTS.md and CLAUDE.md out of your project, since the getting started page says they configure contributors to agent-skills itself.

npx skills add addyosmani/agent-skills
npx skills add addyosmani/agent-skills --list

The first line installs the skills and the second only lists them. Add --skill and a name to take just one. In Claude Code, add the marketplace and install the plugin. The README says the marketplace clones over SSH, and gives an HTTPS form for anyone with no SSH key.

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

For Codex, the plugin takes two lines. The first registers the marketplace and the second installs the plugin.

codex plugin marketplace add addyosmani/agent-skills
codex plugin add agent-skills@agent-skills

Cursor, Gemini CLI, Antigravity CLI, Copilot, OpenCode, Windsurf and Command Code have their own lines in the kit’s notes.

How to use it

With the Claude Code plugin installed, the commands follow the lifecycle, and each one activates the right skills.

Skills also run on their own. The README says designing an API triggers api-and-interface-design and building UI triggers frontend-ui-engineering. Where a built-in command has the same name, as /review does, use /agent-skills:review. On an agent without these commands, name the skill, as the Copilot guide does.

Use the spec-driven-development skill to write a spec for [the feature].

/build auto skips the stepping between tasks once a spec exists. It makes the plan if there is none, asks you to approve it once, then implements every task. The README says each task is still test-driven and committed on its own.

Example

You start a new feature in Claude Code with the plugin installed, and you run three commands in turn. The adoption guide lists them in this order.

/spec   →  SPEC.md
/plan   →  tasks/plan.md
/build  →  one slice at a time

The /spec command asks about the objective, the users, the features, the tech stack and the boundaries. It then saves SPEC.md in the project root and waits for your confirmation. Next, /plan reads that spec in read-only plan mode, slices the work vertically and saves tasks/plan.md and tasks/todo.md for your review. Then /build takes the next pending task, writes a failing test, makes it pass, commits and stops. You end with a spec you confirmed, a task list you reviewed and one committed slice.

For newcomers and experts

If you are new. A coding agent left alone takes the shortest path, and the README says that often means no spec, no tests and no security review. A skill is a Markdown file that tells the agent which steps to follow and what proof to show at the end. Each one also lists the excuses an agent might use to skip a step, with a reply to each. Start with three: spec-driven-development, test-driven-development and code-review-and-quality. The getting started page says not to load every skill at once, because that wastes context.

For experts. Every skill starts with YAML frontmatter holding a name and a description. The README draws the body as Overview, When to Use, Process, Rationalizations, Red Flags and Verification, and the skill anatomy page calls that layout a recommended pattern in which equivalent headings are fine. SKILL.md is the entry point, and supporting references load only when needed. The README says the skills carry ideas from Google’s engineering culture, such as Hyrum’s Law in API design, the Beyonce Rule and the test pyramid in testing, and Chesterton’s Fence in simplification.

One of the personas’ four rules is that a persona does not call another persona. The agents page says /ship is the one fan-out pattern the repository endorses. It runs code-reviewer, security-auditor and test-engineer in parallel, each in a fresh context, and the main agent merges their reports. Agent Teams, an experimental Claude Code feature, can use the same persona names when CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is set.

If your agent already finds skills from their descriptions, do not also paste using-agent-skills into an always-on prompt. The getting started page says that creates two routers for the same task.

Good to know

The skills are Markdown your agent reads, but the commands have the agent act. /build and /test run your test suite, /build also runs the build and commits each task, and /constraints installs checkers. A few details are worth knowing before you install.

• What reaches out: the README and the docs Mindket read say nothing about a server or telemetry of the pack’s own. Your agent has its own settings. The README links the skills CLI and does not describe its settings
• Tools the commands add: /constraints has the agent install the checker for each dimension you pick, such as Semgrep, gitleaks, osv-scanner, axe-core, Lighthouse, size-limit, dependency-cruiser and Stryker. Accessibility and performance need a running URL, or the dimension is dropped. It also adds check:fast, check:task and check:full to package.json and a line to CLAUDE.md. /webperf’s Deep mode can use a Lighthouse report or a CrUX API response, which needs CRUX_API_KEY or GOOGLE_API_KEY
• Permissions: Gemini CLI asks before it activates a skill, and the Antigravity CLI guide says it prompts before executing one. With /build auto, the agent stops for your sign-off on auth or permission changes, destructive data migrations, payments, deletions, deploys, anything touching secrets and anything git revert cannot undo
• Commands: the short lifecycle commands are written for Claude Code, and Gemini CLI has its own wrappers. The README says they do not appear in Copilot. In affected Antigravity CLI releases the wrappers are missing too, which the guide tracks as agent-skills issue 445
• One skill at a time: a per-skill npx install copies only skills/<name>/, so the paths to the shared checklists in references/ are missing. The skill still works. The README tracks the gap as issue 361
• SSH errors: if /plugin install still fails with git@github.com: Permission denied (publickey) on Windows or macOS, the README says to run git config --global url."https://github.com/".insteadOf git@github.com: once
• A plugin warning: the Claude Code plugin install can print that the default commands/ folder is ignored because the manifest sets commands. The getting started page says to expect it. The warning is cosmetic
• Working files: /spec and /plan write SPEC.md, tasks/plan.md and tasks/todo.md. Delete them before merge, or add the folder to .gitignore, if your repository should not keep them
• Removal: the README and docs give no remove lines for the plugin installs. The Antigravity CLI guide gives agy update to update the CLI or check for newer plugin versions. Command Code gives cmd skills add with --force to update and cmd skills remove to remove
• License: MIT. The LICENSE file reads “Copyright (c) 2025 Addy Osmani”