Skill Claude Code: how the skill works and when to write it

What does this solve?

Skill in Claude Code — folder with file SKILL.md, where they put the instructions, which otherwise are dictated anew every session: how to roll out, how to fill out a ticket, what SQL can be used to go to the combat base. Without skills, such instructions live either in the head or in CLAUDE.md, which is read in its entirety every time it is launched and over time turns into a dump where the agent ceases to distinguish the main thing. A skill is loaded only when the task matches its description, so twenty skills are not worth twenty sheets in the starting context. At the same time, discord in the team is removed: the rules are in the repository and come to everyone according to git pull.

How it works

Skill File

Minimum skill - one folder and one file inside it:

.claude/skills/release-checklist/SKILL.md

The folder name works as an identifier. There are two blocks inside the file - a YAML header and a body.

---
name: release-checklist
description: Прогон релизного чеклиста перед выкатом — сборка, миграции, план отката. Использовать, когда просят «выкатить», «собрать релиз», «задеплоить на прод», а также перед созданием тега.
---

# Релизный чеклист

## 1. Перед сборкой
- `make test` — прогон обязателен, красный тест останавливает выкат
- миграции: просмотреть `database/migrations`, для каждой новой описать откат

## 2. Сборка
- только таргеты из `Makefile`, свои команды не изобретать

There are two required fields in the header: name i description. The name is the same as the folder name. The body is regular markdown: headings, lists, tables, pieces of commands. The agent reads it as an instruction for execution, and not as a certificate “to read,” so the wording in the body is written with verbs: “drive away,” “check,” “do not touch.”

What falls into the context and at what point

The start context of the session includes only name i description each available skill - a couple of lines per skill. Body SKILL.md is read at the moment when the skill is called: a match with the description worked or the person asked directly. This leads to the main writing rule: description answers the question “when to use me”, the body answers the question “what to do”.

Description - single hook

A skill that does not work behaves exactly like an unwritten one, and the error is not visible: the agent simply does it in his own way. Therefore, the description is written using triggers.

Weak description:

description: Работа с релизами.

The working description lists: what formulations a person comes with, what files and commands are in use, what data formats, and when the skill does not need to be used.

description: Выкат приложения на прод и на dev-стенд через Makefile. Использовать при просьбах «задеплоить», «выкатить», «поднять стенд», при работе с .gitlab-ci.yml и Makefile, перед созданием тега. Не использовать для правки кода без выката.

The description is read by a machine, not a person - there is nothing to save words here. A long, precise description works, but a short, beautiful one is silent.

Three places where skills lie

Project level - workhorse. The file is in git is next to the code, undergoes review in MR and is updated along with the process it describes. The personal level is suitable for one person’s habits: note format, favorite report layout.

Attached materials

Next to SKILL.md put subfolders: references/ for long references, scripts/ for ready-made scripts, assets/ for templates. The link is given in a relative way and always with the condition of when to open the file:

Полный перечень полей ответа — в `references/api-fields.md`, открывать только при разборе ошибки 422.
Шаблон отчёта — `assets/report.md`, копировать целиком, поля не переименовывать.

So the body SKILL.md remains short, and heavy pieces are pulled up as needed. A two-hundred-line skill with all the references inside works worse than a thirty-line skill with four links.

What the skill doesn't do

It does not bring new tools to the agent: integrations with external systems come via MCP. It does not prohibit actions: a strict prohibition is a hook in settings.json or a permission rule that runs before the model. A skill is a text that the agent will read and take into account.

How to connect

1. Create a folder in the project repository:

mkdir -p .claude/skills/sql-prod

2. Write skill file:

cat > .claude/skills/sql-prod/SKILL.md <<'EOF'
---
name: sql-prod
description: Правила запросов к боевой базе. Использовать при любых просьбах посчитать метрику, выгрузить данные, проверить цифру по базе, а также при словах SELECT, запрос, выгрузка, отчёт по базе.
---

# Запросы к боевой базе

1. Только `SELECT` и `WITH`. Любая правка данных — стоп и вопрос владельцу.
2. `LIMIT` обязателен во всех запросах без исключения.
3. Персональные данные (почта, телефон) не выводить без явной просьбы.
4. Имена таблиц брать из `data/schema_compact.md`, не по памяти.
EOF

3. Check the header: name matches the folder name, description contains the wording with which they actually come.
4. Restart session - the list of available skills is collected at start.
5. Check the response: ask the question in words from the description and see if the agent follows the steps from the body.
6. Commit .claude/skills/ , along with the code, so that the skill goes to the team.
7. Move everything that is longer than the screen into references/ and refer from the body.

Useful scripts

• Release checklist: build, migrations, rollback plan, rollout order through Makefile.
• Rules for going to the combat base: read only, mandatory LIMIT, list of prohibited tables.
• Ticket format in the tracker: what fields to fill out, what text is in the description, where to move the card.
• Analysis of crashes of a specific service: where are the logs, what greps, the three most common reasons.
• Command code review style: what is a blocker, what is a comment, what is ignored.
• Onboarding into the module: directory map, entry points, what cannot be touched.
• Format of a letter to a client: tone, signature, what not to promise.

Limitations

• Weak description = dead skill, and silent failure: the agent does not report that a suitable task passed him by.
• The skill body occupies the context of the current session - skills are not isolated in a separate window, unlike subagents.
• Several large skills with overlapping descriptions compete with each other, and the wrong one is selected.
• Skill does not guarantee execution. This is an instruction that the model follows, not a check on the output; Strict bans are imposed by hooks and rights.
• Personal skills from ~/.claude/skills is not visible to anyone except the owner of the car. For the team, there is only one way - a repository.
• The skill does not monitor its own relevance: the process has changed - the file is edited by hand, otherwise the agent confidently works according to the outdated one.
• Secrets in the body of the skill leak along with the repository. Keys and addresses of food hosts are not placed there.

How to check the result

• Open a new session and ask a question using words from description. A triggered skill can be seen by the fact that the agent performs specific steps from the body of the file instead of general reasoning.
• Insert a marker into the body - a rare requirement like “print a line at the end CHECKLIST-OK" - and see if it appears. Appears, it means the file has been read in its entirety.
• Check with a colleague after git pull: The design skill should work out of the box on his machine.
• Set a request that should not match the description, and make sure that the skill is not called up. A description that is too broad draws the skill into other people’s tasks and gets in the way.
• Run the real task to the end and check the result with what is written in the body: a discrepancy means that the instructions are outdated or formulated in such a way that allows for a second interpretation.

One line rule: a skill is introduced to an instruction that had to be repeated a third time, and is described on the basis of “when to use,” and not “what it can do.”