Agent Skills : the 68k-star repo that teaches AI agents engineering best practices

Agent Skills : the 68k-star repo that teaches AI agents good engineering practices

🔎 A superpowered junior with zero instinct

AI coding agents have a problem no one likes to name. They write code at a dizzying speed, but they act like overly enthusiastic juniors: you ask for a feature, they write it, say "done", and move on. No spec, no tests, no review. The diff is green, technical debt explodes.

This is exactly the observation made by Addy Osmani, engineering lead at Google Chrome and creator of Chrome DevTools and Lighthouse. After 14 years at Google, he saw AI agents repeating the same mistakes as junior developers — except that juniors eventually learn.

On February 15, 2026, Osmani open-sourced agent-skills on GitHub. Three months later, the project reached 39,000 stars. On July 10, 2026, it was trending at #3 worldwide with 68,600 stars. The concept is simple but radical: package the expertise of senior engineers into workflows executable by any AI agent.

Skills are not prompts. They are processes with checkpoints, quality gates, and exit criteria. The missing link between an agent that codes fast and an agent that codes well.

The Essentials

• Agent Skills is an open-source (MIT) framework of 24 production-grade engineering skills, created by Addy Osmani (Google Chrome / Google Cloud AI).
• Each skill encodes a complete workflow with checkpoints, anti-rationalization tables, and proof requirements — not just a simple prompt, but a process.
• Compatible with Claude Code, Cursor, Codex, Gemini CLI, Copilot, Windsurf, OpenCode, Kiro IDE, and Antigravity CLI via pure markdown files.
• The project went from 0 to 68,600+ GitHub stars in 5 months, becoming the de facto standard for AI agent skills.
• 8 slash commands (/spec, /plan, /build, /test, /review, /webperf, /code-simplify, /ship) allow you to invoke workflows in a single command.

Recommended Tools

The 24 Skills: a complete 6-phase lifecycle

Each skill covers a specific phase of software development. Together, they form a Define → Plan → Build → Verify → Review → Ship pipeline that leaves zero blind spots.

DEFINE — Define what you're building before writing a single line

The most underestimated phase by AI agents. Three skills force the agent to understand the problem before coding.

interview-me asks questions one by one until reaching ~95% confidence in understanding the requirement. The agent doesn't assume, it asks. idea-refine applies divergent then convergent thinking to explore alternatives before committing. spec-driven-development requires a complete PRD in 6 sections before any implementation — the skill that ClaudeWave identifies as the most impactful in the repo.

PLAN — Break down without underestimating

planning-and-task-breakdown transforms specs into verifiable tasks with explicit acceptance criteria. No more vague plans that generate half-functional code.

BUILD — 7 skills for writing production-grade code

This is where the engineering density is at its maximum. incremental-implementation forces thin vertical slices with feature flags. test-driven-development enforces the Red-Green-Refactor cycle with Google's 80/15/5 test pyramid (80% unit, 15% integration, 5% e2e) and the DAMP over DRY rule for tests.

source-driven-development anchors every decision in the official documentation of the framework or API being used — the agent no longer guesses APIs. doubt-driven-development is perhaps the most original skill: it applies a 5-step adversarial review (CLAIM → EXTRACT → DOUBT → RECONCILE → STOP) to challenge every technical decision.

frontend-ui-engineering covers component architecture, design systems, and WCAG 2.1 AA compliance. api-and-interface-design applies contract-first design and Hyrum's Law: "when an API has enough users, every observable behavior will be depended on by someone."

VERIFY — Prove that it works

browser-testing-with-devtools uses the official Chrome DevTools MCP to get real runtime data. The agent doesn't just read the code, it inspects the rendering. debugging-and-error-recovery applies a 5-step triage: reproduce, locate, reduce, fix, protect.

REVIEW — The discipline that agents systematically skip

code-review-and-quality applies a review across 5 axes with PR sizing at ~100 lines and severity labels (Critical/Nit/Optional/FYI). This is where the project's Google DNA manifests the most. code-simplification applies Chesterton's Fence: don't remove code without understanding why it exists. security-and-hardening checks the OWASP Top 10, authentication patterns, and secrets management. performance-optimization enforces measure-first with Core Web Vitals.

SHIP — Deliver without breaking

Four skills cover trunk-based development with atomic commits, CI/CD with Shift Left and feature flags, deprecation with the code-as-liability mindset, ADRs for architecture decisions, observability with RED metrics and OpenTelemetry, and pre-launch checklists with staged rollouts.

META — The skill that orchestrates the others

using-agent-skills is a router that analyzes the context and decides which skill to apply. It's the principle of progressive disclosure: the agent only loads what it needs, minimizing token consumption.

Why AI agents need Skills (and not just prompts)

