agent-skills: Forcing Agents Through the Senior-Engineer Loop

Created on 2026-02-15, addyosmani/agent-skills had 100,339 stars and 10,540 forks when fetched on 2026-10-01—about 7.5 months later. The JavaScript project is MIT-licensed, and its homepage presents a 25-skill library organized around a DEFINE→PLAN→BUILD→VERIFY→REVIEW→SHIP loop.

The central engineering bet is that coding-agent reliability can come less from model choice than from forcing a repeatable process. The process is packaged as portable markdown skills, loaded when needed rather than pasted wholesale into every session. That can make checks and evidence part of the workflow, but it also raises questions about portability, runtime behavior, and memory. This is a source-based review, not an installation guide: the point is to identify what systems engineers might copy, what they should avoid, and where the design may break in production. Teams weighing workflow structure against agent autonomy may find agentic code-verification loops useful.

How This Review Was Researched

This review is based on the repository source, documentation, issue tracker, and the creator’s design posts — we did not run it hands-on. The data and design claims below are tied to the GitHub API stats, 2026-10-01 and the repository’s published materials.

The GitHub API reported 100,339 stars, 10,540 forks, 122 open issues, 518 watchers, a 2026-02-15 creation date and 2026-09-26 last push; the project is MIT-licensed and written in JavaScript. The README, skill-anatomy, and comparison documents were fetched from main; the project site, design post, and harness post add context. The vercel-labs/skills, issue #361, Trendshift page, and WikiSkill paper were also consulted; all cited URLs returned HTTP 200 at fetch time. Mishra’s head-to-head figures are third-party disclosures, not reproduced here. Last reviewed: October 2026.

What Exactly Is a “Skill”? (State Machine, Not a Reference Doc)

A skill is “somewhere between a system-prompt fragment and a runbook”: a discrete workflow with checkpoints, evidence, and an exit criterion—not reference documentation. In the README, each skill lives at skills/<name>/SKILL.md; its full body is loaded on demand, not at session start.

Think of a skill as a small state machine: the agent enters a step when the task calls for it and progresses only by following the stated procedure, with a step able to require an action, evidence, and a check before proceeding. Reference material in references/ loads only when a step needs it.

That separation matters: a reference doc explains what something is; a skill specifies what the agent must do next and what counts as completion. Progressive disclosure keeps the initial context footprint low while still drawing on detailed checklists when relevant.

The Anatomy of a SKILL.md: Frontmatter, Rationalizations, and Evidence

A SKILL.md combines routing metadata with an executable-looking procedure: Overview, When to Use, Core Process, Common Rationalizations, Red Flags, and Verification. The skill-anatomy document specifies lowercase-hyphen name matching the directory and a description of at most 1024 characters that states what the skill does and when to trigger it.

The body’s order is practical: establish the skill’s purpose, define positive triggers and negative exclusions, then give numbered steps with literal commands. Common Rationalizations presents an agent’s likely excuse beside a rebuttal. Red Flags calls out signs the process is being skipped; Verification ends with an evidence checklist.

The rationalization table is a distinctive enforcement device: instead of hoping a general instruction persuades the agent to do the slow work, the author anticipates shortcuts in advance and supplies a rebuttal at the point of failure. Reusable pattern: write the predictable failure down, then define the counter-check.

The documented limits create useful boundaries: keep SKILL.md under 500 lines and split reference files longer than 100 lines into repo-root references/. That keeps the main procedure short and separates supporting material instead of one ever-growing prompt.

The Process Machine: 6 Phases, 9 Slash Commands, 4 Review Personas

The six phases map to nine slash commands, from /spec through /ship, with /build auto providing a bounded autonomous mode. Skills can activate from context, and /ship fans work out to four review personas before merging their findings into a go/no-go. The README documents the lifecycle and commands.

The nine commands are /spec, /plan, /build, /test, /constraints, /review, /webperf, /code-simplify, and /ship. With /build auto, the user approves the plan once and the agent then executes tasks autonomously, remains test-driven, and pauses on failures.

At shipment, /ship sends reviews in parallel to code-reviewer, test-engineer, security-auditor, and web-performance-auditor, then merges the results into a go/no-go. The rationale is straightforward: without process prompts, agents tend toward the shortest path to “done,” which can omit specifications, tests, and security checks. A forced lifecycle attempts to make those omissions harder. This plans-first model mirrors spec-driven development: commands matter less than the gates they enforce.

