Claude Code follows the open Agent Skills format and extends it with Claude-specific controls. A skill is a folder containing SKILL.md and optional resources. Claude sees the description first, loads the body when it is relevant, and can expose the same skill as a slash command.

Choose the scope before the content

Put a personal skill under ~/.claude/skills/<name>/SKILL.md when it should be available across your local projects. Put a project skill under .claude/skills/<name>/SKILL.md when it belongs to a repository and should travel with the team. Claude also supports enterprise, nested, additional-directory, plugin, and account-synced locations. The location changes who receives the skill and when it is discovered.

Repository skills are usually the best home for build, review, migration, or release procedures that depend on local files. Personal skills fit reusable work such as document preparation or your preferred research method. Keep rules that apply to every task in CLAUDE.md; a skill is for work that should load on demand.

Create the smallest useful skill

mkdir -p .claude/skills/release-notes

cat > .claude/skills/release-notes/SKILL.md <<'EOF'
---
name: release-notes
description: Draft customer release notes from shipped commits or pull requests. Use for changelogs, launch notes, and weekly product updates.
---

Collect shipped changes, group them by product area, and explain what changed for the user. Flag any claim that cannot be tied to current evidence.
EOF

Claude Code detects many skill edits during the current session, although a newly created top-level skills directory can require a restart. Open the skill menu or invoke /release-notes to confirm it appears.

Automatic and explicit invocation

The description drives automatic matching. Direct invocation gives the user certainty and works well for longer or expensive procedures. Claude-specific frontmatter can make a skill user-only, stop model invocation, inject dynamic context, select tools, or run in a subagent. Keep those extensions deliberate. A portable host may ignore them, so the body should still state the essential workflow.

References, scripts, and trust

Use references/ for long material and assets/ for templates. Use scripts/ for deterministic helpers, then document their inputs and outputs. A skill can contain executable code and can gain access to files, so inspect third-party packages before enabling them. Tool permission fields do not replace a clear explanation of why the tool is needed.

Test the trigger and the result

Start with three requests that should trigger automatically, including informal wording, and three near misses that should not. Then invoke the skill explicitly and check whether the result follows the same evidence and output contract. For a release-notes skill, inspect whether every claim maps to shipped work, whether internal implementation details were removed, and whether the output is useful to a customer.

Claude’s documentation now includes skill evaluation guidance and account-synced skills for remote sessions. Local personal skills do not automatically appear in cloud or Cowork sessions. Commit project skills to the repository or use the documented account/plugin path when the workflow must follow the session.