agent-skills: Production workflows for AI coding agents
It gives AI coding agents an engineering workflow from requirements to release instead of just the shortest coding path.
GitHub addyosmani/agent-skills Updated 2026-09-04 Branch main Stars 107.1K Forks 11.1K
AI coding agents Markdown skills skills CLI Claude Code/Codex

🧭 Decision Guide

Try it if you

  • You use Claude Code, Cursor, or Codex and want consistent spec, test, and review workflows.
    The README Quick Start lists Claude Code, Cursor, and Codex; the lifecycle diagram covers DEFINE, PLAN, BUILD, VERIFY, REVIEW, and SHIP.
  • Your team wants to adopt 25 skills at once instead of writing agent prompts individually.
    The README Quick Start states that `npx skills add addyosmani/agent-skills` installs all 25 skills.
  • You maintain either a greenfield project or an established codebase and need different rollout paths.
    The README Adoption section says the Adoption Guide covers a full lifecycle for greenfield projects and an incremental verification-first rollout for established codebases.

Skip it if you

  • You can only install individual skills but depend on shared checklists in the repository-level references directory.
    The README explicitly says a per-skill npx install copies only `skills//`, not `references/`; this issue is tracked in Issue #361.
  • Your Codex CLI version is below 0.122 and you cannot upgrade to a version supporting native plugins.
    The README Codex section requires Codex CLI v0.122+.
  • Your agent does not accept system prompts or instruction files.
    The README Other Agents section says Skills work with agents that accept system prompts or instruction files.

Requirements

  • An npx environment capable of running the open skills CLI; the README Quick Start uses `npx skills add`.
  • A target agent covered by the README integrations, such as Claude Code, Cursor, Codex, Copilot, or Cline.
  • Codex CLI v0.122+ for the native Codex plugin.
  • A GitHub SSH key for the Claude Code Marketplace, or the HTTPS URL workaround described in the README.
  • A local Claude Code development setup requires `git clone https://github.com/addyosmani/agent-skills.git` first.

First step (verbatim from README)

npx skills add addyosmani/agent-skills

Watch out

  • Installing one skill with `--skill` does not copy repository-level references.
    README Quick Start, Installing one skill; the portability issue is tracked in Issue #361.
  • The Claude Code Marketplace uses SSH by default and may show `Permission denied (publickey)` on Windows or macOS.
    The README Claude Code section documents the SSH error and the `git config --global url."https://github.com/".insteadOf [email protected]:` workaround.
  • Affected Antigravity CLI releases may not discover wrapper commands converted from legacy command TOMLs.
    The README Antigravity CLI section says to invoke namespaced skills directly and links to `docs/antigravity-setup.md`.

Alternatives

  • Project-level AGENTS.md and agent rules:Better when you need only a small set of project rules or want to keep using OpenCode's `AGENTS.md` without introducing 25 skills.
    README OpenCode section
  • Directly maintained system prompts or instruction files:Better when the target agent supports system prompts or instruction files but is outside the native integrations listed in the README.
    README Other Agents section

Not stated in the README

  • The supplied README materials do not specify the file count, input format, or output format of each skill.
  • The supplied README materials provide no test suite, CI status, or automated validation results for the 25 skills.
  • The project data has an empty primary-language distribution, so the implementation language or runtime cannot be confirmed.
  • The project data reports 0 contributors, 0 releases, and 0 recent commits, while the README lists Addy Osmani, Federico Bartoli, and Joan León as maintainers; the discrepancy is unexplained.
  • The supplied README materials do not provide a compatibility matrix across agent versions.
  • The supplied README materials do not quantify effects on code quality, test coverage, or delivery speed.
  • The supplied README materials do not state the latest update date, so current maintenance freshness cannot be assessed.

💡 Deep Analysis

6
Yes We use Claude Code on macOS and Windows machines without GitHub SSH keys. Can we install agent-skills through the Marketplace, or must we use a local clone?
For: A team using Claude Code on macOS or Windows environments without GitHub SSH keys, intending to install agent-skills through the Marketplace

Yes. Marketplace installation remains viable, but without GitHub SSH keys you should use the HTTPS marketplace URL or the documented Git URL rewrite rather than being forced into a local clone.

  • The README marks the Claude Code Marketplace integration as recommended, while warning that the Marketplace clones repositories over SSH.
  • It provides the HTTPS command /plugin marketplace add https://github.com/addyosmani/agent-skills.git, followed by /plugin install agent-skills@addy-agent-skills.
  • If Windows or macOS still reports Permission denied (publickey), the README recommends configuring Git’s insteadOf rewrite so subprocess clones use HTTPS.
  • A local clone and claude --plugin-dir are also documented, but they are an alternative development path, not a requirement for machines without SSH keys.
  • Claude Code (recommended): the Marketplace clones repositories via SSH
  • Quick Start: `/plugin marketplace add https://github.com/addyosmani/agent-skills.git`
  • Quick Start: `git config --global url."https://github.com/".insteadOf [email protected]:`
