Agent Skills

Addy Osmani · article · 2026-05-09 source ↗ Reader 🖥️

Agent Harness Agent Skills Coding Agents Progressive Disclosure Scope Discipline

AI coding agents default to the shortest path to 'done' and systematically skip the invisible senior-engineer work (specs, tests, reviews, scope discipline) that separates reliable software from code that breaks — skills are portable, workflow-shaped markdown files that bolt that scaffolding back on by making it impossible for the agent to rationalize skipping it.

practical · expository/prescriptive — A practitioner manifesto and design rationale for a specific open-source project (agent-skills). Combines exposition of the design decisions with prescriptive advice on applying them beyond the project itself.

Structure

Part	Role
The problem: agents skip the invisible work	Establishes the core failure mode — agents behave like juniors who optimize for 'task complete' and skip every phase that doesn't produce code
What a 'skill' actually is	Defines the unit of work: a workflow with steps and exit criteria, not reference documentation — 'process over prose'
The SDLC the skills encode	Maps the 20 skills and 7 slash commands to six lifecycle phases (Define, Plan, Build, Verify, Review, Ship), showing coverage of the full engineering loop
Five load-bearing principles	Articulates the design decisions that make skills effective: process over prose, anti-rationalization tables, non-negotiable verification, progressive disclosure, scope discipline
The Google DNA	Maps individual skills to specific published Google engineering practices (Hyrum's Law, test pyramid, Beyoncé Rule, 100-line PRs, Chesterton's Fence, trunk-based dev, shift-left, code-as-liability)
How to actually use it / What to steal	Three adoption modes from full install to read-only, plus transferable patterns for human teams
Where this fits in the harness	Positions skills within the broader agent harness architecture alongside AGENTS.md, hooks, tools, and session logs

Key terms

skill Agent Skills
A markdown file with frontmatter containing a workflow — a sequence of steps with checkpoints and exit criteria — that gets injected into an agent's context when relevant; explicitly NOT reference documentation or an essay
process over prose
The design principle that agent instructions must be structured as actionable workflows with verifiable checkpoints, not as expository essays about best practices — because agents will read prose and still skip the actual work
anti-rationalization table Scope Discipline
A table embedded in each skill that pre-pairs common excuses for skipping a workflow step with written rebuttals, designed to defeat the LLM's ability to generate plausible justifications for shortcuts
progressive disclosure Progressive Disclosure
Loading only the skills relevant to the current task phase into context rather than all skills at once, managed by a meta-skill router, to avoid degrading model performance with irrelevant tokens
scope discipline Scope Discipline
The non-negotiable constraint that an agent must touch only what it was asked to touch — no opportunistic refactoring, no TODO-driven rewrites, no adjacent-system changes
senior-engineer scaffolding
The full set of invisible work practices (surfacing assumptions, writing specs, sizing changes, leaving evidence of correctness, refusing to merge unreviewed code) that distinguish reliable engineering from code-pushing
harness Agent Harness
The complete scaffolding around an AI model — prompts, tools, hooks, context policies, skills, session logs — that determines agent behavior; skills are one layer of this

Propositions

