Writing Claude Skills

A Claude Skill teaches Claude how to do something your way. It’s like sharing your personal workflow so Claude can help you faster.

Tips for writing skills that actually work:

• One skill = one job. Don’t try to do everything in one skill
  • Bad: “My coding helper” (does linting, formatting, testing, docs, reviews)
  • Good: “Markdown linter for my blog posts” (only fixes markdown)
• If you have 3 different workflows, make 3 separate skills
• Skills that do too much are messy and don’t work well together
• Write a really good description—Claude reads this first to know when to use it
  • Bad: “helps with formatting”
  • Good: “Fixes markdown syntax and formatting for blog posts when user asks to review a draft”
• Vague description = Claude won’t know when to use your skill
• Be specific about when and why someone needs it
• Make it condition-based (when X happens, use this skill)
  • Example: “Use this when user provides git diffs to fix merge conflicts”

Start with one real problem you actually need to solve:

• Pick one actual thing you need to do, not something you imagine might be useful
  • Example: “I always struggle formatting my blog post frontmatter” is better than “I want to help with writing someday”
• Test if Claude actually uses your skill
  • Example: Does Claude automatically load it when you paste a blog post draft?
• Fix the hardest part first
  • Example: If detecting the frontmatter format is tricky, solve that before worrying about date formatting
• Iterate based on what actually happens
  • Example: If Claude keeps adding extra blank lines, adjust the instructions instead of guessing why

Get the structure right:

• Skills are just folders with a SKILL.md file
• The file needs YAML frontmatter at the top
• Two required fields: name and description
• Everything else is markdown instructions

File organization matters:

• Put templates (files Claude copies) in templates/ folder
  • Example: templates/blog-post-template.md is a blank post structure Claude fills in
• Put reference docs (files Claude reads) in references/ folder
  • Example: references/markdown-style-guide.md tells Claude your formatting rules (but isn’t copied)
• Folder names tell Claude what each file does
• Don’t mix templates and references in the same folder
  • Bad: Everything in one folder with confusing names
  • Good: Clear folders so Claude knows what to do with each file

Keep your skills in version control:

• Keep your skills in a Git repo (like on GitHub)
  • Example: ~/.claude/skills/ as a git repo synced with GitHub
• If they’re just on one computer, they drift and become inconsistent
  • Problem: You edit a skill on laptop but forget the changes on desktop
• Committing to a personal repo keeps all your machines synced
  • Example: git push after tweaking your skill, then git pull on your work computer
• You’ll actually trust them when you can track changes
  • Example: When something breaks, you can see exactly what changed and when

Write your tests first:

• Know what success looks like before you code
  • Example: “Input: messy blog post → Output: clean frontmatter with correct date format”
• This stops you from building something nobody needs
  • Example: If you never actually paste markdown to Claude, don’t build a markdown skill
• Makes debugging way easier later
  • Example: When Claude adds wrong formatting, you have specific test cases to check against

Quick start process with a real example:

1. Pick one workflow you do regularly
   • Example: “I format blog post dates from random formats into YYYY-MM-DD”
2. Write down the exact steps
   • Example: Check for multiple date formats → Convert to ISO format → Update frontmatter
3. Create a skill folder with SKILL.md
   • Example: ~/.claude/skills/blog-date-formatter/
4. Add clear name and description
   • Example: name: “blog-date-formatter”, description: “Converts messy blog post dates to ISO format YYYY-MM-DD when user pastes content”
5. Write instructions in markdown
   • Example: “Look for dates in these formats: ‘July 11, 2026’ or ‘7/11/26’ → Always convert to 2026-07-11”
6. Test it with real examples
   • Example: Paste an actual blog post you wrote and see if Claude fixes the dates right
7. Commit to GitHub
   • Example: git commit -m "Add blog date formatter skill"

Skills aren’t magic, but they make Claude way more useful when you build them right.

Sources:

• Skill authoring best practices - Claude Platform Docs
• The Complete Guide to Building Skills for Claude
• How to create a Claude Code skill
• 7 Rules for Creating an Effective Claude Code Skill
• Teach Claude your way of working using skills