You already know CLAUDE.md (Week 1): rules the agent reads every session. A skill is the next level: packaged know-how the agent loads only when the task calls for it.
One sentence to the agent — a complete skill: trigger in the description, rules with examples in the body. Review the file it wrote; that's your part.
A folder with a SKILL.md file inside — frontmatter (name + description) plus markdown instructions. The description sits in the agent's context so it knows the skill exists; the full body loads only when a task matches. That's the difference from CLAUDE.md: rules load always, skills load on demand — so they cost almost nothing until needed.
Where they live:
.claude/skills/ in the project — shared with the team via the repo.~/.claude/skills/ — personal, across all projects.Changes are picked up live within a session — add or edit a skill and it's there.
The signal is repetition. If you've pasted the same instructions into chat for the third time — a release checklist, your API conventions, how your team writes commit messages — that's a skill. Another signal: a section of CLAUDE.md growing from a fact ("we use pnpm") into a multi-step procedure ("to cut a release: …"). Facts belong in CLAUDE.md; procedures belong in skills.
.claude/skills/commit-style/SKILL.md:
---
name: commit-style
description: Use when writing commit messages or PR descriptions in this project
---
# Commit style
- Subject line: imperative, max 60 chars, no period
- Body: what changed and why, not how
- PR descriptions follow the format: what the agent did / what I changed by hand / what I rejected
Ask the agent to write a commit message — it picks the skill up automatically. The description is what triggers it, same principle as subagents: write it as "Use when…".
Creating one needs no terminal: ask the agent — "create a commit-style skill in this project with these rules: …" — and review the file it writes, or drop the folder in yourself via VS Code. Desktop and CLI pick it up the same way.
Claude Code also ships bundled skills (e.g. /code-review, /debug) — worth exploring before writing your own.
The request never mentions the skill — but there it is in the activity: commit-style skill, picked up by its description. The result: 41 characters, imperative, no period — the agent checks itself against the rules it loaded.
The HackYourFuture curriculum is licensed under CC BY-NC-SA 4.0 *https://hackyourfuture.net/*
Built with ❤️ by the HackYourFuture community · Thank you, contributors
Found a mistake or have a suggestion? Let us know in the feedback form.