The distinction is fundamental. A prompt tells the agent what to do. A skill tells it how to do it, when to stop, and why each step is non-negotiable.

Osmani puts it this way in his founding article: "AI coding agents are extremely capable junior engineers with no instinct for the parts of the job that don't show up in the diff." Translation: agents master the implementation, but they have no instinct for everything that doesn't show up in the diff — specs, tests, reviews, deprecation, observability.

Process over prose

Each skill is structured as a process with inputs, sequential steps, checkpoints, and exit criteria. These are not reference essays that the agent might ignore. They are workflows with gates that the agent must pass.

Anti-rationalization tables

This is the most brilliant detail of the project. Each skill includes a table of the most common excuses the agent might generate to skip a step, along with pre-written rebuttals. For example: "I'll add tests later" → rebuttal: "Tests written after implementation reflect what the code does, not what it should do. Write them first." The agent cannot lie to itself.

Non-negotiable verification

No skill ends without explicit proof requirements: tests must pass, the build must be clean, the runtime trace must be provided. No "I guess it works." Proof or nothing.

The Agent Skills framework marks an inflection point: we are moving from ad-hoc instruction to a structured skill system. As the Silenceper Blog analysis notes, Skills are becoming a standard in the AI Agent ecosystem — several competing projects are emerging around the same format.

How to install and use Agent Skills

Installation is designed to be trivial. Skills are pure markdown files, making them compatible with any agent that accepts system prompts.

Universal installation

npx skills add addyosmani/agent-skills

This CLI command detects your environment and installs the skills in the correct directory. For platforms with a native plugin marketplace, the paths are optimized.

Claude Code

Claude Code offers the most native integration thanks to its plugin marketplace. Two commands are all it takes:

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

Once installed, the 8 slash commands are available directly in the Claude Code session. You type /spec, the agent launches the specification workflow. You type /build auto, and it generates the plan then implements all tasks in a single approved pass. It is with Claude Code, combined with models like Claude Opus 4.7 (Adaptive), that the experience is the smoothest.

Cursor

In Cursor, skills are placed in .cursor/skills/ and .cursor/rules/. The agent loads them automatically at session startup. With GPT-5.5 on the backend, the routing between skills is particularly efficient.

Codex and other CLI agents

OpenAI Codex has supported native plugins since v0.122+:

codex plugin marketplace add addyosmani/agent-skills

Gemini CLI, GitHub Copilot, Windsurf, OpenCode, Kiro IDE and Antigravity CLI all work with markdown files placed in the appropriate configuration directories. Compatibility is almost universal.

The model used on the backend matters less than the skills framework itself. Whether you are on GPT-5.5 (agentic score 98.2), Claude Opus 4.7 (94.3) or Claude Sonnet 4.6 (81.4), the skills provide the structure. A good model without skills produces fast but fragile code. An average model with skills produces structured and verified code.

The Google DNA: 14 years of engineering packaged

What sets Agent Skills apart from the hundreds of GitHub prompts for AI agents is the depth of the encapsulated expertise. Osmani spent 14 years at Google. The skills are not generic best practices — they are principles drawn from Software Engineering at Google, the definitive book on engineering at Google.

Hyrum's Law in the API design skill. The Beyoncé Rule (if you contributed to a piece of code, you are responsible for its quality) in the TDD skill. The 80/15/5 test pyramid. Trunk-based development with atomic commits. Shift Left in CI/CD. The code-as-liability mindset for deprecation. Chesterton's Fence for simplification.

Each principle is integrated into an actionable workflow, not cited as a theoretical reference. The agent doesn't read "apply trunk-based development". It executes a process that is trunk-based development, with checks at each step.

O'Reilly Radar, which republished Osmani's article, validates this approach with the enterprise audience. The key quote sums it all up: AI agents lack instinct for everything that isn't visible in the diff. Agent Skills is the scaffolding that compensates for this gap.

The Skills ecosystem is exploding: an emerging new standard

Agent Skills is no longer an isolated project. It has triggered a movement. The VoltAgent/awesome-agent-skills repository now lists 1000+ skills coming from official dev teams and the community. The Open Agent Skills Directory offers reusable skills for finance, research, web scraping, marketing, and design.

Bilgin Ibryam analyzes on X the top 10 agent skills by GitHub stars and observes a clear trend: small, precise workflows are winning against vague mega-prompts. A skill that does one thing well is better than a prompt that tries to cover everything.

The concept of Skills joins that of the best autonomous AI agents as a modularity standard. In the same way that OpenClaw structures agents into SOUL, AGENTS, and Skills — as explained in our guide to configuring OpenClaw — the Skills format is becoming the common language for describing an agent's capabilities.

For those who want to create an AI agent from scratch, Skills offer a catalog of pre-validated behaviors to compose. And if you are working locally with Ollama, the markdown format of skills works with any locally hosted LLM for agents.

