How to Write a Truly Usable and Effective Agent Skill

What an Agent Skill Is

Skill is a form of structured prompt engineering: a standard file (usually a folder with SKILL.md) that packages domain knowledge, operation steps, code examples, verification commands and security constraints so that an LLM can load and execute the capability on demand.

Core Components

The three core parts are:

Instructions – what the model should do.

Context – project background and team conventions.

Tools – scripts or templates the model can invoke.

These together form an “operation manual” for the model.

Principle 1 – Progressive Disclosure

Load the Skill in three layers to respect token budgets:

Level 1: metadata (≈100 tokens) containing the description.

Level 2: the main SKILL.md body (≤500 lines, ≤5 000 tokens) loaded only when triggered.

Level 3: referenced scripts or resources, loaded on‑demand with no hard limit.

References that are rarely needed should be placed in a references/ sub‑folder and the main file should indicate when to read them (e.g., “if the API returns a non‑200 status, read references/api-errors.md ”).

Principle 2 – Lock Down Deterministic Logic in Scripts

Anything that must be consistent across runs—fixed CLI commands, SQL templates, naming rules, checklists—should be encoded in a script or hard rule rather than left to the model’s judgment. The model then only explains why a check failed or suggests the next step.

Quote: “Fragile, consistency‑required items are locked in code; flexible, reasoning‑required items stay with the model.”

Principle 3 – Write “How” Not “What”

A good Skill provides procedural guidance: concrete steps, runnable code, and verification points. For example, instead of stating “Python is a programming language,” write “Use pandas.read_csv() in three steps to load a CSV.”

Effective techniques include:

Explain the why behind each rule rather than just listing requirements.

Show before/after examples to give the model a clear pattern.

Provide a few‑shot set covering the main branches.

Document “gotchas” (e.g., always filter soft‑deleted rows with WHERE deleted_at IS NULL).

Principle 4 – Author Manually, Not by the Model

Empirical data from SkillsBench shows manually written Skills improve task success by +16.2 %, whereas model‑generated Skills cause a ‑1.3 % drop. Optimal quantity is 2–3 Skills per task; more leads to cognitive overload and a +5.9 % decline.

Keep each Skill between 800 and 1 500 tokens; overly long documents drown useful signals.

Principle 5 – Split Long Skills and Insert Checkpoints

If a Skill exceeds 500 lines or mixes independent workflows, break it into a parent Skill that orchestrates sub‑documents. Every step should have a checkpoint, e.g., run go mod tidy && go build ./... and abort on failure.

Safety Considerations

Snyk’s ToxicSkills study scanned 3 984 public Skills and found 534 with critical security issues. Recommendations:

Never hard‑code API keys; use environment variables.

Require explicit confirmation before destructive actions (DDL, bulk file changes).

Back up data before modification and provide rollback commands.

Guard against prompt injection by treating external reads as data only.

Evaluating a Skill

Run a simple benchmark with 20 test queries (10 should trigger, 10 should not). If the trigger rate is unstable, first verify the path and description. If execution deviates, improve steps, add before/after examples, and insert checkpoints. SkillsBench advises a deterministic validator (programmatic assertions) and to retire any Skill whose success rate stays below 70 %.

Publishing Checklist

Clear objective and timing.

Precise description with trigger phrase, temporal placement, and domain keywords.

Executable steps, not vague statements.

Enough examples (Before/After or few‑shot).

Explicit boundaries and manual‑review points.

Complete verification commands.

Security safeguards (no hard‑coded secrets, safe delete/DDL, input validation).

Concise structure; split when the body becomes too long.

In summary, writing a high‑quality Agent Skill is less about adding more prompt text and more about distilling team knowledge into a reproducible, safe, and token‑efficient package that the model can reliably invoke.