Agent Skills: engineering discipline for coding agents

Everything you need to know about addyosmani/agent-skills: a collection of verifiable workflows that tries to build specification, testing, review, and delivery into the work of coding agents.

What Agent Skills is

Agent Skills is a library of engineering skills for coding agents. Each skill is a Markdown document with metadata and a process: steps, checkpoints, warning signs, responses to rationalizations, and a verifiable exit condition. It is not a model or an execution platform.

Its premise is that an agent usually jumps straight from a request to an implementation and skips less visible tasks: pinning down requirements, designing, testing before implementing, reviewing, and preparing delivery. The repository packages those steps into 24 skills: 23 covering the development cycle, plus using-agent-skills, which decides which flow to apply.

The README frames the journey as define → plan → build → verify → review → ship. Beyond the skills, it offers four review profiles —code, tests, security, and web performance— and reference material for security, accessibility, performance, and observability.

Glowing digital document with metadata, checkmarks, and warning symbols, representing a Skill as a structured Markdown file.

The origin: from a repository created in February to a public explainer in May

The GitHub API places the repository’s creation on February 15, 2026; the earliest recoverable commit in its history, Add AGENTS.md, is from that same day and is signed by Addy Osmani. Osmani’s GitHub account identifies him as a former Google director who worked on Gemini and Google Cloud; that biography comes from the account itself, not an institutional attribution of the project to Google.

Futuristic timeline with the dates February 15 and May 3 over a network of nodes representing the repository's growth to 27,000 stars.

Osmani published the launch article “Agent Skills” on May 3, 2026. There he says the project had passed 27,000 stars and lays out the starting problem: agents optimize for the “task completed” signal, while reliable engineering work also demands specifications, tests, evidence, and review. His answer isn’t to add lengthy documentation to the context, but to give the agent a short sequence it can execute and check.

The tension with built-in features is explicit: a rules file or a general explainer doesn’t guarantee an agent will apply the practice when it matters. Agent Skills uses a router skill to progressively load the relevant workflow, instead of loading the whole catalog upfront. For Claude Code, the repository also documents a session-start hook that injects using-agent-skills; its test checks the JSON content both with jq and without that utility available.

Philosophy and principles

Osmani’s text and the README hold to five verifiable design decisions:

Process over prose: a skill must sequence concrete actions, not just describe good practices.
Anti-rationalization: tables collect excuses for skipping steps and their rebuttal, because models can justify plausible-sounding shortcuts.
Non-negotiable verification: a test, build output, trace, or review constitutes evidence; a claim that something “looks right” doesn’t close the task.
Progressive disclosure: the context needed for the current phase is loaded, not the entire material at once.
Scope discipline: the agent should not refactor adjacent systems or expand a task without understanding and justifying the change.

The author relates these ideas to engineering practices published by Google —for example, Hyrum’s Law, readability review, testing, and gradual rollouts— but the source presents this as inspiration and adaptation by the project, not official Google documentation.

AI core protected by holographic shields deflecting ghost-like excuses, representing the anti-rationalization principle.

How it works

The flow can be invoked through eight slash commands:

Goal	Command	Stated principle
Define what to build	`/spec`	Specification before code
Break down the work	`/plan`	Small, atomic tasks
Implement	`/build`	One vertical slice at a time
Prove it works	`/test`	Tests are evidence
Review before merging	`/review`	Improve code health
Audit web performance	`/webperf`	Measure before optimizing
Simplify	`/code-simplify`	Clarity over cleverness
Prepare delivery	`/ship`	Faster is safer

Futuristic command center with the flow's eight slash commands, from /spec to /ship, arranged in a circular interface.

/build can generate the plan and execute its tasks after a single approval: each task keeps test-driven development and a separate commit, and the process stops on failures or risky steps. Skills are also activated by context: the README gives API design and interface work as examples.

General installation uses the open skills tool:

npx skills add addyosmani/agent-skills
npx skills add addyosmani/agent-skills --list
npx skills add addyosmani/agent-skills --skill code-review-and-quality

Terminal running the command npx skills add addyosmani/agent-skills and pulling structured Markdown files.

