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

Level 3: Connect AI to your tools · 9 min · Updated 19 November 2026 · Path: Agent skills

By the end 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](https://ai-powered.com/academy/glossary/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

*Diagram: 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](https://ai-powered.com/academy/glossary/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.

**Steps**

1. Find a skill on its listing page in the [agent skills](https://ai-powered.com/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:

- [Skill creator](https://ai-powered.com/skills/skill-creator): Guides an agent through drafting, testing and tuning new agent skills with measured evals
- [Rea analysis optimization](https://ai-powered.com/skills/rea-analysis-optimization): Finds and fixes wasted work in REA analysis code while verifying results stay equivalent
- [Rea changelog update](https://ai-powered.com/skills/rea-changelog-update): Rewrites REA release notes from pinned Git history with verified contributor credit
- [Rea tool design](https://ai-powered.com/skills/rea-tool-design): Audits and designs REA investigation tools, CLI and MCP contracts and Evidence semantics
- [Reverse engineer anything](https://ai-powered.com/skills/reverse-engineer-anything): Reverse engineers binaries, apps and firmware with REA and builds web app environments

## Write your first SKILL.md

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

```markdown
---
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.

**Try it**

Write a skill for one task you repeat, put it in `.claude/skills/<name>/SKILL.md` (or your agent's skills folder), start a new session and ask for the task without naming the skill. If the agent doesn't pick it up, make the description more specific about *when* to use it.

**Watch out**

Anthropic warns that skills which fetch data from external URLs are particularly risky, because the fetched content can carry instructions, and that even trustworthy skills can change if their dependencies do. Pin what you can, and re-read a skill when it updates.

## Key takeaways

- 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

- Put your team's conventions where every agent reads them: [context engineering](https://ai-powered.com/academy/code-with-ai-agents/context-engineering).
- Browse [agent skills](https://ai-powered.com/skills) by category, and check whether each one runs scripts.

## Sources

Official documentation, checked on 19 November 2026:

- [Agent Skills overview (agentskills.io)](https://agentskills.io)
- [Agent Skills overview (Claude docs)](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)
