XNews

Addy Osmani's Agent Skills: Spec Writing and Frontend Anti-Patterns

Addy Osmani's Agent Skills: Spec Writing and Frontend Anti-Patterns

Addy Osmani's 89.4K-star 'agent-skills' open-source project introduces a specification for structuring AI agent instructions. The core is SKILL.md, the only required file per skill, with optional scripts/ and references/ directories. Key design rules include: a frontmatter description that answers 'what' and 'when' without summarizing the process to prevent shortcutting; a 'Common Rationalizations' section that preempts AI excuses for skipping steps; and a 'Verification' section requiring evidence-based exit criteria. Scripts must output JSON to stdout. The project makes a conscious tradeoff to store shared references at the root for a single source of truth, sacrificing per-skill portability. Six writing principles are outlined: process over knowledge, specificity, evidence over assumptions, anti-rationalization, progressive disclosure, and token awareness. A companion analysis identifies eight frontend UI anti-patterns common in AI-generated interfaces: default purple/indigo colors, excessive gradients, uniformly large border-radius, generic hero sections, lorem ipsum placeholder text, oversized padding, uniform card grids, and heavy shadows, each explained by their prevalence in training data and their negative impact on design quality and performance.

Key insights

AI Instructions Must Preempt Rationalizations to Be Effective

The 'Common Rationalizations' section in SKILL.md is the most innovative feature, explicitly listing the excuses an AI agent might use to skip steps and providing counter-arguments. This design acknowledges that language models, like humans, will attempt to rationalize shortcuts. By blocking these paths preemptively, the specification shifts from assuming compliance to engineering behavioral reliability. This approach draws from human behavioral tools like checklists and discipline sheets, adapting them directly to prompt engineering for more predictable AI agent execution.

AI-Generated Frontend Code Suffers from Eight Identifiable Visual Anti-Patterns

A detailed breakdown of AI-generated UI code reveals eight recurring anti-patterns: default purple/indigo color schemes, excessive gradients, uniformly large border-radius, template-like hero sections, placeholder text, oversized padding, uniform card grids, and heavy shadows. These patterns stem from their overrepresentation in training data, such as Tailwind examples and Stripe-style landing pages. The negative impact includes loss of brand differentiation, damaged user trust, masked layout bugs from placeholder text, and performance degradation from shadow rendering. The analysis advocates for intentional, design-system-driven choices over statistical defaults.

Agent Skill Structure Enforces Token Economy Through Progressive Disclosure

The specification mandates a strict token economy by design. SKILL.md is limited to 500 lines, with detailed information placed in scripts or a single layer of reference files that are loaded on-demand. The rules require scripts to output structured data to stdout, as script execution itself does not consume context, but inline code blocks incur a token cost with every load. This design treats prompt context as a billable resource, ensuring that every paragraph in the main skill file must justify its token cost by directly contributing to behavior change.

Shared References Involve a Documented Tradeoff Between Portability and Consistency

The project consciously places shared testing, security, and performance checklists in a root references/ folder instead of duplicating them within each skill’s directory. This prevents the inevitable drift of multiple copies. However, the specification openly documents the tradeoff: this approach sacrifices the ability to independently install a single skill with all its dependencies. The tradeoff is logged and tracked as issue #361, demonstrating a deliberate engineering documentation practice of acknowledging debt rather than ignoring it.

Source posts