A Claude Code skill is a folder containing a SKILL.md file with YAML frontmatter and natural-language instructions. Claude Code auto-discovers skills under ~/.claude/skills/ and loads the matching one when your prompt's intent overlaps with the skill's description. This guide walks through writing your first skill end-to-end — directory layout, frontmatter fields that matter, anti-trigger discipline, and how to package for distribution via this registry.
A Claude Code skill is a self-contained packet of context plus instructions that Claude Code loads on demand. When you start a session, Claude reads the name + description field of every skill under ~/.claude/skills/. When your prompt's intent matches one, Claude loads the full body of that skill into its working context — and only that one (skills don't interfere with each other unless explicitly chained).
That model has three implications worth internalizing before you write anything:
linkedin-post-writer with description "Generates LinkedIn posts in the user's brand voice" activates on prompts about writing LinkedIn content, not on general coding tasks.The minimum viable skill is one file:
~/.claude/skills/
└── my-skill/
└── SKILL.md
Claude Code's discovery walks every direct child directory of ~/.claude/skills/ and registers anything containing a SKILL.md. The directory name becomes the slug — keep it short, lowercase, hyphen-separated. Most skills in the ClaudSkills registry follow verb-noun or noun-modifier patterns: commit-push-pr, pre-mortem, fabric, osint.
Skills can ship companion files alongside SKILL.md:
~/.claude/skills/
└── my-skill/
├── SKILL.md # main skill definition (required)
├── README.md # human-facing overview (ignored by Claude)
├── scripts/ # executable helpers Claude can run
│ └── do-thing.py
├── references/ # additional context Claude loads on demand
│ └── api-reference.md
└── assets/ # output templates (slide decks, HTML, etc.)
└── report-template.html
Only SKILL.md is read into context at activation time. scripts/ are executed via Bash tool calls when the body instructs Claude to run them. references/ are loaded lazily when the body explicitly asks Claude to read them. This progressive disclosure pattern keeps the active context small even when the skill ships hundreds of pages of supporting material.
The first lines of every SKILL.md are YAML frontmatter, fenced by ---:
---
name: my-skill
description: Generates X for Y purpose. Use when the user wants to do Z.
---
# Skill body starts here
The two required fields:
name — short identifier. Should match the directory slug for clarity but doesn't have to. This is what shows up in Claude Code's skill list.description — 1-3 sentences describing what the skill does AND when Claude should invoke it. The "when" half is what drives auto-activation. Treat it like a function signature with a usage hint, not marketing copy.A good description encodes both capability and trigger conditions:
Bad: "AI-powered LinkedIn writer that helps you grow your network."
Good: "Generates LinkedIn posts in the user's brand voice from a topic or rough notes. Use when the user mentions LinkedIn, social posts, or thought-leadership content."
The good version tells Claude (a) what it does, (b) what input shape it accepts, (c) which user phrases should trigger it. The bad version describes outcomes without clear trigger signals.
For the full list of optional frontmatter fields (model, tags, allowed-tools, user-invokable, etc.) see the SKILL.md frontmatter reference.
Once activated, Claude reads everything below the frontmatter and treats it as part of its working instructions. The body should answer four questions, in roughly this order:
Use Markdown structure aggressively. Claude parses headings (H2/H3) as section boundaries and follows them when reasoning about which part of the skill applies to the current step. Long unstructured paragraphs hurt activation accuracy because Claude can't tell which clause is load-bearing.
Code blocks belong inside the body for any commands or file templates. Claude treats fenced ``` blocks as literal — useful for shell snippets the user should run, file templates Claude should write verbatim, or example outputs.
The single highest-impact technique for writing skills that work reliably: tell Claude when NOT to use them. Without explicit anti-triggers, Claude tends to over-activate skills based on loose keyword matches.
Pattern that scores well in the ClaudSkills quality system:
## When to use
- The user wants to draft a LinkedIn post from a rough note or topic.
- The user explicitly asks for "social media content" or "LinkedIn".
## When NOT to use
- For Twitter/X content (use the `x-thread-writer` skill).
- For long-form blog posts (use `blog-post-writer`).
- For internal company memos or status updates (use generic prompting).
- When the user just shares a LinkedIn link without asking for content.
The "When NOT to use" section reduces false-positive activations. Claude reads it and stops itself from invoking the skill on adjacent-but-different intents. Skills with explicit anti-triggers consistently rank higher in our registry's structural-quality scoring.
Iterate on the description and anti-triggers until activation matches your intent. This is the most under-invested-in step; spend 30 minutes on it and your skill will work twice as well in practice.
To share your skill:
skills/<slug>/. The ClaudSkills miner crawls public repos with SKILL.md files daily.SKILL.md frontmatter (e.g. tags: [type:integration, lang:python, ai:claude]) so the registry's tag taxonomy picks it up correctly.Within 24 hours your skill appears in the catalog at https://claudskills.com/skills/<slug>/ with a generated SEO page, structured-data JSON-LD, and a clean curl-able SKILL.md URL for manual install.
Copy this into ~/.claude/skills/my-skill/SKILL.md and edit:
---
name: my-skill
description: |
Does ONE_SPECIFIC_THING for ONE_AUDIENCE.
Use when the user mentions TRIGGER_PHRASE_1 or TRIGGER_PHRASE_2.
tags:
- type:generator
- lang:python
license: MIT
---
# my-skill
ONE-PARAGRAPH overview of what this skill produces and the kind of
input it expects.
## When to use
- BULLET about an explicit user intent
- BULLET about a phrase that should trigger this
- BULLET about a context where this fits
## When NOT to use
- BULLET about adjacent-but-different intent (point to the right skill)
- BULLET about a context where this would be wrong
- BULLET about a partial-match trap to avoid
## Workflow
1. NUMBERED step-by-step instructions
2. With concrete decision points
3. And explicit output format
```bash
# Code blocks for any commands the user or Claude should run
echo "example"
```
## Output format
Describe the SHAPE of the output — markdown sections, JSON schema,
code structure, etc. Claude follows this strictly.
Once you have something working, browse the top 100 hand-picked skills for patterns from authors who've been doing this for a while — anti-trigger discipline, structural decomposition, and reference-doc loading are the techniques to study.
Found a bug or want a topic covered? Email acreatorstore@translatea.com or submit a PR via GitHub.