Claude Skills Best Practices: What Belongs in a Skill

Most Claude skills go wrong in the same place. The author writes down everything they know about a job, when a skill is only the procedure for doing it. The best practice that decides all the others is what you leave out. This guide is the set of Claude skills best practices that survive contact with a real repo: what belongs inside a SKILL.md and what quietly rots it, how to write a description that actually fires, how to package a skill so someone else can install it, and why the facts about your product belong somewhere a skill cannot reach.

Key takeaways

• A skill is a procedure, not a knowledge base. Write down how a task gets done, not what happens to be true about your project this week.
• The description in the frontmatter is the highest-leverage line in the file. Claude reads it to decide whether to load the skill at all, so vague wording means the skill never fires.
• Keep the body deterministic: named sections, real commands, a length cap. "Be helpful here" is not an instruction.
• Any line that would be wrong after a normal month of work is a fact, not a step. It belongs in a living brain with an update mechanism, not in a SKILL.md.
• Assume strangers will install your skill. Skills travel as folders in GitHub repos, as plugins registered in settings.json, and through community lists, so anything that is only true on your machine breaks silently downstream.

What a Claude skill actually is, and what it can do

Before any of the practices make sense, be precise about the mechanism, because the mechanism is what makes most of the rules obvious.

A Claude skill is a folder. Inside it is a SKILL.md file with YAML frontmatter carrying two required fields, name and description, followed by the instructions the model reads when it decides the skill is relevant. The folder can also hold helper scripts and reference documents, which is what makes a skill a small self-contained pack rather than a saved prompt.

What a skill does is narrower than people assume. It does not teach the model anything new, and it does not run in the background. It sits dormant until the description matches what you are doing, then loads its instructions into the conversation so the model performs that one task your way instead of its own. That is the whole mechanism, and it is why the description is the highest-leverage line in the file. A skill that never fires is worth nothing no matter how good the body is, so write the description as a list of the real triggers ("use when the user asks to draft a PR description, summarize changes for review, or write release notes") rather than a summary of the skill's contents.

The second thing that shapes good authoring is where the file ends up. Skills travel. They get copied into .claude/skills/, pushed to a repo, installed as plugins by people who will never ask what you meant. That gives you a single test that decides most of what goes in: write only what stays true after the file leaves your laptop.

Where Claude skills actually live today

Here is the practical map, grouped by what you are trying to do.

A few notes on each.

GitHub repos are the base layer. Almost every shared skill traces back to a repo somewhere. The advantage is you can read the SKILL.md and any bundled scripts before you install, which you should always do, because a skill can include instructions that run commands. Treat an unknown skill the way you would treat an unknown shell script.

Plugin marketplaces are the closest thing to an app store. A marketplace is just a URL you register, after which you can install plugins from it, and plugins can carry skills, slash commands, and agents together. This is the smoothest path for install-and-update, but you are trusting the marketplace owner, so stick to ones you can vet. Ours is one you can read end to end first: /plugin marketplace add mkhalid1/locul-skills installs the skills we publish, free and with no account. The live count is on that page rather than repeated here, because a number typed into an article is exactly the kind of fact that goes stale the moment the directory changes. That directory doubles as the worked example for the rest of this guide, including the ones that were tested and cut instead of shipped.

Curated lists are how you find things in the first place. They are unofficial, they go out of date, and they are still the fastest way to see what the community has already built so you do not rebuild it.

How to package a skill pack for sharing

A "skill pack" is nothing more than a folder (or a repo of folders) laid out the way Claude expects. Here is the minimum structure for one skill.

my-skill/
  SKILL.md

And here is a real SKILL.md you can copy and adapt. This one packages a repeatable task: writing a tight PR description from a diff.

---
name: pr-description
description: Write a clear, structured pull request description from a
  git diff. Use when the user asks to draft or improve a PR description,
  summarize changes for review, or write release notes for a branch.
---

# PR Description Writer

When asked to write a PR description:

1. Run `git diff main...HEAD` (or the branch the user names) to get the changes.
2. Group the changes by area (feature, fix, refactor, tests, docs).
3. Output in this exact order:
   - **What changed** (2 to 4 bullets, plain language, no restating file names)
   - **Why** (the problem this solves, one or two sentences)
   - **How to test** (concrete steps a reviewer can run)
   - **Risk** (what could break, or "low" with one reason)
4. Keep it under 200 words. No filler, no "this PR."

Two things make this shareable and not just a prompt. The description names the exact triggers (draft a PR description, summarize changes, write release notes) so the model loads it at the right moment. The body is deterministic: fixed sections, a word cap, and a real command to run.

To turn one skill into a pack, put several of these folders in one repo:

my-claude-skills/
  pr-description/
    SKILL.md
  changelog/
    SKILL.md
  test-plan/
    SKILL.md
  README.md

Push that to GitHub, and you have shared a skill pack. Someone installs it by copying the folders into their .claude/skills/ directory, or, if you publish it as a plugin marketplace, by registering your marketplace URL and installing. That is the whole distribution story today.

Skills versus knowledge: the distinction that decides what to share

This is where most skill repos quietly fail, and it is the reason a marketplace alone will never be enough.

A skill is a procedure. It encodes how to do a repeatable task the same way every time: how you format a PR, how you structure a test plan, how you run a release. Procedures are a great fit for sharing, because the steps are the same for everyone who does that task.

A skill is a bad place to store facts. The moment you write "our API base URL is X" or "we price the Pro tier at Y" into a SKILL.md, you have created a landmine. Those facts change. The price moves, the service gets re-owned, the URL migrates. The skill still says the old thing, confidently, forever, because nothing updates it. You end up with a shared repo of instructions that are half-true, and the person who installed your pack has no way to know which half.

Here is the split, made concrete.

Read the right column again. Those are exactly the things that make an AI's output about YOUR work useful instead of generic, and none of them belong in a skill, because a skill has no mechanism to keep them current. That is a different job. Skills answer "how do I do this task." Live context answers "what is true about me, my product, and my decisions right now."

Where a Memory Pack fits (and where a skill still wins)

Once you accept that split, the shape of the tooling becomes obvious. You want two things that do not fight each other.

For procedures, keep sharing skills. A repo of SKILL.md folders, installed by hand or through a plugin marketplace, is the right tool for repeatable how-to.

For facts, you want a bundle that carries the actual current context of a domain, its facts, opinions, and playbooks, in a form your AI can read and, critically, one that can be updated when the world changes. That is what a Memory Pack is: a curated bundle of facts, decisions, and playbooks with entity tags, schema-validated, that you inject into a brain your AI reads over MCP. The difference from a skill is that the underlying brain uses supersedence: when a fact changes, the old value is marked superseded and the new one takes over, with history preserved. A skill has no version of that. It just says whatever you last typed.

So the clean division for a team looks like this:

• Share skills for the how (PR format, release steps, test plans).
• Share a Memory Pack for the what (current facts, decisions, positions) that your AI needs to make the how produce work that sounds like you and is actually correct.

Locul is a local-first desktop app that builds and maintains that living brain from what you already produce, then serves it to your AI tools over MCP, so the facts stay current without you babysitting a repo. It is free to start, 500 memories, local AI, if you want to see the difference between a shared skill and shared context.

One honest note on scope: team share-codes for Memory Packs are on the roadmap, not shipped, so today packs are shareable as bundles you install, not one-click team sync. If you need shared living context inside a team right now, that is the direction to watch, not a claim to bank on.

A practical setup you can copy

If you are assembling your own stack today, this is a sane layout.

• A skills repo on GitHub with one folder per repeatable task, each with a sharp description. Copy into .claude/skills/ or ship as a plugin marketplace for easy updates.
• A separate home for facts. Do not smuggle facts into skills. Keep the things that change (pricing, ownership, decisions, current state) in a living brain with a real update mechanism.
• A review habit. Before installing anyone's skill, read the SKILL.md and any bundled scripts. Skills can run commands. If a line would be wrong after a normal month of work, it does not belong in a skill.

The reason this matters is the same reason a bigger model does not fix generic output: quality is capped by the freshness of the context you feed it. A marketplace solves distribution. It does not solve currency. For the currency side, see how to give your AI a memory that lasts, which covers the update mechanism a skill repo cannot give you.

---

Frequently asked questions

Is there an official Claude skills marketplace?

Not a single official storefront the way an app store works. Skills are distributed through GitHub repos, through plugin marketplaces you register in settings.json and install from, and through community curated lists. For one-step install and updates, plugin marketplaces are the closest thing, but you are trusting whoever runs them, so vet the source first.

How do I share a Claude skill I built?

Package it as a folder with a SKILL.md (frontmatter with name and description, then the instructions), bundle any helper scripts in the same folder, and push it to a GitHub repo. Others install it by copying the folder into their .claude/skills/ directory, or by adding your repo as a plugin marketplace and installing from it. A README that shows the trigger phrases helps people know when the skill fires.

What is the difference between a Claude skills repo and a Memory Pack?

A skills repo distributes procedures: how to do a repeatable task the same way each time. A Memory Pack distributes facts, opinions, and playbooks about a domain, and it plugs into a brain that can update those facts when they change. Put how-to in skills, put current facts in a living brain, and do not mix them, because a skill has no way to stay current.

Can I put my project's details inside a skill?

You can, but you should not put facts that change. Pricing, service ownership, current version numbers, and this week's decisions all go stale, and a skill has no mechanism to update them, so it will keep asserting the old value. Keep procedures in the skill and keep the changing facts somewhere with a real update path. See give your AI memory that lasts for how that update path works.

Do shared skills work with local or open-weight models?

Skills are plain instruction files, so they are not tied to a specific model. If you run a local model, the skill format still applies, though how the model loads and follows it depends on your client. For the context side, Locul supports local embeddings via Ollama so the living brain that feeds your AI can run on your machine too, which matters if you are keeping facts local rather than shipping them to a cloud.

How do I keep my shared skills from going out of date?

Review them on a schedule and strip out anything that is a fact rather than a step. A good test: if a line in the SKILL.md would be wrong after a normal month of work, it is a fact, not a procedure, and it belongs in a living brain instead. Skills you keep purely procedural age slowly. Skills stuffed with project facts rot fast, and no marketplace fixes that for you.