10 Best Practices for Writing Agent Skills (That Trigger)

Short answer: write each agent skill for one job, give it a description that says what it does and when to use it, keep SKILL.md short and move detail into linked files, and test it with and without the skill before you rely on it. The ten practices below come from Anthropic's skill authoring guide, the agentskills.io open standard, and the OpenAI Codex and Cursor docs, checked on Oct 30, 2026.

New to skills? Start with How to Create Your Own Agent Skill. For exact frontmatter fields and limits, see our SKILL.md Template post.

1. Give each skill one job

OpenAI's skills guide puts it plainly: keep each skill focused on one job. agentskills.io compares scoping a skill to scoping a function. Too narrow, and several skills must load for one task. Too broad, and the skill is hard to activate precisely. Its example: querying a database and formatting the results is one coherent unit; adding database administration is too much.

Name it after the job. Anthropic suggests gerund names such as processing-pdfs or analyzing-spreadsheets, and warns against vague names like helper, utils or documents.

2. Write a description that triggers

This is the practice that decides whether a skill is ever used. At startup, agents load only each skill's name and description; the full SKILL.md is read only when a request matches. agentskills.io says the description carries the entire burden of triggering.

Say what it does, then when to use it. Anthropic asks for both, written in the third person, because the description is injected into the system prompt. Avoid 'I can help you...' and 'You can use this to...'. agentskills.io adds: describe what the user is trying to achieve rather than the skill's internals, and list contexts where the skill applies even when the user doesn't name the domain.

Bad: Helps with documents.

Bad: Processes data.

Bad: I can help you process Excel files.

