§

Best Practices for Setting Up a Claude Skill

Jason

·

Most teams I've watched try to install a Claude skill spend an afternoon writing one, run it twice, and then forget it exists. The skill is technically present in the vault. Nobody types its name again. Six weeks later it gets archived along with the other half-finished automation projects, and the team goes back to pasting the same multi-paragraph instruction block into a fresh Claude chat every Monday morning.

The skills that survive that fate share a set of properties. They are short. Their descriptions tell Claude when to reach for them in plain language. They keep their scope narrow enough to finish a real task. They are tested with real work before they get shared with anyone else. None of this is a secret — Anthropic's own authoring guide lays out the same principles — but the gap between knowing the principles and producing a skill that earns its place is large, and it shows up in production every day.

This post is the fourth in a series. The first three covered the Obsidian and Claude stack, the PARA organizing method on top of it, and the CLAUDE.md file that orients Claude when a session starts. This one is about the layer that sits on top of all three: skills, which let you package a repeatable workflow once and invoke it forever after with a single slash command.

What a skill is, and how it differs from CLAUDE.md

A skill in Claude Code, Claude Desktop, and Claude Cowork is a folder with a SKILL.md file inside it. The folder name becomes the command — ~/.claude/skills/commit/SKILL.md creates /commit. The SKILL.md contains a YAML frontmatter block (mainly a name and a description) and a markdown body with the instructions Claude should follow when the skill is invoked.

Skills follow the Agent Skills open standard, which works across Anthropic's product line and a growing list of other AI tools. Anthropic ships the same model in Claude Code, Claude Desktop, and Claude Cowork — the GUI agentic product launched in January 2026 for knowledge workers who don't live in a terminal.

The mental model that helps most: CLAUDE.md is what Claude reads at the start of every session to learn who you are and what you do. A skill is what Claude reads only when invoked — when it matches a request semantically, or when you type /skill-name. CLAUDE.md is for facts that always apply. Skills are for procedures that sometimes apply.

This distinction matters because of a hard constraint. Every line in CLAUDE.md costs context tokens in every session, forever. Lines inside a skill cost nothing until the skill is invoked. A 400-line instruction set inside a SKILL.md is fine. A 400-line CLAUDE.md is broken. If a section of your CLAUDE.md has grown into a procedure rather than a fact, the official docs are explicit about what to do with it: move it to a skill.

Where to put a skill, and who gets it

Skills live in one of four locations, and the choice determines who can use them. From Anthropic's docs:

  • Personal — ~/.claude/skills/<name>/SKILL.md. Available across every project on your machine. Use this for skills you want personally — voice checkers, drafting helpers, your preferred commit format.
  • Project — .claude/skills/<name>/SKILL.md inside the project root. Available to anyone who clones the project. Use this for skills the whole team needs — release procedures, project-specific checks, custom deployment commands.
  • Plugin — <plugin>/skills/<name>/SKILL.md. Distributed as part of an installable plugin. Use this when you want to share a skill across many teams or publish it for the wider community.
  • Enterprise / managed — deployed by IT through managed settings. Available to every Claude user in the organization. Use this for company-wide policy, compliance procedures, and standards that nobody should be able to skip.

Project skills are the right default for most consulting work, because the skill lives next to the work it acts on and travels through git with the rest of the project. Personal skills are right for individual habits that don't belong to any one client. The choice is not architecturally complicated — picking the wrong location is easy to undo with a mv.

Six decisions that make or break a skill

These are the decisions where most teams either compound their leverage or quietly poison the skill. None of them are technical. They are all about scope, naming, and discipline.

1. Pick a name in gerund form. Anthropic's own authoring guide recommends naming skills as activities: processing-pdfs, analyzing-spreadsheets, writing-documentation. Verb-plus-noun is acceptable too (process-pdfs). What you want to avoid is the generic noun: helper, utils, tools, documents. The name field has hard rules — maximum 64 characters, lowercase letters, numbers, and hyphens only, and the words "anthropic" and "claude" are reserved.

