Agent Skills: Packaging Knowledge for Coding Agents

Tools let an agent do something. Skills help it know how to do something properly.

That distinction sounds small, but it changes how I organise AI-assisted development. Instead of pasting the same instructions into every session, I can package the context, process and supporting files in a version-controlled skill.

What a skill contains

The Agent Skills format is deliberately simple. A skill is a directory with a SKILL.md file containing frontmatter and instructions. It can also include scripts, references, templates and other assets.

release-check/
├── SKILL.md
├── scripts/
│   └── check-release.mjs
├── references/
│   └── release-policy.md
└── assets/
    └── release-notes.md

The description is important. Agents usually see the name and description before loading the full instructions, so it should say what the skill does and when it applies. The body can then contain the actual workflow, edge cases and checks.

Skill, tool, prompt or agent?

These concepts overlap, but I find this split useful:

  • A tool is an executable capability: search a database, open a pull request or send an email.
  • A prompt is a request or reusable starting instruction.
  • A skill is a repeatable method that combines judgement, instructions and optional resources.
  • An agent is the system that decides what to do and when to use its available capabilities.

A release skill might tell an agent to inspect the diff, run a specific test suite, check migrations, generate notes and stop if a security-sensitive file changed. The tools perform the checks. The skill supplies the order and the judgement.

Progressive disclosure keeps context under control

The best skill is not a giant manual. It gives the agent just enough information to recognise when it applies, then loads detail as the task needs it:

  1. Discovery: the agent sees the skill name and description.
  2. Activation: a matching task loads SKILL.md.
  3. Execution: scripts, references and templates are read or run when required.

This keeps the everyday context small without throwing away the detail needed for an unusual case. It also makes skills easier to review: the main workflow stays short, while specialist material lives beside it.

What makes a skill useful

I look for four things:

  • A clear trigger. It is obvious when the skill applies.
  • A defined outcome. The agent knows what done looks like.
  • Real project context. The instructions name the conventions, boundaries and checks that matter here.
  • A safe failure mode. The skill says when to stop and ask instead of guessing.

The last point is easy to miss. A skill should not merely make an agent more willing to act. It should make the agent more predictable. For production work, that means explicit approval points, small changes, verification and useful evidence at the end.

Skills are software too

Once a skill affects a real workflow, I treat it like code. I keep it in version control, review changes, test the scripts and remove stale instructions. A skill that silently describes yesterday's architecture is worse than no skill because it gives confident agents the wrong map.

I also keep skills narrow. “Build the whole product” is too broad to be dependable. “Add a PostgreSQL migration, update the repository layer and run the migration checks” is specific enough to repeat and improve.

The payoff is not that an agent becomes magically smarter. The payoff is that good engineering practice becomes available at the moment it is needed, without rebuilding the same context in every session.