My Claude Skills that You Might Want to Copy

Claude skills have changed the way I work with Claude Code, and the same folders now serve Codex and VS Code as well. A skill is a folder with a SKILL.md file that teaches Claude how to do one job the way you want it done, and after a few hundred of them I have a fair idea of which ones earn their keep and which ones only add weight. So, if you are building your own set of Claude Code skills and want a shortcut, this guide can surely help.

I have been building and pruning this library for a while now, for my own sites and for client work.

One article cannot walk through every skill, and some of the ones I use are other people’s work that I have no right to hand out. But the ones I built myself, and the plumbing that lets one copy of each serve three tools, are fair game, and in this guide I will try my best to cover those properly: the writing and voice skills, the anti-slop set, the WordPress and graphics sets, and the housekeeping that keeps a large library usable.

The public skills live on GitHub and in a free community pack on my freebies page, and I will point to each one as it comes up. Or, if you would rather have someone set this up for your team, I am always available for a chat. Let’s get started.

My working rule: Put a repeatable instruction in a skill, isolated work in an agent, and access to an outside system in MCP. A skill teaches Claude how to do a job. It should not turn into a second operating system stuffed into one Markdown file.

What Claude Skills Are

Claude skills are folders of instructions that Claude loads when a task matches their purpose. Each one has a required SKILL.md file at the top and optional scripts, references, templates and assets next to it. Anthropic’s Agent Skills documentation describes the format as reusable, filesystem-based expertise, and that is a fair description as long as you remember that the folder does nothing until its description matches a request.

That distinction matters in daily use. A prompt tells Claude what to do once. A Claude Code skill records how a repeated job should work, when it applies, which files to read, which commands are allowed and what a finished result looks like. If I keep pasting the same checklist into sessions, I have already found a skill candidate.

Part	Required?	What it does	Example from my library
SKILL.md	Yes	Declares the name and description, then gives Claude the working instructions	stop-slop/SKILL.md
references/	No	Holds detail that Claude reads only when the task needs it	Banned phrase lists, API notes, block schemas, the voice file
scripts/	No	Turns repeatable mechanical work into code Claude runs instead of reading	Voice core extraction, screenshot capture, slop scoring, validation
examples/ or templates	No	Shows the expected input and output shape	Before-and-after edits, payload examples, layouts
Assets	No	Supplies files the workflow needs without placing their contents in the main instructions	Fonts, SVG bases, document templates

The smallest useful skill is about 20 lines. The biggest mistake is treating that minimum as an invitation to write a 900-line policy manual. Anthropic’s guidance is to keep SKILL.md under 500 lines and move conditional detail into referenced files, and my own library only got better once I started following that properly. The main file should orient and route. The supporting files should carry the depth.

The anatomy of a real SKILL.md

The stop-slop skill is the cleanest example I have. Its frontmatter says what it does and when to use it. Its body carries 6 rules, a quick check and a self-audit, and it points at the anti-slop files in my writing system instead of copying a stale snapshot into the package.

---
name: stop-slop
description: Remove AI writing patterns from prose. Use when drafting, editing, or reviewing text to eliminate predictable AI tells.
---

# Stop Slop

Eliminate predictable AI writing patterns from prose.

## Canonical Sources

- writing-system/anti-slop/banned-phrases.md
- writing-system/anti-slop/ai-tells.md
- writing-system/anti-slop/slop-detector.json

## Core Rules

1. Cut filler phrases.
2. Break formulaic structures.
3. Vary rhythm.
4. Trust readers.
5. Cut quotables.
6. Keep production off the page.

A portable skill needs both fields in the frontmatter, and the limits are tighter than most people expect:

• name is at most 64 characters of lowercase letters, numbers and hyphens, and it cannot contain the words “anthropic” or “claude”.
• description is required, at most 1,024 characters, and cannot contain XML-style tags.
• Claude Code shows at most 1,536 characters of the description and when_to_use text combined in its listing, so the main use case goes first.

Shorter generally wins, because the description has one job: help Claude decide whether this skill belongs in the task at hand.

How Claude Skills Load

Claude skills load in stages. Claude sees a short listing of names and descriptions first, reads the SKILL.md body when a skill is invoked, and opens supporting files only when the job calls for them. That is what keeps a big library affordable, but it is not free. Every name sits in the listing, and every invoked body stays in the conversation. This is the part of my daily Claude Code workflow that most people never look at, and it decides whether a library of 300 skills helps or hurts.

