InterviewKata
AI engineering · Module 11 of 21 · Level 3: Configure your tools

Agent Skills: know-how, loaded only when needed

AGENTS.md is for what every session needs. But your team also has procedures: how to add a migration, run a release, write tests the house way. Skills package each procedure as a folder the agent opens only when the task calls for it, so you can have dozens without filling the desk.

1. The idea

A good cook doesn't memorise every recipe or spread them all over the counter. Recipe cards sit in a drawer, and the cook can see the title tabs at a glance. When someone orders lasagne, they pull out that one card and follow it, measurements and all.

A skill is a folder with a SKILL.md file: a short header (YAML frontmatter) with a name and a description, then instructions in Markdown. It can also carry scripts, reference docs and templates. Agent Skills is an open standard: Anthropic introduced it in October 2025 and published it in December 2025, and it's now read by dozens of tools, including all five in this track.

The key mechanism is progressive disclosure, loading only what's needed, in three levels:

  1. Metadata, always: only each skill's name and description (around 100 tokens) are loaded at the start. That's the title tab on the card.
  2. Instructions, when relevant: when a task matches the description, the agent reads the full SKILL.md. The spec recommends keeping it under 5,000 tokens and 500 lines.
  3. Resources, if needed: scripts, reference files and templates are read or run only when the instructions call for them. A script's code doesn't even need to enter the context, only its output.

2. How it works

A skill folder. Only the description is always loaded; everything else waits in the drawer.

Step through a session with 30 skills installed, and watch the context window.

3. Try it yourself: the SKILL.md checker

