Claude Skills: How I Run 168 of Them in Production

Claude Skills stopped being a folder of clever prompts for me when the count reached 168. At that size, the writing inside each SKILL.md still matters, but the system around it matters more: clear descriptions, narrow jobs, one canonical library, predictable loading, and enough housekeeping that Claude can find the right instruction when work gets messy.

More skills don’t guarantee better output. My current library is past the point where I can pretend every package deserves equal attention. The useful part is the plumbing. I keep one source tree, expose it to the tools I use, and turn repeated corrections into reusable procedures. The tradeoff is choice pressure: vague descriptions, duplicate packages, and oversized instructions make a large library worse, not better.

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

What Claude Skills Actually Are

Claude Skills are folder-based instruction packages that Claude loads when a task matches their purpose. A portable Agent Skill contains a required SKILL.md entrypoint plus optional scripts, references, examples, templates, and assets. Anthropic’s Agent Skills documentation describes the format as reusable, filesystem-based expertise rather than a one-off chat prompt.

That distinction is practical. A prompt tells Claude what to do once. A Claude Code skill records how a repeated job should work, when the job applies, which files to consult, which commands are permitted, and what a valid result looks like. If I keep pasting the same checklist into sessions, I have already found a skill candidate.

The smallest useful skill can be 20 lines. The biggest mistake is treating that minimum as an invitation to write a 900-line policy manual. Anthropic recommends keeping the SKILL.md body under 500 lines and moving conditional detail into referenced files. The main file should orient and route. Supporting files should carry depth.

The anatomy of a real SKILL.md

The stop-slop skill in my active library is a clean example. Its frontmatter says what the skill does and when to use it. Its body states five core rules, a quick check, a scoring method, and links to deeper examples. The site-specific anti-slop files remain the source of truth, so the skill routes to them instead of copying a stale snapshot into every 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

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

## Core rules

1. Cut filler phrases.
2. Break formulaic structures.
3. Vary rhythm.
4. Trust readers.
5. Check the final draft.

A portable skill should include both name and description. The Agent Skills standard limits names to 64 characters using lowercase letters, numbers, and hyphens. Descriptions can run up to 1,024 characters, but shorter usually wins because the description has one job: help Claude decide whether the skill belongs in this task.

How Claude Skills Work Under the Hood

Claude Skills use progressive disclosure: Claude sees a small listing first, loads the main instructions after invocation, and reads supporting files only when needed. This saves context compared with putting every workflow into CLAUDE.md. It does not make a library free. Names and descriptions still occupy listing space, and invoked instructions enter the conversation context.

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 trigger situation.
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 automatically.
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.

In Claude Code, an invoked SKILL.md stays in the session rather than disappearing after one answer. The current Claude Code skills guide says the rendered content enters as one message, remains for the session, and is carried through compaction within a shared budget. Re-invoking identical content does not keep appending full duplicate copies in current releases.

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

You can also call a skill directly with /skill-name. Manual invocation is useful when timing matters or when the workflow has side effects. Claude Code supports disable-model-invocation: true for skills that only a user should start, such as deployment, publishing, billing, or sending a message. A description can guide a model. It cannot replace an approval boundary.

What 168 skills cost in context

Anthropic’s general Agent Skills model describes metadata as a small per-skill cost, then full instructions on demand. Claude Code adds a more specific control: skillListingBudgetFraction reserves 1% of the context window for the skill listing by default. When the listing exceeds that budget, Claude Code drops descriptions for less-used skills and keeps only their names. The skill remains callable, but Claude has less information for automatic selection.

This is where hoarding starts to hurt. A library of 168 precise names can still work. A library of 168 long, overlapping descriptions makes the router fight for space before the actual task begins. The current /doctor check estimates listing cost against that budget, while /skills lets you turn a package on, reduce it to name-only, keep it user-invocable, or turn it off.

Check out my shared Claude Code skills here on GitHub.

Where Agent Skills work now

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

Anthropic’s current support guide covers the Claude plan and code-execution requirements. For developers, the API currently uses the Skills API alongside code execution and beta headers. Those details can change, so copy the request shape from the live platform docs rather than an old blog post.

My 168-Skill Library, Categorized

My current Claude Skills census contains 168 immediate child directories under ~/.claude/skills whose SKILL.md entrypoint resolves. That definition matters. It follows the root symlink and counts callable top-level packages, not every nested test fixture, dependency copy, reference file, or packaging artifact anywhere below the tree.

The category labels below are mine, not Anthropic’s. Each of the 168 current directory names appears once. The counts add up to 168, so this is a census rather than a handpicked sample.

The largest group is WordPress and block development at 40 packages. That reflects the work, not a marketplace strategy. The library grew from actual site, plugin, Gutenberg, SEO, publishing, design, and education tasks. Some packages overlap. A large library needs consolidation as much as expansion.