2. Write the description in the third person, not the first. This is one of the most common mistakes in public skill repositories. Anthropic's docs are blunt about why: "The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems." Write "Processes Excel files and generates reports. Use when the user mentions spreadsheets, .xlsx files, or asks for tabular analysis" — not "I can help you process Excel files." Claude is reading the description to decide whether to load the skill, and first-person framing makes that decision-making worse.

3. Put the trigger conditions in the description. The description is the only field Claude sees when deciding whether to invoke the skill automatically. Anthropic recommends including both what the skill does and when to use it, with key terms users would naturally say. "Generates descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes." Notice the trigger phrases: "commit messages", "staged changes". Those words are bait for Claude's selection logic.

4. Keep the body under 500 lines. Anthropic's docs target "under 500 lines for optimal performance" and recommend splitting longer content into separate files referenced from SKILL.md. Once a skill is invoked, its full content sits in context for the rest of the session, so every line is a recurring token cost across every subsequent turn. The discipline is the same one that applies to CLAUDE.md: write as if every line cost real money, because in attention terms every line does.

5. Decide who can invoke it. The frontmatter has two fields that govern invocation, and most skill authors leave them at the defaults without thinking about it:

  • disable-model-invocation: true — only you can invoke the skill by typing its name. Claude will not load it automatically. Use this for anything with real-world side effects: /commit, /deploy, /send-email. You don't want Claude deciding to deploy because your code "looks ready."
  • user-invocable: false — only Claude can invoke the skill. Use this for background reference material — a legacy-system-context skill that explains how an old subsystem works. Useful when relevant, but not a meaningful command.
  • Defaults — both you and Claude can invoke. Use for skills that benefit from automatic triggering, like style checkers or research helpers.

6. Set appropriate degrees of freedom. Match the level of specificity in the skill to how fragile the task is. The Anthropic guide uses an analogy I've found useful: think of Claude as a robot walking a path. Database migrations are a narrow bridge with cliffs on both sides — give exact commands, do not let Claude improvise. A code review is an open field — give general direction and trust Claude to find a good route. Getting the freedom level wrong in either direction has a cost: too rigid on open-field tasks wastes the model's capacity, and too loose on narrow-bridge tasks ships bugs.

A worked example: the NRW Brand Voice Reviewer

To make the structure concrete, here is how one of the skills inside Not Really Wines — NunnCurtis Labs' fictional demo winery, which we run as a public showcase of this kind of setup — is built. NRW maintains a 6_Skills/ folder in their Obsidian vault with two skills: a Brand Voice Reviewer and an SEO-GEO Auditor. The Brand Voice Reviewer is the simpler of the two and a good template to study.

The skill lives at D:\NRW Vault\6_Skills\Brand-Voice-Reviewer\SKILL.md. The frontmatter:

---
name: brand-voice-reviewer
description: Reviews draft copy against the Not Really Wines brand voice and compliance rules. Use whenever the user asks for a voice check, drafts an email or social post, prepares wholesale outreach, or writes anything destined for an NRW audience. Flags banned phrases, compliance issues (alcohol-free vs non-alcoholic, unsubstantiated health claims), and tone drift.
disable-model-invocation: false
user-invocable: true
---

Two things to note. First, the description is third person and front-loads the trigger phrases — "voice check", "drafts an email", "wholesale outreach" — so Claude knows when to reach for it. Second, both invocation flags are left at the defaults, because both modes matter: Maren wants to type /brand-voice-reviewer explicitly when finalizing a press response, and she also wants Claude to invoke it automatically the moment she pastes a draft DTC email into the chat.

The body of the skill is short. It states the four rules of the brand voice from D:\NRW Vault\CLAUDE.md — warm but precise, plain over clever, sentence case for headlines, no emojis in DTC emails or wholesale communications — and the two TTB-compliance rules: always non-alcoholic, never alcohol-free, and no health claims without TTB-approved phrasing. It then provides a five-step process for the model to walk: read the draft, flag voice issues with line numbers, flag compliance issues separately, propose specific rewrites, and end with an APPROVE or REVISE recommendation.

