Mandatory YAML Frontmatter Fields in Flutter Skill Definitions

Skill definitions in the flutter/skills repository require exactly two mandatory YAML frontmatter fields: applyTo and title (or name in legacy files).

The flutter/skills repository manages AI-powered coding assistants through Markdown-based skill definitions. Each skill file must begin with a YAML frontmatter block that the generator tooling parses to determine when and how to apply the skill. Understanding which fields are mandatory ensures your custom skills pass validation and execute correctly.

The Two Required Frontmatter Fields

applyTo – File Pattern Matching

The applyTo field accepts a list of strings containing glob patterns that specify which project files the skill targets. According to the parser implementation in tool/generator/skill_parser.dart, the generator checks these patterns against the codebase and only invokes the skill when a match occurs. This field controls the execution scope, allowing you to target specific file types like Dart source files or configuration files such as pubspec.yaml.

title – Skill Identification

The title field provides a string value that serves as the human-readable name for the skill. This identifier appears in selection UIs and prompt references throughout the tooling. While older skill definitions found in skills/*/SKILL.md may use name instead, title is the current standard enforced by the generator and should be used for all new skill definitions.

Validation in the Skill Generator

The requirements are enforced programmatically in tool/generator/skill_parser.dart, where the YAML frontmatter parser explicitly checks for the presence of both applyTo and title. If either field is missing, the generator throws a validation error and refuses to process the skill file. This strict validation ensures every skill has sufficient metadata for proper routing and display. Documentation for this behavior is available in tool/generator/README.md, which outlines the complete skill definition specification.

Optional Fields for Enhanced Functionality

While only two fields are mandatory, the frontmatter specification supports additional optional keys that improve documentation and prompt engineering:

• description – Extended explanation of the skill's purpose
• examplePrompt – Sample queries that trigger this skill
• instructions – Detailed guidance for the AI model
• resources – External references or context files

Minimal Working Examples

The following examples demonstrate the minimum valid frontmatter required for the skill generator to accept a definition:

---
applyTo:
  - '**/*.dart'
  - '!test/**'
title: "Fix layout overflow"
---

---
applyTo: ['pubspec.yaml']
title: "Add http package"
---

Both validate successfully against the parser in tool/generator/skill_parser.dart and can be placed in any skills/*/SKILL.md file.

Summary

• Two fields are mandatory: applyTo (list of glob patterns) and title (string)
• Validation occurs in: tool/generator/skill_parser.dart
• Legacy support: Older files may use name instead of title
• File location: Skill definitions reside in skills/*/SKILL.md
• Optional enhancements: description, examplePrompt, instructions, and resources provide additional context but are not required

Frequently Asked Questions

What happens if I omit a mandatory frontmatter field?

The skill generator will fail with a validation error when parsing your SKILL.md file. The generator explicitly checks for applyTo and title in tool/generator/skill_parser.dart and throws an exception if either is missing, preventing the skill from being indexed or executed.

Can I use name instead of title in new skill definitions?

While some older skill definitions in the repository use name, new definitions should use title as it is the current standard enforced by the generator. The parser may support both for backward compatibility, but title is the recommended field for all new contributions.

Where are skill definitions stored in the repository?

Skill definitions are Markdown files located at skills/*/SKILL.md, where the directory name represents the skill identifier. Each file must contain the mandatory YAML frontmatter block at the top to be recognized by the generator tooling.

Is applyTo limited to specific file extensions?

No, applyTo accepts any valid glob pattern as a list of strings. You can target specific files like pubspec.yaml, broad patterns like **/*.dart, or exclude paths using negation patterns like !test/**. The generator matches these against the project's file structure to determine skill applicability.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}