Skills explained, and installing your first
A skill is a markdown file containing instructions for a specific task, which the agent loads only when that task comes up. It is a way of teaching an agent how you want something done, once, instead of explaining it every session.
The problem skills solve
You can put instructions in your CLAUDE.md or AGENTS.md, and that works until the file gets long. Everything in it is loaded on every request, whether relevant or not, and long instruction files both cost tokens and dilute attention.
Skills fix this by being conditionally loaded. The agent sees only each skill's name and description at startup, roughly a line each. When a task matches a description, it loads that skill's full instructions.
The format
A skill is a directory containing a SKILL.md file. The file starts with YAML frontmatter and continues with markdown instructions.
--- name: changelog-writer description: Writes release notes from git history. Use when cutting a release or when the user asks for a changelog. --- # Changelog Writer ## Steps 1. Get the commit range since the last tag 2. Group changes into Added, Changed, Fixed, Breaking 3. Write one line per change, describing user impact ## Rules Write what changed for the user, not what the developer did. Drop internal refactors with no user visible effect. Never invent a version number or a date.
Only name and description are required. Spec compliant runtimes ignore frontmatter keys they do not recognise, so extra metadata is safe to add.
The description is the most important line
The agent decides whether to load a skill based on its description alone. A vague description means the skill never fires.
Write it in two parts: what it does, and when to use it.
Weak: Helps with documentation.
Strong: Writes release notes from git history. Use when cutting a release, tagging a version, or when the user asks for a changelog.
The second one contains the trigger words someone would actually say.
Installing one
Skills live in a directory your harness watches. For Claude Code that is .claude/skills/ in a project, or ~/.claude/skills/ for skills available everywhere.
mkdir -p .claude/skills/changelog-writer
Then put your SKILL.md inside it. Restart the session and the skill is available.
There are CLIs that install skills from repositories, which saves creating files by hand:
npx skills add owner/repo
Writing one that works
Be specific about the steps. A skill that says "write good documentation" adds nothing the model does not already believe it is doing. A skill that says "read package.json for the real script names before writing install instructions" changes the output.
Include the rules that encode your taste. The value is in your opinions: what to leave out, what to never do, what the output should look like.
Keep the body under a few thousand tokens. It gets loaded into context when triggered. Long skills crowd out the actual work.
Put reference material in separate files. The skill directory can contain other files the agent reads only if needed.
Test whether it fires. Ask something in your own words and see whether the skill loads. If it does not, the description is wrong.
When not to use a skill
If the instruction applies to everything you do in a project, put it in CLAUDE.md or AGENTS.md instead. Skills are for task specific knowledge.
If you use it once, just say it in the prompt.
The security part
A skill is executable instruction text that your agent will follow. Installing a skill from a stranger is closer to running a script than to reading a document.
Read any skill before installing it, particularly anything that tells the agent to run commands, fetch URLs, or send data somewhere. This is a real attack surface and it is under-appreciated right now.