The README claims that tool is compatible with more than 70 agents and lists, among others, Claude Code, Cursor, Codex, Copilot, Cline, and Gemini. It also contains integrations and directories specific to Claude Code, Codex, Gemini, Antigravity, and OpenCode. That is compatibility documented by the project; it does not amount to certification from each vendor.

Official and semi-official status

The repository includes a marketplace manifest, and Osmani’s article documents, for Claude Code, the commands /plugin marketplace add addyosmani/agent-skills and /plugin install agent-skills@addy-agent-skills. That establishes an installation mechanism through the marketplace the project itself configured.

No page from a vendor accepting Agent Skills into an official marketplace, nor an announcement from Anthropic, OpenAI, Google, Cursor, or another company endorsing it, was retrieved in the sources consulted. Its verifiable status is therefore community-driven or semi-official through its native integrations, not an official vendor endorsement. The 81,424 stars and the Hacker News thread show notable adoption, but they don’t amount to a formal designation as a de facto standard.

The ecosystem

Ecosystem map with a central monolith representing the main repository, surrounded by satellite nodes and a constellation of stars.

addyosmani/agent-skills concentrates the project’s adapters: .claude-plugin, .codex-plugin, .gemini, .opencode, .agents/plugins, and commands. These aren’t separate repositories, but formats and integrations within the main repository.
agentskills/ is cited by the Hacker News user kergonath as an official repository of the skills ecosystem. The retrieved conversation doesn’t allow determining its exact technical relationship to Agent Skills, so no integration or direct competition is attributed to it.
obra/superpowers and the skills by Matt Pocock are the two collections that Agent Skills’ own comparison document names as closest references. The first favors autonomous runs with subagents, a strict process, and worktree isolation; the second is described as a toolbox for Claude Code with a characteristic interrogation loop. This relationship comes from the repository itself, not from an affiliation.

Forks and translations

The GitHub forks API returned, among the highest-starred, Dev-moe-kyawaung/agent-skills (17), rosnjs/agent-skills (5), and wizzeart/agent-skills (2). Their descriptions repeat the original project’s description; they are therefore classified as forks, not as independent ports or extensions.

No verifiable community translation was identified in the queries performed. In addition, CONTRIBUTING.md states that the project does not accept translations of documentation or skills, to avoid them going stale. That policy doesn’t prove external translations don’t exist; it only explains they aren’t part of the main repository.

The public repositories of addyosmani were queried to locate sibling projects. With the retrieved sources, no sibling repository specifically dedicated to Agent Skills, evaluations, or a separate marketplace was established; that relationship is not invented here.

Repo numbers

Measured: August 3, 2026, GitHub API and page.

Metric	Value
Stars	81,424
Forks	8,775
Subscribers	440
Commits	383
Open issues reported by the API	145
Branches	12
Tags	7
Primary language	JavaScript
License	MIT
Created	February 15, 2026
Latest recoverable commit	July 26, 2026
Latest release	`0.6.5`, July 26, 2026

The top contributors returned by the API by number of contributions were addyosmani (218), nucliweb (33), federicobartoli (33), dj2313 (6), Dashsoap (4), and Keerthi-Sreenivas (4). The count of 383 commits was corroborated with the main page and with the last recoverable page of commit pagination.

GitHub returns watchers_count with the same value as the stars; that’s why subscribers_count is reported here as the real subscriber figure. The open_issues_count field may include open pull requests, so 145 isn’t necessarily an issues-only count. The API returned updated_at as August 3, 2026, matching the measurement date; it is transcribed as metadata, not as an inference about additional activity.

How to contribute

CONTRIBUTING.md asks contributors to first check the catalog and open pull requests, read the anatomy of a skill, and justify in the proposal the gap it aims to fill. If there’s overlap, the existing skill should be extended instead of creating another directory.

A new skill requires a directory with a lowercase, hyphenated name, a SKILL.md with name and description metadata, and a case in evals/cases/<name>.json: at least three positive triggers, two negative ones, and one behavior evaluation. Execution evaluations must use real files from evals/fixtures/; conversational skills can use a human-reviewed dialogue evaluation. Continuous integration enforces these requirements.

