SKILL.md

A SKILL.md is a markdown file that serves as the fundamental unit for a Claude Code skill. It consists of two distinct parts: YAML frontmatter enclosed within --- markers, and markdown content that provides the instructions Claude follows when the skill is executed.

The SKILL.md file resides within a specific directory structure. For personal skills available across all your projects, it's located at ~/.claude/skills/<skill-name>/SKILL.md. For project-specific skills, the path is .claude/skills/<skill-name>/SKILL.md. If the skill is part of a plugin, it will be found at <plugin>/skills/<skill-name>/SKILL.md.

The directory name containing the SKILL.md file dictates the command you use to invoke the skill via a slash command (e.g., /skill-name). The name field within the YAML frontmatter, however, sets the display label that appears in skill listings. An exception occurs with plugin-root SKILL.md files, where the name field directly determines the command name, as there's no dedicated skill directory to derive it from.

Beyond the SKILL.md file itself, the skill directory can house additional files such as reference documentation or scripts. These supplementary files are loaded by Claude Code only when they are needed during the skill's operation. Claude Code actively monitors these skill directories. Consequently, changes made to a SKILL.md file or the addition of new files will take effect within the current session without requiring a restart. However, creating a top-level skills directory that did not exist at the start of the session will necessitate a restart for Claude Code to recognize it.

Claude Code skills adhere to the Agent Skills open standard, promoting interoperability and a consistent approach to skill development. For guidance on creating well-structured skill files, refer to Authoring Skills.