Frontmatter

Frontmatter is the YAML block delimited by --- at the top of a SKILL.md file. It serves as the configuration for the skill, controlling its metadata and execution behavior.

Key fields within the frontmatter allow for detailed control:

• name: The display name for the skill. If omitted, the skill's directory name is used.
• description: A crucial field explaining what the skill does and its intended use case. If this is missing, the skill falls back to using the first paragraph of the markdown content. This field is load-bearing for automatic invocation.
• when_to_use: Provides additional context for triggering the skill, appended to the description.
• argument-hint: Offers a hint displayed during autocompletion, such as [issue-number].
• arguments: Defines named positional arguments that can be used with $name substitution.
• disable-model-invocation: Setting this to true prevents Claude from automatically invoking the skill.
• user-invocable: Set to false to hide the skill from the / command menu. Note the correct spelling is user-invocable with a 'c'.
• allowed-tools: Specifies tools that can be used without explicit permission while the skill is active.
• disallowed-tools: Lists tools that are removed from the available pool when the skill is active.
• model: Determines which model Claude uses while the skill is active.
• effort: Categorizes the skill's complexity with levels like low, medium, high, xhigh, or max.
• context: Setting this to fork runs the skill in a forked subagent context.
• agent: Specifies the subagent type to use when context is set to fork.
• hooks: Allows for defining hooks scoped to the skill's lifecycle.
• paths: Uses glob patterns to limit when the skill automatically activates.
• shell: Defines the shell to use, either bash or powershell.

While many fields offer fine-grained control, the description field is particularly important for enabling automatic skill invocation. For example, the Skill Creator skill uses frontmatter to define its name, description, and arguments, guiding users on how to build new skills.