The whole SKILL.md runs about 90 lines. It does one job well and does not try to be a general-purpose copywriter. When Priya Sandhu (NRW's DTC director) drafts a launch email for the rosé three-pack, Claude invokes the skill automatically, catches an "alcohol-free" phrasing in the subject line (banned at NRW per TTB compliance — the word the brand uses is "non-alcoholic"), proposes a rewrite, and the email ships in twenty minutes instead of two hours of back-and-forth.

Common anti-patterns

A few patterns show up repeatedly in skills that don't earn their place. None are dramatic, but all are common.

Skills that try to do everything. A skill called content that "helps with drafting blog posts, emails, social media, press releases, and meta descriptions" is too broad for Claude to invoke confidently. The description does not give the selector enough signal to know which task you want. Better: five separate skills, each named for the activity, each with a tight description.

Descriptions written for humans, not the selector. "Our brand's writing helper." is what a docs page would say. "Reviews draft copy against the NRW brand voice and compliance rules. Use when the user drafts DTC emails, social posts, wholesale outreach, or press replies." is what the model needs. Always assume the description will be the only thing Claude reads when deciding to load the skill.

Skills that duplicate CLAUDE.md content. If a fact lives in both CLAUDE.md and a skill, you are paying for it twice — once in every session, once when the skill is invoked. Anthropic's docs put it directly: "Do not waste CLAUDE.md lines on things Claude will learn after one session of working in your codebase." The same logic in reverse applies to skills. Either a fact is universal (in which case it belongs in CLAUDE.md) or it's procedural and situational (in which case it belongs in a skill), and it should not live in both.

Skills that don't get tested before sharing. Anthropic recommends building three evaluations before writing extensive documentation — three representative tasks that test what the skill is meant to do. Run them. Measure whether Claude's behavior improves with the skill versus without it. A skill that passes a single one-off test will fail the moment a real user hits an edge case. Three real tests catch most of the failures that would otherwise become bug reports from teammates.

Time-sensitive content inside the skill body. "Before August 2025, use the old API." will be wrong six months from now. Push time-sensitive details to an Old patterns collapsible section that documents the history without cluttering the current path.

How to test a skill before sharing it

Anthropic recommends an iterative process they call "build with Claude A, test with Claude B." It works because Claude understands both how to write effective agent instructions and what an agent needs to succeed. The loop:

  1. Work through a real task without the skill, letting yourself paste context, explain preferences, and provide procedural knowledge naturally. Notice what you re-explain.
  2. Ask Claude (call it Claude A) to extract the reusable pattern into a draft skill.
  3. Review for length and conciseness. Cut explanations Claude already knows. Move large reference material into separate files.
  4. Test the draft skill with a fresh Claude session (Claude B) on a different but similar task. Observe what Claude B does — does it invoke the skill when expected? Does it follow the procedure?
  5. Return to Claude A with specific observations. "Claude B forgot to filter test accounts. The skill mentions filtering, but maybe it's not prominent enough." Iterate.
  6. Repeat across several real tasks before sharing the skill with a teammate.

The pattern works because Claude B is acting as the user's stand-in. Whatever the model misses with the skill, a real user will miss too. Iterating on observed behavior is what catches the failures assumptions miss.

Smaller skills, more of them

If a skill is approaching 500 lines, the right move is almost never to make it longer. The move is to break it into two skills with sharper descriptions, or to push half the content into a supporting reference file the skill links to. Anthropic's own bundled skills — /simplify, /batch, /debug, /loop, and /claude-api, all shipped with Claude Code — are each small and tightly scoped, and they are the pattern to copy.

If you want help setting up a vault, an Obsidian + Claude workflow, and a small library of skills that fit how your business operates — institutional knowledge, brand voice, compliance procedures, the steady-state work the team does every week — that is the work we do at NunnCurtis Labs.

Resources

← All insights