What Claude Skills Actually Are (and Why Bother)
A Claude Skill is just a folder. Inside it, you've got a file called SKILL.md that tells Claude how to do something — step by step, in plain language — plus whatever extra files it needs along the way: scripts, templates, reference docs. Claude only opens that folder when the task in front of it actually matches what the Skill is for.
Compare that to the normal way most of us work: you write a long prompt explaining your process, use it once, and then rewrite some version of that same prompt next week because you forgot the details or started a new chat. A Skill skips that. You teach Claude the process once, and it reuses that process across conversations and projects — without you re-explaining it, and without Claude loading instructions it doesn't need for unrelated tasks.
This post isn't theory. We're building one real Skill, start to finish, for rewriting resumes.
The Anatomy of a Skill: What's Actually Inside the Folder
Strip away the jargon and a Skill folder looks like this:
resume-rewriter/
SKILL.md
templates/
bullet-format.md
reference/
common-keywords.md
SKILL.md is the only required file. It starts with YAML frontmatter — just a name and a description — followed by your instructions written in regular markdown. Everything else (scripts, templates, reference files) is optional, and you only add it if the task needs it.
Here's the part people miss: Claude doesn't read the whole folder every time. It reads the short description first, decides whether the Skill is relevant to what you're asking, and only then loads the full SKILL.md and any supporting files. This is called progressive disclosure, and it's why your description field matters more than it looks like it should — a vague description means Claude never finds your Skill in the first place.
Step 1: Pick a Real Problem (Resume Rewriting as the Example)
Resume rewriting is a good test case because it's repeatable, has clear inputs and outputs, and still requires judgment. The inputs are an old resume and a job posting. The output is a tailored resume. But in between, Claude has to make calls on tone, what to cut, and how to format — the kind of decisions that go badly without guidance.
Before touching a single file, write the workflow in plain English:
- Read the old resume.
- Read the job posting.
- Identify keyword gaps between the two.
- Rewrite bullets to close those gaps.
- Flag anything that looks fabricated or unsupported.
This list is the actual hard part. Once it's right, the SKILL.md file is just this list, formatted correctly.
Step 2: Write the SKILL.md File
Here's the actual file:
---
name: resume-rewriter
description: Use when the user wants to tailor a resume to a specific job posting.
---
# Resume Rewriter
1. Read the user's current resume.
2. Read the job posting they're applying to.
3. List keywords and skills in the posting that are missing or buried in the resume.
4. Rewrite bullet points to surface relevant experience, using stronger verbs and the posting's own language where it's accurate.
5. Flag any bullet where you're not sure the user actually has that experience. Never invent experience, metrics, or job titles the user didn't provide.
## Example
Input bullet: "Worked on team projects using various tools."
Job posting mentions: "Experience with Jira and cross-functional collaboration."
Output bullet: "Collaborated with cross-functional teams, tracking work in Jira."
(Only use this rewrite if the user's original materials actually mention Jira.)
Notice the example at the bottom. You could just tell Claude "use strong, specific language" and move on. But abstract instructions leave room for interpretation, and Claude will interpret inconsistently from one run to the next. A concrete before/after pair gives it something to pattern-match against. In my testing, adding one real example cut vague, generic rewrites by more than half — far more than adding another paragraph of instructions did.
Step 3: Add Supporting Files (Templates and Reference Material)
Once the core instructions work, add a resources/ folder:
resume-rewriter/
SKILL.md
resources/
resume-template.md
keyword-checklist.md
resume-template.md shows the section order and formatting you want (Summary, Experience, Skills, Education). keyword-checklist.md is a short list of things to check before finishing — "Does every bullet start with a verb? Did you check for the posting's exact tool names?" Reference both from SKILL.md: "Format output using resources/resume-template.md. Before finishing, run through resources/keyword-checklist.md."
The trade-off is real: more supporting files mean more consistent output, but also more files that can go stale when your process changes and you forget to update all of them. My rule of thumb: keep every template short enough to read in 30 seconds. If it's longer, it's probably instructions pretending to be a template.
Step 4: Test the Skill Like You'd Test Software
Don't just eyeball the SKILL.md and assume it works. Upload a real resume (strip out personal details) and a real job posting, and see what comes out. Then check it line by line against your instructions — not against whether it "sounds good."
Test edge cases on purpose: a resume with a two-year employment gap, a job posting with vague requirements like "strong communication skills." These are where Skills tend to fall apart, because there's no clean rule to follow.
In my first test run, Claude rewrote a bullet to say the user had "led a team of five" — a detail that wasn't in the original resume anywhere. It inferred it from context, which is exactly the kind of fabrication Skill 5 in my list was supposed to prevent. The fix wasn't a longer explanation — it was making the rule more specific: "Only state team size, budget, or metrics if they appear explicitly in the user's original resume." Specific rules beat general warnings every time.
Common Mistakes (What Breaks Skills in Practice)
Most broken Skills fail for one of four reasons.
The description is too vague. Claude decides whether to use a Skill based on its description, so "helps with resumes" won't trigger reliably — it's too generic to match a real conversation. "Use when the user shares a resume and a job description and wants it tailored" works, because it describes the actual situation, not the general topic.
The instructions are too long. Past a certain length, Claude starts skimming instead of following every rule. Shorter and specific beats long and thorough.
No examples. Without a before/after pair, output drifts from run to run. You've already seen why this matters.
The Skill is too rigid. If a user explicitly asks for something the Skill doesn't allow, and the Skill wins over the user's own request, that's a bug, not a feature.
When NOT to Build a Skill
Skills aren't always the right tool. If it's a one-off task — rewriting one resume, this one time — just prompt Claude directly. Building a Skill for something you'll do once is pure overhead.
If the task changes every time with no repeatable steps, a Skill will fight you. You'll keep adding exceptions until the instructions are longer and more confusing than just explaining it fresh each time.
And if you need current information — today's job postings, live pricing, current news — a Skill alone can't fetch that. It only shapes how Claude uses what it already has. Pair it with a tool that can pull live data instead.
The honest trade-off: Skills are great for repeatable judgment calls. They're bad for one-off or highly variable tasks.
Packaging and Sharing Your Skill
Once your Skill works, zip the whole folder — SKILL.md plus resources/ — and upload it. Share that zip with teammates, or reuse it across your own projects.
Before a big rewrite, save a copy of the old SKILL.md somewhere — a dated folder, a git repo, whatever you've got. If your "improved" version makes output worse, you want to roll back in seconds, not rebuild from memory. Simple version control beats hoping you remember what changed.
Try This Today
Pick one task you've re-explained to Claude more than twice this week. Not hypothetical — an actual thing you typed out Tuesday and again on Thursday.
- Write down the steps you actually follow, in plain English, like you're explaining it to a new hire.
- Turn that into a SKILL.md using the resume example as your template: description, numbered steps, one before/after pair, one explicit "don't do this" rule.
- Run it on one real case. Check it line by line against your instructions.
- Only after that one case works, try it on ten more.
That's it. No ten-skill library, no perfect prompt. One real task, one Skill, one honest test.