1. Metadata is the discovery layer. Claude sees the skill name and, when the listing budget permits, its description. The description should state both the job and the situation that triggers it.
2. The SKILL.md body is the instruction layer. Claude Code adds the rendered body to the conversation when you invoke the skill directly or Claude selects it on its own.
3. References and code are the working layer. Claude reads a referenced file or runs a bundled script only when the active job calls for it, and a script’s code never enters context, only its output.

Once invoked, the rendered SKILL.md stays in the session, and the Claude Code skills guide spells out what that costs. Claude Code does not re-read the file on later turns, so guidance meant to apply throughout a task should read as standing instructions rather than one-time steps. Re-invoking a skill whose content has not changed adds a short note instead of a second copy. When the conversation compacts, Claude Code re-attaches the most recent invocation of each skill, keeping the first 5,000 tokens of each inside a shared 25,000-token budget, most recent first, so a skill invoked early in a long session can drop out completely. When a skill seems to stop working halfway through a task, that budget is the first thing I check, and re-invoking the skill is generally the fix.

That makes the description a routing rule, not decoration. Compare these two versions:

Description	What Claude can infer	Likely result
Helps with writing	Almost nothing about task, input or timing	Missed triggers or noisy over-triggering
Remove AI writing patterns from prose. Use when drafting, editing, or reviewing text to eliminate predictable AI tells.	The action, the material, and 3 moments when it applies	Much cleaner automatic matching

You can also call a skill directly with /skill-name. 2 frontmatter fields decide who is allowed to start one:

• disable-model-invocation: true keeps a skill off Claude’s own list. Only you can run it, and its description stays out of context until you do. Publishing, deployment, billing and anything that sends a message belong here.
• user-invocable: false does the reverse. Claude can apply it as background knowledge, but it never shows in the slash menu, because nobody would type it as a command.

A description can guide a model. It cannot replace an approval boundary. That is why the skills in my library that push to WordPress read their credentials from an environment file rather than from the skill folder, why a publish transition still waits for my explicit go, and why a hook is the right tool when a call has to be blocked outright rather than discouraged.

What a large library costs in context

Claude Code reserves 1% of the model’s context window for the skill listing. Every name always appears, but when the descriptions overflow that budget, Claude Code shortens them, starting with the skills you invoke least, and a shortened description loses the exact words Claude needed to match your request. The skill is still callable by name. It just stops being found on its own.

This is where hoarding starts to hurt, and it is the reason I keep a census of the library. 3 settings help when the count grows:

• skillListingBudgetFraction raises the budget, for example 0.02 for 2% of the window.
• skillOverrides can set a low-priority skill to name-only, so it lists without a description and frees room for the ones that matter.
• skillListingMaxDescChars changes the 1,536-character cap on each entry.

/doctor estimates the listing cost and names the biggest contributors, and the Skills row in /context shows the size after the budget is applied, which is what the model receives. Neither one tells you which skills fire most often. That telemetry does not exist, so the census later in this guide is a count of what is installed, not a ranking of what gets used.

Where skills work

Agent Skills span more than the terminal now, but the surfaces do not share one library. Claude Code, the Claude app and the Claude API use the same folder idea with different installation and runtime rules, and a package added in one place does not appear in the others by itself.

Surface	How you add a custom skill	Limit to keep in mind
Claude Code	A folder under ~/.claude/skills/ for every project, .claude/skills/ inside one project, managed settings for an organization, or a plugin	Filesystem skills stay separate from app and API uploads; skills have the same network access as any program on your machine
Claude app	Customize > Skills, then upload a ZIP with SKILL.md at the root, with code execution turned on	Anthropic’s support article lists Free through Enterprise while the platform docs list only the paid plans, so check before you rely on a Free account; uploads are per user, and enabled skills also apply in the Excel, PowerPoint, Word and Outlook add-ins and in Cowork
Claude API	Create the skill through the Skills API, then attach its skill_id to the container alongside the code execution tool	No network access and no runtime package installs; uploaded skills are shared workspace-wide

Claude Code can also pull the skills you enabled on claude.ai into a reserved ~/.claude/skills/synced/ folder when you ask it to, and the /skills menu labels those as coming from claude.ai sync. That is a download, not a link. A local skill with the same name wins over the synced one, and nothing flows back up. Anthropic’s support guide covers the app side; for the API, copy the request shape from the live platform docs rather than from any blog post, mine included.

My Skill Library by Job

Before the individual skills, here is what the library looks like as a whole. The census counts immediate child directories under ~/.claude/skills whose SKILL.md resolves, following the root symlink and nothing deeper, so nested fixtures, reference files and packaging artifacts do not inflate it.

