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

> Understand SKILL.md YAML frontmatter in i-have-adhd. Learn how metadata and the disable-model-invocation flag control static or dynamic Instagit responses.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: deep-dive
- Published: 2026-08-08

---

**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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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:

```markdown

# 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:

```yaml
---
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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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.