Futuristic workstation assembling a new skill directory next to a checklist of contribution requirements.

For changes to the startup hook or the router skill, the guide requires running:

bash hooks/session-start-test.sh

The contribution is licensed under MIT. The guide also limits scope: focused changes, preserving structure and tone, and verifying that the YAML metadata remains valid.

How the community received it

The main conversation retrieved is the Hacker News thread 48015397, posted by BOOSTERHIDROGEN on May 4, 2026. Its root item in the Algolia API records 376 points and 212 comments.

Abstract visualization of a Hacker News thread with conversation bubbles connected by glowing fiber-optic threads.

encoderer wrote that they had adopted several skills and singled out the API design and interface testing ones as particularly useful. That’s concrete praise of two areas, not a comparative evaluation.
ElijahLynn explained they used it on a new personal project and that it let them focus on architecture and product design instead of deciding how to build every part; they also thanked the repository and its contributors.
y-curious said they would take away many ideas, but raised a concern about the possibility of uninstalling the plugin and argued each skill should be personalized for the developer. bvirkler replied that a plugin was just a set of files and asked why it couldn’t be deleted; the source preserves the doubt, not a conclusive technical resolution.
kergonath recounted having to come up with most of their own skills and that Claude wasn’t particularly helpful in creating them. That’s a criticism of the agent’s assistance on that task, not an accusation of a repository failure.

An earlier submission also appeared, 47670950, by msolujic, with 2 points and 0 comments. It serves as evidence of early discovery, but not as community endorsement or criticism.

Agent Skills versus other proposals

Proposal	Verifiable overlap	Verifiable difference per `docs/comparison.md`
`obra/superpowers`	A collection of skills for coding agents.	It focuses on autonomous runs with reasoning, subagents, a strict process, and worktree isolation; Agent Skills orders the full cycle by phases and adds review profiles and evaluations in the repository.
Matt Pocock’s skills	A collection of workflows for coding agents.	It’s presented as a curated, opinionated tool for Claude Code, with an interrogation loop; Agent Skills distributes its catalog across the six phases of the development cycle.

The comparison itself warns that neither is “better” in the abstract. The contrast is limited to how the author characterizes the projects; no independent evaluation measuring outcomes, cost, or quality between them was retrieved.

Use cases and who this repository can help

Teams that want an agent to stop jumping from a request straight to a code change can use the sequence /spec → /plan → /build → /test → /review → /ship to make specification, evidence, and review visible.
Owners of API, interface, or security changes can trigger specialized skills like api-and-interface-design, frontend-ui-engineering, and security-and-hardening, instead of relying on a general, unverifiable guideline.
Maintainers of an internal workflow for agents can adopt the anatomy the repository requires —process, rationalizations, warning signs, and exit condition— and its evaluation cases to check that a skill activates and behaves as expected.
People working across several agent environments can install the set with npx skills or use the documented adapters for Claude Code, Codex, Gemini, Antigravity, or OpenCode; it’s worth checking behavior in your own environment first, since the stated compatibility isn’t a vendor certification.

Resources

Repository: https://github.com/addyosmani/agent-skills
Documentation and installation: https://github.com/addyosmani/agent-skills#quick-start
Author’s announcement and philosophy: https://addyosmani.com/blog/agent-skills/
Official skills: https://github.com/addyosmani/agent-skills/tree/main/skills
Contribution guide and evaluations: https://github.com/addyosmani/agent-skills/blob/main/CONTRIBUTING.md and https://github.com/addyosmani/agent-skills/tree/main/evals
Comparison with related proposals: https://github.com/addyosmani/agent-skills/blob/main/docs/comparison.md
Community and reviews: https://news.ycombinator.com/item?id=48015397 and https://news.ycombinator.com/item?id=47670950
Discord: no official Discord link was retrieved in the sources consulted.

Note: this article combines the README, contribution guide, comparison document, and launch article for Agent Skills; the GitHub API and page; and Hacker News via Algolia, retrieved on August 3, 2026. Figures change over time.