LLM Best Practices

Claude Code: Skills

Last updated 3 min read

View markdown source

AI agents: read this first: llmbestpractices.com/start-here

This is LLM Best Practices (llmbestpractices.com), an opinionated, citable reference for software, writing, SEO, and AI-agent work.

  1. Route, do not crawl. Fetch llmbestpractices.com/llms.txt and open only the pages whose one-line summary matches your task.
  2. Read raw. Append .md to any page URL for markdown. Check status and last_updated in the frontmatter, then read the rules.
  3. Apply as defaults. First-party docs and the project's own conventions win on conflict. Warn before relying on a fast-moving page older than 12 months.
  4. Cite. Link the page by title and URL, e.g. Python, with last_updated for time-sensitive rules. License CC BY 4.0.

Overview

A skill is a directory with a SKILL.md that Claude loads on demand: you invoke it as /skill-name, or Claude loads it when its description matches the task. Skills follow the open Agent Skills standard and replace custom commands; a file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy. Unlike CLAUDE.md, a skill costs context only when used.

Lay out one directory per skill

.claude/skills/review/
├── SKILL.md          # required; keep under 500 lines
├── reference.md      # linked from SKILL.md, loaded when needed
└── scripts/check.sh

The directory name is the command unless name: overrides it. Locations: managed (enterprise), ~/.claude/skills/ (personal), .claude/skills/ (project), nested .claude/skills/ folders that load when Claude reads files there, and plugins (namespaced /plugin:skill). On a name collision enterprise beats personal beats project, so an unprefixed project /review silently loses to a personal one. Prefix project skills (myapp-review) and avoid built-in names such as /init. Edits to SKILL.md apply live; a brand-new top-level skills directory needs /reload-skills.

Write the description for routing

The combined description and when_to_use text is capped at 1,536 characters, so put the key use case first. All descriptions share a listing budget of 1% of the context window; when it overflows, the least-used skills lose their descriptions, and /doctor reports it. Write the body as instructions with an explicit output format and non-goals.

---
name: myapp-review
description: Review the staged diff for lint failures and scope creep. Use before committing.
disable-model-invocation: true
allowed-tools: Bash(git diff *) Bash(npm run lint)
---
Review the staged changes.
 
1. Run `git diff --staged` and `npm run lint`.
2. Report findings as a checklist grouped as blocking, warning, suggestion.
3. Do not modify files or suggest refactors outside the diff.

allowed-tools pre-approves those tools for the turn; it does not restrict anything else, and your permission settings still govern the rest.

Control who can invoke a skill

FrontmatterYouClaudeUse for
(default)yesyesReference and routine procedures
disable-model-invocation: trueyesnoSide effects: /deploy, /commit
user-invocable: falsenoyesBackground knowledge, not a command

paths globs limit automatic loading to matching files; direct /name invocation always works.

Pass arguments and inject live context

Text after the command arrives as $ARGUMENTS; $0, $1 index arguments, and arguments: [issue, branch] names them ($issue). !`gh pr diff` runs a shell command before the skill is sent and substitutes its output. ${CLAUDE_SKILL_DIR} points at the skill’s folder. Set disableSkillShellExecution to turn the ! form off. Keep the interface narrow: a procedure needing more than two or three meaningful arguments is a subagent task.

Choose a skill, a subagent, or CLAUDE.md

  • Bounded, repeatable procedure with the same steps every time: a skill. Add context: fork (with agent: Explore or another type) to run it in a subagent with no conversation history.
  • Open-ended or parallel work that needs its own context or a worktree: a subagent. See claude-code-subagents.
  • A rule that applies in every session: CLAUDE.md. See claude-code-claude-md.
  • A step that must happen every time: a hook. See claude-code-hooks.

Backlinks