Authoring Agent Skills

This skill is the operating procedure for writing skills that comply with the Agent Skills specification (agentskills.io) and follow Google's Agent Skills whitepaper guidance on portable skill design. It covers the SKILL.md format, frontmatter constraints, naming, the description field as a routing mechanism, progressive disclosure, bundled resources, and the evaluation gates a skill must pass. The whitepaper's core discipline: a skill without a test is a hope, not a capability.

When to use

• Creating a new skill folder from scratch, from a runbook/doc, or from a successful agent trace.
• Reviewing, refactoring, or debugging an existing SKILL.md (wrong triggering, bloated body, vague description).
• Deciding where content belongs: skill vs AGENTS.md vs MCP.

Do NOT use this skill for:

• One-off task instructions — just do the task; a skill is for reusable workflows.
• Project-wide conventions (stack, build commands) — those belong in AGENTS.md, which is always loaded; skills load on demand. Vercel's production analysis found a passive AGENTS.md index of project conventions hit a 100% pass rate vs a 53% baseline — global context belongs there, skills are for narrow, action-specific workflows.
• Connecting the agent to an external system (Drive, Salesforce, an API) — that is an MCP server's job. Skills and MCP compose: the skill is know-how, MCP is reach. Do not reinvent MCP as scripts.

Rules

Structure (spec-normative)

1. A skill is a directory containing, at minimum, a SKILL.md. Optional conventional directories: scripts/ (executable code), references/ (documentation loaded on demand), assets/ (templates, images, data files). Any additional files are allowed.
2. SKILL.md = YAML frontmatter + Markdown body. Required frontmatter fields: name, description. Optional: license, compatibility (1-500 chars; only include if the skill has real environment requirements — most skills do not need it), metadata (string-to-string map; use reasonably unique key names), allowed-tools (space-separated string of pre-approved tools, e.g. Bash(git:*) Bash(jq:*) Read; experimental, support varies).
3. name: 1-64 characters; only lowercase a-z, 0-9, and hyphens; must not start or end with a hyphen; no consecutive hyphens (--); must match the parent directory name. PDF-Processing, -pdf, pdf--processing are all invalid.
4. description: 1-1024 characters, non-empty. Must describe both what the skill does AND when to use it, with specific keywords agents can match against tasks.
5. Validate before shipping: skills-ref validate ./my-skill (reference library at github.com/agentskills/agentskills, skills-ref) checks frontmatter validity and naming conventions.

Progressive disclosure (the token budget)

6. Design for three loading levels: (1) metadata — name + description, ~100 tokens, loaded at startup for ALL skills; (2) instructions — full SKILL.md body, loaded only on activation, keep under 5,000 tokens (spec recommendation); (3) resources — files in scripts/, references/, assets/, loaded only when required. Scripts execute without their code entering the token window.
7. Keep SKILL.md under 500 lines (spec). Whitepaper rule of thumb: if the SKILL.md is getting long, the next paragraph belongs in references/, not the body. Bodies over 5,000 words are a skill smell — probably two skills, or reference material.
8. Never evaluate or budget a skill in isolation: production agents co-load 5 to 15 skills simultaneously. A body that exceeds 5,000 tokens may work alone but causes context rot when co-loaded.
9. Reference other files with relative paths from the skill root, kept one level deep from SKILL.md. Avoid deeply nested reference chains. Keep individual reference files focused — smaller files mean less context per on-demand load.

The description field (the routing algorithm)

