Writing Claude Skills - Jayaprakash Sundararaj

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:

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:

Pick one workflow you do regularly
Example: "I format blog post dates from random formats into YYYY-MM-DD"
Write down the exact steps
Example: Check for multiple date formats → Convert to ISO format → Update frontmatter
Create a skill folder with SKILL.md
Example: ~/.claude/skills/blog-date-formatter/
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"
Write instructions in markdown
Example: "Look for dates in these formats: 'July 11, 2026' or '7/11/26' → Always convert to 2026-07-11"
Test it with real examples
Example: Paste an actual blog post you wrote and see if Claude fixes the dates right
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.