Edit the frontmatter and see whether it meets the Agent Skills specification: the exact rules for name and description.

    4. Why it matters at work

    The description is the trigger

    The agent decides to open a skill from its description alone. A good one says what it does and when to use it, in the words people actually type.

    WeakStrong
    "Angular helper""Creates or changes an Angular component following our conventions. Use when adding a screen, dialog, card, form or widget under web/app."
    "DB stuff""Writes a Flyway migration. Use whenever a table, column or index changes. Never edits an applied migration."

    Which tasks deserve a skill

    Good candidates are repeated, multi-step, full of conventions people forget, and checkable at the end: adding a component, endpoint or migration; writing tests the house way; the release checklist; a report in a fixed format. Not a skill: one-off tasks, facts every session needs (those go in AGENTS.md), or anything a plain script does better (write the script, and let the skill call it).

    Writing rules

    1. Numbered, imperative steps. Agents follow procedures better than prose.
    2. End with the check: the command that proves it was done right.
    3. Scripts for anything exact (validation, formatting, generation). Text instructions drift; scripts don't.
    4. Keep SKILL.md lean; move long references into references/ files it points to.
    5. Test triggering: five requests that should use it and five that shouldn't. Fix the description until both pass, in two tools.

    5. In your five tools

    The same SKILL.md works everywhere; only the folder differs. Checked October 2026.

    ToolProject skillsPersonal skillsUse one
    Claude Code.claude/skills/NAME/SKILL.md (only this folder)~/.claude/skills/Automatic, or /NAME. Custom commands are now skills too.
    Antigravity CLI.agents/skills/~/.gemini/antigravity-cli/skills/Automatic; browse with /skills
    GitHub Copilot (VS Code).github/skills/, .agents/skills/ or .claude/skills/~/.copilot/skills/ (also ~/.agents/skills/)Automatic by description
    Cursor.agents/skills/ or .cursor/skills/ (also reads Claude and Codex folders)~/.cursor/skills/, ~/.agents/skills/Automatic by description
    Codex CLI.agents/skills/ in each folder up to the repo root~/.agents/skills/Automatic, or $NAME; /skills to browse
    One skills folder for the whole team.agents/skills/ is read by Antigravity, Copilot, Cursor and Codex. Claude Code reads only .claude/skills/, so keep the skills in one place and point the other at it (for example a symlink), or package them as a plugin (Module 12).

    6. Remember it

    Memory hook: "Recipe cards in a drawer"Every skill's title is visible; the full recipe comes out only when that dish is ordered. Write the title so the right card gets pulled, and the recipe so it ends with a taste test.
    How this hook works: what “Recipe cards in a drawer” means

    What the slogan means, phrase by phrase

    “Recipe cards”
    Each skill is a precise, step-by-step procedure for one kind of task, with ingredients (scripts, templates) clipped to it.
    “in a drawer”
    Out of the way until needed: progressive disclosure. Thirty skills cost only their titles until one is used.
    Implied: the title tab
    The description. If it doesn't say what the recipe is for, the cook never pulls the card out.
    Implied: the taste test
    A good recipe ends with how to check the result: the command that proves the skill was followed.

    Why this picture fits: it explains the two things people get wrong: putting everything in AGENTS.md (the counter gets cluttered) and writing vague descriptions (the right card is never found).

    The story → the concept

    KitchenAgent Skills
    The title tabname and description (always loaded, about 100 tokens)
    The recipe on the cardSKILL.md body (loaded when the task matches)
    Ingredients clipped to the cardscripts/, references/, assets/ (used only if needed)
    The note on the counterAGENTS.md: always in view, so keep it short
    The taste testThe final check command
    A shared family recipe boxSkills committed to the repo, or shipped in a plugin

    Watch it on an example

    1. Your team keeps forgetting migration rules, so you write db-migration/SKILL.md: "Writes a Flyway migration. Use whenever a table, column or index changes."
    2. Most sessions never touch the database; the skill costs about 30 tokens there.
    3. Someone asks "add a discount_code column to orders". The description matches, so the agent opens the card: new V{N} file, never edit applied ones, then run scripts/check_migrations.py.
    4. The script's output proves it's right. Same result in Claude Code, Cursor and Codex, from the same folder.

    The trap it saves you from

    Stuffing procedures into AGENTS.md until it's 2,000 lines, or writing a skill titled "helpers" that never gets picked up.

    It still works when…

    You package skills with subagents and hooks into a plugin (Module 12): a whole recipe box installed in one step, for every teammate.

    7. Common mistakes

    Running unreviewed skillsSkills can include scripts that run on your machine. Read every script in a skill you didn't write, exactly as you would a dependency.
    Vague descriptions"Helps with PDFs" never triggers reliably. Say what it does and when to use it, with the words users type.
    A wall of proseNumbered steps and a final check are followed far more reliably than paragraphs.
    A skill for something a script should doIf it's deterministic, write the script; the skill just tells the agent when and how to run it.
    Name and folder that don't matchThe spec requires the name to match the folder name, in lowercase letters, digits and single hyphens.

    8. Hands-on lab (roadmap week 11)

    1. Pick two tasks you repeat and often get wrong (a migration, a component, a release step).
    2. Write each skill: frontmatter (check it above), numbered steps, a final check command; add a script if part of it is exact.
    3. Test triggering with five should-use and five shouldn't-use requests, in two tools. Fix the description until both pass.
    4. Test the outcome on a real task and review the result against the skill's own checklist.
    5. Commit it to the repository's skills folder, so every session (and anyone else on the project) gets it.

    9. Self-check quiz

    With 30 skills installed, what's in the context before any of them is used?

    Progressive disclosure: metadata always, instructions when relevant, resources only if needed.

    What must a good description say?

    The agent chooses skills from the description alone.

    "Run tests with BAZEL_TEST=1": skill or AGENTS.md?

    Every session needs it, so it belongs in the always-loaded note. Skills are for procedures some tasks need.

    Which project folder is read by Antigravity, Copilot, Cursor and Codex?

    .agents/skills/ is the shared location; Claude Code uses .claude/skills/.

    10. Go deeper

    ResourceTimeWhy
    Agent Skills specification15 minThe exact format, field rules and progressive-disclosure guidance.
    anthropics/skills30 minReal, well-written example skills to learn from.
    Skills in Claude Code and Agent Skills in VS Code20 minLocations, invocation and options in two tools.
    Agent Skills (Cursor)10 minHow Cursor discovers skills, including other tools' folders.