Your first Skill in 30 minutes, when slash commands aren't enough

Slash commands are great, as long as you remember to type them. That is exactly where the problem is. After three weeks you know that you wanted /review, but you just do not type it anymore. Skills solve exactly that. They are Markdown files like slash commands, but they trigger automatically when Claude recognizes in the prompt that the skill fits. You say "take a look at the auth code", and Claude silently loads your simplify skill in the background and works accordingly. I will show you how to write your first useful skill in 30 minutes and where the pitfalls are.

1. Understand how skills work technically

A skill is a directory under ~/.claude/skills/<name>/ with at least one file in it: SKILL.md. The frontmatter at the top defines when the skill should trigger. The body is the instruction for what Claude should do when it triggers. On every prompt Claude scans the frontmatter of all available skills and decides, based on the description, whether one matches. If yes, it loads the body as additional context and uses it for the answer.

That means: the description in the frontmatter is not documentation, it is the trigger mechanism. If it says "for German blog posts", it triggers on "write me a blog post in German". If it says "use this skill for code review", it does not trigger because "code review" is too vague. Precise triggers are everything.

2. Create your first skill

Make the directory and the file:

mkdir -p ~/.claude/skills/simplify
cat > ~/.claude/skills/simplify/SKILL.md <<'EOF'
---
name: simplify
description: |
  Use when reviewing code the user just wrote or edited. Looks
  for unused imports, duplicated logic, premature abstractions,
  dead error paths, and overlong functions. Triggers on phrases
  like "review this", "check my code", "anything to clean up".
---

# Simplify

When invoked:

1. Read the changed files in the working directory
2. Look specifically for:
   - Unused imports or variables
   - Logic duplicated within 50 lines
   - Functions over 60 lines that could split
   - Catch blocks that swallow errors silently
   - Premature abstractions used only once
3. Return max 5 concrete findings with line numbers
4. No general praise, no "looks good overall", just findings
EOF

Save it, done. Claude Code does not need to be restarted, live detection picks it up. If you now type "review my last file", Claude should silently load the skill and look for the named patterns.

3. The description is your trigger, not your documentation

This is the one point where beginners always fail. They write something like description: A code review helper and wonder why the skill never triggers. Claude decides based on the description whether the skill fits, so it has to say concretely WHEN it should fit. Format it as "Use when..." plus typical trigger phrases.

Bad: description: Helps with code review.

Good: description: Use when the user asks you to review, check, or clean up code they just wrote. Looks for duplication and dead code. Triggers on "review this", "any improvements", "code smell".

Write as much in there as needed so Claude can match reliably. 200 to 400 characters is common. Above that it gets redundant, below it triggers unreliably.

4. Limit allowed-tools when security matters

If your skill should run bash commands or write files, you can narrow the permissions via frontmatter. This is not cosmetic, it prevents the skill from accidentally running rm -rf because the LLM output went sideways.

---
name: deploy-staging
description: Use when the user says "deploy to staging" or "push to staging". Runs the staging deploy script and reports back.
allowed-tools: Bash(./scripts/deploy-staging.sh), Read
---

# Deploy Staging

1. Run `./scripts/deploy-staging.sh`
2. Tail the last 50 lines of output
3. Report success or failure clearly

The Bash(./scripts/deploy-staging.sh) entry allows only exactly this one command. Other bash calls still ask for confirmation. That way you build a skill that can do a lot, but does not kill your server by accident.

5. Bundle scripts and references

Skills are allowed to be more than just SKILL.md. You can pack in helper files that Claude reads when needed. Directory layout:

~/.claude/skills/release-notes/
├── SKILL.md
├── scripts/
│   └── git-summary.sh
└── references/
    └── tone-guide.md

In SKILL.md you then point to them:

# Release Notes

When invoked:
1. Run `./scripts/git-summary.sh` to get commits since last tag
2. Read `./references/tone-guide.md` for our style
3. Write release notes following the tone guide

Advantage: the skill stays readable, logic lives in scripts, style guides in reference files. On updates you only edit the relevant file, not everything at once.

