Writing Agent Skills

When writing the skill, one rule overrides all others:

• [NEVER] write meta references, self-thoughts, or anything that isn't an instruction
• [ALWAYS] keep it simple stupid (KISS principle)
• [Always] short and easy to follow directives

1. Basic skill structure

A skill is a folder: SKILL.md (required) + optional scripts/, references/, assets/, evals/. Three loading layers:

• Always loaded: name + description frontmatter.
• Loaded on trigger: the SKILL.md body.
• Loaded on demand: files under scripts/, references/, assets/.
• Never loaded during normal use: evals/ holds the skill's own evaluation/test suite.
• [ALWAYS] use relative paths for referencing these files (ie. "read references/first.md")
• To build an eval suite for a skill, load and follow evaluating-agent-skills (this skill defines the writing and structure standards only).

2. Description

The description is the trigger. Write both the what the skill does and the when to use it. Also add a negative case: when NOT to trigger. For example:

• {BAD} "Helps with documents" / "API helper"
• {GOOD} "Create, edit, and analyze .docx files; tracks changes, comments, formatting, text extraction. Triggers whenever the user is working with docx files. [DO NOT] trigger when working with any other file types"

If a skill is only ever invoked by explicit name (never auto-triggered), say so plainly in the body; the description then only needs to be accurate, not optimized for triggering.

3. Writing format

• Use directives ("[Always] use X")
• Be direct, less is more
• Lead with a short example over a long explanation.
• When a rule needs a reason, give one short line, don't pad it into a paragraph.
• KISS principle: simplicity is the primary goal, not a side effect; easier to read for both humans users and agents.
• Write impersonally, third person neutral. Skills are written for LLM agents to use directly.
• Highlight keywords with ** and/or [] brackets to increase the weight of the instruction.
  • Enforcement keys: [ALWAYS], [MUST], [DO], [FOLLOW]
  • Negative rules: [NEVER], [DO NOT]
  • Combine ** and [] for an even stronger petition; other verbs are allowed too.
• Add variance to both sentence length and structure; uniform rhythm reads as generated text.
• [NEVER] use AI-tell vocabulary:
  • EN: delve, tapestry, realm, landscape, journey, nuanced, multifaceted, transformative, pivotal, robust, seamless, invaluable, moreover, additionally, notably, crucially, "not only... but also", "in conclusion", "in summary", "paving the way", "shed light on"
  • ES: cabe destacar, es importante señalar, en el panorama actual, juega un papel fundamental, sin lugar a dudas, no obstante, asimismo, por otra parte, en conclusión, en resumen, en definitiva, desafíos, perspectivas futuras, multifacético, transformador
• [NEVER] use em-dashes as an emphasis shortcut; connect ideas with periods, commas, or semicolons.
• [NEVER] close with formula phrases ("in conclusion", "en conclusión") or add meta-comments about the text itself ("as a language model", "espero que esto sirva").

4. Keep it lean

Every line carries weight: it costs tokens, affects model behavior, and has a maintenance cost.

• Body of SKILL.md under ~500 lines.
• Split multi-topic skills into separate references/*.md files the agent loads only when needed.
• If a reference file exceeds 500 lines, put a table of contents with line hints at the top.
• If the skill is multi-staged, put each stage in its own file under a stages/ folder (a convention of some skills, not part of the standard layout) and reference them from the main SKILL.md with relative paths.

5. Set the right level of freedom

Describe the goal, not a rigid step sequence, unless order genuinely matters:

• {BAD} "Step 1: read the file. Step 2: parse JSON. Step 3: update the port. Step 4: write it back."
• {GOOD} "Update the database port in the config file to the value the user specifies."

Prefer constraints over procedures: "Always run tests before opening a PR. Never push to main", not a scripted checklist of git commands.

If exact step order is truly critical (fragile if step 3 runs before step 2), that's not a skill problem: write a script and have the skill call it. Scripts live in scripts/*.*

6. Naming the skill

• Propose 3 alternatives to the user; [MUST] present your recommendation, [NEVER] pick one or apply the name without the user's choice
• Name in frontmatter and directory [MUST] be equal (eg. my-test-skill/SKILL.md → "name: my-test-skill")
• Use kebab-case: lowercase letters and hyphens

7. Keeping vs retiring a skill

Retire a skill when its description no longer fits the useful routing window, or its capability has been covered by another skill or by the base model. Retirement means deleting the skill's directory and cleaning up dangling cross-references in other skills. [NEVER] leave a stub folder with no real description behind.

Source

Distilled from Philipp Schmid, "8 Tips for Writing Agent Skills", https://www.philschmid.de/agent-skills-tips (published 2026-04-13). Read the original for the full prose, examples, and the linked companion piece on evaluating skills.