The highest-leverage file in agent tooling right now is a markdown file with three lines of YAML on top. A skill costs its host agent one description line at session start; the full procedure loads only when invoked. Write one for Claude Code and, because Agent Skills became an open standard, the same file runs in Codex, Copilot, Cursor, Gemini CLI, and roughly 40 other products.
And yet half the SKILL.md files I see in the wild fail at the same three places: a name the spec rejects, a description the agent never triggers on, and a body that should have been a description. So I built the Agent SKILL.md Builder: fill in the fields, get a spec-compliant file with live linting, copy it to .claude/skills/<name>/SKILL.md. Free, no sign-up, client-side like everything else here.
The three failure points, and what the linter does about them
1. The name. The spec wants kebab-case, lowercase letters, digits, and hyphens, max 64 characters. The builder validates as you type. Trivial? Sure. But a spec violation here means some hosts silently ignore your skill, and "silently" is the operative word: nothing errors, the skill just never loads, and you conclude skills don't work.
2. The description. This is the one that matters. The description is the only part of your skill the agent sees when deciding whether to load it. It's not documentation; it's a routing rule. A description like "Helps with deployments" never fires. The linter checks for an explicit trigger clause ("Use when deploying to production or preparing a release...") and warns when the description is too short to route on, or over the 1024-character cap. If you take one thing from this post: write the description as the answer to "when should the agent reach for this?", not "what is this?"
3. The body. Two failure modes, both flagged. A body under ~40 words shouldn't be a skill at all: if it fits in the description, it's config, not procedure. A body pushing past ~1500 words should move its bulk into reference files inside the skill folder, linked from SKILL.md, so the always-relevant instructions stay tight. The linter also flags anything that looks like a hardcoded credential, because people genuinely do paste API keys into skill files, and a skill gets shared far more casually than a .env.
There's an allowed-tools picker too: omit it and the skill inherits the session's tools, or restrict a risky procedure to read-only tools, which pairs naturally with the guardrail thinking from the hooks post.
Why skills earn their place in your stack
The economics, which I laid out in MCP vs. skills: an MCP server ships dozens of tool schemas into your context at session start whether you need them or not; a skill costs one line until the moment it's needed. That's why the context auditor so often ends with the recommendation "demote this to a skill." Skills are the cool-storage tier of context engineering: procedures like deploy flows, incident runbooks, and migration guides that are gold when relevant and dead weight the rest of the time.
The portability is what changed the calculus this year. A skill you write once is now infrastructure that follows your team across agent products, which means the hour you spend writing a good one amortizes across every tool your team touches. The catch is that portability runs through spec compliance, and spec compliance is exactly the boring part humans get wrong on Friday afternoon.
So the builder does the boring part. You bring the only thing that matters: a procedure worth encoding. Build one, start with your deploy checklist or your incident runbook, and put the description through the "when should the agent reach for this?" test before you ship it.