A Technical Dissection of SKILL.md Frontmatter

This is a technical reference for the frontmatter block within a Claude SKILL.md file. Its purpose is to explain each field and its effect on skill behavior, specifically how it triggers. The information here is not theoretical; it is based on our direct experience parsing, installing, and testing 743 unique skills submitted to SkillProof. Our methodology involves running every skill against a standardized set of real-world programming tasks, and a significant part of that process is first understanding the author’s intent as declared in the SKILL.md.

What we’ve found is that this small block of YAML is the most critical and often misunderstood part of a skill’s definition. A misconfigured frontmatter can silently disable a skill, leading an author to debug their script when the problem is in the metadata. This guide documents what each field does, how they interact, and which configurations to avoid.

The SKILL.md Frontmatter Block

Every SKILL.md file begins with a YAML frontmatter block, delimited by ---. This is a standard convention in many static site generators and documentation tools, but in the context of a Claude skill, it is not just for human consumption. The model parses this block to understand the skill’s identity, capabilities, and constraints.

This claude skill yaml section is the control panel for your skill. The base model uses this data to decide if, when, and how to execute the tools you’ve provided. Thinking of it as just informational comments is the first mistake.

A minimal frontmatter block looks like this:

---
name: example-skill
description: A brief but precise explanation of what this skill does.
allowed-tools: [python]
---

We will examine each of these fields, plus the critical invocation control flags, based on patterns observed across the 700+ files we’ve analyzed.

Core Identity: name and description

These two fields define what the skill is to both the user and the model. However, they have very different roles in how the skill is triggered.

name

The name field is a unique string that identifies the skill. It is used for explicit invocation when a user types @ followed by the skill name. For example, @example-skill. The name must be a single, non-spaced string. Conventionally, it is lowercase and uses kebab-case.

While important for identification and direct user calls, the name has little to no influence on the model’s autonomous decision to use the skill. The model does not infer capability from the name git-history-analyzer. It relies on the description for that.

description

This is the single most important field in the entire SKILL.md frontmatter. The description is not a comment. It is the primary instruction set that tells the model when your skill is the appropriate tool for a given task. It is the API documentation for the model itself.

In our testing, the quality of the description is the variable with the highest correlation to a skill’s success score. Vague descriptions lead to inconsistent triggering, incorrect tool usage, or the skill being ignored entirely. This is a frequent root cause when a Claude skill is not triggering as expected.

A poor description: "Analyzes code."

This is useless. It provides no information about what kind of analysis, what inputs it expects, or what outputs it produces. The model has no reason to choose this skill over its own internal capabilities.

A functional description: "Accepts a file path as input. Reads the specified file and uses the py-complexity tool to calculate the cyclomatic complexity of each function. Returns a list of functions and their complexity scores."

This is effective because it is precise and action-oriented:

1. Inputs: It clearly states it accepts a file path.
2. Actions: It specifies what it does (reads the file, calculates cyclomatic complexity).
3. Tools: It even hints at the tool it will use (py-complexity).
4. Outputs: It defines the expected return format (a list of functions and their complexity scores).

When the model is presented with a task like “Can you check the complexity of the functions in main.py?”, it can match this request directly to the capabilities outlined in the second description. The first description would be ignored.

When you write your own Claude skill, spend most of your time refining the description. Write it as if you are documenting a function for another engineer to use, because that is exactly what you are doing.

Tool Permissions: allowed-tools

The allowed-tools field is a list of executables that the skill is permitted to invoke. This acts as a security sandbox. The model cannot, under any circumstances, call a tool that is not explicitly listed in this array.

allowed-tools: [python, bash, jq]

This is a critical security and reliability feature. It prevents a skill from executing arbitrary code and clearly defines its operational scope. During our testing, we verify that the tools listed are appropriate for the skill’s stated purpose. A skill that claims to be a simple JSON formatter but lists bash in allowed-tools is a red flag. While it might be using bash to pipe to jq, it also grants the skill the ability to run any shell command, which is an unnecessary expansion of privilege.