/plugin marketplace add https://github.com/addyosmani/agent-skills.git
Not stated in the README:The README does not specify whether Marketplace installation requires a particular Claude Code version.;The README does not describe the effect of corporate proxies, firewalls, or enterprise Git configuration on HTTPS subprocess clones.
It depends We maintain an existing codebase in Cursor and require the AI agent to complete testing followed by a five-axis review before merge. Can this project directly provide those quality gates?
For: A maintenance team responsible for change risk in an existing codebase, using Cursor and requiring tests plus a five-axis review before merge

It depends. The project can provide the workflow instructions and review entry points, but it cannot independently prove that tests passed or replace CI, static analysis, or security scanners.

  • The README provides test-driven-development and code-review-and-quality, covering test-driven implementation and a five-axis review before merge.
  • For Cursor, the documented integration places workflow skills under .cursor/skills/ and short policies under .cursor/rules/*.mdc; it explicitly says not to paste full skills into rules.
  • The project insight states that the repository is not an independent testing platform, CI system, deployment system, or security scanner.

So it is suitable for standardizing what the agent must attempt and report, but not sufficient as the sole source of objective evidence. The actual gate still depends on the repository’s test commands, CI results, and scanning tools.

  • Quick Start: `code-review-and-quality` is described as `five-axis review before merge`
  • Quick Start: Cursor uses `.cursor/skills/` and `.cursor/rules/*.mdc`; full Skills should not be pasted into rules
  • Project insight, usage_limitations: it is not an independent testing platform, static analyzer, CI system, deployment system, or security scanner
npx skills add addyosmani/agent-skills --skill code-review-and-quality   # five-axis review before merge
Not stated in the README:The README does not specify automatic discovery and trigger precedence for each Skill after Cursor integration.;The README does not state whether review results have a machine-readable format for direct CI integration.;The README does not describe compatibility with a maintenance team’s existing test, static-analysis, and security-scanning tools.
Yes I maintain an existing codebase in Claude Code and only want to start with code-review-and-quality and test-driven-development rather than installing all 25 skills at once. Is this project suitable for that gradual workflow?
For: An individual developer using Claude Code on an existing codebase who wants to start with code review and test-driven development instead of enabling all 25 skills at once

Yes. The project fits this gradual workflow because the README explicitly supports installing individual skills, and these two skills target review and verification rather than requiring the complete lifecycle.

  • code-review-and-quality is described as “five-axis review before merge.”
  • test-driven-development is described as “red-green-refactor, enforced,” making it a reasonable entry point for an existing codebase.
  • Claude Code supports both Marketplace and local plugin installation, so adoption can remain scoped to the current repository.

There is one concrete limitation: the README says a per-skill install copies only skills// and not the repository-level references/ directory. Shared checklists referenced by the selected skill may therefore be unavailable. A single-skill installation is appropriate only after checking whether those references are needed.

  • Quick Start: `npx skills add addyosmani/agent-skills --skill code-review-and-quality # five-axis review before merge`
  • Quick Start: `npx skills add addyosmani/agent-skills --skill test-driven-development # red-green-refactor, enforced`
  • Quick Start: per-skill installation copies only `skills//`, not the repository-level `references/` directory
npx skills add addyosmani/agent-skills --skill test-driven-development   # red-green-refactor, enforced
Not stated in the README:The README does not identify which specific reference checklists these two individually installed skills require.;The README does not specify the auto-trigger priority for individually installed skills in Claude Code.
It depends We want to standardize AI development across Claude Code, Cursor, and Copilot, but our codebase already has its own architectural history, test commands, and release policies. Can we copy these Skills directly?
For: A software engineering team standardizing AI-assisted development while retaining its own architecture documentation, test commands, and release policies

It depends. The project is suitable as a shared process layer, but it should not replace the team’s existing architecture, testing, and release rules without customization.

  • The README presents Skills as Markdown workflows containing explicit steps and engineering judgment, and documents distribution across Claude Code, Cursor, and Copilot.
  • The project insight explicitly states that generic skills do not automatically understand business constraints, architectural history, compliance requirements, or organizational release policies; copying them directly may produce unsuitable checks.
  • The recommended repository context includes architecture documentation, development and test commands, acceptance criteria, data-safety requirements, and release procedures.
  • The team can therefore share the project as a common baseline while adding repository context and host-specific rules, instead of maintaining three unrelated workflow systems.
  • README Why Agent Skills: Skills encode “when to write a spec, what to test, how to review, and when to ship”
  • Project insight, common_pitfalls: generic skills do not automatically understand business constraints, architectural history, compliance requirements, or organizational release policies
  • Project insight, best_practices: add architecture documentation, development and test commands, acceptance criteria, data-safety requirements, and release procedures
npx skills add addyosmani/agent-skills --list     # browse before installing
Not stated in the README:The README does not explain how conflicts between team-rule precedence and generic Skill rules should be resolved.;The README does not provide ready-made adapters for specific compliance frameworks or enterprise release policies.;Project data shows `release_count` is 0, but the README does not define an organizational version-pinning mechanism.
Yes I lead a greenfield project and plan to have an agent in Codex CLI v0.122+ handle requirements clarification, specification, planning, testing, review, and shipping. Should I adopt the complete skill package?
For: A technical lead establishing architecture and delivery practices for a greenfield project, planning to use Codex CLI v0.122+ from requirements through shipping

Yes. It is particularly suitable for a greenfield project that wants to establish a complete delivery process from the beginning, because the skill set spans the lifecycle rather than focusing only on code generation.

  • The project insight organizes the workflow into DEFINE, PLAN, BUILD, VERIFY, REVIEW, and SHIP, matching the requested end-to-end path.
  • The Quick Start provides a one-command installation for all 25 skills, which is appropriate when multiple lifecycle stages must work together.
  • Codex CLI v0.122+ supports native plugin installation, and installed skills can be invoked with @, such as @spec-driven-development.
  • The value proposition is to encode clarification, specification, testing, review, and shipping practices as executable agent steps.

The trade-off is process overhead: the project insight notes that the full set can create skill-selection and interaction burden. Adoption is suitable when the greenfield team accepts explicit lifecycle checkpoints instead of direct code-edit requests.

  • Project insight, solution_analysis: lifecycle organized as `DEFINE, PLAN, BUILD, VERIFY, REVIEW, SHIP`
  • Quick Start: `npx skills add addyosmani/agent-skills # install all 25 skills`
  • Codex: `Codex CLI v0.122+`, with skills invoked using `@spec-driven-development`
npx skills add addyosmani/agent-skills            # install all 25 skills
Not stated in the README:The README does not specify the default trigger order for the complete skill package in Codex.;The README does not explain how the SHIP phase integrates with a specific deployment platform, approval flow, or production permissions.;The README provides no quantitative measurement of context length or execution-time impact for the complete package.
Yes We use Codex CLI v0.122+, GitHub Copilot, and Gemini CLI. Can we use one agent-skills workflow for requirements, coding, and review without maintaining three separate prompt sets?
For: A software engineering team using Codex CLI v0.122+, GitHub Copilot, and Gemini CLI that wants consistent entry points for AI-assisted requirements, implementation, and review

Yes, with platform-specific loading configuration. The reusable unit is the Markdown workflow, but installation and discovery are not identical across the three hosts.

  • The README describes Skills as plain Markdown that works with agents accepting system prompts or instruction files.
  • Codex CLI v0.122+ can install the repository as a native plugin, read the root skills/ directory, and invoke skills with @.
  • Gemini CLI supports native skill installation or persistent context through GEMINI.md; Copilot uses agents/ and .github/copilot-instructions.md.
  • Therefore, the team can share one workflow source, but must maintain host-specific integration files and procedures. The project removes duplicated workflow content, not every integration task.
  • Quick Start: `Skills are plain Markdown - they work with any agent that accepts system prompts or instruction files.`
  • Codex: `Codex CLI v0.122+`, reads the root `skills/` directory and invokes skills with `@`
  • Gemini CLI: native Skills or `GEMINI.md`; GitHub Copilot: `agents/` and `.github/copilot-instructions.md`
codex plugin marketplace add addyosmani/agent-skills
Not stated in the README:The README does not define equivalent trigger rules or context precedence across the three platforms.;The README does not explain how the team should version and approve changes to all platform-specific configuration.

✨ Highlights

  • 25 skills cover the full DEFINE-to-SHIP lifecycle
  • The skills CLI supports 70+ agents including Claude Code
  • Workflows include verification gates and anti-rationalization tables
  • MIT-licensed with 92,155 GitHub stars

🔧 Engineering

  • Uses 25 Markdown skills to structure definition, planning, coding, testing, review, and shipping
  • npx skills add installs all skills or a specific skill such as code-review-and-quality
  • Native integrations cover Claude Code, Gemini CLI, Codex, and Command Code

⚠️ Risks

  • Installing one skill does not copy the references directory, so shared checklist paths are unavailable
  • The Claude Code Marketplace clones via SSH, so missing GitHub SSH keys can cause errors
  • The README materials provide no language distribution, releases, or recent commit data

👥 For who?

  • Teams using AI-assisted development with Claude Code, Cursor, or Codex
  • Engineering teams that need to encode spec, test, and review workflows into agents
  • Codebases adopting either the greenfield full lifecycle or incremental rollout