SKILL.md File Structure in the i-have-adhd Repository: A Complete Technical Breakdown

The SKILL.md file follows a rigid eight-block hierarchy—from YAML front-matter to pre-send validation—that enables runtime agents to parse and enforce ADHD-friendly output rules programmatically.

The skills/i-have-adhd/SKILL.md file in the ayghri/i-have-adhd repository serves as the canonical machine-readable contract for the "i-have-adhd" skill. Its structure balances human readability with deterministic parsing requirements, using specific line ranges and ATX-style headings to delineate behavioral rules, exceptions, and validation checkpoints that runtime agents apply to every response.

Hierarchical Block Structure of SKILL.md

The file organizes content into eight distinct logical sections, each serving a specific function in the skill's lifecycle from registration to response validation.

Front-Matter Metadata (Lines 1–9)

The file opens with YAML front-matter consumed by the skill-loader during initialization. This block contains the skill's identity metadata including name: i-have-adhd, description, license information, and classification tags. The runtime uses these key-value pairs to register the skill in the agent's available capability set without parsing the entire document.

Header and Overview (Lines 11–14)

Following the front-matter, an H1 heading # i-have-adhd and a brief paragraph provide human-readable context about the skill's purpose. This section targets developers reading the source code rather than runtime parsers, offering a concise summary of the ADHD-friendly output goals before the technical specifications begin.

Persistence Declaration (Lines 15–20)

This block establishes the session-scoped nature of the skill with an explicit declaration that "These rules apply to every response…" until explicitly disabled. Unlike transient prompt modifiers, the persistence section ensures agents maintain the ADHD-friendly formatting across multi-turn conversations without requiring reactivation.

ADHD Reading Premises (Lines 21–30)

Before enumerating rules, the file establishes five factual premises about ADHD cognition that justify the subsequent constraints. These numbered facts cover working-memory limitations, friction reduction requirements, and attention span considerations. This foundational block ensures agents understand the cognitive rationale rather than applying rules mechanically.

Core Rules Section (Lines 31–107)

The bulk of the file comprises ten numbered rules forming the behavioral contract. Each rule follows a self-contained structure containing:

• Description: The specific constraint or requirement (e.g., "Lead with the next action" for Rule 1, "Number multi-step tasks" for Rule 2, "No preamble/closing pleasantries" for Rule 10)
• Good/Bad Examples: Concrete output snippets demonstrating compliant versus non-compliant formatting
• Implementation Guidance: Technical notes for agents on how to satisfy the requirement

The hierarchical headings within this section use ## and ### markers, enabling parsers to locate specific rules programmatically while maintaining readable documentation.

Exception Handling (Lines 117–127)

Titled "When to break the rules," this section defines override conditions where strict adherence may be suspended. Valid exceptions include explicit user requests to disable formatting, destructive actions requiring confirmation, or safety-critical scenarios where clarity supersedes brevity. This block prevents rigid adherence from compromising necessary caution.

Pre-Send Validation (Lines 128–138)

A final sanity-check list that agents execute before transmitting responses. This checklist instructs the runtime to prune disallowed phrasing—specifically preamble removal and closing pleasantries referenced in Rule 10—and verify that concrete next actions exist as required by Rule 3. The validation serves as a programmatic gate ensuring compliance before user-facing output generation.

End-of-File Marker (Lines 140–141)

The file terminates with an explicit marker indicating the conclusion of the skill definition. This delimiter prevents parsers from truncating content or misinterpreting trailing whitespace as part of the validation rules.

Programmatic Parsing and Runtime Implementation

The SKILL.md structure supports both static analysis and dynamic enforcement. Runtime environments implement specialized loaders to consume these sections:

# Runtime registration parses front-matter without loading full document

skill = load_skill(
    path="skills/i-have-adhd/SKILL.md",
    name="i-have-adhd",
    description="Shape output for a reader with ADHD…"
)

When generating responses, agents apply the hierarchical rules starting with Rule 1's requirement to lead with actionable instructions:

# Compliant output format after applying Rule 1

Run `npm install jsonwebtoken`, then edit `src/auth.ts:42`.

Before transmission, the runtime executes the pre-send check outlined in lines 128–138:

def pre_send_check(text):
    # Remove disallowed openers/closers per lines 32-34 (Rule 10)

    text = strip_preamble_and_closers(text)
    # Ensure concrete next action exists (Rule 3)

    assert "Next:" in text
    return text

Related Files and Repository Layout

The canonical definition at skills/i-have-adhd/SKILL.md is mirrored at .cursor/skills/i-have-adhd/SKILL.md for Cursor IDE compatibility, with CI pipelines maintaining synchronization between versions. Additional context files include:

• AGENTS.md: Repository map providing entry-point guidance for autonomous agents navigating the codebase
• README.md: High-level usage documentation for human developers implementing the skill

This distributed structure ensures consistent ADHD-friendly behavior across multiple runtime environments while maintaining a single source of truth in the canonical SKILL.md location.

Summary

• Eight-section hierarchy: Front-matter, Header, Persistence, Premises, Rules (lines 31–107), Exceptions, Pre-send check, and EOF marker
• Self-documenting rules: Each of the ten rules includes descriptions, examples, and implementation guidance for deterministic parsing
• Line-specific architecture: Fixed line ranges (e.g., lines 1–9 for metadata, lines 128–138 for validation) enable precise programmatic access
• Session persistence: Rules activate for the entire conversation until explicitly disabled, not per-message
• Validation gates: Pre-send checks enforce compliance before user-facing output generation
• Cross-platform mirrors: The .cursor/ directory contains IDE-specific copies synchronized with the main skills/ definition

Frequently Asked Questions

What is the purpose of the YAML front-matter in SKILL.md?

The front-matter (lines 1–9) provides machine-readable metadata that the skill-loader consumes during agent initialization to register the skill's name, description, license, and tags without parsing the full document. This enables efficient capability discovery and filtering before loading the behavioral rules.

How do runtime agents parse the ten rules section?

Agents locate the Rules section (lines 31–107) using ATX-style heading markers (## and ###), then process each numbered rule's self-contained unit of description, good/bad examples, and implementation guidance. The consistent structure allows parsers to extract specific constraints—for example, identifying that Rule 1 requires leading with the next action while Rule 10 prohibits preambles.

Can the ADHD-friendly rules be overridden during a session?

Yes, the "When to break the rules" section (lines 117–127) defines explicit override conditions including user requests to disable formatting, destructive operations requiring confirmation, or safety-critical scenarios. Agents check these exceptions before applying the standard rule set to determine if strict adherence should be suspended.

What distinguishes the canonical SKILL.md from the .cursor version?

The file at skills/i-have-adhd/SKILL.md serves as the canonical definition, while .cursor/skills/i-have-adhd/SKILL.md provides a Cursor IDE-compatible mirror. Continuous integration pipelines maintain synchronization between these files, ensuring that ADHD-friendly formatting remains consistent whether the skill runs in general runtime environments or Cursor-specific implementations.

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