TopolearnSkills turn prompts you keep retyping into shared, versioned tools, without bloating every session's context.
A skill is a folder containing a SKILL.md file: markdown instructions with a short header (frontmatter, the block between --- lines at the top). Where you save it decides who gets it:
.claude/skills/<name>/SKILL.md: this project, shared via git,~/.claude/skills/<name>/SKILL.md: you, in every project,- plugins can ship skills too (next lessons).
There are two ways a skill runs. You can invoke it as a command: a skill named fix-issue becomes /fix-issue. Or Claude loads it on its own when your request matches the skill's description. Only names and descriptions sit in context at the start; the full body loads when used, which is why skills are a better home than CLAUDE.md for long, occasional workflows.
Common frontmatter fields:
description: what it does and when to use it; write it carefully, it drives automatic use.disable-model-invocation: true: only you can trigger it. Use this for anything with side effects, like deploys.allowed-tools: tools Claude may use without asking while the skill runs.context: fork: run it in a separate subagent context.
$ARGUMENTS in the body is replaced by whatever you type after the command; $0, $1 pick individual arguments.
Older custom commands in .claude/commands/<name>.md still work and create /name the same way; skills are the recommended form now because they add supporting files and invocation control. /skills lists what is available and what each costs in context.
Claude Code also ships bundled skills, for example /code-review, /simplify and /batch.
Example
---
name: fix-issue
description: Fix a GitHub issue end to end. Use when asked to fix issue #N.
disable-model-invocation: true
allowed-tools: Bash(gh issue view *), Bash(npm test *)
---
Fix GitHub issue $ARGUMENTS.
1. Run `gh issue view $ARGUMENTS` and restate the problem in one paragraph.
2. Find the relevant code; write a failing test that reproduces the bug.
3. Fix the code until the new test and the existing suite pass.
4. Commit with a message referencing the issue, then open a PR.
# saved as .claude/skills/fix-issue/SKILL.md, run with: /fix-issue 1234Remember
- A skill is .claude/skills/<name>/SKILL.md; it becomes /name
- Claude may load a skill automatically from its description; disable-model-invocation prevents that
- Only descriptions load up front, so long workflows belong in skills rather than CLAUDE.md
Watch out for
- Leaving automatic invocation on for a skill that deploys or deletes things, so Claude may run it when it merely seems relevant.