Good (Anthropic's example): Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

Good (agentskills.io's example): Analyze CSV and tabular data files: compute summary statistics, add derived columns, generate charts, and clean messy data. Use this skill when the user has a CSV, TSV, or Excel file and wants to explore, transform, or visualize the data, even if they don't explicitly mention 'CSV' or 'analysis.'

Front-load the key use case and trigger words. OpenAI's guide says exactly that, and the limits explain why. Claude Code caps each entry in its skill listing at 1,536 characters and, when you have many skills, drops descriptions to fit a budget of 1% of the context window. Codex limits its initial skills list to 2% of the context window. The spec allows 1,024 characters; Anthropic's claude.ai help page lists 200.

Mind the edges. If the skill fires on the wrong requests, make the description more specific or say what it does not do. For a skill you only ever want to run by hand, Claude Code and Cursor both support disable-model-invocation: true. And don't expect a skill to fire for trivial requests: agentskills.io notes that agents usually consult skills only for tasks they can't handle alone.

3. Build it from a real task, not general knowledge

agentskills.io calls this out as a common pitfall: asking an LLM for a skill without domain context produces generic advice like 'follow best practices'. Instead, do the task once with the agent, correcting it as you go, then turn the steps that worked and the corrections you made into the skill. Runbooks, style guides, review comments and past incident write-ups are good source material. Anthropic describes the same loop: one Claude session helps you write the skill, a fresh one tests it.

It's also worth checking whether someone has already published the skill you need. Search Skill Store 33 by task, read the SKILL.md, and adapt it to your conventions.

4. Only write what the agent doesn't already know

Anthropic's guide starts from 'Claude is already very smart'. Its example: a 50-token instruction to use pdfplumber beats a 150-token explanation of what PDFs are. agentskills.io suggests one test per line: would the agent get this wrong without it? If not, cut it. Two more rules from Anthropic: avoid time-sensitive notes like 'before August, use the old API', and use one term for one thing throughout.

5. Keep SKILL.md under 500 lines and link out

Anthropic and Claude Code's docs both say to keep SKILL.md under 500 lines; agentskills.io adds 5,000 tokens. Move detailed material into separate files, link each one directly from SKILL.md (Anthropic says one level deep, because nested references may only be partly read), and add a table of contents to any reference file over 100 lines. Most importantly, say when to load each file. agentskills.io's example: 'Read references/api-errors.md if the API returns a non-200 status code' is better than 'see references/ for details'.

6. Match strictness to how fragile the task is

Both Anthropic and agentskills.io describe degrees of freedom. Give the agent latitude where many approaches work, such as a code review. Be exact where one mistake is costly, such as a database migration: 'Run exactly this command. Do not add flags.' And offer a default rather than a menu: 'Use pdfplumber; for scanned PDFs use pytesseract' beats a list of five equal libraries.

7. Show an example or template instead of describing the output

Agents pattern-match well against concrete structures, says agentskills.io, so a template is more reliable than a prose description of a format. Anthropic recommends input and output pairs where style matters, as with commit messages. Keep short templates inline; put long ones in an assets or examples folder and reference them.

8. Add gotchas, a checklist and a check-your-work step

agentskills.io calls gotchas the highest-value content in many skills: concrete facts that defy reasonable assumptions, such as 'the users table uses soft deletes'. Keep them in SKILL.md, and add a new one each time you have to correct the agent. For multi-step work, give a checklist the agent can track. For quality-critical output, add a loop: do the work, check it against a validator or reference, fix, repeat. Anthropic says this pattern greatly improves output quality.

9. Use scripts only for steps that must be exact

OpenAI's guide says to prefer instructions over scripts unless you need deterministic behaviour or external tooling. When you do bundle a script, Anthropic says it should handle its own errors rather than leave them to the agent, and SKILL.md should say whether to run it or read it. Cursor asks for self-contained scripts with helpful error messages. A good signal from agentskills.io: if the agent writes the same helper code on every run, bundle it. If the skill calls MCP tools, Anthropic recommends fully qualified names such as ServerName:tool_name.

10. Test with and without the skill, then iterate

Anthropic recommends building evaluations before writing extensive documentation: at least three scenarios, a baseline without the skill, and tests on every model you plan to use, since what works for Opus may need more detail for Haiku. Claude Code's docs make a useful distinction: a skill triggering tells you Claude found it, not that it did what you intended, so measure both.

For triggering, agentskills.io suggests about 20 realistic prompts, half that should trigger and half near-misses that shouldn't, each run three times. For output, start with 2 or 3 test cases and compare with and without the skill. In Claude Code, the skill-creator plugin (/plugin install skill-creator@claude-plugins-official) runs both loops for you.

FAQ

How long should a skill description be?

A sentence or two, ideally under 200 characters if you'll upload it to claude.ai. The open spec caps it at 1,024 characters, and Claude Code truncates each listing entry at 1,536, so put the key use case first.

Should a skill description say 'I', 'you' or neither?

Neither. Anthropic recommends the third person ('Processes Excel files and generates reports'), because the description is injected into the system prompt. Follow it with a 'Use when...' clause.

How long should a SKILL.md file be?

Under 500 lines. agentskills.io also suggests under 5,000 tokens. Move detailed material into reference files and say in SKILL.md when to read each one.

Why does my skill trigger on the wrong requests?

The description is too broad. Make it more specific, say what the skill does not cover, or set disable-model-invocation: true in Claude Code or Cursor so it only runs when you call it.

Related guides: Skill Not Triggering, SKILL.md Template, and 5 checks before you approve a SKILL.md.

Let your agent search Skill Store 33

Sources

Anthropic, Skill authoring best practices, https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices (read Oct 30, 2026)

Anthropic, Extend Claude with skills (Claude Code docs), https://code.claude.com/docs/en/skills (read Oct 30, 2026)

Anthropic Help Center, How to create custom skills, https://support.claude.com/en/articles/12512198-creating-custom-skills (read Oct 30, 2026)

Agent Skills, Best practices for skill creators, https://agentskills.io/skill-creation/best-practices (read Oct 30, 2026)

Agent Skills, Optimizing skill descriptions, https://agentskills.io/skill-creation/optimizing-descriptions (read Oct 30, 2026)

Agent Skills, Evaluating skill output quality, https://agentskills.io/skill-creation/evaluating-skills (read Oct 30, 2026)

OpenAI, Build skills (ChatGPT and Codex), https://learn.chatgpt.com/docs/build-skills (read Oct 30, 2026)

Cursor, Agent Skills, https://cursor.com/docs/context/skills (read Oct 30, 2026)

This article was created with the help of AI (AI-Assisted). Every config key and command was checked against the official docs in the Sources list. ReadyAI is accountable for the content.

Keep reading