Claude Code skills best practices

A skill is a folder with a SKILL.md file. Claude Code uses a skill when it is relevant, or you can call one yourself with /skill-name. This page collects the habits that make a set of skills easier to live with. The Claude Code facts come from Anthropic’s skills documentation (opens in a new tab), and the guides linked below go deeper on each step.

Choose a skill

Read the skill’s description before anything else. Claude Code lists each skill by name and description, and picks from that list, so the description tells you what the skill is for in the same words Claude will use.

• It names a job, not a topic. “Make a 6-second kinetic-type title video from three short lines” tells you what you get. “Helps with video” does not.
• It says what it needs. Look for the software and files it asks for, such as a Node.js version or FFmpeg, before you install it.
• You can see a result first. A skill page that shows what the skill makes saves you installing it to find out.

For example, Kinetic Title Drop is free, says it makes a six-second 1080p title video (MP4), and lists Node.js 22 or newer and FFmpeg under “What you need”. Editorial OG Card is free too, and makes 1200×630 link-preview images. To compare more, see the best design skills for Claude Code. New to the idea? Start with What are agent skills?.

Put it in the right folder

Use a personal skill for your own habits and a project skill for something the whole repository should share. If the same name exists in two places, enterprise wins over personal, and personal wins over project. Plugin skills carry the plugin’s name in front, so they do not clash with the others. Where skills live covers the other agents, and Install a skill in Claude Code shows three ways to add one.

Check it before you run it

A skill can bundle scripts, and the agent can run them. Read SKILL.md and every script, and look at what the skill fetches from the internet. In the header, check allowed-tools: Anthropic’s docs say it lists tools Claude can use without asking permission during the turn that runs the skill. The grant clears when you send your next message. Safety checks before running a skill has the full checklist.

Lookbk skills are built to be read. The header of each holds only a name and a description, scripts are plain files in the folder, and tools run through npx with the version pinned. Each package also carries a TESTED.json that lists the commands that ran, such as building its example briefs and rendering them.

Keep the list short and the descriptions distinct

Claude Code loads a listing of every skill’s name and description into context. Anthropic’s docs say the listing always keeps every name, but with many skills it drops some descriptions to fit a budget of 1% of the context window, starting with the skills you use least. Each entry’s description and when_to_use text together is also cut at 1,536 characters, so put the main use first.

• Remove skills you no longer use. Run /doctor for an estimate of what the listing costs and which skills add most.
• Give each skill one job. Two skills with overlapping descriptions make it harder for Claude Code to tell which you mean.
• If you want the skill to run only when you ask, set disable-model-invocation: true in its header. You can still call it with /skill-name.
• If a skill fires when you did not want it, make its description more specific.

To write or tighten a description, see Write a description that makes a skill trigger.

Combine skills

Skills do not need wiring together. You ask for the job, and Claude Code uses the skill whose description matches. A title video and a link-preview image are two jobs, so they are two skills with two different descriptions: one for Kinetic Title Drop, one for Editorial OG Card.

• Ask for one job per request, in plain words, when you want a particular skill to answer.
• Call a skill by name with /skill-name when two skills could fit.
• Install a skill from a plugin if you want it kept apart from your own: its name carries the plugin name, so it can sit beside a personal skill of the same name.

Update, roll back and remove

Lookbk has no separate update command. Running the install command again replaces the skill’s whole folder with the current version, so copy the folder somewhere outside every skills folder first if you may want the old one back. Anything you edited inside the folder is lost. Update, roll back and remove skills walks through it. To remove a skill, delete its folder.

When Claude Code does not use a skill

• The skill does not trigger

  Check the description has words you would say. Ask “What skills are available?” to see whether it is listed, rephrase your request, or call it with /skill-name.

• /skill-name is not recognized either

  Claude Code may have refused the skill’s name. Names with zero-width spaces, control characters, < or > may not load. Start claude --debug and search the log for [names].

• It works, but Claude cannot match it to requests

  If the header’s YAML is malformed, the body still loads with empty metadata. Run claude plugin validate ~/.claude/skills to find the file, or claude --debug for the parse error.

• Claude follows the skill at first, then stops

  Claude Code adds the skill’s content when it is invoked and does not re-read the file on later turns. After the conversation is compacted, invoke the skill again, and keep the most important instructions near the top of SKILL.md.

• A rule must hold every time

  Move it into a hook. Claude Code runs a hook whenever its event occurs, whether or not Claude is following the skill.

More fixes are in Skill not working?.

Share skills with a team

Anthropic’s docs give three ways: commit .claude/skills/ to version control, put a skills/ folder in a plugin, or deploy skills organization-wide through managed settings. If you share a Lookbk skill in a project folder, each teammate installs it with their own account, as the install guide explains. Check a skill’s license before you hand it on; which licenses let you sell a skill explains what each allows.