Progressive Disclosure: How 25 Skills Fit in ~5K Tokens — and the references/ Gap

The library keeps its session-start context to skill names and descriptions, loads a full SKILL.md when a workflow step calls for it, and opens references only when needed. The comparison document describes the 25-skill library as fitting in roughly 5K tokens through this progressive disclosure.

The tradeoff appears in distribution. A per-skill install through the vercel-labs/skills CLI copies only skills/<name>/; some skills refer to checklists in the repository-root references/, so those sibling paths can dangle in an isolated install. This is the portability footgun tracked by issue #361: the issue is closed, but the README still prints the warning.

Per-skill installs suit a self-contained skill and a narrow dependency; whole-repo installs are safer when workflows rely on shared references, or when later edits add such dependencies. Production choices should validate copied paths in the packaging layer or preserve the repository layout; a low token footprint does not guarantee a complete package.

Portability as a Design Decision: “Write the Procedure, Not the Workaround”

The project describes markdown skills as portable across 70+ hosts, at the cost of host-native dynamic behavior. Its rule is “write the procedure, not the workaround”: avoid model names, versions, and private tool names. The README presents that neutrality as a portability choice, not a promise of identical behavior everywhere.

The repository also checks in thin per-host adapters for native discovery (.claude-plugin/, .cursor/skills/, .gemini/, .codex-plugin/, plus Copilot, OpenCode, Windsurf, Kiro, and Command Code). The split is sound: keep the procedure portable, fit each host with adapters, and avoid host-specific workarounds in the shared workflow. The creator’s harness engineering post explains why adapters matter when a shared artifact meets different runtimes.

Neutrality has a real cost: a procedure avoiding model-specific behavior may leave performance on the table for a tuned host. The WikiSkill paper warns that skills groomed against one model can make a stronger model perform worse. Model-neutrality hedges that failure, not equal behavior across models.

How agent-skills Relates to AGENTS.md, Plugins, and Cursor Rules (a Layer, Not a Replacement)

agent-skills is a workflow layer alongside AGENTS.md and CLAUDE.md, not a replacement for either. Those files are rolling prose rulebooks loaded whole; skills are discrete, on-demand procedures with exit criteria. The comparison document explicitly warns against pasting full skills into Cursor rules.

View it as a stack: repository-level guidance supplies standing context, skills supply task-specific procedures, host adapters support native discovery, and vercel-labs/skills provides a distribution CLI. The project began as a Claude Code plugin model and extended across hosts rather than treating markdown alone as complete runtime integration.

For an existing agent platform, the question is not “Should this replace AGENTS.md?” but “Which instructions should always be present, and which should load only for a relevant task?” Keep stable constraints in the rulebook, treating AGENTS.md as an engineering contract. Move multi-step workflows with checks and completion conditions into skills, and avoid loading the entire library into a global rules file where it consumes context even when irrelevant.

The In-Repo Eval Framework: Three Tiers From Structure to Real Traces

The repository’s three-tier eval checks whether skills are structurally valid, whether descriptions route prompts cleanly, and whether a real execution trace follows the intended checklist. The README makes self-verification part of the artifact, though it does not provide a benchmark of code-completion quality or performance numbers.

Tier 1 checks structural validity. Tier 2 checks description vocabulary and routing, including whether two skills collide for a trigger. Tier 3 grades a real execution trace against the checklist the skill intends to enforce.

This beats shipping a prompt folder with no validation: structure and routing tests catch malformed metadata or ambiguous activation before users see them, and trace grading asks the harder behavioral question—did the agent actually perform the required steps?

The boundary matters, though. These tiers are not a benchmark harness for code quality, task success, or model comparisons, and the repository reports no numbers behind them. Teams should treat the framework as a useful self-check for skill integrity, then add task-level evaluations if they need evidence about coding outcomes. That distinction is central to evaluation-harness architecture: a valid workflow is not itself proof of a better result.

How Does agent-skills Compare on the Ground? (Mishra’s Head-to-Head)

The comparison is less about which repository has the most skills than what each layer optimizes: enforced process, distribution, or agent autonomy. The table separates documented architecture from undisclosed data. Mishra’s reported head-to-head figures are third-party disclosures in the comparison document, not results reproduced for this review.

