Explainer · 6 min read
How Claude Code Skills Work, and How to Use Them for Content Workflows
A Claude Code skill is a folder containing a SKILL.md file: YAML frontmatter that tells Claude when to use it, plus markdown instructions Claude follows when it runs. Per Anthropic's documentation, only the skill's description sits in context until it is invoked, so long reference material costs almost nothing until needed.
What is a Claude Code skill made of?
Every skill needs a SKILL.md file with two parts: YAML frontmatter between --- markers, and markdown instructions. Skills can include other files such as reference documents, examples and scripts. The documentation says Claude Code skills follow the Agent Skills open standard, which works across multiple AI tools. It advises keeping SKILL.md under 500 lines and moving detail into separate files.
- Create a folder named for the skill, for example
caption-writer. - Add
SKILL.mdwith adescriptionthat says what the skill does and when to use it. - Write the instructions Claude should follow, and reference any supporting files so Claude knows when to load them.
- Test it by asking in your own words, then by typing
/caption-writer.
Where do skills live?
| Scope | Path | Loads in |
|---|---|---|
| Enterprise | .claude/skills/<name>/SKILL.md in managed settings | All users where the organisation deploys it |
| Personal | ~/.claude/skills/<name>/SKILL.md | All your projects on that machine |
| Project | .claude/skills/<name>/SKILL.md | Sessions in that repository |
| Plugin | <plugin>/skills/<name>/SKILL.md | Wherever the plugin is enabled, as /plugin-name:skill-name |
When names collide, enterprise beats personal and personal beats project.
How does a skill load, step by step?
- At session start, Claude Code loads each skill's name and description into context, not the full body.
- Claude decides a skill is relevant from its description, or you invoke it directly with
/skill-name. - The rendered
SKILL.mdenters the conversation as a single message and stays there across later turns. - Supporting files and scripts are read or run only when the instructions call for them.
- Edits to skill files are picked up in the current session without a restart.
The combined description and when_to_use text is truncated at 1,536 characters in the skill listing, and when many skills overflow the listing budget (1% of the model's context window by default) Claude Code drops descriptions for the least-used skills first.
Which frontmatter fields matter most?
| Field | What it does (per the documentation) |
|---|---|
description | What the skill does and when to use it; Claude uses it to decide when to apply the skill. The only field recommended |
name | Command name in the / menu; defaults to the directory name |
disable-model-invocation: true | Claude cannot invoke the skill on its own; use for workflows with side effects or where you control the timing |
user-invocable: false | Only Claude can invoke it; for background knowledge |
allowed-tools | Tools usable without asking permission during the turn that invokes the skill; it does not restrict which tools exist |
context: fork | Runs the skill in a separate subagent that does not see the conversation, so instructions must stand alone |
paths, hooks, model | Optional scoping, lifecycle hooks and model override; see the documentation |
Unknown field names are ignored without an error, so a typo silently disables the setting.
Skill, CLAUDE.md or hook: which one for which job?
| Mechanism | When it loads or runs | Use it for |
|---|---|---|
| CLAUDE.md | Always in context | Facts that apply to every task |
| Skill | Body loads only when used | A repeatable procedure or long reference |
| Hook | Every time its event fires, whether or not Claude follows the skill | A rule that must hold every time |
The documentation recommends moving any rule that must hold every time into a hook, because Claude can stop following a skill later in a long conversation or after compaction.
What content workflows suit skills?
These patterns are our assessment from building content tools, not claims from the documentation.
| Pattern | Skill design | Invocation |
|---|---|---|
| Voice and hook rules | Instructions only: tone, banned phrases, hook formats | Automatic by description |
| Plan to rendered slides | Instructions plus a script that renders from a plan file | Manual /render-carousel with disable-model-invocation |
| Caption batch | Instructions plus a checklist the output must pass | Automatic or manual |
| Publishing | Anything that posts or sends | Manual only; never automatic |
How do you vet a skill before running it?
- Read
SKILL.mdand every script it references. - Check
allowed-tools: the documentation warns that a project skill's allowed-tools applies even in a folder you have never trusted. - Look for shell commands injected with the
!syntax, which run before the content reaches Claude. - Check the licence and requirements.
- Run it first on a throwaway topic and read the output.
For free versus paid carousel skills see Claude Code Instagram Carousel Skills: Free vs Paid.
Frequently asked questions
What is a Claude Code skill?
A folder with a SKILL.md file: YAML frontmatter that tells Claude when to use it, and markdown instructions Claude follows when the skill runs. It can also include reference files and scripts.
When does Claude use a skill?
When it judges the skill's description relevant to your request, or when you invoke it with /skill-name. Setting disable-model-invocation: true limits it to manual use.
Where do I put a skill so it works in every project?
In ~/.claude/skills/<skill-name>/SKILL.md for a personal skill. Project skills go in .claude/skills/ inside the repository.
Why is my skill not triggering?
The documentation suggests checking that the description contains the keywords you naturally use, confirming the skill is listed, rephrasing your request, or invoking it directly. Malformed YAML leaves Claude without a description to match.
Are skills safe to install from GitHub?
Review them first. A project skill's allowed-tools setting applies even in an untrusted folder, and skills can run scripts and shell commands, so read SKILL.md and any scripts before running.
The Content Engine researches a niche, writes post ideas and renders carousels (PNG) and reels (MP4) on your own computer. USD 67 one time, 7-day refund. It needs a paid Claude plan (Pro or higher), Node.js and FFmpeg, and we have tested it on Windows only.
See the Content EngineSources and our data
- Claude Code docs: Extend Claude with skills — read in full 2026-10-30; the page shows no date and names versions up to v2.1.309
- Our own assessment: the content workflow patterns table reflects how we structure our own tools; it is not from the documentation.
Go deeper: how The Content Engine works · pricing and the 7-day refund · compare the options · glossary of Instagram terms · all guides
Keep reading
GuideClaude Code Instagram Carousel Skills: Free vs PaidWhat a free Claude Code carousel skill does, what a paid kit adds, how to vet any skill.
GuidePlan 30 Days of Instagram Carousels in One Afternoon With ClaudeFour pillars, 40 ideas, 30 slots and the Claude prompts to fill them in one afternoon.
GuideHow to Make Instagram Carousels With ClaudeClaude writes one idea per slide, code renders the slides, you check every frame.Facts last verified 2026-10-30 against the sources listed above; pages can change, so check the source before relying on a number. Results vary. No promise of views, followers or income. The Content Engine is an independent product, not made or endorsed by Meta, Instagram or Anthropic. Claude is named only as the tool it runs on.