Skip to content

Agent skills: what they are, how to install one, how to write a SKILL.md

Level 3: Connect AI to your tools. About 9 min. Checked on 19 November 2026 against Agent Skills format (agentskills.io), Claude Code skills.
Stage 3 of 4: Connect AI to your tools

In this lesson you'll install a skill safely, write a SKILL.md for a task you repeat, and check that your agent picks it up.

Every Monday you ask your agent for the weekly release notes, and every Monday you explain the same things: group by Added, Changed and Fixed; skip internal refactors; link the tickets. A skill is how you explain it once.

What a skill is

An agent skill is a folder with a SKILL.md file in it. The file starts with a name and a description, then the instructions. The folder can also hold scripts, reference documents and templates.

The format was developed by Anthropic and released as an open standard at agentskills.io, which lists the agents that support it. That's the point: you write a skill once and use it in any agent that reads the format.

release-notes/
├── SKILL.md
├── scripts/        (optional)
├── references/     (optional)
└── assets/         (optional)

Why skills don't fill up your agent's memory

  1. 1Name and descriptionAlways, at start-up

    About 100 tokens per skill

  2. 2SKILL.md instructionsWhen a task matches

    Under 5k tokens

  3. 3Extra files and scriptsOnly if needed

    Nothing until used

How a skill loads. At start-up the agent reads only each skill’s name and description. When a task matches, it reads the SKILL.md instructions. Extra files and scripts load only if the instructions point to them.

At start-up the agent reads only each skill's name and description. It reads the full instructions when a task matches, and opens extra files or runs scripts only when the instructions call for them. So you can install many skills without crowding the agent's context window.

A skill

  • Teaches the agent how to do a task: steps, format, rules.
  • A folder of text and optional scripts.
  • Example: "how we write release notes".

An MCP server

  • Gives the agent access: new tools and live data.
  • A program the app connects to.
  • Example: "read our issue tracker".

They work best together: a skill can tell the agent which MCP tools to use, and in what order.

Install a skill safely

Anthropic's advice is to use skills only from sources you trust, and to read every file first. A skill is instructions plus code, so treat it like installing software.

  1. Find a skill on its listing page in the agent skills section. The page shows whether it runs scripts and lists install steps for the agents it supports.
  2. Open the repository and read SKILL.md and every script. Look for network calls or file access that don't match what the skill says it does.
  3. Install it. In Claude Code, a skill is a folder in ~/.claude/skills/ (for all your projects) or .claude/skills/ in a project. In the Claude apps, you upload it as a zip on paid plans with code execution on.
  4. Ask for the task in plain words and check that the agent used the skill.

Popular skills for developer work, from the directory:

Picks for developer tools from the directory, most popular first.

More for developer tools
  1. Guides an agent through drafting, testing and tuning new agent skills with measured evals

    • Free
    • 197K GitHub stars
    • AI models and LLM tooling
  2. Finds and fixes wasted work in REA analysis code while verifying results stay equivalent

    • Open source
    • 465K GitHub stars
    • Developer tools
  3. Rewrites REA release notes from pinned Git history with verified contributor credit

    • Open source
    • 465K GitHub stars
    • Developer tools
  4. Audits and designs REA investigation tools, CLI and MCP contracts and Evidence semantics

    • Open source
    • 465K GitHub stars
    • Design and media
  5. Reverse engineers binaries, apps and firmware with REA and builds web app environments

    • Open source
    • 465K GitHub stars
    • Security

Write your first SKILL.md

Pick a task you explain to your agent at least once a week. Then write:

---
name: release-notes
description: Write release notes from merged pull requests. Use when the user asks for release notes, a changelog or "what shipped".
---

# Release notes

1. List the pull requests merged since the last tag.
2. Group them under Added, Changed and Fixed. Leave out internal refactors.
3. One line each, in plain words, linking the pull request.
4. End with a one-sentence summary for people outside the team.

The description does the most work: it's what the agent matches your request against. Say what the skill does and when to use it. In Anthropic's format the name is lower-case letters, numbers and hyphens, up to 64 characters, and the description can be up to 1,024 characters.

In short

  • A skill is a folder with a SKILL.md: name, description, instructions.
  • Agents load it only when a task matches the description.
  • Read every file before installing; write descriptions that say when to use the skill.

What to try next

Share this lesson

Lesson 1 of 1 in this path

Words used in this lesson

Sources

Official documentation, checked on 19 November 2026. Products change: if a step differs, the source has the current version.

Get the next lesson

New Academy lessons are announced in the weekly AI-Powered email.