I am not calling any of these the most-used skills. The allowed evidence for this census is package names, skill instructions, symlink targets, and export archives. It contains no trigger-frequency telemetry. The seven-skill list below is a practical starter set, not a ranking disguised as data.

If you revisit this list in 2026, rerun the command. Skill counts decay faster than articles because one rename, archive, or missing entrypoint changes the result immediately.

One Skill Library, Three AI Tools

I store my Claude skills on my iCloud Drive. This helps me port skills between machines, and I can use these skills on all my Macs.

My skill architecture has one canonical iCloud tree, two filesystem symlinks, and one separate Codex catalog path. The slogan “one folder, three tools” is directionally right, but calling all three consumers symlinks would be wrong on this machine.

Claude, Codex and the shared Agents path are symlinks but the skills are saved on iCloud Drive.

iCloud Drive/claude-sync/
├── skills/                         # canonical custom-skill source
├── context/voice-dna.md            # canonical voice source
└── _skill-packages/                # portable export archives

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

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

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

This gives Claude Code and tools that follow ~/.agents/skills the same bytes. Codex keeps its system packages separate while preserving the Claude-sync source path for custom skills. One edit to the canonical stop-slop/SKILL.md reaches the consumers that point at that tree. There is no three-way copy job to forget.

The same pattern resolves shared context. In this writing system, voice/voice-dna.md points to ../../claude-sync/context/voice-dna.md. Inside stop-slop, references/voice-dna.md points to ../../../context/voice-dna.md. The nested writing packages go up one extra level. Different access paths, one canonical voice file.

What the symlink solves, and what it does not

A symlink solves duplication. It does not solve portability, conflict handling, or surface-specific installation. Anthropic states that custom skills do not sync automatically between Claude Code, Claude, and the API. A local filesystem link cannot upload a package to Claude or create a workspace skill ID in the API.

It also does not make every nested folder a valid personal skill. Claude Code expects personal packages at ~/.claude/skills/<skill-name>/SKILL.md. Current nested discovery refers to package-local .claude/skills/ directories in a repository, not arbitrary category folders such as ~/.claude/skills/writing/blog-article/. Keep personal skill folders directly under the recognized root unless a plugin or tool has documented another loader.

What my .skill packages actually are

The _skill-packages folder is an export layer, not a Claude Code requirement. The current stop-slop.skill file identifies as a ZIP archive and contains SKILL.md, a license, and its reference files. The .skill suffix is a local packaging convention that keeps the artifact recognizable.

Claude’s upload flow asks for a ZIP with the skill folder at the archive root. The Skills API also accepts uploaded bundles. So I treat a .skill archive as source material, not as proof that every Claude surface will import it directly. Repackage it to the structure required by the destination. Renaming an extension is not a deployment method.

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 external service. That is a feature. 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 three times: release notes, pull-request review, article cleanup, a database query pattern, or 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, two inputs, and three user phrasings. You have not written the instructions yet, but the router already has enough information to make a decision.

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 portable metadata in YAML frontmatter and the procedure in Markdown. State inputs, ordered work, failure boundaries, and 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 will prevent more bad release notes than another page of tone adjectives.

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 state when Claude should read it. Avoid a chain where one reference points to another reference that points to a third. Anthropic’s authoring guide recommends one-level references because deep chains get skipped.

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

If the skill needs a deterministic transformation, add a script and make the error behavior explicit. If the work needs an outside database, WordPress site, or 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. Current releases watch 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 Claude Code can watch it.

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 three matching prompts and two 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 Claude, 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 a prompt snippet.

My Most Used Skills

These seven are my most used skills.

The stop-slop package has also become a published teaching asset. My Stop Slop skill walkthrough shows the patterns it catches and why a named editorial gate works better than asking an AI to “sound human.” The skill is useful because the instruction is inspectable. You can disagree with a rule, edit it once, and run the new standard everywhere that points to the canonical tree.

The screenshot and FAQ skills show the other end of the spectrum. They encode exact output contracts. One requires a visible highlight and inspected PNG. The other requires flattened ACF fields and a string row count. Those rules would be tedious to restate in every article session, which is exactly why they belong in skills.

seo-magic and wp-plugin-development are reference-heavy. amazon and ca-daily combine instructions with scripts and outside systems. This range is the point. A skill can be a ten-line checklist or a router for a production workflow. Its job still needs one sentence.

Mistakes That Kill Skill Adoption

Skill adoption fails when Claude cannot tell when to load the package, when the instructions ask for too many unrelated jobs, or when the workflow hides side effects behind friendly prose. Most failures are routing and trust failures before they are writing failures.

A vague description