We have seen skills fail because they attempt to call a tool that isn’t listed. Conversely, we have flagged skills for requesting overly broad permissions that are not justified by their description or implementation. The principle of least privilege applies: only allow the exact tools necessary for the skill to function.

Invocation Control: user-invocable and disable-model-invocation

These two boolean flags are less common but have a profound impact on skill behavior. They control the source of the invocation: can a user explicitly call the skill, and can the model decide to use it on its own? The default for both is false if they are omitted, but the effective default behavior of a standard skill assumes user-invocable: true and disable-model-invocation: false.

Their interaction can be confusing, so here is a summary table:

user-invocable	disable-model-invocation	Behavior	SkillProof Verdict
true (or omitted)	false (or omitted)	Standard: User can @ mention; model can invoke autonomously.	The expected configuration for most skills.
false	false (or omitted)	Autonomous Only: User cannot @ mention; model can invoke.	For background tasks or helper functions.
true	true	Explicit Only: User must @ mention; model cannot invoke.	For tools with side effects or high cost.
false	true	Disabled: Neither user nor model can invoke.	Broken configuration. We flag these.

user-invocable

This flag determines if a user can directly trigger the skill using an @ mention. The default, true, is the behavior most users expect. A user-invocable claude skill is one you can call on demand.

Setting user-invocable: false means the skill can only be triggered by the model’s autonomous decision-making process. The user cannot force it to run. This is a valid choice for skills that act as background helpers or part of a larger chain of tools, but it can be a major source of confusion. We have tested several skills where this flag was set to false without any notice in the documentation. Users trying to @ mention the skill would see no response and assume it was broken. If you set this to false, you must document it clearly.

disable-model-invocation

This flag is the inverse of user-invocable. It determines if the model is allowed to proactively choose the skill on its own.

The default, false, allows the model to use the skill whenever its description matches the user’s request.

Setting disable-model-invocation: true forbids the model from using the skill autonomously. The skill can only be run if user-invocable is also true and the user explicitly @ mentions it. This is useful for tools that are expensive, have significant side effects (like making a network request or modifying files), or require very specific input that the model might not be able to infer correctly on its own.

The Silent Failure Combination

The most problematic configuration we’ve discovered in our testing is the combination of user-invocable: false and disable-model-invocation: true. As the table shows, a skill configured this way cannot be triggered by any means. The user is blocked from calling it, and the model is forbidden from choosing it.

In our review of over 700 SKILL.md files, we have found skills with this exact configuration. From the user’s perspective, the skill is installed but completely non-functional. It’s effectively dead code. In every case, we queue these skills for manual inspection. Sometimes it’s an author’s mistake. Other times, it appears to be a way to temporarily disable a skill in a repository without deleting it. Regardless of the reason, shipping a skill with this configuration is an error.

Practical Implications from 743 Skill Tests

Understanding the claude skill frontmatter is not an academic exercise. It is the key to building reliable and effective skills. Our testing of 743 skills has reinforced a few key truths:

1. The description is the trigger. Time spent refining it is never wasted.
2. Defaults are usually correct. Most skills should be user-invocable and model-invocable.
3. Deviations must be deliberate and documented. If you make a skill autonomous-only or explicit-only, your users need to know why.

This is why SkillProof exists. Of the 743 skills we’ve processed, 31 actually performed worse than using plain Claude. Many of these failures were not due to bad code, but to a poorly constructed SKILL.md frontmatter that caused the skill to trigger at the wrong time, or not at all. Another 204 skills passed our tests but required non-obvious setup, often related to understanding how the invocation flags were set. We publish these findings—the successes and the failures—because a skill’s true value is determined by its real-world performance, not just its code.

Finding skills that get this right is the purpose of our directory. A well-configured skill like a Codebase Summarizer will have a precise description and sensible invocation settings, allowing it to function as a reliable extension of the model.

You can browse all 508 skills that passed our tests in our catalog. Each listing includes the exact SKILL.md frontmatter used and our verdict on its effectiveness. See for yourself what a well-configured, battle-tested skill looks like.