The parallel with Hermes's Skills system is striking. The Hermes Skills system relies on the same principle: an agent that learns and improves through the addition of modular skills. The convergence between these independent projects confirms that the Skills format is becoming a de facto standard.

The 8 slash commands: a complete workflow in 8 words

Beyond the 24 individual skills, Agent Skills exposes 8 shortcut commands that chain workflows together.

The /build auto command is the most powerful — and the most dangerous. It generates the plan and implements it in a single approved pass. On a model like GPT-5.5 or Claude Opus 4.7, with the skills as guardrails, the result is impressive. But on a less capable model, approving a complete pass without intermediate verification remains risky.

Agent Skills vs. vibe coding: two opposing philosophies

Vibe coding — writing code by vaguely describing what you want — exploded in 2025-2026. It's appealing but fragile. Agent Skills represents the anti-vibe coding: more discipline, more process, more verification.

It's no coincidence that Medium/Vibe Coding titled its article on the project "Google's Engineering Playbook For Your Agents". The message is clear: vibe coding is a starting point, not a methodology. Skills are the transition from prototype to production.

The Reddit discussion nicely sums up the community sentiment: "AI agents are amazing at spitting out code fast. But they act like eager juniors: you ask for a feature, they write it, say 'done,' and move on." Skills fix exactly this.

Record & Replay: when the agent learns by observing

A parallel movement reinforces the Skills approach: record & replay. OpenAI Codex recently introduced the ability to show a task once so the agent repeats it infinitely. You perform an action in your IDE, Codex records it and reproduces it.

Record & Replay and Agent Skills are complementary. The former captures empirical workflows (what you actually do). The latter provides prescriptive workflows (what a senior would ideally do). Together, they cover the entire spectrum: observing to learn, following to improve.

❌ Common mistakes

Mistake 1: Confusing Skills and prompts

Skills are not improved system prompts. They are processes with gates, anti-rationalization tables, and exit criteria. Treating them like prompts means ignoring 80% of their value. The difference is the same as between a checklist and a procedures manual.

Mistake 2: Installing the Skills and approving everything without reading

/build auto is convenient, but blindly approving cancels out the benefits of the quality gates. The idea is not to replace your judgment, but to give the agent a framework that makes your judgment easier to exercise. Read the checkpoints. Verify the evidence.

Mistake 3: Using all 24 skills at the same time

The using-agent-skills meta-skill exists for a reason: progressive disclosure. Loading all 24 skills into the agent's context consumes tokens unnecessarily and dilutes attention. Let the router do its job.

Mistake 4: Ignoring the anti-rationalization tables

These tables are the most innovative mechanism of the project. They anticipate exactly how agents try to short-circuit processes. If you remove or ignore them, the agent reverts to its rushed junior behaviors.

Mistake 5: Thinking that Skills replace humans

Osmani himself says it in his LinkedIn post on the 0.6.3 release: "AI might have made implementation cheaper, but not the engineering judgment. The more capable the agents become, the more valuable engineering judgment becomes." Skills automate the process, not the judgment.

❓ Frequently Asked Questions

Will Agent Skills replace my team's workflows?

No. Skills codify best practices, not your specific processes. Use them as a starting point and adapt them to your context. The markdown format makes customization trivial.

Which AI model works best with Agent Skills?

Models with the best agentic scores (GPT-5.5 at 98.2, Gemini 3 Pro Deep Think at 95.4, Claude Opus 4.7 at 94.3) best leverage routing between skills. But even Claude Sonnet 4.6 (81.4) benefits significantly from the framework compared to using it without skills.

Does it work with local open source LLMs?

Yes. Skills are pure markdown. Any agent that accepts system prompts can use them, including self-hosted models like Kimi K2.6 or GLM-5 via Ollama. The quality of the routing will depend on the model, but the workflows remain executable.

What is the difference with MCP servers?

MCP servers provide capabilities (accessing an API, reading a file, inspecting a page). Skills provide processes (how to chain these capabilities into a coherent workflow). They are complementary layers, not competing ones.

How many tokens do Skills consume?

The meta-skill routes to the relevant skill, so only one skill is loaded into the context at a time. The consumption is comparable to a long system prompt. Progressive disclosure is designed specifically to avoid saturating the context.

✅ Conclusion

Agent Skills does not solve the problem of AI coding poorly — it solves the problem of AI coding without a method. By packaging 14 years of Google expertise into executable workflows, Addy Osmani has created the missing standard in the AI agent ecosystem. Going from 0 to 68,600 stars in 5 months is no passing hype: it is the recognition that the missing link between a fast agent and a reliable agent is engineering. If you are using AI agents to code and don't know Agent Skills yet, now is the time to explore it on GitHub.