In short:

  • Skills are focused instruction modules for recurring tasks.
  • They are loaded when needed, so your base context stays cleaner.
  • You can use skills with or without AGENTS.md.
  • If you use both: AGENTS.md stays high-level, skills hold the detailed methods.

Most people hearing about skills for the first time ask the same questions:

  • What are they, really?
  • Why should I care?
  • How do I actually use them?

This article is written in that order.

What skills are (without buzzwords)

A skill is a reusable playbook for a specific kind of work. Usually it is a folder with a SKILL.md file and optional supporting files (examples, scripts, templates, checklists).

The key idea is simple: instead of repeating complex instructions in every prompt, you package them once and let the agent load them when relevant.

Think of it this way:

  • your prompt = the immediate task
  • skill = the tested method for doing that task well

That pattern now shows up across major providers, including Anthropic, OpenAI Codex, Cursor, and GitHub Copilot.

Why skills are useful

Skills help because most AI failures are not about “no code generated.” They are about inconsistency:

  • one run writes tests, another skips them
  • one run respects architecture, another drifts
  • one run handles edge cases, another misses obvious ones

A good skill reduces that variance by giving the agent a clearer method and better defaults for a specific job.

If you already use AGENTS.md, skills are a natural complement:

  • AGENTS.md can define global standards and what “done” means
  • skills can carry detailed, task-specific instructions and examples

That usually means better outputs and a shorter, cleaner global instruction file.

If you do not use AGENTS.md, skills are still useful on their own.

How to use skills (example-first)

The easiest way to understand skills is to see compact examples.

Example 1: Testing skill

You often ask the agent to “add tests,” but quality varies. Create a testing skill:

  • SKILL.md defines your test standards (naming, fixtures, edge-case checklist, required assertions)
  • examples/ shows good tests from your own codebase
  • scripts/ contains test commands the agent should run

Result: “add tests for this endpoint” produces more predictable, production-usable tests.

Example 2: Refactor skill

Refactors often break behavior silently. Create a refactor skill:

  • rules for safe refactors (public API compatibility, migration notes, changelog expectations)
  • required validation steps before finishing
  • examples of acceptable diff size and structure

Result: less “looks clean but broke stuff,” more controlled changes.

Example 3: Documentation skill

Docs are usually hand-wavy when generated ad hoc. Create a docs skill:

  • required sections for PR notes or release notes
  • style and tone guide
  • examples of good before/after explanations

Result: documentation becomes consistent and genuinely useful.

Practical rollout plan

If you want to start today, do this:

  1. Pick one repeated pain point (testing, refactoring, docs, migrations).
  2. Write a small SKILL.md for that one thing.
  3. Add 2-3 high-quality examples from your own repository.
  4. Use it for a week and refine based on failures.
  5. Only then add the next skill.

This beats trying to design a perfect skill system on day one.

Where AGENTS.md fits (optional but powerful)

Many teams already know AGENTS.md. If that is you, a clean split works well:

  • AGENTS.md: principles, constraints, done criteria, commands
  • skills: detailed methods for specific workflows

In practice, this can also help context efficiency: the global file stays compact while detailed instructions live in targeted modules loaded when relevant.

But again: skills do not require AGENTS.md. They just pair very well with it.

Continuing the FLAD conversation

If you’ve followed the FLAD journey on Gadlet (part 1 and part 2), the strategic point is this:

AGENTS.md helped push agents through a full quality loop instead of stopping at first draft. Skills let us shape each stage of that loop with much higher precision.

That changes the operating model:

  • less reliance on one giant generic instruction file
  • more reusable, specialized operational knowledge
  • better transferability of quality across agents and providers

This is one reason skills matter beyond convenience. They move quality from “model magic” toward explicit, versionable process design.

Who supports skills today

The broad direction is convergence, though implementations differ.

  • Anthropic: strong public framing around progressive loading and reusable skill packages, plus a public skills repository.
  • OpenAI: skills documented in Codex and the API tools/skills guidance, with AGENTS.md guidance documented separately.
  • Cursor: positions skills for dynamic context discovery and procedural instructions in addition to always-on rules.
  • GitHub Copilot: agent skills built around SKILL.md plus supporting resources.
  • Lovable: strong knowledge/instruction features, though not yet the same first-class public SKILL.md model.

Final thought

Skills are still early, and teams are still learning how to structure them well.

But for anyone serious about reliable AI-assisted development, they are already one of the most practical upgrades available:

  • simpler prompts
  • clearer execution methods
  • more consistent outputs
  • and a cleaner separation between global standards and task-level know-how

If you have been experimenting with skills, I would love to hear what worked, what failed, and what you had to change before they became truly useful.