What is a Claude Code skill?
A folder containing a SKILL.md file that teaches Claude how to do one specific job. Claude loads it when a task matches the skill's description.
Claude Code
Claude Code skills: turn a repeated job into something you ship
A Claude Code skill is a folder with a SKILL.md file that teaches Claude how to do one job your way. Claude reads the short description first and loads the full instructions only when a task matches, so you can keep many skills without crowding every session.
Updated September 30, 2026 · By Dr. Sam Sammane
From the TheoSym channel
Claude Code: ship the skill
Published September 21, 2026
A 43-second TheoSym short on turning a job you repeat into a Claude Code skill and shipping it to your team.
Watch on YouTubeWhat is inside a skill
The description is the most important line. It tells Claude when the skill applies, so write it the way you would describe the job to a new colleague.
- SKILL.md, with a name, a description and the instructions
- Optional files such as scripts, templates and reference documents the instructions point to
The format is documented in the Claude Code skills guide. Check it for current fields and folder locations.
Skills, project instructions and hooks: which one for what
| Tool | Best for | When it applies |
|---|---|---|
| Project instructions | Facts and rules that are always true for the project | Every session |
| Skills | A specific repeatable job with its own steps and files | When a task matches the description |
| Hooks | Rules that must never be skipped | Every time, at a set point |
Jobs that make good skills
- A release checklist or changelog format
- A pull request review with your team's standards
- A migration procedure you have run before
- A brand voice or writing guide for docs and copy
- A report your team builds the same way each week
How to write and ship a skill
Shipping is the point. A skill on one laptop helps one person. A skill in the repository raises the floor for the whole team.
- Pick a job you have explained to Claude more than twice.
- Write down the steps the way you would want them done, with one good example.
- Write a description that names the trigger clearly.
- Test it on three real tasks and tighten anything Claude got wrong.
- Commit it to the repository, so everyone on the team gets the same skill and changes are reviewed like code.
Keep skills small and honest
One skill, one job. If a skill needs to do five things, split it. Keep the instructions specific enough that a result can be checked, and pair skills with hooks for the parts that must always happen. See Claude Code best practices for the full workflow.
Claude Code skills: common questions
How is a skill different from project instructions?
Project instructions apply to every session. A skill is loaded only when a task matches its description, so it suits a specific repeatable job.
Where do I put a skill so my team gets it?
Commit it to the project repository in the skills folder described in the Claude Code docs. Everyone who pulls the repo gets the same skill.
How do I write a good skill description?
State what the skill does and when to use it, in plain language, the way you would brief a new colleague. A vague description means Claude will not know when to load it.
Should I use a skill or a hook?
Use a skill to teach a job. Use a hook to enforce a rule that must never be skipped. Many workflows use both.
Want an agent you can trust in production?
TheoSym ships production agents with the eval suite, MCP tools and harness included. Bring one real workflow to a 15-minute call with Sam and see what building it would involve.