Skill Scaffold Generator
Generate a valid SKILL.md with the right frontmatter.
- $29 Free
- 45 sec
- No signup
Name the skill and its trigger
Describe what it does
Copy the SKILL.md scaffold
You get: A valid SKILL.md scaffold with correct frontmatter and outline.
Define your skill
commit-writer/SKILL.md
--- name: commit-writer description: Writes conventional-commit messages from a staged diff. Use when the user asks to commit changes or write a commit message. Do not use when there are no staged changes to describe. --- # commit-writer ## Overview Writes conventional-commit messages from a staged diff. ## When to use this skill Use this skill when the user asks to commit changes or write a commit message. Do not use it when there are no staged changes to describe. ## Instructions 1. Read the staged diff with git diff --cached 2. Infer the change type and scope 3. Write a conventional-commit subject under 72 chars 4. Add a short body explaining the why 5. Output only the final commit message ## Notes - Keep this file focused on one capability. Split unrelated work into separate skills. - Reference supporting files with relative paths if the skill needs scripts or templates.
Save as .claude/skills/commit-writer/SKILL.md in your repo (or ~/.claude/skills/commit-writer/SKILL.md for a personal skill).
What a Skill is and how it differs from everything else
A Skill packages a repeatable capability into a folder that Claude Code loads on demand. The heart of it is SKILL.md - a markdown file with YAML frontmatter (a name and a description) followed by the instructions. Unlike a subagent, a skill does not run in its own separate context or hold its own tool permissions; it is guidance that the current session pulls in when the task matches. Think of a subagent as a specialist you delegate to, and a skill as a playbook the session opens when it is relevant.
The design goal of a skill is progressive disclosure. The short description is always visible so Claude knows the skill exists and when it applies. The full body is only loaded when the skill actually fires. That keeps your context lean while still giving Claude a deep, reliable procedure the moment it is needed.
The two frontmatter fields that matter most
- name - a short, kebab-case identifier for the skill. It should match the folder the SKILL.md lives in (for example, commit-writer/SKILL.md).
- description - the single most important line in the file. It must say both what the skill does and, precisely, when to use it. This is what Claude reads to decide whether to load the skill, so vague descriptions mean the skill never fires.
Write the description for the trigger, not the brochure
A weak description says 'Helps with commits.' A strong one says 'Writes conventional-commit messages from a staged diff. Use when the user asks to commit or write a commit message.' The 'use when' clause is what makes the skill activate at the right moment.
How to structure the body
- Overview - one or two sentences on what the skill accomplishes, so anyone reading the file understands its purpose fast.
- When to use - restate the trigger conditions in the body, and add when NOT to use it. Explicit boundaries stop the skill from firing on tasks it does not fit.
- Instructions - a numbered, concrete procedure. Each step should be an action Claude can actually take, ending with a verification step so the work is checked, not assumed.
- Notes / references - point to any supporting scripts or templates in the skill folder using relative paths, and note anything the reader should know.
Keep each skill to one capability
The most common mistake is a kitchen-sink skill that tries to do five loosely-related things. That makes the description hard to write, so the skill either never triggers or triggers on the wrong tasks. One skill, one job. If you find yourself writing 'and also' in the description, that is the signal to split it into two skills. Small, sharply-scoped skills compose better and fire more reliably than one sprawling one.
Where skills live
A project skill lives at .claude/skills/<name>/SKILL.md inside your repo, so it is committed and shared with your team. A personal skill lives at ~/.claude/skills/<name>/SKILL.md and follows you everywhere. The folder can hold more than just SKILL.md - scripts, templates, and reference docs the instructions point to all live alongside it. When Claude loads the skill, it can read those supporting files as needed.
Bundling scripts and templates with a skill
Because a skill is a folder, not just a file, it can carry its own assets. If your procedure needs a shell script, a config template, or an example output, drop those in the same folder and reference them by relative path in the instructions. This is what turns a skill from a prose reminder into a genuine, executable capability - the instructions tell Claude what to do, and the bundled files give it the exact tools to do it consistently.
How to test that a skill fires
- Save the SKILL.md, then start a task that clearly matches the trigger and check that Claude reaches for the skill.
- Try a near-miss task that should NOT trigger it, to confirm the boundaries in your description are tight enough.
- If it fires too rarely, the description is too narrow or missing the 'use when' clause; if it fires too often, the boundaries are too loose.
- Iterate on the description first - it is the lever that controls activation - before touching the body.
Frequently asked questions
What is a Claude Code Skill?
A skill is a folder containing a SKILL.md file that packages a repeatable procedure. Claude loads it on demand when the task matches the skill's description, giving the session a reliable playbook without cluttering the context until it is needed.
Where does SKILL.md go?
At .claude/skills/<name>/SKILL.md in your repo for a project skill shared with your team, or ~/.claude/skills/<name>/SKILL.md for a personal skill that follows you across projects. The folder name should match the skill name.
What is the difference between a skill and a subagent?
A subagent runs in its own separate context with its own tool permissions and is delegated a task. A skill is guidance loaded into the current session when relevant. Use a subagent to offload work, a skill to give the session a procedure.
Why does my skill never trigger?
Almost always the description. If it does not clearly state when to use the skill, Claude will not know to load it. Add an explicit 'Use when...' clause describing the exact conditions that should activate it.
Can a skill include scripts or templates?
Yes. The skill is a folder, so you can bundle scripts, templates, and reference files alongside SKILL.md and point to them by relative path in the instructions. That is how a skill becomes an executable capability rather than just a note.
How long should a SKILL.md be?
Long enough to be a complete procedure, short enough to stay focused on one capability. If the description needs an 'and also', split it into two skills. Concise, single-purpose skills fire more reliably than sprawling ones.
Liked this tool? The club is the next step.
Join Claude Code Club for $9/month. 650+ lessons, weekly updates, and the workflows behind every tool on this site.
- No experience needed
- Cancel anytime
- Updated weekly