10. Spend disproportionate time here: the description is the ONLY thing the model sees when deciding whether to load the skill. A vague description means an unused skill.
11. Front-load trigger keywords ("Generate a commit message…", not "This skill helps with…"). State what it does, when to use it, and when NOT to use it — the anti-trigger clause prevents over-triggering. Be pushy in wording if the model under-triggers.
12. Size: ≤1024 chars in YAML (spec hard limit); the whitepaper's practical guidance is that most authors aim for roughly 50 words.
13. Write it to pass four checks (industry-standard target: 90% trigger accuracy): testable specificity (you can write 3 positive and 3 negative triggers), clarity (ambiguous queries don't overlap adjacent skills), execution fidelity (describes actual performance, not aspirational behavior), rephrasing stability (routes consistently across phrasings).

Naming

14. Prefer gerund form: processing-pdfs, not pdf-processor; managing-databases. Avoid generic names (helper, utils, tools, data), vendor prefixes (claude-*, gemini-*, anthropic-*), and internal jargon outsiders won't recognize.
15. Note a source conflict: the whitepaper suggests snake_case directories with kebab-case skill names; the spec requires name to match the parent directory name and allows only lowercase alphanumerics and hyphens. For spec compliance, use kebab-case for both and keep them identical.

Body content

16. The spec places no format restrictions on the body; recommended sections: step-by-step instructions, examples of inputs and outputs, common edge cases. The whitepaper's template adds: When to use, When NOT to use, Workflow, Examples, Output format, Anti-patterns to avoid.
17. One skill, one job. If you cannot describe the skill in one sentence, it is two skills — decompose before writing. If the description needs "and" between unrelated capabilities, split it.
18. Run the task yourself first. Real failure produces signal; speculation produces noise.
19. Give the reason, not just the rule. Models generalize to edge cases when they understand why an instruction exists. If you are typing "ALWAYS" or "NEVER" in caps, stop and explain the rationale instead — models learn to ignore capitalized imperatives (the whitepaper calls this accumulating Context Debt).
20. Every line must earn its place. Keep gotchas, exact commands, business logic, anti-patterns. Cut boilerplate the model already knows ("always validate output").
21. Make instructions verifiable: if the agent can't tell whether it followed a rule, the rule is too vague.

Bundled resources

22. Bundle what repeats: deterministic work (parsing, math, formatting) belongs in scripts/, not in prose instructions — "Shift Intelligence Left" by pushing logic into standard, testable scripts. Replace negative LLM instructions with deterministic constraints that make invalid actions impossible.
23. Scripts must be self-contained or clearly document dependencies, include helpful error messages, and handle edge cases gracefully.
24. Knowledge only relevant once the skill is running (domain principles, definitions, edge-case handling) goes in references/; templates and schemas go in assets/.

Evaluation and portability

25. Practice Evaluation-Driven Development: write three JSON evaluation cases (Input, Expected Tools, Expected Output) BEFORE drafting the SKILL.md body. This forces a functional spec upfront and surfaces description ambiguities early.
26. Test both directions: prompt where the skill SHOULD trigger and confirm it fires; prompt where it should NOT and confirm it stays quiet. Poorly designed skills actively subtract capability — SkillsBench (2025) found 19% of 84 real-world tasks performed worse with a skill than without; Vercel measured a 56% non-invocation rate for skills expected to fire.
27. Gate skills through authority tiers: Read-Only (LLM-as-Judge eval; 90% trigger accuracy) → Draft-Only (golden dataset of 20+ cases; human approval) → Action-Allowed (full adversarial red-teaming; sustained pass^k across runs; human sign-off).
28. Agent-drafted skills (meta-skill output) enter the library at the draft tier regardless of confidence, and a human reviews the diff. An un-reviewed agent-drafted skill is often worse than no skill at all. Don't start with meta-skills; get the manual authoring loop working first.
29. Keep skills portable: do not tie a skill to one runtime, hard-code paths, or embed secrets. The format is shared across tools but install paths, activation rules, and per-tool details (allowed-tools whitelisting, security gates) are not — check the target tool's docs; a shared .agents/skills/ project-root convention is emerging.
30. Treat skills as code: version them, pin them, review them in PRs. Domain experts own domain skills.

Checklist

Copy-paste before shipping any skill:

• name: 1-64 chars, lowercase a-z/0-9/hyphens only, no leading/trailing/consecutive hyphens, matches directory name
• description: 1-1024 chars; states what it does + when to use + when NOT to use; trigger keywords front-loaded
• 3 positive and 3 negative trigger phrases written and tested; target 90% trigger accuracy
• Three JSON eval cases (Input, Expected Tools, Expected Output) written before the body was drafted
• SKILL.md body under 500 lines / under 5,000 tokens; overflow moved to references/
• Deterministic, repeated work bundled in scripts/ (self-contained, helpful errors); templates in assets/
• File references are relative paths, one level deep from SKILL.md
• Frontmatter validates: skills-ref validate ./my-skill
• Eval coverage — all four satisfied, else the skill stays at draft tier: Trigger (positive AND negative cases), Execution (correct outputs across representative inputs), Regression (zero drops in the existing library suite), Token budget (co-loaded with 5-15 skills without degrading unrelated turns)
• Deployment: scripts have unit tests passing in CI; eval suite passes in CI with min-pass threshold; security scan clean (no secrets, no untrusted deps); description reviewed by someone other than the author; cross-tool install paths tested if shipping publicly

Anti-patterns

• Vague descriptions like "Helps with PDFs" or "a helpful skill for…" — rewrite to name the trigger, the inputs, and the output.
• SKILL.md bodies over 5,000 words — split the skill or move detail to references/.
• Hard-coded paths or secrets.
• "Always do X" global rules inside a skill — those belong in AGENTS.md.
• Installing untrusted third-party libraries or skills without scanning; unpinned skill dependencies.
• Reinventing MCP as scripts.
• Skill smells (revise on sight): two domain teams could plausibly own it; you can't write three test cases for it; it references no other resource (probably a long instruction that belongs in the system prompt); you keep adding "edge cases" sections (each edge case probably wants its own skill).
• Bulk-generating a library: the whitepaper warns that pointing an agent at an empty folder and asking it to fill it with skills is the fastest way to a bad library — build one workflow at a time.
• Over-engineering SKILL.md for one specific model — ruins portability; audit triggers across multiple model families instead.

Source

• Agent Skills Specification — https://agentskills.io/specification — 2025-12-18
• Agent Skills (Google/Kaggle whitepaper, Singhal, Hernandez Larios, Das, Nigam, Kolan) — https://www.kaggle.com/whitepaper-agent-skills — May 2026

Distilled from the official document(s) above on 2026-08-12. If this skill and the source disagree, trust the source.