• 347 callable skills in total
• 182 of these are mine, written for my sites, my clients and my writing
• 165 are symlinks into 2 third-party sets, Meng To’s X writing collection and a vendor’s Bricks Builder set, which I use daily and cannot redistribute

The category labels below are mine, and every one of the 182 appears once, so the counts add up. The third column is the part that matters for this guide: where you can get a copy.

Job	Skills	Where you can copy them
Writing, voice and publishing	74	stop-slop, slop-detector and red-pen on GitHub; the method behind the private voice skills is in this guide and in the Voice DNA kit
WordPress and block development	44	The WordPress-skills, generateblocks-skills and bricks-skills repositories on GitHub
Design and frontend	31	design-slop on GitHub; clarify, distill, quieter, polish and harden in the claude-code-skills repository
Images and media	17	png-graphics, gpt-image, svg-graphics and the featured image tools in the community pack
SEO, analytics and affiliate APIs	16	seo-magic, seo-rank, seo-score and ai-seo in the community pack
Total	182	Every skill of mine with a resolvable SKILL.md

WordPress used to be the largest group, and it still is the largest technical one. Writing overtook it this year because every recurring correction to my voice became a rule, and every rule that needed its own trigger became a skill. The counts move every week. If you read this in 2026, rerun the census instead of trusting the table:

ls -d ~/.claude/skills/*/SKILL.md | wc -l

One rename, one archive or one missing entrypoint changes the result immediately, which is exactly why a count makes a poor headline and a good housekeeping check.

The Writing and Voice Skills Worth Copying

Most of the library exists so that Claude can write and publish as me without sounding like a machine, and this group changed the most in the last few weeks. The pattern behind every one of these skills is the same: one canonical voice file, small skills that route to it, and scripts that do the mechanical parts so the instructions stay short. You can copy the pattern even where you cannot copy the file.

gaurav

This is the default writing skill. Anything published under my name runs through it unless a narrower skill owns the surface, and what makes it worth copying is the way it loads context in tiers instead of all at once.

Tier	What loads	When
0	A voice core extracted by script from the canonical voice file, plus a short standing-rules file	Always
1	The matching format file, the voice contract, the page layout rules, the article workflows, the file that holds every public number about me, the affiliate lists	By task type, from a trigger table
2	My own edited writing samples, newest folder first	Last, right before drafting
3	The self-edit gate and the banned-phrase list	After the draft exists
4	Invisible-character and file-metadata cleanup	At the end, right before the push

The full voice manual runs to about 125 KB. Loading all of it on every run, along with every sample, was the reason drafts had started to sound generic: the 40 lines that record my own corrections were outweighed roughly 50 to 1 by everything else in context, and a model follows volume before it follows a priority label. So a small Python script now pulls a fixed list of headings out of the canonical file, corrections first, and prints them. It has a --check flag that fails when a heading in the manual gets renamed, and a --write flag that refreshes a fallback snapshot for the day the script cannot run. The manual stays the single source. The skill reads about a third of it by default and opens the rest only when the voice itself is being diagnosed.

Before the first drafted sentence, state in one line which files were loaded and which trigger fired each one. If a trigger in the table fired and its file is not on that line, the run is incomplete. Fix the load before drafting.

That rule sits near the top of the skill, and it is the reason I trust a run. A skill that is allowed to summarize its references from memory will do exactly that, and the draft shows it.

The other half of this skill is the introduction and the close. Both run on 4 short moves taken from introductions I approved by hand, and the skill reads its own draft against those worked samples and flattens anything sharper or cleverer. That sounds like a small thing. It removed the single most common complaint I had about machine drafts, which was the contrarian opening line that sounds sharp and reads as filler.

voice-dna-creator

This one builds the voice file the gaurav skill reads. It asks the discovery questions, prefers unpolished samples over edited ones, and writes a profile with an emotional palette, a teaching section, sentence rules, banned phrases and paired good and bad examples. The rule that matters most sits at the top of the skill: the canonical voice file already exists and gets edited, never regenerated, and every skill that needs it links to that one file.

The part I would copy first is the corrections loop. I had the skill draft 4 articles on 4 different kinds of topic, then edited one of them word by word. The diff between the draft and my edit became a section at the top of the voice file that outranks every other rule in the system. 9 corrections came out of one partial edit, and most of them are things no style guide would have told a model: name the middle path out loud instead of leaving it implied, turn inline lists into bullets, keep the plain evaluative words a banned-phrase list would flag, and leave my Indian English grammar alone. I also run drafts through Pangram as an outside check, and a draft that passes every internal rule and still scores as machine written tells me the problem is substance, not sentences.

What most people do:

Write in a friendly, expert, conversational tone with short punchy sentences and no jargon.

What works better:

Read the corrections section first. Where it conflicts with any other rule in this file or in a skill, it wins. A 1 to 3 word sentence is rare in this voice, so zero is the normal count. Inline lists of 3 or more items become bullets. Full forms stay in a measured, teacherly sentence.

The model and the topic are the same in both cases. The second version comes from an edit the writer actually made, so it produces sentences the writer would keep. The first produces the same blog everyone else gets. The public version of this process, with a template and a set of extraction prompts, is in my guide on training AI to write like you.

stop-slop and slop-detector

stop-slop is the editing rule set: 6 rules, a quick check and a self-audit, all routing to the canonical banned-phrase and AI-tell files. slop-detector is the scorer that goes with it. It reads a Markdown or HTML file and sorts what it finds into 4 levels: exact production narration fails outright, rhetorical scaffolds warn once they repeat, lexical tells become review prompts for a human, and document-level patterns get diagnosed rather than counted. It prints 2 numbers, the score from automatic findings and the ceiling if every review prompt turns out to be real, because a script cannot tell a quoted phrase from a used one. Both skills are public and MIT licensed, and the detector ships with the scanner, a caption linter and regression tests. My Stop Slop walkthrough shows the patterns it catches and why a named editing gate works better than asking a model to “sound human”.

remove-ai-marks

This is the last step before a push. It strips invisible Unicode from the text, meaning zero-width joiners, bidirectional controls, variation selectors and odd spaces that survive a paste into the block editor and then break search and diffs, and it strips C2PA, EXIF and XMP metadata from images headed for the media library. The rule worth copying is the one it refuses to do. It never runs a paraphrase or “humanize” pass on my pieces, because those passes work by churning word choice and syntax, which is exactly where a voice lives. If the wording needs to change, that is a self-edit against the voice file, not a statistical rewrite. Removing a mark also does not make a piece human written, and the skill reports only what it verifiably removed.

article-updater

Every change to a live post goes through this. It fetches the stored post with a cache-buster, snapshots everything it is not allowed to change, meaning the slug, title, excerpt, featured image, taxonomy, every link and every image URL, and then makes surgical edits with occurrence-count assertions so a replacement that matches twice or not at all stops the run. It pushes with Python rather than a shell heredoc, because a heredoc corrupts the <!-- wp:* --> comments that hold a Gutenberg post together, and it reads the post back afterwards and diffs the stored content against what was sent. If the post changed underneath it between snapshot and push, the guard aborts. The skill is private, but the guard is 30 lines of Python that anyone can write, and it has saved me from overwriting someone else’s edit more than once.

faq and seo-magic

2 smaller skills show the range of this group. faq turns article content into one single-line ACF accordion block with the exact flat repeater keys WordPress expects, a string row count and paired field references, and it exists because a wrong field name renders the block blank while the API still answers with a 200. seo-magic repackages an existing article around the searches it is actually getting: title, opening, snippet and structure, then the Rank Math handoff and a verification step. It refuses to treat “add more words” as the fix, and it hands technical work, deeper topical coverage and AI-citation strategy to sibling skills instead of growing into a department. A skill can be a 10-line checklist or a router for a production workflow. Its job still has to fit in one sentence.

The Anti-Slop Set You Can Install Today

If you searched for the stop slop skill, this is your section. The claude-code-skills repository holds 8 skills for copy, design and code, each a self-contained folder of Markdown and Python that works in Claude Code, Codex, Cursor and anything else that reads a SKILL.md.

Skill	Job	Origin	License
stop-slop	Drafting rules that remove predictable AI writing patterns	Mine	MIT
slop-detector	Scores a draft or page against the 4-level severity model, with a scanner and tests	Mine	MIT
red-pen	Strict line editor built on Orwell and Butterick, with a reason per change	Rich Tabor	See NOTICE.md
clarify	Rewrites UX copy: buttons, errors, helper text, empty states	Adapted from impeccable	Apache-2.0
distill	Strips a design to its essence	Adapted from impeccable	Apache-2.0
quieter	Tones down loud designs without flattening them	Adapted from impeccable	Apache-2.0
polish	Final pass before a UI ships: spacing, alignment, radii, states	Adapted from impeccable	Apache-2.0
harden	Long text, RTL, missing data, slow networks, keyboard and screen reader access	Adapted from impeccable	Apache-2.0

git clone https://github.com/wpgaurav/claude-code-skills.git
cd claude-code-skills
./install.sh claude stop-slop slop-detector
python3 slop-detector/scripts/scan.py draft.md

The installer copies only the folders you name and never touches the rest of your skills. Restart Claude Code after installing, then run /stop-slop or ask for the job in plain words. If you would rather track the repository, symlink the folders instead of copying them and a git pull updates every skill at once.

5 of those 8 are near-verbatim copies of Paul Bakaus’s impeccable commands, and red-pen is Rich Tabor’s. The NOTICE file says so, and the license field on each folder matches its origin. For 4 months my own repository carried a single MIT line over all of it, which is the mistake to avoid when you publish a collection. If you fork the repository, keep that file. The design side of the same idea lives in design-slop, a skill that detects and removes the generic AI look from web pages, dashboards and blocks.

WordPress and Graphics Skills

The WordPress group is the largest technical one and the most public. 3 repositories carry most of it:

• WordPress-skills: 125+ skills across WordPress, design, SEO, marketing and frontend, including the wp-block, wp-plugin, wp-theme, wp-rest-api and wp-wpcli-and-ops family, for Claude Code, Cursor and other agents that read a SKILL.md
• generateblocks-skills: GenerateBlocks V2 layouts, CSS mode, dynamic data and block serialization that survives the editor’s recovery mode
• bricks-skills: Bricks Builder elements, templates, query loops and conditions

The graphics skills are private, but the rules inside them are the useful part. png-graphics designs a graphic as Tailwind HTML, renders it at 2x, then runs a critique pass and a polish pass before anything is uploaded, and it holds an 11px floor on text and a standing rule that skipping the graphic is a valid outcome when the prose or a table already does the job. featured-image renders every hero image twice, one native light and one native dark from the same source, and exactly one ships. annotated-screenshots captures a live page, highlights the clause or price that proves a claim, and refuses to upload until the PNG has been inspected. None of them work toward an image count, because a decorative image is the visual form of filler.

25 of my skills, including png-graphics, gpt-image, svg-graphics, seo-magic, seo-rank, generateblocks-layouts and stop-slop, are packaged as a community edition on my freebies page, with install notes, package notes and SHA-256 checksums. Credentials, personal profiles and private site data are stripped out, and the placeholder references tell you where your own go. The rest of the tools I build sit on the AI Toolbox page.

One Skill Library, Three AI Tools

Every skill lives in one folder on iCloud Drive, which is how the same library follows me between Macs. Claude Code and the shared Agents folder that VS Code reads are symlinks to it, and Codex points at the same tree as an external skill root while keeping its own system packages separate. One edit to stop-slop reaches all three. There is no copy job to forget, and the split between Codex and Claude Code becomes a question of which tool suits the job, not which one has the current rules.

iCloud Drive/claude-sync/
├── skills/                         # canonical custom-skill source
├── context/voice-dna.md            # canonical voice source
├── skills/writing-standalone/      # flattened single-file exports
└── _skill-packages/                # portable .skill archives

~/.claude/skills
└── -> iCloud Drive/claude-sync/skills

~/.agents/skills
└── -> iCloud Drive/claude-sync/skills

~/.codex/skills                     # real directory, not a symlink
└── Codex reads claude-sync as a configured external skill root

Claude Code follows a symlinked skill entry and reads SKILL.md from the target, and when the same target is reachable from more than one location it loads the skill once. The same trick resolves shared context. In the writing system, voice/voice-dna.md points at the canonical file 2 folders up. Inside stop-slop, references/voice-dna.md points at the same file 3 folders up. The access paths differ, the voice file is one, and a small shell script rebuilds those links whenever a skill is added.

What the symlink solves, and what it does not

A symlink solves duplication. It does not solve portability, conflict handling or surface-specific installation. Custom skills do not sync between Claude Code, the Claude app and the API, and a local link cannot upload a package anywhere. It also does not make every nested folder a valid personal skill: Claude Code expects ~/.claude/skills/<skill-name>/SKILL.md, and the nested discovery it supports is for a project’s own .claude/skills/ in a subdirectory, not for category folders under the personal root.

iCloud adds a trap of its own. It periodically writes a conflict copy named something 2.md next to a symlink, and that copy is a stale snapshot a skill can load by mistake. A find-and-delete for that pattern is part of my monthly pass, and I would build it in from the start on any cloud-synced library.

Flattened exports for tools that cannot follow a symlink

Some tools read a skill over a network boundary or accept one file at a time, and a folder full of symlinks arrives empty there. So the writing skills also exist as single flattened files: each one is the skill body with a shared context appendix appended, generated by a 3-line loop and never edited by hand. When a source skill retires, its export is deleted in the same pass, because a stale export keeps answering with instructions that were deliberately retired.

cd ~/.claude/skills
for name in blog-article product-review tutorial; do
  { cat "$name/SKILL.md"; printf '\n\n---\n\n'; cat _shared-writing-context.md; } \
    > "writing-standalone/$name.md"
done

The .skill archives are the other export layer. Each one is a ZIP with a different extension, and the Claude app wants SKILL.md at the root of that archive with every symlinked reference dereferenced first, or the upload lands with empty references. Uploading over an existing skill replaces it with no way back, so the archive is source material to repackage for a destination, not a deployment method on its own.

How to Create Your First Claude Code Skill

Create your first Claude Code skill by choosing one repeated job, giving it a specific description, writing a short SKILL.md, and testing both matching and non-matching prompts. Start with a personal folder under ~/.claude/skills if the workflow should follow you everywhere. Use a project .claude/skills folder when the instructions belong to one repository.

The example below creates a release-note skill. It has no scripts and no outside service, and that is deliberate. A first skill should prove that Claude can discover and follow the instructions before you add code, credentials, hooks or publishing.

Step 1: Choose one repeated job

Pick a task you have explained at least 3 times: release notes, pull-request review, article cleanup, a database query pattern, a project-specific QA check. Write one sentence that starts with an action and ends with the situation in which Claude should use it.

• Too broad: Helps with software projects.
• Useful: Writes release notes from the current Git diff and changelog. Use when the user asks for release notes, a release summary, or a customer-facing changelog entry.

The second version gives Claude an action, 2 inputs and 3 user phrasings. You have not written the instructions yet, but the router already has enough to decide.

Step 2: Create the skill directory

Use a lowercase, hyphenated name. The directory becomes the command you can type after a slash in Claude Code.

mkdir -p "$HOME/.claude/skills/release-notes"
nano "$HOME/.claude/skills/release-notes/SKILL.md"

For a repository-owned skill, create .claude/skills/release-notes/SKILL.md inside that project instead. Project skills belong in version control when the team should review and share them. Personal skills should not carry private project assumptions.

Step 3: Write SKILL.md

Put the portable metadata in YAML frontmatter and the procedure in Markdown. State inputs, ordered work, failure boundaries and the output shape. Do not tell Claude to be helpful. Tell it what a finished result contains.

---
name: release-notes
description: Writes release notes from the current Git diff and changelog. Use when the user asks for release notes, a release summary, or a customer-facing changelog entry.
---

# Release Notes

## Inputs

- Read the current Git diff.
- Read CHANGELOG.md when it exists.
- Ask for the target version only if it cannot be inferred.

## Procedure

1. Group changes into Added, Changed, Fixed, and Removed.
2. Describe user-visible behavior, not internal file movement.
3. Flag breaking changes before the main notes.
4. Do not claim a fix unless the diff or test output supports it.

## Output

Return a Markdown heading with the version, then concise categorized bullets.
Omit empty categories.

This skill is small enough to read in one screen. It also has a proof boundary: no claiming a fix without evidence. That one rule prevents more bad release notes than another page of tone adjectives would.

Step 4: Add supporting files only when the main file needs them

Add a reference when a rule applies only in some cases or when examples would bury the main workflow. Link the file from SKILL.md and say when Claude should read it. Keep references one level deep. A chain where one reference points to another that points to a third gets skipped, and the rule at the end of the chain might as well not exist.

release-notes/
├── SKILL.md
└── references/
    ├── public-example.md
    └── breaking-change-policy.md

If the skill needs a deterministic conversion, add a script and make its error behavior explicit. If the work needs an outside database, a WordPress site or a SaaS account, consider MCP instead of hiding a fragile API client inside the instructions.

Step 5: Test the trigger and the non-trigger

Start Claude Code in a small Git project with claude. Claude Code watches existing skill roots for SKILL.md changes, so edits appear during the session. If you created the top-level skills directory itself after launch, restart once so it can watch the new directory.

claude

# Natural-language trigger
Write customer-facing release notes for my current changes.

# Direct invocation
/release-notes

Then test a nearby request that should not trigger it: “Explain this diff to me.” If the release-note format appears anyway, the description is too broad. Test at least 3 matching prompts and 2 near misses. A skill that fires on everything is not reusable, it is background noise.

Step 6: Inspect, narrow and share

Use /skills to confirm the package is available and /context to see how much skill material occupies the session. If Claude misses valid triggers, add the words users actually type. If it fires too often, remove generic terms and name the input or output more precisely.

Share a Claude Code skill as a reviewed folder in Git or as part of a plugin. For the Claude app, package the folder as the ZIP structure described in Anthropic’s custom skill guide. Review every script before installing a skill from someone else. A skill can tell Claude to execute code, so the trust boundary is closer to a plugin than to a prompt snippet.

What Quietly Ruins a Skill Library

Skill adoption fails when Claude cannot tell when to load a package, when the instructions ask for too many unrelated jobs, or when a workflow hides its side effects behind friendly prose. Most of these failures are routing and trust failures before they are writing failures, and each one below cost me something before I fixed it.

A vague description. “Helps with SEO” competes with audits, schema, internal linking, ranking analysis and content editing, so Claude either ignores it or reaches for it too often. The fix is to name the job, the input, the output and the user’s own words: “Audit an existing WordPress page for technical SEO issues and return prioritized fixes. Use when…”

One skill that owns a department. A single “marketing” skill cannot route paid ads, email, conversion work, analytics and pricing with equal precision, and it grows into the 900-line manual from earlier. Split by decision and output. Focused packages compose better, and Claude can use more than one when a task crosses a boundary.

Treating instructions as enforcement. A skill can say “never publish without approval”, and that sentence is not a security control. User-only invocation, permission rules, hooks, restricted accounts and separate credentials enforce policy. Skills teach judgment and procedure.

Hardcoded secrets and unreviewed scripts. API keys do not belong in SKILL.md, in a shell example or in a shared ZIP. Read credentials from an environment file or a secret store and grant the smallest scope. Anthropic’s own security guidance says to use skills only from trusted sources, because instructions and code can direct tool calls that do not match the package’s friendly description.

Project rules in the personal library. A block schema for one client belongs with that repository, and a general code review method belongs in the personal root. Precedence makes this worse than it looks: enterprise skills override personal ones, personal ones override project ones, and a duplicate name can make a correct skill look broken because another scope wins.

Hoarding without a retirement rule. Every new description competes for listing space. Archive a package when its job moved into Claude Code itself, merged into another skill or belongs in project instructions, and treat cloud-sync conflict copies the same way. Two almost identical entrypoints, with Claude left to guess which one is current, is how a good library starts to feel unreliable.

Skill Housekeeping With /doctor, /skills and /context

Use /doctor for configuration health, /skills for visibility and /context for actual context occupancy. Between them they cover every question about a library except the one people ask most, which is what gets used.

Command	What it shows	What it does not prove
/doctor	Installation health, invalid settings, unused extensions, duplicate subagent names, proposed fixes and skill-listing pressure with its biggest contributors	It does not provide a ranked history of which skills triggered most often
/skills	Available project, personal, plugin and synced skills plus visibility controls	A visible skill is not proof that Claude will choose it for every matching prompt
/context	Current context use by system prompt, memory, skills, agents, MCP and messages	Context size alone does not measure instruction quality

Anthropic’s configuration debugging guide says /doctor checks unused extensions, not unused skills, and the skills guide adds the listing cost estimate. Neither gives trigger-frequency telemetry, so a claim that a tool told you which skills to delete is a claim the tool cannot support.

How nested .claude/skills discovery works

Claude Code loads project skills from the starting directory and its parents up to the repository root. When Claude reads or edits a file below the starting directory, skills from that subdirectory’s own .claude/skills/ become available too, so in a monorepo apps/web/.claude/skills/deploy/SKILL.md applies when Claude works inside apps/web.

If a nested skill and a root skill share a name, both stay available. The root command stays /deploy, the nested one appears as /apps/web:deploy, and invoking the unqualified name still tells Claude to apply the nested variant for files in its directory. This is useful package scope. It is not a reason to build arbitrary category folders 2 or 3 levels below ~/.claude/skills.

A monthly housekeeping pass that takes less than an hour

1. Run /doctor and fix invalid settings before editing any skill text.
2. Open /skills and turn off obsolete or risky packages you do not want available.
3. Rerun the census and investigate every change from the previous count.
4. Check descriptions for overlap, vague verbs and text beyond the listing cap.
5. Open every side-effect skill and confirm manual invocation, permission scope, credentials and verification.
6. Delete cloud-sync conflict copies, repair broken symlinks, and regenerate flattened exports and archives that fell behind their source.
7. Move conditional detail out of any SKILL.md that has become a manual.

Do not run this pass around a vanity count. A library that shrinks by 20 can be an upgrade if the remaining descriptions are clearer and the retired procedures moved to the right place.

Claude Skills vs Agents vs MCP Servers

Use a skill for reusable knowledge in the active workflow, an agent for isolated work with its own context, and MCP for tools or data outside Claude Code. They work together, but they solve different problems, and choosing by novelty creates bloated setups. Choosing by boundary keeps the system understandable.

Question	Claude Skill	Subagent	MCP server
What is it?	Reusable instructions, knowledge, workflow and optional local resources	A separate worker with its own context, prompt, tools and permissions	A protocol connection to tools, resources, prompts, databases or APIs
When does it load?	Name and description are listed first; full instructions load when invoked	Starts when the main session delegates a task	Server names and instructions load at startup; tool schemas are deferred by Tool Search in the default current setup
Where does work happen?	Usually in the main conversation; a skill can also fork to an agent	In an isolated context, with results returned to the caller	In the connected local or remote server, with tool results returned to Claude
Context cost	Listing metadata plus invoked instruction content	Separate model tokens, then the returned result uses parent context	Tool names and server instructions plus schemas and results for tools actually used
Best for	Style rules, release procedures, API conventions, QA checklists	Research, noisy logs, independent review, bounded parallel work	WordPress, GitHub, databases, browsers, SaaS accounts, live business data
Wrong use	Calling an API connection a skill or expecting prose to enforce security	Spawning a worker for a one-step task that needs the parent context	Building a server just to store a writing checklist

Anthropic’s feature comparison describes the same split: skills add reusable content to the main context, subagents use separate windows, and MCP connects outside services. My Rank Math MCP server guide shows the combination in one place. Rank Math supplies WordPress SEO abilities through MCP, and a skill teaches Claude the order, the proof rules and the approval boundary for using them. The same pairing applies to WP-MCP: the server gives Claude controlled WordPress operations, and the workflow still needs a procedure for drafts, metadata, media, validation and human approval, which is what my WP-MCP setup notes cover.

For content work, the skill may also carry the rules for putting the answer at the top of a section and for citing sources. My guide to formatting blog posts for AI search explains the reader-facing result. The skill is the internal repeatable method and the article is the public teaching asset. They are related, and they are not the same file wearing two names.

The Limits

There are a few things this library cannot do, and it is better to plan for them than to discover them.

A skill cannot enforce anything. It can say “never publish without approval” and a model can still be talked around the sentence, so only manual invocation, permission rules, hooks and separate credentials actually hold a line. The library does not sync across surfaces on its own either. Every claude.ai upload is a separate package with SKILL.md at the archive root and its symlinks dereferenced, and every re-upload replaces the previous copy with no restore.

The voice skills cannot manufacture substance. A business advice piece drafted with no notes from me passed every internal check, zero fragments, zero banned phrases, clean scan, and still scored as fully machine written on an outside detector, because it had nothing in it only I could say. The rule now is to ask me for raw material before an opinion piece gets drafted at all, and the tiered load replaced the full-manual load for the same reason: more context did not make the voice more mine, it buried the 40 lines that were.

And 165 of the skills on my machine are other people’s work. They run here and stop here, which is why the census separates them and why the “copy” in the title only ever points at the public repositories and the community pack.

Final Remarks

If you have read this far, you have the whole system: one canonical folder, small skills with precise descriptions, scripts for the mechanical parts, and a corrections file that outranks the rules you wrote. The idea I want you to keep is that the count is not the system. Routing, shared references and verification are.

When someone asks me what to do next with their own library, I tell them the same 3 things. Start with 5 skills, not 50, and run them for 2 weeks before adding one, because a description only gets precise after it has missed a few triggers. Put your own edits above every rule you wrote, because a rule describes the writer you imagine and an edit describes the writer you are. And keep every side effect behind manual invocation from day 1, because the first time Claude publishes something on its own is not the day you want to learn about that frontmatter field.

The public skills are on GitHub and the community pack is on the freebies page, and both keep getting the same edits my private copies get. If you would rather have someone set this up for your team, I am always available for a chat.

That is all from my end. I hope it helps.

FAQs on Claude Skills

These answers cover the installation, context, sharing and architecture questions that usually come up after someone builds a first Claude Code skill.