“Helps with SEO” competes with audits, schema, internal linking, ranking analysis, and content editing. Claude either ignores it or reaches for it too often. Name the job, input, output, and user language: “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, CRO, analytics, and pricing with equal precision. Split by decision and output. Focused packages compose better, and Claude can use more than one when a task crosses boundaries.

Treating instructions as enforcement

A skill can say “never publish without approval,” but that sentence is not a security control. Use user-only invocation, permission rules, hooks, restricted accounts, or separate credentials for side effects. Skills teach judgment and procedure. Deterministic controls enforce policy.

Hardcoded secrets and unreviewed scripts

API keys do not belong in SKILL.md, a shell example, or a shared ZIP. Read credentials from an approved secret store or environment file 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.

Putting project rules in the personal library

A WordPress block schema for one client should live with that repository. A general code-review method can live in the personal root. Claude Code precedence also matters: enterprise skills override personal skills, personal skills override project skills, and plugins use namespaced commands. Duplicate names can make a correct skill appear broken because another scope wins.

A reference maze

SKILL.md should link directly to the file needed for a branch of work. If the model must follow four internal links to find the rule, it may stop early or load irrelevant material. Keep the entrypoint short, make reference names literal, and add a table of contents to long reference files.

Hoarding without a retirement rule

Every new description competes for listing space. Archive a package when its job moved into Claude Code, merged into another skill, or belongs in project instructions. Cloud-sync conflict copies deserve the same treatment: inspect the winner, remove the duplicate, and regenerate exports. Do not leave two almost-identical entrypoints and expect Claude to infer which one is current.

Skill Housekeeping With /doctor, /skills, and /context

Use /doctor for configuration health, /skills for visibility, and /context for actual context occupancy. On July 13, 2026, my installed Claude Code reports version 2.1.207. That version supports the current nested project-skill behavior and symlink handling documented for 2.1.203 and later.

This corrects a tempting but unsupported claim: /doctor is not documented as an unused-skill analytics tool. Anthropic’s configuration debugging guide says it checks unused extensions, not unused skills, and proposes fixes for setup problems. The settings guide adds skill-listing cost estimation. Neither source gives trigger-frequency telemetry.

How nested .claude/skills discovery works

Claude Code loads project skills from the starting directory and parent directories up to the repository root. When Claude reads or edits a file below the starting directory, it can discover a closer .claude/skills/ root for that package. In a monorepo, apps/web/.claude/skills/deploy/SKILL.md can then apply when Claude works inside apps/web.

If a nested skill and a root skill share a name, both remain available. The root command stays /deploy, while a current Claude Code release can expose the nested variant with a directory-qualified name such as /apps/web:deploy. This is useful package scope. It is not a reason to build arbitrary personal categories two or three folders below ~/.claude/skills.

A monthly housekeeping pass that takes less than an hour

1. Run /doctor and fix invalid settings before editing skill text.
2. Open /skills and turn off obsolete or risky packages you do not want available.
3. Run the resolvable-directory census and investigate changes 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. Inspect sync conflicts, broken symlinks, missing references, and stale export archives.
7. Move conditional detail out of any SKILL.md that has become a manual.

Do not optimize this pass around a vanity count. A library shrinking from 168 to 150 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 can work together, but they solve different problems. Choosing by novelty creates bloated setups. Choosing by boundary keeps the system understandable.

Anthropic’s feature comparison describes the same split: skills add reusable content to the main context, while subagents use separate windows. MCP connects external services. My Rank Math MCP Server guide shows the combination clearly. Rank Math supplies WordPress SEO abilities through MCP; a skill can teach Claude the order, proof rules, and approval boundary for using them.

The same pairing applies to WP-MCP. The server gives Claude controlled WordPress operations. The workflow still needs a procedure for drafts, metadata, media, validation, and human approval. If you want the connection side, see my WP-MCP setup and safety notes.

For content work, the skill may also encode answer-first structure and citation rules. My guide to formatting blog posts for AI search explains the reader-facing result. The skill is the internal repeatable method; the article is the public teaching asset. Those are related, but they are not the same file wearing two names.

What I Would Do With a New Skill Library

Start with five skills, not 168: one writing or code standard, one review checklist, one repeated production task, one project-specific reference, and one skill that uses an existing tool well. Run them for two weeks. Improve descriptions when triggers miss. Split any package that produces two unrelated outputs.

Then add a canonical source only when duplication appears. Symlinks are useful after two consumers need the same tree. Before that, they add debugging. Keep side effects manual, references shallow, scripts inspectable, and the main file short enough to understand during a code review.

If you want working examples rather than an empty directory, browse my published AI Toolbox. Pick one skill whose job you already repeat. Read every line. Install it in the narrowest scope. Then change it until the instructions match your work instead of mine.

Frequently Asked Questions

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