Why AI Coding Agents Need Skills

The word "need" in the title is not marketing. Between 2025 and 2026, Cursor, Claude Code, Codex, Gemini CLI, and others converged on the same Skill directory convention. The community has produced a wave of installable packages: some manage ADHD-friendly replies, others manage 39 types of editorial diagrams. What they share: process knowledge has moved from chat history into version control.

Why Skills are needed now

Early Coding Agent usage was simple: system prompt plus user-pasted long instructions. That works for individuals on short tasks. As team scale goes up, three hard problems appear:

• Context budget. Deployment steps, design systems, security gates, and commit conventions can't all be injected in full every turn.
• Trigger precision. Diagram specs are only needed when drawing architecture diagrams; loading 40 diagram types while fixing a typo is waste.
• Portability. The same handbook needs to run in Cursor desktop, Claude Code terminal, Codex, and even custom Agents — it can't be locked to any one product's Rules format.

Skills address all three at once: a short description acts as the routing key; the body and references/ expand on demand; the directory layout aligns with an open standard and the folder itself is the deliverable.

What a Skill is: folder + SKILL.md

Per agentskills.io and Cursor docs, a Skill is at minimum:

my-skill/
  SKILL.md          # required: YAML frontmatter + Markdown steps
  references/       # optional: long docs, read during execution
  scripts/          # optional: executable scripts, output into context
  assets/           # optional: templates, sample diagrams

The frontmatter at the top of SKILL.md is a routing contract, not decoration:

---
name: my-skill
description: What it does. When to use it.
disable-model-invocation: false
---

# Body steps
...

Discovery paths vary by product but the convention has converged: project-level is commonly .cursor/skills/ or .agents/skills/; user-global is commonly ~/.cursor/skills/. Nested directories (e.g. apps/web/.cursor/skills/) can automatically scope a Skill to a subtree.

Three-tier loading: discover → activate → on-demand

This is the core difference between Skills and "write everything into Rules."

1. Discovery: At session start, the Agent sees only each Skill's name + description.
2. Activation: When the task description matches, or the user types /skill-name / @skill-name, the full SKILL.md body is loaded.
3. On-demand: During execution, references/ is read and scripts/ are run; script output goes into context while the source is not typically injected in full.

A broken description is a broken route. A good description answers two things at once: what it does, and what signals should trigger it.

Case 1: i-have-adhd — output shape is a skill too

ayghri/i-have-adhd is deliberately narrow: it doesn't teach the Agent how to write code, it only specifies how to speak. Its description states: lead with the next action, number multi-step tasks, restate status across turns, suppress tangents, give concrete time estimates, keep completed items visible. It defaults to disable-model-invocation: true and is opened with /i-have-adhd until the user says stop.

Among its ten rules, the ones most valuable for Coding Agents are:

• Lead with the next action, no preamble.
• Multi-step tasks must be numbered; list cap around 5 items.
• Restate current status each turn to reduce "where were we."
• State errors as facts, no apology stacking.

It proves one thing: Skills don't only serve "domain expert handbooks" — they also serve "interaction contracts." Once output shape is version-controlled, a team can share a single low-friction conversation style rather than everyone rewriting their own system prompt.

Case 2: diagram-design — domain handbooks don't belong in Rules

cathrynlavery/diagram-design goes to the opposite extreme: nearly 40 editorial-grade diagram types (architecture, sequence, state machine, ER, Sankey, Wardley…), output as standalone HTML/SVG, explicitly rejecting "just throw a Mermaid layer on top and call it done." It also requires checking brand tokens before first output, and loads layout syntax and semantic patterns from references/ by diagram type.

If you wrote this handbook in full into Always-on Rules:

• Sessions that fix a README typo carry the full diagram spec;
• Token costs rise and the actually relevant repo context gets squeezed out;
• When diagram types are updated, the Rules file becomes an unmaintainable monolith.

Made into a Skill: startup registers only a long description (listing diagram types and trigger conditions); only when the user says "draw a deployment diagram" does it activate; layout references for the specific type are read on demand. This is the engineering evidence that "Agents need Skills" — not because they can't draw diagrams, but because the knowledge required to draw them well already exceeds the reasonable size of a persistent prompt.

Skills vs Rules vs MCP

All three are often used together: a Rule locks "never commit secrets"; a Skill specifies "verify these 8 steps before releasing"; MCP provides the "create GitHub Release" tool. Skills don't replace Schema — they only tell the Agent when and in what order to fill that Schema.

From two Skills to the agentskills.io ecosystem

i-have-adhd and diagram-design represent two poles: interaction contract vs domain depth. Between them, a full distribution chain has emerged:

• Open standard. agentskills.io defines frontmatter, body, and discovery paths; multiple Agent products implement the same folder convention.
• Editors and CLIs. Cursor scans the skills directory at startup; Claude Code, Codex, Gemini CLI, OpenCode, and others provide plugin mechanisms or directory conventions.
• Installers. Community tools like npx skills add …, plugin marketplaces, and skilldrop turn Git repos into installable packages.
• Composition. Discipline Skills (commit, review, failure recovery) and engineering lifecycle Skills (spec, test, release) are beginning to declare Pair with relationships.

The sign of a mature ecosystem is not "number of Skills" but: the same folder can be discovered, routed, and progressively loaded by different runtimes without rewriting a prompt for each product.

The contract layer: description, frontmatter, and JSON

For readers of this site, Skills and Structured Output share the same engineering intuition: write the interface clearly first, then let the model fill it in.

1. Frontmatter is a machine-readable discovery contract (YAML — essentially structured fields).
2. description is the natural-language version of a routing Schema: a match failure means the wrong tool was selected.
3. If a Skill drives MCP / Function Calling, the actual input and output should still be JSON Schema; the Skill body only writes steps and acceptance criteria — don't bury field types inside prose.

A sample "Skill metadata" object that is ready to be validated (illustrative — not an official enforced schema):

{
  "name": "diagram-design",
  "description": "Create branded architecture and flowchart diagrams as standalone HTML/SVG.",
  "disable_model_invocation": false,
  "triggers": ["architecture diagram", "sequence diagram", "draw.io redraw"],
  "loads": ["SKILL.md", "references/style-guide.md"]
}

You can use this site's tools to convert that object into a Schema first, then decide which fields belong in the frontmatter and which in the body. The "skill catalog" on the Agent side will eventually look like a tool catalog: short descriptions always resident, long handbooks on demand.

How to write, install, and trigger

1. Create .cursor/skills/your-skill/SKILL.md (team-shared) or ~/.cursor/skills/... (personal global).
2. Write clear name + description; include both capability and trigger conditions in the description.
3. Keep the body short: steps, anti-patterns, when to stop. Long tables go in references/, referenced with relative links.
4. For destructive or billing-sensitive flows, set disable-model-invocation: true to enforce slash-command triggering.
5. Commit to Git. Restart / reload the Agent to let the discovery layer rescan.
6. Triggering: description match for auto-routing, or /your-skill / @your-skill in chat.

If you already have Rules or slash commands, consider migrating them to Skills first, then removing the duplicate persistent prompts — after migration, verify with an unrelated task: the old handbook should no longer appear in context.

Acceptance testing in JSON Toolbox

1. Paste Skill metadata or tool input samples into JSON Format to confirm they parse.
2. Use JSON → Schema or Structured Output to generate a validation contract.
3. If the Skill drives MCP / Function calls, run them through MCP Tool and Function Calling respectively — don't duplicate the same fields twice.
4. Validate a second set of real returns with Schema validation; when they don't align with expectations, use JSON Diff.

All data is processed in the browser and never uploaded to a server.

FAQ

What is the difference between an Agent Skill and a Cursor Rule?

Rules are more persistent; Skills only expose their index by default and load on match. Skills are also easier to reuse across products with the same folder.

What does the i-have-adhd Skill actually do?

It constrains output shape: next action first, numbered steps, state restatement, suppressed tangents, time estimates, short lists. Typically opened explicitly with /i-have-adhd.

Why is diagram-design evidence that Skills are needed?

Nearly 40 diagram types plus brand and semantic references — a volume far beyond what persistent Rules can hold. Progressive loading means it only expands during diagramming tasks.

Are Skills and MCP / Function Calling the same thing?

No. A Skill is a handbook; MCP / Functions are tools. Tools still need JSON Schema; the Skill specifies when and in what order to call them.

How do I add a Skill to a project?

Place a SKILL.md in the skills directory, write name / description and steps, commit to the repo, then reload the Agent. Sensitive flows can be restricted to slash-command trigger only.

Summary

AI Coding Agents need Skills because their capability boundary has expanded from "single-turn generation" to "repeatable professional processes." Persistent Rules can't carry the volume of domain handbooks; pure chat prompts can't be versioned or shared. i-have-adhd shows that interaction contracts can be skill-ified; diagram-design shows that deep domain knowledge must be progressively loaded; agentskills.io turns a folder into a cross-product standard component. For developers, the next step is not piling on more prompts but collecting processes into SKILL.md and tools into Schemas — short index, hard contract, body on demand.

Related tools