How to Create Claude Code Skills
This guide explains what skills are, when to create one, and how to ask Claude to build one for you. You do not need to know how to write the skill file yourself — just describe the workflow you want to automate.
What Is a Skill?
Section titled “What Is a Skill?”A skill is a reusable, multi-step workflow that Claude Code can execute when you type /skill-name in any session. Think of it as a recipe: instead of explaining the same 10-step process every time, you invoke the skill and Claude walks through all the steps automatically.
Each skill has two parts:
- The skill file (
.claude/skills/skill-name/SKILL.md) — instructions written for Claude, telling it what to do step by step. This file is invisible inside Obsidian but lives in the git repo and syncs to all machines. - The guidelines document (somewhere in the vault) — a human-readable reference that explains the same workflow. Visible in Obsidian, linked into the graph, searchable. Claude reads this document as part of executing the skill.
When Should Something Be a Skill?
Section titled “When Should Something Be a Skill?”A good skill is a multi-step workflow that you’d otherwise have to explain from scratch each time.
Ask yourself:
- Does this task involve more than 3 steps?
- Would I need to remind Claude of specific conventions, file locations, or validation steps every time?
- Do I (or Asia) do this task repeatedly?
- Does it involve creating files, updating indexes, or checking cross-references?
If yes to most of these, it’s a good candidate for a skill.
Good Skill Candidates
Section titled “Good Skill Candidates”| Workflow | Why it works as a skill |
|---|---|
| Create a content campaign | Involves KB research, creating directories, writing structured notes with specific frontmatter, updating three indexes, running wikilink validation, checking bidirectional links |
| Create a blog post from a topic | Research KB for source material, create outline with correct frontmatter, link to campaign note, update blog index, load voice guides |
| Prepare a newsletter for sending | Compile HTML from campaign sections, validate all internal links, check FluentCRM merge codes, generate subject line options, verify send logistics |
| Run post-edit handoff | Split discussion notes from clean copy, archive working notes with no_embed: true, update inboxes, verify wikilinks |
| Full wikilink audit | Scan entire vault, report broken links with suggestions, identify backtick paths that should be wikilinks, check for orphaned notes |
| Log a contact inquiry | Create inquiry note from template, run fit assessment against criteria, draft response, update inquiry index |
| Onboard a new study group cohort | Create cohort directory, set up forum structure, create session summary templates, update program index |
Things That Are NOT Skills
Section titled “Things That Are NOT Skills”Some things feel like they could be skills but actually belong as standing instructions in CLAUDE.md — rules that apply to every session automatically, without needing to be invoked.
| Rule | Why it’s not a skill |
|---|---|
| ”Load voice guides before writing” | This is a pre-condition for many tasks, not a standalone workflow. It’s already in CLAUDE.md and applies automatically to every writing task. |
| ”Check inboxes at session start” | Already in CLAUDE.md. Happens every session. |
| ”Run wikilink checker after structural changes” | Already in CLAUDE.md. A standing instruction, not an invokable workflow. |
| ”Use wikilinks instead of backtick paths” | A convention, not a workflow. Belongs in CLAUDE.md under Wikilink Standards. |
| ”Append machine identity to git commits” | A convention applied to every commit. Already in CLAUDE.md. |
The distinction: A skill is something you choose to do at a specific moment (“I want to create a campaign now”). A rule is something that should always be true (“always load voice guides before writing”).
How to Create a New Skill
Section titled “How to Create a New Skill”You do not need to write any files yourself. Just describe the workflow to Claude in a conversation. Here’s what that looks like:
Step 1: Describe the workflow
Section titled “Step 1: Describe the workflow”Tell Claude what you want automated. Be specific about:
- What the task produces (files, updates, messages)
- What information Claude should research or check first
- What conventions or standards apply
- What validation should happen at the end
Example:
“I want a skill that prepares a newsletter for sending. It should compile the HTML from the campaign sections in the newsletter issue note, check that all links resolve, verify FluentCRM merge codes are correct, give me subject line options, and confirm the send date and audience segment.”
Step 2: Claude builds both parts
Section titled “Step 2: Claude builds both parts”Claude will create:
- A guidelines document in the appropriate vault area — the human-readable reference
- A skill file at
.claude/skills/skill-name/SKILL.md— the executable instructions - An entry in the skills index so it’s discoverable in Obsidian
Step 3: Commit, push, and test
Section titled “Step 3: Commit, push, and test”Claude will commit and push. The skill syncs to all machines via git pull. Type / in any Claude Code session to see it in the autocomplete, or type /skill-name directly.
Step 4: Iterate
Section titled “Step 4: Iterate”If the skill doesn’t quite work the way you want, just tell Claude what to change. The skill file and guidelines can be updated in any session.
Naming Skills
Section titled “Naming Skills”Skill names should be:
- Short — you’ll type them frequently (
/create-campaign, not/create-a-new-content-campaign-with-social-media) - Verb-first — describes the action (
/create-,/prepare-,/audit-,/log-) - Specific enough to be unambiguous when you see it in the
/menu
Where Skills Live
Section titled “Where Skills Live”| What | Where | Visible in Obsidian? |
|---|---|---|
| Skill file | .claude/skills/skill-name/SKILL.md | No (dotfolder) |
| Guidelines document | Wherever makes sense in the vault (e.g., under the area it serves) | Yes |
| Skills index | 03-resources/claude-code-skills/index.md | Yes |
| Skill creation rules | CLAUDE.md (under “Claude Code Skills” section) | Yes (loaded every session) |
The skill file and guidelines document are not duplicates. The skill file is written as instructions to Claude (“You are creating a campaign…”). The guidelines document is written as reference for Patrick and Asia (“This is how campaigns work…”). The skill reads the guidelines as its first step.
Related
Section titled “Related”- Claude Code Skills Index — browse all available skills
- _campaign-creation-guidelines — example of a guidelines document (for the
/create-campaignskill)