The philosophies differ: agent-skills enforces explicit gates—define, plan, test, review, establish evidence—while Superpowers optimizes an autonomous inner loop with deep, narrow procedures. The best fit depends on whether a system’s failures come from missing checks or a need for self-direction.

agent-skills’ notable combination is process as a portable artifact, progressive disclosure, three eval tiers, and four-persona review fan-out. Mishra’s disclosed figures report about 8 minutes to code versus 12, 7 versus 5 validation passes, and roughly identical token efficiency. Those are third-party-reported, not reproduced here, and are one disclosed comparison, not a general guarantee.

The gaps temper the result: none of the compared frameworks provides durable cross-session memory, the alternatives disclose no in-repo eval frameworks, and neutrality trades away model-specific tuning. The table’s n.r. cells mean the cited material reports no comparable figure; they are not estimates.

What Are the Hard Tradeoffs and Failure Modes?

The sharpest costs are structural rather than cosmetic: markdown cannot provide host-native dynamic behavior, model-neutral procedures cannot be tuned to every model, and isolated installs can lose shared reference files. The comparison document and issue #361 make these tradeoffs concrete instead of theoretical when adapting the pattern.

First, portability means accepting a lowest-common-denominator procedure and maintaining adapters where native discovery matters. Second, the references/ gap means per-skill packaging needs path validation or a whole-repo layout. Third, neutrality protects against one-model overfitting but cannot guarantee optimal performance on every model; a reason to evaluate, not to abandon portable procedures.

A shared frontier is missing durable cross-session memory: skills govern the current workflow but keep no persistent account of decisions across sessions; that capability belongs in a separate memory or state layer. The README describes 25 skills—24 lifecycle skills plus the using-agent-skills meta-router—while the site labels 24, a documentation inconsistency, not a different runtime capability.

The creator is Addy Osmani, an ex-Google/Chrome web-performance lead; collaborators include Federico Bartoli and Joan León. The Trendshift page adds an adoption signal, but popularity does not establish workflow quality; judge the pattern against your own task mix and failure modes.

The Bottom Line

agent-skills makes a strong case that agent reliability is a process problem engineers can shape: portable workflows, explicit exit criteria, progressive disclosure, in-repo checks, and a /ship review fan-out. For agent-infrastructure teams, adopt the pattern as a layer beside AGENTS.md, prefer whole-repo installs, and plan separately for the missing cross-session memory.

The most reusable idea is not a particular command; it is making the procedure, evidence, and stopping condition explicit. The weakest assumption would be that portable markdown behaves identically across hosts or models. Treat the skill pack as a workflow design to validate and maintain, not a substitute for runtime integration or outcome evaluation.

1. Adopt process-as-on-demand-skill: define triggers, ordered steps, exit criteria, and an evidence checklist.
2. Use anti-rationalization tables and progressive disclosure: anticipate shortcuts while keeping inactive procedures out of the full session context.
3. Layer skills beside AGENTS.md: use adapters for host discovery and prefer whole-repo packaging where references/ dependencies exist.
4. Budget for what the skills do not supply: durable cross-session memory and benchmark-level evidence of coding quality.

FAQ

The three questions below cover the most common adoption concerns for teams evaluating the library before integrating it: whether skills replace AGENTS.md, whether the markdown files work across the many supported agents, and whether skills persist knowledge between sessions; the README documents the design behind each answer.

Is agent-skills a replacement for AGENTS.md?

No. AGENTS.md is a rolling rulebook loaded whole each session, while skills are discrete, on-demand procedures with checkpoints and an exit criterion. The comparison document positions skills as a workflow layer beside such files, not a replacement for them; keep stable constraints in AGENTS.md and move multi-step workflows into skills.

Does agent-skills work across different coding agents?

agent-skills are markdown procedures designed to run across 70+ hosts through per-host adapters such as .claude-plugin/, .cursor/skills/, and .gemini/. The README frames that neutrality as a portability choice, not a promise of identical behavior, so plan for host-specific behavior where native discovery matters.

Does agent-skills remember context between sessions?

No. Skills govern the current workflow but do not persist decisions across sessions, so durable state belongs in a separate memory or state layer. The comparison table lists cross-session memory as none for every framework it compares, meaning persistence is a gap you must fill separately.

📖 Related Reads

• ToolBrain — tool reviews, LLM comparisons, and AI workflow guides

Cross-links automatically generated from CodeIntel Log.