You have pasted the same brand voice notes into Claude forty times. Every brief starts with “here’s our audience, here’s our tone, here’s what we never say.” Then a new chat forgets all of it.
A Claude Code skill fixes that. You write the instructions once, in a folder, and Claude loads them when the job calls for it. This guide shows you how to build a Claude Code skill from an empty folder to a tested, working brand-voice skill. No engineering background needed. You need a text editor and about an hour.
New to the idea? Start with what Claude Code skills are and come back.
What a Claude Code skill is (the 60-second answer)
A Claude Code skill is a folder containing a file called SKILL.md. The file opens with a short YAML header (frontmatter) that names the skill and describes when to use it, followed by plain Markdown instructions. Claude reads every skill’s description at the start of a session and loads the full instructions only when your request matches.
That last part matters for marketers. According to Anthropic’s Claude Code skills docs, only the description sits in context until the skill is invoked. So you can keep a dozen skills installed (brand voice, content briefs, SEO checklist, email QA) without stuffing all of them into every conversation.
Where skills live
| Location | Path | Who gets it |
|---|---|---|
| Personal | ~/.claude/skills/<skill-name>/SKILL.md | You, in every project on this machine |
| Project | .claude/skills/<skill-name>/SKILL.md | Anyone who opens this repository or folder |
| Plugin | <plugin>/skills/<skill-name>/SKILL.md | Anyone who installs the plugin, invoked as /plugin-name:skill-name |
| Enterprise | Managed settings directory | Everyone on managed machines |
If two skills share a name, the docs say enterprise beats personal and personal beats project.
Rule of thumb: put a skill in ~/.claude/skills while you build it. Move it into a project’s .claude/skills folder when your team should share it. Package it as a plugin when people outside the team need it.
Two ways a skill runs
- Claude invokes it when your message matches the description. You ask “write a LinkedIn post about our spring launch” and the brand-voice skill loads.
- You invoke it by typing
/skill-nameat the start of a message, for example/brand-voice draft a welcome email.
Takeaway: a skill is a reusable prompt with a trigger. The trigger is the description, which is why most of this guide is about writing that one field well.
Study the best existing skills before you build your own
Before you write a line, read three or four skills that already work. Good public skills show you description phrasing that triggers, how authors split long instructions into reference files, and what a realistic size looks like. It costs nothing and saves you the most common beginner mistakes.
Free GitHub repos worth reading
Star counts below were pulled from the GitHub API on 1 November 2026. They change daily, so treat them as a snapshot.
| Repo | Stars (1 Nov 2026) | What to study in it |
|---|---|---|
| anthropics/skills | ~186,200 | Anthropic’s own examples, including brand-guidelines, doc-coauthoring, internal-comms and skill-creator. The closest thing to a reference style. |
| ComposioHQ/awesome-claude-skills | ~78,500 | A curated directory. Useful for finding skills by category rather than as a model to copy. |
| coreyhaines31/marketingskills | ~57,800 | Marketing skills such as copywriting, cro, seo-audit, ai-seo and emails. Note how product-marketing acts as a shared context skill other skills check first. |
| alirezarezvani/claude-skills | ~29,100 | A large mixed library that includes marketing skills. Good for comparing many description styles side by side. |
| TheCraigHewitt/seomachine | ~7,600 | An SEO content workflow built on Claude Code. Shows how a multi-step writing process gets broken into pieces. |
| AgriciDaniel/claude-blog | ~2,600 | A blog-writing skill set. Handy for seeing how a long writing pipeline is staged. |
Anthropic also publishes knowledge-work-plugins, which includes a marketing plugin. Reading a plugin shows you how several skills get bundled together.
Most of the community repos install with the skills CLI, for example:
npx skills add coreyhaines31/marketingskillsThe repo’s README also documents --skill to pick individual skills and -a claude-code to target Claude Code. For the full install walkthrough, see how to install Claude Code skills.
Paid packs and vendors
Paid skill bundles exist. Prices below come from the vendors’ own pages as of 1 November 2026. We have not bought or audited these packs, so this is a listing, not a recommendation.
| Pack | Stated price | Notes |
|---|---|---|
| SuperSkills | $50 one-time | The vendor’s page describes a bundle of 139 skills delivered as a ZIP. |
| OpenClaw Revenue skills bundle | $79 lifetime, $199 team tier | Per the vendor page. |
A word of caution. Some packs advertise thousands of skills and countdown-style “slots left” offers. Count matters less than quality, and you can read every free repo above before deciding whether to pay. If a vendor will not show you a sample SKILL.md before purchase, that tells you something.
What to look for when you read a skill
- The description. Does it say what the skill does and when to use it, with concrete trigger phrases?
- Length. Is
SKILL.mdshort, with detail pushed intoreferences/? - Steps. Are instructions numbered and checkable, or a wall of advice?
- Examples. Does it show a good output and a bad one?
- Boundaries. Does it say what the skill should not do?
Takeaway: borrow structure, not text. Your brand voice is the part no public repo can give you.
How to build a Claude Code skill in 7 steps
Building a skill takes seven steps: pick one repeated job, create the folder, write the frontmatter, write the instructions, add reference files, add scripts if needed, then test. Each step below is small. The order matters, because the job you pick shapes every field after it.
Step 1: Pick one job you repeat every week
The best first skill is boring. It is something you already do the same way each time:
- Applying brand voice to drafts
- Turning a keyword into a content brief
- Checking a page against an on-page SEO checklist
- Rewriting product copy into three ad variants
Avoid “do all my marketing.” One skill, one job. If you want ideas by role, see Claude Code skills for marketers and skills for content writers.
Step 2: Create the folder
Open a terminal and run:
mkdir -p ~/.claude/skills/brand-voice
touch ~/.claude/skills/brand-voice/SKILL.mdUse lowercase letters and hyphens for the folder name. The docs say name defaults to the folder name, so a clean folder name gives you a clean slash command.
Step 3: Write the frontmatter
Frontmatter sits between two --- lines and must start on the very first line of the file. Here is the minimum:
---
name: brand-voice
description: Applies the Acme brand voice to marketing copy. Use when writing or editing blog posts, emails, social posts, landing pages or ads for Acme, or when the user says "on-brand", "brand voice" or "make this sound like us".
---That is enough to work. The next section covers every other field.
Step 4: Write the instructions
Below the frontmatter, write Markdown the way you would brief a sharp freelancer. Numbered steps, clear rules, one example. Keep it tight: Anthropic’s docs recommend keeping SKILL.md under 500 lines and moving detail into separate files.
Step 5: Add a references folder
Long material (full style guide, persona sheets, banned-claims list) goes into references/. Link each file from SKILL.md so Claude knows when to open it.
Step 6: Add a scripts folder (optional)
If part of the job is mechanical, like counting words or flagging banned phrases, put a small script in scripts/. Claude runs it rather than reading it.
Step 7: Test, then iterate
Start a fresh session, ask for something that should trigger the skill, and watch whether it loads. We cover testing in detail below.
Takeaway: a working skill can be one file with five lines of frontmatter. Everything else is refinement.
SKILL.md frontmatter fields, checked against Anthropic’s docs
Only description is recommended; every frontmatter field is technically optional. Claude Code ignores fields it does not recognise, so a typo fails silently. The table lists the fields marketers will actually use, with meanings taken from Anthropic’s SKILL.md reference.
| Field | What it does | Should a marketer use it? |
|---|---|---|
name | The command name in the / menu. Defaults to the folder name. | Yes, match the folder. |
description | What the skill does and when to use it. Claude uses this to decide when to apply the skill. | Always. This is the trigger. |
when_to_use | Extra trigger context, such as phrases or example requests. Appended to the description. | Useful if your description gets long. |
argument-hint | Autocomplete hint, e.g. [keyword]. | Nice for brief-style skills. |
disable-model-invocation | true means only you can run it with /name. | Yes for skills that publish or send things. |
user-invocable | false hides it from the / menu so only Claude invokes it. | Rarely. |
allowed-tools | Tools Claude can use without asking during that turn. | Only for trusted scripts. |
model / effort | Model or effort level for the current turn. | Optional. |
context: fork | Runs the skill in a separate subagent. | Advanced. |
paths | Glob patterns limiting automatic activation to matching files. | Handy for content repos, e.g. content/**/*.md. |
metadata, license, compatibility | Accepted, not acted on. | For sharing. |
Two limits worth knowing
- The description cap. Per the docs,
descriptionpluswhen_to_useis truncated at 1,536 characters in the skill listing. Put the important trigger words first. - Portability. Outside Claude Code (claude.ai uploads or the Skills API), only
name,description,license,compatibility,metadataandallowed-toolsare allowed, and other keys cause an error. If you plan to share a skill with someone on claude.ai, stick to those six.
One more gotcha from the docs: if your YAML fails to parse, the skill loads with no fields set. A stray colon inside an unquoted description can do this. Wrap descriptions in quotes when they contain colons.
Takeaway: name and description cover 90% of what you need. Reach for the rest when a specific problem asks for it.
How to write a description that makes your skill trigger
A description triggers reliably when it says what the skill does, names the situations it applies to, and includes the literal phrases a user would type. Claude matches your request against every installed description. Vague text like “helps with content” gives it nothing to match.
Community write-ups on DEV and blog.fsck.com point to the description as the most common reason a skill never fires. Some Reddit users report better results with directive wording (“Use when…” or even “MUST be used when…”). Treat that as practitioner advice to test, not a rule.
Weak versus strong descriptions
| Weak | Strong |
|---|---|
| ”Brand voice skill." | "Applies the Acme brand voice to marketing copy. Use when writing or editing blog posts, emails, social posts or ads for Acme, or when the user says on-brand, brand voice or make this sound like us." |
| "Helps with briefs." | "Turns a target keyword into a content brief with search intent, outline, FAQs and internal links. Use when the user gives a keyword and asks for a brief, outline or content plan." |
| "SEO stuff." | "Checks a draft against an on-page SEO checklist (title, meta, headings, links, schema). Use when the user asks to review, audit or optimise a page or post for SEO.” |
A four-part formula
- Verb + object: “Applies the brand voice to marketing copy.”
- Contexts: list the content types (blog, email, ads, landing pages).
- Trigger phrases: the words people really type (“on-brand”, “make this sound like us”).
- Exclusions, if needed: “Do not use for legal or investor documents.”
Common description mistakes
- Starting with the skill’s backstory instead of its job
- Using internal jargon nobody types (“apply VX-2 framework”)
- Overlapping with another skill so neither wins clearly
- Burying trigger phrases past the character cap
If a skill should never run by surprise (one that posts to a CMS, say), skip the trigger-phrase work and set disable-model-invocation: true. You then run it only with /name.
Takeaway: write the description last, after you know exactly what the skill does, and read it as if you were Claude scanning 30 of them.
Using the references/ and scripts/ folders
references/ holds long documents Claude reads when needed; scripts/ holds small programs Claude runs. Splitting them out keeps SKILL.md short and readable, and means Claude loads the heavy material only for the task that needs it.
Anthropic’s docs show this layout:
brand-voice/
├── SKILL.md (overview and steps)
├── references/
│ ├── voice-guide.md (loaded when needed)
│ ├── personas.md
│ └── banned-claims.md
└── scripts/
└── check-banned.sh (executed, not loaded)What goes in references/
| File | Contents | When SKILL.md tells Claude to open it |
|---|---|---|
voice-guide.md | Tone, sentence style, words you use and avoid, before/after examples | Every drafting or editing task |
personas.md | Two or three audience profiles | When the user names an audience |
banned-claims.md | Claims legal or leadership will not approve | Before final output |
examples.md | Three approved pieces of copy | When tone is unclear |
The docs are explicit that you should link each supporting file from SKILL.md. A file Claude is never told about is a file Claude may never read.
What goes in scripts/
Scripts suit anything with a right answer: word counts, banned-word checks, reading-level scores, CSV cleanup. Reference them with ${CLAUDE_SKILL_DIR}, which the docs describe as a way to point at bundled scripts regardless of the working directory:
Run `${CLAUDE_SKILL_DIR}/scripts/check-banned.sh <file>` and fix every line it prints.You do not need to write code yourself. Ask Claude to write the script, read what it produces, and run it once on a sample file before you trust it.
Takeaway: if you would hand it to a freelancer as an attachment, it goes in references/. If you would ask them to run a checker, it goes in scripts/.
Worked example: a complete brand-voice skill
Below is a full, copy-paste brand-voice skill for a fictional company called Acme. Swap in your own voice rules, audiences and banned claims. It uses only portable frontmatter fields, so it also works if you upload it to claude.ai.
The full SKILL.md
---
name: brand-voice
description: "Applies the Acme brand voice to marketing copy. Use when writing, editing or reviewing blog posts, emails, social posts, landing pages or ads for Acme, or when the user says on-brand, brand voice, our tone, or make this sound like us. Do not use for legal, HR or investor documents."
---
# Acme brand voice
You write and edit marketing copy for Acme, a project-management tool for small agencies.
## Before you write
1. Read `references/voice-guide.md` in full.
2. If the user names an audience, read the matching section of `references/personas.md`. If not, ask one question: "Who is this for: agency owners or project managers?"
3. Confirm the format (blog, email, social, ad, landing page) and the length.
## Voice rules (summary)
- Plain, direct and warm. Write like a project lead talking to a peer.
- Second person ("you"). Short sentences, mixed with the occasional longer one.
- Lead with the reader's problem, then the outcome, then the feature.
- Use numbers only when the user supplies them or they appear in `references/`.
- British or American spelling: American.
## Never
- Invent statistics, customer names, quotes or results.
- Use these words: revolutionary, game-changer, seamless, unlock, leverage, synergy.
- Promise outcomes ("guaranteed", "double your revenue").
- Make any claim listed in `references/banned-claims.md`.
## Process
1. Draft the copy following the rules above.
2. Run `${CLAUDE_SKILL_DIR}/scripts/check-banned.sh` on the draft if you saved it to a file, and fix each flagged line.
3. Check the draft against the "Before/after" examples in `references/voice-guide.md`.
4. Return the copy, then a short note listing any claims that need proof from the user.
## Output format
- The finished copy first, ready to paste.
- Then a heading "Needs proof" with a bullet list, or "None".
## Example
User: "Make this on-brand: Our revolutionary platform seamlessly streamlines agency workflows."
Good output:
"Stop chasing status updates in five different apps. Acme puts every client project on one board, so you can see what is late before your client does."
Needs proof: None.The supporting files
A minimal references/voice-guide.md needs four parts: a one-paragraph description of the voice, a “we say / we don’t say” table, three before/after rewrites, and formatting rules per channel.
A starter scripts/check-banned.sh can be a one-line grep:
#!/bin/bash
grep -n -i -E "revolutionary|game-changer|seamless|unlock|leverage|synergy" "$1"Make it executable with chmod +x scripts/check-banned.sh.
Variation: a content-brief skill
The same pattern works for briefs. Change three things:
| Part | Brand voice | Content brief |
|---|---|---|
| Description trigger | ”on-brand”, “make this sound like us" | "brief”, “outline”, “content plan for [keyword]“ |
argument-hint | none | [keyword] |
| References | voice guide, personas, banned claims | brief template, internal link list, SERP checklist |
SEO people can go deeper with Claude Code skills for SEO and skills for keyword research.
Takeaway: steal this structure, replace every Acme detail, and you have a working skill today.
How to test a Claude Code skill
Test a skill by triggering it two ways (by request and by /name), checking the output against your rules, and comparing against a session without the skill. A skill that loads but produces off-brand copy is still broken.
A simple test plan
| Test | How | Pass looks like |
|---|---|---|
| Listing | Run /skills in Claude Code | brand-voice appears |
| Direct call | Type /brand-voice rewrite: [paste copy] | Skill loads, follows the process |
| Natural trigger | Fresh session: “write a LinkedIn post for Acme’s launch” | Claude loads the skill without being told |
| Near miss | ”Write our privacy policy” | Skill does not load (it is excluded) |
| Rule check | Feed it copy full of banned words | All flagged and removed, nothing invented |
| Baseline | Same prompt with the skill turned off | Clear difference in tone |
The docs describe turning off personal or project skills for a baseline by setting them to "off" in skillOverrides, and running realistic prompts in fresh sessions with and without the skill.
Fixing the usual failures
- Never triggers: rewrite the description with the exact phrases you used in your test prompt.
- Triggers on the wrong tasks: add an exclusion line, or narrow the contexts.
- Loads but ignores rules: move the most important rules higher in
SKILL.mdand make them numbered steps. - Breaks after an edit: check your YAML. The docs note that a parse failure loads the skill with no fields set. Run
claude --debugto see what was loaded.
Edits to files under ~/.claude/skills/ or .claude/skills/ are picked up in the same session, per the docs. If you created a brand-new top-level skills directory, run /reload-skills.
Takeaway: write your five test prompts before you edit anything, then rerun them after every change.
Iterating: how good skills get better
Iteration means running the skill on real work, noting each output you had to fix by hand, and turning each fix into a rule, example or reference file. Your first version will be wrong in small ways. That is normal.
A practical loop:
- Use the skill on five real tasks.
- Keep a list of every manual correction.
- Group corrections. Tone issues go to
voice-guide.md. Process issues go toSKILL.mdsteps. Repeated mechanical fixes become a script. - Add one before/after example for each recurring mistake.
- Rerun your test prompts.
Watch the size. When SKILL.md creeps toward the 500-line guideline, move sections into references/. When a skill tries to do two jobs, split it into two skills with clearly different descriptions.
Version your skills if a team uses them. A project skill in .claude/skills/ can sit in Git, so changes get reviewed like any other file. For teams without engineers, Claude Code skills for non-developers covers simpler setups.
Takeaway: every hand-edit you make is a missing line in your skill.
Using the skill-creator skill to build skills faster
Anthropic’s skill-creator is a skill that builds and tests other skills. You describe the job, it interviews you, drafts the SKILL.md, and can write test cases. It lives in the anthropics/skills repo.
According to Anthropic’s docs, you can install it as a plugin:
/plugin install skill-creator@claude-plugins-officialThe docs say it writes test cases to evals/evals.json, runs them in isolated subagents and grades the results.
How to brief skill-creator
Give it what a human would need:
- The job, in one sentence
- Two or three real examples of good output
- Your rules and banned claims (paste them or point to files)
- The phrases you want to trigger the skill
- What it should not do
Hand-built versus skill-creator
| Hand-built | skill-creator | |
|---|---|---|
| Speed to first draft | Slower | Faster |
| Control over wording | Full | You edit afterward |
| Test cases | You write them | Generated for you |
| Best for | Learning how skills work, small skills | Larger skills, teams, repeated builds |
Our suggestion: build your first skill by hand so you understand each field, then use skill-creator for the next ones. Always read what it writes. It drafts from your inputs, so vague inputs still produce a vague skill.
Takeaway: skill-creator speeds up the typing, not the thinking. You still own the description and the rules.
Frequently asked questions
How do I create a skill in Claude Code?
Make a folder under ~/.claude/skills/ (for example brand-voice), add a SKILL.md file with name and description frontmatter, then write your instructions below it. Claude Code picks it up automatically.
What is the difference between a Claude skill and a prompt?
A prompt is typed each time. A skill is saved in a folder, triggers on its own when your request matches its description, and can carry reference files and scripts.
Where are Claude Code skills stored?
Personal skills go in ~/.claude/skills/, project skills in .claude/skills/ inside a project, and plugin skills inside the plugin’s skills/ folder.
What frontmatter fields does SKILL.md need?
None are strictly required. Anthropic recommends description, and name defaults to the folder name. Other fields like allowed-tools and disable-model-invocation are optional.
Why is my Claude Code skill not triggering?
Usually the description is too vague or lacks the words you type. Add concrete contexts and trigger phrases, check that the YAML parses, and confirm the skill appears in /skills.
Can I build a Claude skill without coding?
Yes. A skill is a Markdown file. Scripts are optional, and you can ask Claude to write them for you.
How long should a SKILL.md file be?
Anthropic recommends keeping it under 500 lines and moving detailed material into separate reference files.
Do Claude Code skills work on claude.ai?
Skills can be uploaded to claude.ai, but only the name, description, license, compatibility, metadata and allowed-tools fields are allowed there.
What is the skill-creator skill?
An Anthropic skill that helps you draft, test and refine new skills. It is available in the anthropics/skills repo and as a plugin.
How do I invoke a skill manually?
Type /skill-name at the start of your message, for example /brand-voice rewrite this email.
Can I stop a skill from running automatically?
Yes. Set disable-model-invocation: true in the frontmatter, and it runs only when you type its slash command.
How many skills can I install at once?
The docs do not set a simple number, but every description takes space in context and long listings get truncated, so keep descriptions focused.
Should I buy a paid skill pack?
Read the free repos first. Many marketing skills are free on GitHub. If you do pay, ask to see a sample SKILL.md before buying.
How do I share a skill with my team?
Commit it to .claude/skills/ in a shared repository, or package it as a plugin.
What is the difference between a skill and a slash command?
Skills create slash commands. The older .claude/commands/<name>.md format still works, but skills add supporting files and automatic triggering.
Your next step
Pick the one job you repeated most last week. Create the folder, write a five-line frontmatter, paste in the instructions you keep retyping, and run the six tests above. When it passes, add references/. When it fails, fix the description first.
Want to see what other marketers install before building? Browse Claude Code skills for copywriters or run an audit workflow with skills for SEO audits.
Sources and methodology
- Anthropic, Claude Code skills docs: https://code.claude.com/docs/en/skills (frontmatter fields, locations, limits, testing)
- anthropics/skills: https://github.com/anthropics/skills
- anthropics/knowledge-work-plugins: https://github.com/anthropics/knowledge-work-plugins
- coreyhaines31/marketingskills README (install command and skill names)
- GitHub API star counts, retrieved 1 November 2026
- Vendor pricing pages as linked, retrieved 1 November 2026
- Community troubleshooting: dev.to, blog.fsck.com and Reddit threads on skills not triggering
This guide was written from the documentation and public repos above. The Acme example is fictional and illustrative.
