A Claude Code **Agent Skill** is a `SKILL.md` file of instructions Claude adds to its toolkit. Per Claude Code's skills docs, Claude uses a skill when it's relevant, or you can invoke one directly with `/skill-name`. Custom commands have been merged into skills: `.claude/commands/deploy.md` and `.claude/skills/deploy/SKILL.md` both create `/deploy`. Prefer skills for new work (supporting files and frontmatter). This post covers Claude Code only. Cursor skills packaging is a separate how-to: package a Cursor skills pack. For skill versus rule as a packaging choice, see skill vs rule.
Where to put SKILL.md
From the docs' "Where you save a skill" table:
| Location | Path | Loads in |
|---|---|---|
| Personal | `~/.claude/skills/<name>/SKILL.md` | All your projects on this machine |
| Project | `.claude/skills/<name>/SKILL.md` | This repository (commit to share) |
The same docs also list enterprise, nested, plugin, and additional-directory locations. Start with personal or project for most teams.
Frontmatter that controls invocation
Frontmatter is YAML between `---` markers; the markdown body follows. All fields are optional; `description` is recommended so Claude knows when to use the skill. The file's first line MUST be the opening `---` or the frontmatter is ignored (Frontmatter reference).
Key trigger fields from "Control who invokes a skill":
| Field | Effect |
|---|---|
| `description` / `when_to_use` | Tell Claude when to load the skill |
| `disable-model-invocation: true` | User-only: invoke with `/name`; Claude can't auto-invoke |
| `user-invocable: false` | Claude-only: hidden from the `/` menu |
Default: both you and Claude can invoke. By default, skill descriptions stay in context; the full body loads when the skill is invoked.
Minimal example:
---
description: Summarize uncommitted changes and flag risky diffs. Use when the user asks what changed or wants a commit message.
---Instructions
Summarize the working tree changes in two or three bullets, then list risks. ```
Supporting files and size
Supporting files live beside `SKILL.md` in the skill directory. The docs say: "Keep `SKILL.md` under 500 lines." Move long reference material into separate files and link them from the skill body (Add supporting files).
Dynamic context: a line like `` !`command` `` runs before the skill content is sent; the command output replaces the placeholder (Inject dynamic context).
Pitfalls
- Frontmatter not on line 1. If the opening `---` isn't the first line, Claude Code ignores the frontmatter.
- No `description`. Without it, Claude has less to match against when deciding whether to load the skill.
- Expecting skills to block tools. Skills are instructions. To block a Bash command, use a PreToolUse hook: block a command with a PreToolUse hook.
- Re-teaching Cursor skills here. Paths, frontmatter, and triggers differ by product; keep Cursor how-tos on the Cursor posts.
How to check it
Create `.claude/skills/<name>/SKILL.md` with a clear `description`, restart or reload skills, then ask something that matches the description and also try `/<name>`. To confirm user-only behavior, set `disable-model-invocation: true` and verify Claude doesn't auto-load it.
Where the kit fits
The Operator Pack ($47) ships markdown seats + skills + install.sh across Cursor, Claude Code, and Grok Bot. You can also start at /free. Cheat Sheet for the skim checklist mindset.
Soft next step
Pick one procedure you keep pasting into Claude Code, save it as `.claude/skills/<name>/SKILL.md` with a clear `description`, and decide whether Claude may auto-invoke it or only you via `/name`. Soft ladder: /free, then the Operator Pack ($47). Related: skill vs rule, package a Cursor skills pack, Claude Code PreToolUse hook.