How SKILL.md YAML Frontmatter Works in i-have-adhd: A Complete Guide

The SKILL.md YAML frontmatter in the i-have-adhd repository defines skill metadata and runtime behavior, including the critical disable-model-invocation flag that determines whether the Instagit harness returns static content or generates dynamic responses via a language model.

The SKILL.md file sits at the root of each skill directory in the ayghri/i-have-adhd project, acting as both the configuration manifest and content source. Its YAML frontmatter—the delimited block between the opening and closing --- lines—contains declarative metadata that dictates how the Instagit harness loads, categorizes, and executes the skill before processing any markdown body content.

Core Fields in the SKILL.md YAML Frontmatter

The frontmatter in skills/i-have-adhd/SKILL.md utilizes specific fields to control skill identity and runtime characteristics.

name

The name field defines the unique identifier used to invoke the skill. In the i-have-adhd skill, this value determines that users trigger the skill by entering /i-have-adhd.

description

This field provides a human-readable summary displayed in skill catalogs and help commands. It describes the skill's purpose to users browsing available capabilities.

disable-model-invocation

The disable-model-invocation boolean flag is the most critical behavioral switch. When set to true—as implemented in the i-have-adhd skill—the harness does not call the underlying language model. Instead, it returns the static markdown content defined in the file body, ensuring deterministic, consistent output essential for enforcing specific communication styles.

license

The license field contains an SPDX-compatible license declaration for the skill source code, enabling automated compliance checking and catalog filtering.

metadata and Hermes Integration

The metadata block serves as a free-form bucket for additional classification data consumed by downstream tools like the Hermes UI:

• metadata.hermes.tags: Discovery and filtering tags used in the Hermes interface
• metadata.hermes.category: High-level grouping category for organizing similar skills
• metadata.hermes.related_skills: Array of skill identifiers conceptually linked to this skill

How the Instagit Harness Processes the Frontmatter

When the harness loads a skill, it performs a sequential parse of skills/i-have-adhd/SKILL.md. First, it extracts the YAML frontmatter located between the delimiter lines (lines 1-12), registering the skill under the specified name and attaching description and licensing metadata.

The harness then checks the disable-model-invocation flag. If true, it bypasses the LLM entirely and treats the content starting at line 13 as the static response body. This pre-written guidance is sent directly to the user upon invocation, guaranteeing that /i-have-adhd always returns identical, predictable output regardless of context.

When invoked, the skill returns the first line of the markdown body:

# i-have-adhd

Modifying Skill Behavior Through Frontmatter

You can alter the skill's runtime behavior by modifying the YAML frontmatter. To enable dynamic content generation via the language model, change the invocation flag:

---
name: i-have-adhd
description: Provides ADHD communication guidance
disable-model-invocation: false
license: MIT
metadata:
  hermes:
    tags: ["productivity", "neurodiversity"]
    category: communication
    related_skills: ["active-listening", "clear-communication"]
---

After committing this change, subsequent calls to /i-have-adhd trigger the model, allowing the skill to compose fresh responses while still respecting any remaining static guidelines in the markdown body.

Summary

• The SKILL.md YAML frontmatter in skills/i-have-adhd/SKILL.md configures skill metadata and runtime behavior for the Instagit harness.
• The disable-model-invocation flag determines whether the skill returns static content (true) or generates dynamic LLM responses (false).
• Metadata fields like name, description, and license control skill registration and catalog display.
• Hermes-specific metadata enables UI integration through tags, categories, and related skill linking.
• Content appearing after line 13 serves as the static response body when model invocation is disabled.

Frequently Asked Questions

What happens if disable-model-invocation is set to false?

When disable-model-invocation is set to false, the Instagit harness calls the underlying language model to generate dynamic responses. The skill can then produce context-aware, varying output based on the user's input rather than returning the fixed static content defined in the markdown body.

Where is the skill response content defined?

The response content begins at line 13 of skills/i-have-adhd/SKILL.md, immediately following the closing --- of the YAML frontmatter block. When disable-model-invocation is true, this markdown body is returned verbatim to the user. When false, this content serves as context or instructions for the LLM.

How does the Instagit harness use the metadata field?

The harness passes the metadata block to downstream tools such as the Hermes UI, which consumes metadata.hermes.tags for search filtering, metadata.hermes.category for skill grouping, and metadata.hermes.related_skills for recommendation engines. The core harness itself primarily uses this data for organizational purposes rather than runtime execution.

Can I add custom fields to the SKILL.md frontmatter?

Yes, you can add custom fields to the YAML frontmatter, though only standard fields like name, description, and disable-model-invocation affect core harness behavior. Custom fields within the metadata object are preserved and passed to external tools, making them available for custom integrations or future harness extensions without breaking existing functionality.

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