Writing Claude Skills

, Jayaprakash

A Claude Skill hands Claude your workflow in a file, so you stop re-explaining it every session.

What I learned writing a few:

  • 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
  • A skill that does five jobs fires at the wrong time and steps on your other skills
  • Spend your effort on the description. Claude reads it first, and it decides whether your skill loads at all
    • Bad: “helps with formatting”
    • Good: “Fixes markdown syntax and formatting for blog posts when user asks to review a draft”
  • A vague description means the skill sits there unused
  • Say when the skill applies and what problem it solves
  • 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 problem you already have:

  • 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 whether Claude reaches for the skill on its own
    • Example: Does it load when you paste a blog post draft, without you naming it?
  • Fix the hardest part first
    • Example: If detecting the frontmatter format is tricky, solve that before worrying about date formatting
  • Change the instructions based on what Claude does, not what you assumed it would do
    • 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 start trusting a skill once you can see its history
    • 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 catches skills nobody needs before you write them
    • Example: If you never paste markdown to Claude, don’t build a markdown skill
  • It also gives you something to check against when the skill misbehaves
    • 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"

A skill is a file of instructions you stopped having to retype. Build one for the workflow you run most, and see whether Claude picks it up on its own.

Sources: