Claude Code Skills: Best Practices and 3 Examples

Claude Code skills are folders with a SKILL.md file that teach Claude a repeatable task: YAML frontmatter says what the skill does and when to use it, and the Markdown body holds the instructions, optionally backed by scripts and reference files. Claude sees only each skill's name and description until a task matches, then loads the rest. Good skills have a precise description, a short SKILL.md, scripts for anything deterministic, and they get tested before anyone else installs them.

Below: the format, where skills live, best practices, three skills you can copy, where to find more, and how to share your own privately. Everything was checked against the Claude Code skills documentation and Anthropic's skill authoring best practices as of November 2026.

What a Claude Code skill is

A skill is a directory. The only required file is SKILL.md; everything else is optional:

my-skill/
├── SKILL.md          # frontmatter + instructions (required)
├── reference.md      # detailed docs, read only when needed
├── examples.md       # sample inputs and outputs
└── scripts/
    └── helper.py     # executed, not loaded into context

The frontmatter is where Claude decides whether to use the skill. In Claude Code every field is technically optional (the name defaults to the folder name), but the docs recommend always writing a description. If you want the same skill to work in other tools, follow the stricter Agent Skills specification, which requires both name (up to 64 lowercase letters, numbers and hyphens, matching the folder) and description (up to 1,024 characters). We cover that standard in Agent Skills: the open SKILL.md standard explained.

Progressive disclosure: why skills are cheap

Anthropic's Agent Skills overview describes three loading levels:

1. Metadata, about 100 tokens per skill, always in context so Claude knows the skill exists.
2. Instructions, the SKILL.md body (recommended under 5,000 tokens), loaded only when the skill is triggered.
3. Resources: reference files are read when needed, and scripts are run, so only their output enters context.

That is the practical difference from CLAUDE.md: a skill's body costs nothing until it is used, so you can keep dozens installed. If you are unsure whether something belongs in a skill, a subagent or your project instructions, see skills vs agents vs AGENTS.md.

Where Claude Code skills live

Claude Code looks in several places. The location decides who gets the skill:

Location	Path	Who gets it
Personal	~/.claude/skills/<name>/SKILL.md	You, in every project on this machine
Project	.claude/skills/<name>/SKILL.md	Everyone who clones the repo (commit it)
Nested	<subdir>/.claude/skills/<name>/SKILL.md	Sessions working in that subdirectory
Plugin	<plugin>/skills/<name>/SKILL.md	Anyone with the plugin enabled, as /plugin-name:skill-name
Enterprise	Managed settings directory	Every user in the organization

When two skills share a name, enterprise wins over personal and personal over project; plugin skills are namespaced, so they never collide. Three more details from the docs are worth knowing:

• Slash commands were merged into skills. .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy; old command files keep working.
• Edits apply live in the current session. Only a brand-new top-level skills directory needs /reload-skills.
• Project skills are found upward, from the start directory to the repository root, which suits monorepos.

Claude Code skills best practices

1. Write a description that triggers

The description is the only thing Claude reads before choosing a skill, often from a long list. Anthropic's guidance is specific: say what the skill does and when to use it, include the words a user would actually type, and write in the third person, because the text is injected into the system prompt.

# Too vague: rarely triggers
description: Helps with documents

# Specific: names the task, the file types and the trigger phrases
description: Extracts text and tables from PDF files, fills forms and merges
  documents. Use when working with PDFs or when the user mentions forms or
  document extraction.

In Claude Code, description plus the optional when_to_use field are truncated at 1,536 characters in the skill listing, so put the trigger words first.

2. Keep SKILL.md lean

Anthropic puts it bluntly: the context window is a public good. Assume Claude already knows what a PDF or a git tag is, and write only what it could not guess: your conventions, your file locations, your edge cases. Concretely:

• Keep SKILL.md under 500 lines; move detail to reference.md or a references/ folder.
• Link reference files directly from SKILL.md, one level deep. Claude may only preview files that are referenced from other references.
• Give reference files longer than about 100 lines a table of contents at the top.
• Offer one default approach instead of a menu of five libraries.
• Leave out dates and "after August, do X" notes; they rot.

3. Bundle scripts for anything deterministic

If a step must be done the same way every time (parsing, validating, calling an API), ship a script. Claude runs it and only the output enters context, which is more reliable and cheaper than having Claude regenerate the code each time. Make the script handle its own errors ("solve, don't defer" in Anthropic's words) and say clearly in SKILL.md whether Claude should run the script or read it.

One rule we add: no API keys in a skill folder, ever. Skills get copied, committed and shared. If a script needs a credential, have it read an opaque reference at runtime; EnvSave does this with es_ keys so neither the skill nor the agent sees the real value. Our Claude Code API key setup guide covers the options.

4. Control who can invoke it

By default both you and Claude can trigger a skill. For anything with side effects (deploys, commits, messages to other people) add disable-model-invocation: true so it only runs when you type /skill-name. The opposite, user-invocable: false, hides background knowledge skills from the / menu while letting Claude use them.

Note that allowed-tools does not restrict tools. In Claude Code it pre-approves the listed tools for the turn that invokes the skill, so you are not prompted for each git command. Use disallowed-tools if you want to remove tools.

5. Test before you share

Anthropic recommends building evaluations first: run Claude on a few representative tasks without the skill, note where it fails, write the minimum instructions that fix those failures, and compare. Their checklist asks for at least three scenarios, tested on every model you plan to use, since instructions that suit Opus may be too thin for Haiku. Also test a near-miss request and confirm the skill does not fire.

Claude Code skills examples

Three small skills, each showing one technique. All three folders were checked with the Agent Skills reference validator, skills-ref; the third uses Claude Code-only fields, which matters if you share it with other agents (more on that below).

Example 1: instructions only

---
name: commit-message
description: Writes Conventional Commits messages from the staged git diff. Use when the user asks to commit, write a commit message, or describe staged changes.
---

# Commit messages

1. Run `git diff --staged`. If it is empty, tell the user nothing is staged and stop.
2. Write one message in this format:

   type(scope): imperative summary under 72 characters

   One short paragraph on why the change was made.

3. Allowed types: feat, fix, docs, refactor, test, chore.
4. Show the message and ask before running `git commit`.

Example 2: a bundled script

changelog-entry/SKILL.md:

---
name: changelog-entry
description: Adds a dated entry to CHANGELOG.md from the commits since the last git tag. Use when the user is preparing a release, bumping a version, or asks to update the changelog.
---

# Changelog entry

Run the script from the repository root and paste its output under the
`## Unreleased` heading of CHANGELOG.md:

    python3 scripts/commits_since_tag.py

Group the lines under Added, Fixed and Changed. Drop merge commits and
anything starting with `chore:`. Never edit older entries.

changelog-entry/scripts/commits_since_tag.py:

"""Print commit subjects since the most recent tag, one per line."""
import subprocess
import sys


def run(*args: str) -> str:
    return subprocess.run(args, capture_output=True, text=True, check=False).stdout.strip()


last_tag = run("git", "describe", "--tags", "--abbrev=0")
if not last_tag:
    print("No tags yet: listing the last 20 commits.", file=sys.stderr)
    rng = ["-20"]
else:
    rng = [f"{last_tag}..HEAD"]
log = run("git", "log", *rng, "--no-merges", "--pretty=format:- %s")
print(log or "No new commits since " + last_tag)

Run in a test repo with two commits after tag v0.1.0, it prints exactly what Claude will see, and nothing else enters context:

$ python3 scripts/commits_since_tag.py
- feat(cli): add --json flag
- fix: handle empty input

Example 3: live context, manual only

Claude Code can run shell commands before the skill reaches Claude with the !`command` syntax; the output replaces the placeholder. This skill is manual-only and pre-approves the two gh commands it needs:

---
name: pr-summary
description: Summarizes the current pull request for reviewers. Use when the user asks for a PR summary, review notes, or what changed in this branch.
disable-model-invocation: true
allowed-tools: Bash(gh pr diff *) Bash(gh pr view *)
---

## Pull request context
- Title and body: !`gh pr view --json title,body`
- Changed files: !`gh pr diff --name-only`

## Your task
Write three sections: What changed, Why, and What reviewers should check first.
Keep it under 200 words and name files with their paths.

Per the docs, a failing command aborts the whole invocation, so append || true to commands that may exit non-zero. The strict validator rejects this skill (Unexpected fields in frontmatter: disable-model-invocation) because that field is a Claude Code extension; Claude Code itself accepts it.

Where to find Claude Code skills: GitHub, library and marketplace

• Anthropic's skills repo. github.com/anthropics/skills is the reference library, with document skills (docx, pdf, pptx, xlsx), skill-creator, mcp-builder, webapp-testing and more. It doubles as a plugin marketplace: run /plugin marketplace add anthropics/skills, then /plugin install document-skills@anthropic-agent-skills or example-skills@anthropic-agent-skills. The README says the skills are for demonstration and education, so test before relying on them.
• The official plugin marketplace. Claude Code registers claude-plugins-official on your first interactive session; run /plugin to browse it, or use the web catalog at claude.com/marketplace. Plugins bundle skills with agents, hooks and MCP servers (docs). Anthropic also runs a community marketplace, claude-community.
• skills.sh. A cross-agent directory from Vercel, ranked by installs. Its CLI installs from any GitHub repo: npx skills add vercel-labs/agent-skills (source).
• GitHub search. Many teams publish skills in ordinary repos; search for SKILL.md files.

Treat every third-party skill as code you are about to run. Claude Code's own plugin security page warns that a plugin "can execute arbitrary code on your machine with your user privileges", and Anthropic's docs recommend using skills only from sources you trust and auditing every bundled file otherwise.

How to version and share your own skills privately

Once you have a handful of good skills, two problems appear: you want a history of changes, and you want to give one skill to one colleague or client without publishing your whole library. Your options:

• Commit them to the project in .claude/skills/. Simple and versioned, but tied to one repo.
• Package them as a plugin in a private marketplace repo. Claude Code clones private marketplaces with your existing git credentials. Good for a team that all uses Claude Code and installs the same bundle.
• Publish each skill to its own private repo and share it per person. This is what Skylls does.

Skylls is a CLI on top of GitHub: every skill gets its own private repository, each version is a git tag with a changelog entry, a gitleaks secret scan runs before anything is pushed, and GitHub repo access decides who can install what. Here is the real top of skylls --help (version 1.17.0), trimmed:

$ skylls --help
Share agent skills, agents and swarms via GitHub.

    find                Search skills by keyword and/or folder.
    add                 Install a skill (name or name@version).
    push                Publish a new version of your skill to its private
                        repo.
    share               Let GitHub users install your skill (no users: who has
                        access).
    pull                Check for new versions (--update installs them).
    agents             Share and install agents (yours live in ~/agents).
    swarms              Share and install swarms (yours live in ~/swarms).

A typical round trip, from the Skylls docs:

# you
skylls push changelog-entry -m "First version"   # private repo, v1.0.0, scanned for secrets
skylls share changelog-entry @teammate           # one person, one skill

# your teammate
skylls source add <you>                          # once: accept your shares
skylls add changelog-entry -g                    # installs to ~/.claude/skills/
skylls pull --update                             # later: get new versions

Because the folder is the same Agent Skills format, -a all installs one copy for Claude Code (.claude/skills) and links it for Codex (.agents/skills) and Gemini CLI (.gemini/skills). Teammates who cannot edit your skill can send skylls suggest instead, and you accept or decline.

If your skills are worth reusing, they are worth backing up and sharing on purpose. Try Skylls (npm install -g @skylls/cli && skylls setup) to give each skill its own private repo, versions and a secret scan, or talk to us if you want help designing skills and agents for your team.