Lifetime access is $57 through 30 November.
Skillsh
Skillsh
Toggle sidebar
Login Get access · $57
← All guides

Updated

Agent skills best practices

Agent skills best practices

A good skill is accurate, focused, and safe. These practices come from skills that held up in real work, and they apply whether you're buying a skill or writing your own.

Keep the description honest and specific

The description field is the one thing the agent reads for every skill at startup, before it opens any instructions. It decides whether the skill matches the task, so it has to be specific about what the skill does and when to use it.

Good:

description: Review a pull request against a security checklist before approval. Use whenever the agent is asked to review or approve code changes.

Weak:

description: Helps with code.

A vague description means the skill either never triggers or triggers at the wrong time.

One skill, one job

A skill that does everything does nothing reliably. "Code review" and "deployment runbook" are two skills, not one. Small skills are easier to test, easier to fix, and easier to chain together.

Keep the body short

The spec recommends keeping instructions under about 500 lines or 5000 tokens. Move long reference material — API details, edge cases, full style guides — into a references/ folder. The agent loads those on demand instead of carrying them for every task.

release-checklist/
  SKILL.md           # the steps, kept short
  references/
    rollback.md      # the long, detailed runbook

Document failure modes

Every workflow has a way to go wrong. Say what it is and what to do about it. A deployment skill that explains "if the health check fails, roll back with the steps in references/rollback.md" is far safer than one that only lists the happy path.

Be careful with allowed-tools

The allowed-tools field pre-approves tools the agent can call. It's useful for scoping a skill to exactly the tools it needs, but list only what's necessary. Pre-approving more than you need widens the blast radius if the instructions are ever wrong.

Test on more than one runtime

A skill written to the open standard should work on any compliant runtime — but "should" is not "does". Run it on at least two before you rely on it. Differences in how runtimes read instructions will surface here, not in production.

Version deliberately

Skills are folders, so they version the way code does: change the content, keep the name stable, and bump a changelog. If a change is breaking, say so in the description or the body so users know to re-test.

Where to go next

The authoring tag collects everything about building skills, and how to write your own agent skill takes you through the full loop.

Related posts