Aug 14, 2026

Write AI agent skills that actually work

By Thales de Assis

A practical guide to SKILL.md playbooks: progressive loading, trigger-rich descriptions, Gather-Act-Verify structure, and a checklist that keeps coding agents on track.

1 What an agent skill really is

An AI agent skill is a small, versioned playbook. Usually a folder with a SKILL.md. It tells a coding agent when to wake up and how to run one job: open a PR, grill a plan, insert a knowledge pill, review security, deploy to staging.

PortableSame SKILL.md pattern works in Cursor, Claude Code, Codex, and other Agent Skills tools
Version-controlledLives in the repo (or your user skills folder), not trapped in a chat tab
ActionableCan point at scripts, templates, and references the agent actually runs or reads
ProgressiveOnly the name and description sit in context until the skill is needed

Skills are not career skills

Search “AI skills for engineers” and you get Python, RAG, evals. Useful later. Day to day I care more about agent skills: short process files that stop the model from reinventing your workflow every session.

Links Cursor Skills docs Agent Skills standard Earlier thales.dev guide

2 Skills vs rules

If everything is always-on context, you burn tokens and the agent ignores half of it. Split the job:

RulesStatic guidance that should apply often: stack conventions, “never force-push main,” house style.

Keep rules shortIf a rule is a full workflow, it probably wants to be a skill instead.

SkillsOn-demand playbooks. Loaded when the task matches the description (or when you type /skill-name).

Scope with pathsFrontmatter paths can limit a skill to **/*.tsx or a package folder so it stays quiet elsewhere.

A skill that never triggers is a docs file with a costume. Fix the description before you pad the body.

3 How loading works (why short beats long)

Cursor-style agents do not dump every skill body into the prompt. They climb a ladder:

DiscoverOnly name + description for each skill
ActivateFull SKILL.md when the task matches
On demandRead references/, run scripts/

Context cost Tiny catalog→One playbook→Extra files if needed

Keep SKILL.md lean

Put the decision tree and steps in the main file. Park long checklists, API tables, and style dumps in references/. The agent opens those only when the step needs them.

4 Anatomy of a good SKILL.md

Minimum shape: a folder named like the skill, plus frontmatter the agent can index.

Minimal skeleton

---
name: deploy-staging
description: Deploy this app to staging. Use when the user asks to deploy, ship to staging, or release a preview.
---

# Deploy staging

## Instructions
1. Read current git status and failing tests.
2. Run scripts/validate.sh
3. Run scripts/deploy.sh staging
4. Verify the health URL returns 200

Field	Required	What it is for
`name`	Yes	Lowercase id; must match the folder name
`description`	Yes	Trigger text. This is the search index, not marketing copy
`paths`	No	Glob list so the skill only surfaces on matching files
`disable-model-invocation`	No	`true` = slash-command only (good for destructive or billing flows)

Cursor
Claude Code
Codex
agentskills.io

Links SKILL.md format mattpocock/skills

5 Write the description like a trigger list

Most “my skill never runs” bugs are vague descriptions. The body can be perfect and still sleep forever.

Do this

Lead with what the skill does in plain words
List real verbs users type: “open PR”, “publish article”, “triage bugs”
Add negative triggers when overlap is messy
Write in third person (how the agent catalogs it)

Avoid this

“Helpful coding assistant for deploys”
Synonym spam that never names the user phrases
Descriptions that could match half the chat
Hiding the only trigger words in the body

Trigger-rich example

description: Create a GitHub pull request for the current branch. Use when the user asks to open a PR, create a pull request, or submit changes for review. Do not use for push-only or local commits.

6 Structure the body: Gather, Act, Verify

I steal this shape from people who ship skills that survive real repos. It forces the agent to look before it types, then prove the work landed.

Gather: which files, status commands, or docs must be read first
Act: the ordered steps, scripts, or edits (one verb family: deploy or release, not both as synonyms)
Verify: tests, HTTP checks, git status, screenshot, whatever proves done

If a step cannot end on something checkable, the model will invent success. Put the acceptance test in the skill.

Loop Gather→Act→Verify→Fix or stop

7 Quality checklist before you commit

Ship-ready skill checks
One job	Trigger verbs	Checkable steps	Lean main file
Composable	Repo truth	Guardrails	Pruned sediment

One job“Grill a plan” or “red-green-refactor.” Not “do engineering.”
Trigger verbsName the phrases you actually type: “open a PR,” “publish article.” Not “helpful assistant.”
Checkable stepsEach step ends on something you can prove, or the agent will invent “done.”
Lean main fileKeep SKILL.md short. Park long dumps in references/ until a step needs them.
ComposableCall smaller skills. Avoid nesting rival slash-command empires.
Repo truthPoint at real paths (CONTEXT.md, ADRs, scripts). Do not invent process in chat memory.
GuardrailsSay what not to do when it matters: no force-push, no prod without a flag, no silent schema changes.
Pruned sedimentAfter a real run, cut anything the agent ignored. Skills rot when you only add.

Acceptance test

Trigger the skill with three different phrasings of a real task. If none load it, rewrite the description. Only then grow the body.

8 Start this week

Concrete path

Pick one pain you hit twice a week (PR writeups, deploys, article inserts, flaky reviews)
In Cursor, try /create-skill or copy a thin skill from a trusted set
Write the description first, with the verbs you actually say out loud
Fill Gather → Act → Verify with checkable steps
Move long reference material into references/
Run it on a real change, then prune anything the agent ignored

9 Resources worth opening

Resource	Why open it
Cursor Agent Skills docs	Directories, frontmatter, scripts, migration from rules
Cursor: coding with agents	Rules vs skills, plan mode, practical agent habits
agentskills.io	Open standard behind the `SKILL.md` pattern
mattpocock/skills	Small, composable skills aimed at real engineering failure modes
Metablogue: skills that work	Trigger writing, context budgets, negative triggers