explicitestablishedThe default behavior of any AI coding agent is to take the shortest path to 'done,' skipping specs, tests, reviews, scope discipline, and verification.conf: high
supports ←Claude Code: Best practices for agentic coding · p6 — The observation that Claude jumps straight to coding without explicit research-and-plan steps is a concrete instance of Osmani's claim that a coding agent's default is the shortest path to 'done,' skipping planning and verification.
supports ←Agent Skills: Bridging AI and Senior Engineer Practices · p2 — Identical diagnosis of the agent default-to-shortest-path failure mode, compressed into the promotional post.
extends ←Agent Skills: Bridging AI and Senior Engineer Practices · p5 — The essay diagnoses the default-to-done failure mode; this post adds the sharper 'capable junior engineer, not senior' framing as the underlying reason the failure mode exists and recurs.
explicitcorroboratedThe work that separates senior engineers from juniors is mostly invisible — it doesn't show up in the diff.conf: high
supports ←Agent Skills: Bridging AI and Senior Engineer Practices · p1 — Restates the same 'invisible work defines seniority' premise that grounds the full essay's argument.
explicitAgents skip these steps for the same reason juniors do: the reward signal points at 'task complete,' not 'task complete with the design doc and evidence.'conf: high
refinesAgent Skills: Google-Backed AI Coding Agent Workflow · p6 — Osmani supplies the mechanism behind the discipline deficit: the reward signal points at 'task complete', not at completing with evidence and design artifacts.
extendsAgent Skills: Google-Backed AI Coding Agent Workflow · p1 — Adds the causal mechanism for why unconstrained agents skip discipline: the reward signal points at 'task complete', the same reason juniors skip.
explicitA workflow with steps and exit criteria is agent-actionable; an essay on best practices is not.conf: high
refinesAlex Wang's Post · p4 — Wang says repeated instructions should become skills; Osmani specifies what makes a skill actually work — a workflow with steps and exit criteria, not an essay of best practices.
refinesAgent Skills: Google-Backed AI Coding Agent Workflow · p4 — Osmani adds the condition under which markdown instructions transmit judgment: they must be workflows with steps and exit criteria, not essays.
explicitMost 'AI rules' repos fail in practice because their rules are essays, not workflows.conf: high
explicitLLMs are excellent at rationalization — they will produce plausible paragraphs explaining why any particular task doesn't need the usual discipline.conf: high
explicitdevelopedAnti-rationalization tables are pre-written rebuttals to lies the agent hasn't yet told.conf: high
extends ←agent-skills/docs/comparison.md at main · addyosmani/agent-skills · GitHub · p3 — Reframes the anti-rationalization table/Red Flags mechanism (established as agent-skills' core discipline in the earlier Osmani piece) as the project's key comparative differentiator against Superpowers and Matt Pocock's skills.
refines ←Lessons from building Claude Code: How we use skills · p5 — Osmani's anti-rationalization tables are pre-written rebuttals to specific model rationalizations; this doc's broader 'gotchas section' generalizes the same underlying pattern (externalizing hard-won, failure-derived knowledge into the skill) beyond just rationalization-countering to any non-obvious operational fact.
explicitMost engineering decay isn't anyone choosing bad work — it's people accepting plausible-sounding justifications for skipping what they don't feel like doing.conf: high
explicitcorroboratedScope discipline is the single biggest determinant of whether an agent's PR is mergeable or has to be unwound.conf: high
supports ←Agent Skills: Bridging AI and Senior Engineer Practices · p4 — Both single out scope discipline as the single biggest determinant of a mergeable agent PR — same claim, same wording almost verbatim.
explicitA frontier model has read 'Hyrum's Law' in training data but does not apply it when designing your API at 3am — skills make it do so.conf: high
supportsExternalization in LLM Agents: A Unified Review of Memory, Skills, Protocols and Harness Engineering · p2 — Concrete instance of externalization activating latent capability: the model has read Hyrum's Law in training but only applies it when a skill makes it do so.
explicitestablishedEvery token loaded into context degrades performance somewhere, so progressive disclosure is necessary at scale.conf: high
supportsAnatomy of a perfect Openclaw setup · p2 — Both claim context tokens degrade instruction adherence, motivating small instruction files and progressive disclosure of skills.
refines ←Audit your Agent files · p7 — Osmani's earlier piece frames the cost of clutter as token-level degradation requiring progressive disclosure; this piece clarifies the mechanism precisely — an installed skill's body is not loaded until invoked, so the real cost of an unused skill is discovery/confusion, not per-prompt tokens.
extends ←Lessons from building Claude Code: How we use skills · p6 — Osmani's post asserts progressive disclosure is necessary at scale because every token degrades performance; this doc gives the concrete mechanism (treat the whole skill folder — references/, assets/, scripts/ — as context engineering, pointed to from SKILL.md and read on demand).
supports ←Agent Skills · p2 — Osmani asserts every token loaded into context degrades performance somewhere, requiring progressive disclosure at scale; this whitepaper supplies the concrete measurement (150,000 to ~2,000 tokens, a 98%+ reduction) behind that same claim.
supports ←Your AGENTS.md might be a big problem · p4 — Every AGENTS.md rule consumes instruction budget on every request whether relevant or not, confirming that progressive disclosure is necessary.
supports ←When AI Writes the Code, Specifications Need an Exit Strategy · p9 — Shares the token-cost premise behind progressive disclosure — oversized specification material degrades agent attention the same way oversized skill/context material does.
explicitThe longer the agent run, the more senior-engineer scaffolding must be enforced rather than merely suggested.conf: high
implicitThe anti-rationalization pattern is equally valuable for human teams — writing down the lies your team tells itself prevents the same decay.conf: high
implicitGood engineering culture can be encoded in five non-negotiable lines and requires no tooling to adopt.conf: medium

Arguments

Skills (workflow-shaped markdown files) are necessary to make agents produce reliable software

Implicit premises:

Reliable software requires the invisible work, not just the code
Agents cannot discover the need for invisible work through the reward signal alone

Anti-rationalization tables are the most important design innovation for constraining agent behavior

Implicit premises:

The rationalization failure mode is harder to guard against than simple omission because it produces convincing justification
Static rebuttals are sufficient to overcome dynamic rationalization in current models

Progressive disclosure is required for skill-based systems at scale

Implicit premises:

The context window is a scarce resource with diminishing returns
A small router skill can reliably classify tasks into the correct subset

The principles behind agent skills are equally applicable to human engineering teams

Implicit premises:

The failure modes of agents and tired/rushed engineers are structurally identical

Narratives

The agent-as-unsupervised-junior narrative: AI agents are extremely capable but lack the instincts for invisible work, just like junior engineers who haven't yet learned that shipping code without specs/tests/reviews creates incidents.
→ Frames the entire piece and makes the problem emotionally legible to senior engineers
Google engineering culture as portable wisdom: documented practices (Hyrum's Law, Beyoncé Rule, 100-line PRs, Chesterton's Fence) are proven solutions that agents simply fail to apply despite having read about them in training data.
→ Legitimizes the skill approach by grounding it in established, high-status engineering practice

Questions addressed

✅ Why do AI coding agents produce unreliable software by default?
They optimize for 'task complete' and skip the invisible senior-engineer work (specs, tests, reviews, scope discipline) because their reward signal doesn't include it.
✅ What is the right unit of instruction for constraining agent behavior?
Workflows with steps and exit criteria — not essays or reference documentation — because only workflows are agent-actionable.
✅ How do you prevent an LLM from rationalizing its way out of process requirements?
Anti-rationalization tables: pre-written rebuttals paired with common excuses, embedded in each skill.
✅ How do you scale a library of 20+ skills without poisoning the agent's context?
Progressive disclosure via a meta-skill router that activates only the relevant skills for the current phase.
✅ What existing engineering practices should agents be forced to follow?
Google's published practices: Hyrum's Law, test pyramid, Beyoncé Rule, 100-line PRs, Chesterton's Fence, trunk-based dev, shift-left, code-as-liability.
⭕ How reliable is the meta-skill router at classifying tasks correctly?
⭕ What is the empirical impact of skills on defect rates or PR quality?

Gaps

evidentiaryNo empirical evidence for skill effectiveness. The article claims 26K stars as social proof but provides no data on defect rates, PR merge rates, or incident reduction with vs. without skills.
closed byAgent Skills — Supplies exactly the missing empirical data: SkillsBench's benchmark of 84 real-world tasks (19% of skills performed worse than no skill) and Vercel's production analysis (56% non-invocation rate; a skill stripped of instructions scoring lower than no skill at all) — though the data complicates rather than confirms Osmani's optimistic framing, showing poorly-designed skills actively subtract capability rather than being merely inert when unused.
structuralThe meta-skill router is asserted but not explained. How does the 'using-agent-skills' router actually decide which skills to activate? What happens when it misclassifies a task? The reliability of the entire system depends on this component.
closed byAgent Skills — Explains the routing mechanism Osmani's meta-skill router left unexplained: the skill's description field is the entire routing signal the model sees, validated against a 90% trigger-accuracy target using explicit positive/negative test cases scored for testable specificity, clarity, execution fidelity, and rephrasing stability — a concrete, testable account of how activation decisions are made and verified.
argumentativeAnti-rationalization tables assume static excuses. The article treats rationalization as a finite, enumerable set. But LLMs can generate novel justifications not covered by any pre-written table. No discussion of what happens when the agent rationalizes in a way not anticipated by the table.
practicalNo discussion of the cost of false enforcement. Skills add friction. What happens when the skill system forces an agent to write a spec for a one-line typo fix? The article mentions that 'a small bug fix might use three' skills but doesn't address the overhead/accuracy tradeoff.
evidentiaryPortability is claimed but not demonstrated. The article asserts the same SKILL.md works across Claude Code, Cursor, Gemini CLI, Codex, etc. but provides no evidence that different harnesses interpret the same markdown workflow identically.

Closes gaps elsewhere

Agent Skills: Google-Backed AI Coding Agent Workflow · g2 — Identifies the deviation failure mode (LLM rationalization of skipped steps) and prescribes countermeasures: anti-rationalization tables and enforcement rather than suggestion on long runs.

Agent Skills

Structure

Key terms

Propositions

Arguments

Narratives

Questions addressed

Gaps

Closes gaps elsewhere

Related documents