6. Version skills and share them in the team

Personal skills live in ~/.claude/skills/. Project skills in .claude/skills/ in the repo, those you commit. Advantage of project skills: everyone on the team gets the same setup automatically. Disadvantage: your weekly-review skill does not spill into the next repo.

My setup: what is project-specific (coding standards, deploy scripts, internal tone of voice) lives in the repo. What is generally useful (simplify, debrief, tone-fix) lives in the home dir. A private skill ~/.claude/skills/dailylog/ that manages my own notes, I do not want in every client repo.

If you share skills with others who do not work in the same repo: pack them into a git repo, have people clone it into ~/.claude/skills/. The plugin system is overkill before you have 10 skills.

7. Three skills almost everyone needs

So you do not start from zero, three skills that have proven themselves for me.

simplify, already shown above. Let it trigger after every larger edit, catches 80 percent of "oh right, I forgot to clean that up".

debrief, called at the end of a session. Reads the last 20 actions, writes a short summary, saves it to nex_summarize or a memory tool. That way you still know days later what went on in that one session.

deutsche-texte, when you often write in German. Forces real umlauts instead of oe/ae/ue/ss. Triggers on "schreib mir nen", "erstell einen Post auf Deutsch", "uebersetz das ins Deutsche".

---
name: deutsche-texte
description: Use when writing German text users will see (blog posts, landing pages, social media, i18n strings). Forces real umlauts ä, ö, ü, ß instead of ASCII digraphs ae, oe, ue, ss. Skip for filenames, slugs, code identifiers.
---

# Deutsche Texte

When the user asks for German text:
- Use real umlauts: ä, ö, ü, ß
- Never use ASCII digraphs: ae, oe, ue, ss
- Exception: file paths, URL slugs, code identifiers stay ASCII
- After writing, scan output once for accidental digraphs

Three small files, immediate payoff.

8. When skill, when slash command

Both are Markdown plus frontmatter, the difference is how they trigger. Skills fire when Claude recognizes it from the natural prompt. Slash commands fire only when you type /name. From that follows:

Skills are better for things Claude should always do when the context fits. Code review after every edit. Tone check on German texts. Debrief after end of session.

Slash commands are better for things you want to trigger explicitly. Deploy. Test run with specific flags. Status snapshot where you know exactly that you need it now.

Rule of thumb: if you would forget to start it manually, make a skill. If it is destructive or expensive, make a slash command so you have to consciously type it.

9. The two mistakes everyone makes at the start

Trigger phrased too vaguely. If you write description: Code helper, the skill triggers either on every prompt or never. Both are crap. Put concrete trigger phrases in, "Use when..." format, at least two example user sentences.

Body too vague. If the body reads "review the code carefully", you get a wall of text back. Put acceptance criteria in. Max number of findings, concrete output form, what should NOT come back. Just like with slash commands: a skill is only as good as the prompt in it.

Bonus mistake: creating too many skills at once. You do not remember which ones you have, they collide in triggers, one triggers where another should. Start with three. Only build more once the three really run.

10. What is next

Once the first three skills run, you will notice that some patterns repeat. That is exactly when it becomes time for hooks, which run automatically on events without a prompt even being needed. Look at the playbook Hooks gegen Halluzinationen if you want the next level.

If you want to share skills with others and distribution becomes important, look at the playbook MCP Server publishen, which applies analogously to skill bundles too. And if you want to get into more complex workflows, Erster Sub-Agent in 30 min shows how to expand a skill into a dedicated sub-agent.

My tip: create a single skill now, simplify, with the frontmatter from step 2. Let it run for a week. Then you will know yourself what you are still missing and which skill makes sense next.

Source

Specs verified via verify_anthropic_doc_spec against the official docs on 2026-05-06:

• https://code.claude.com/docs/en/skills (frontmatter reference, allowed-tools, bundled scripts, live change detection, auto-discovery)

Recipes consulted in the Academy:

• Phase 1, Recipe 1.2 "Skills", short introduction with trigger examples
• Lesson L4-04 "Hooks und Skills", conceptual distinction