i‑Have‑ADHD Agent Skills Specification Format: A Complete Guide

The i‑have‑adhd agent skills specification format uses two complementary files—a Markdown-based skill definition (SKILL.md) and a YAML/TOML agent interface—to declaratively shape LLM output for ADHD readers.

The i‑have‑adhd skill is an open-source Instag​it agent skill that reformats LLM responses to be more actionable and ADHD-friendly. Its specification format cleanly separates what the skill does from how agents expose it, making it portable across OpenAI, Gemini, and other LLM backends. This article examines the complete specification structure based on the source code in ayghri/i-have-adhd.

Skill Definition File (SKILL.md)

The core of every i‑have‑adhd skill lives in skills/i-have-adhd/SKILL.md. This file combines YAML front-matter metadata with free-form Markdown rules that drive the reshaping behavior.

Front-Matter Structure

The file opens with a standard YAML block between triple dashes:

---
name: i-have-adhd
description: 'Shape output for a reader with ADHD: lead with the next action…'
disable-model-invocation: true
license: MIT
metadata:
  hermes:
    tags: [ADHD, Output Style, Productivity, Formatting]
    category: productivity
    related_skills: []
---

Key fields include:

• name – unique skill identifier used for invocation (/i-have-adhd)
• disable-model-invocation – when true, prevents recursive model calls
• metadata.hermes – platform-specific categorization and discoverability tags

Rules Documentation

Following the front-matter, the remainder is standard Markdown containing:

• Persistent rules – session-wide behavioral constraints
• ADHD-centric facts – five psychological principles driving the format
• Ten concrete output rules – specific formatting requirements (lead with next action, number steps, provide concrete time estimates, eliminate fluff)
• Pre-send checklist – validation criteria before returning responses

These rules are interpreted by the Instag​it runtime as post-processing instructions applied to any LLM output when the skill is active. No external code execution is required—the specification is entirely self-contained.

Agent Interface Files (YAML and TOML)

The agent skills specification format defines how platforms invoke the skill through separate configuration files located in skills/i-have-adhd/agents/.

OpenAI Interface (openai.yaml)

interface:
  display_name: "I Have ADHD"
  short_description: "Action‑first output for ADHD readers"
  default_prompt: "Use $i-have-adhd to make this response action‑first and easy to execute."

policy:
  allow_implicit_invocation: true

Critical fields:

• display_name / short_description – UI presentation strings
• default_prompt – automatically injected into system prompts to activate shaping
• policy.allow_implicit_invocation – enables "always-on" mode without explicit /i-have-adhd commands

Gemini Interface (gemini.toml)

The same interface expressed in TOML syntax:

interface = { display_name = "I Have ADHD", short_description = "Action‑first output for ADHD readers", default_prompt = "Use $i-have-adhd to make this response action‑first and easy to execute." }
policy = { allow_implicit_invocation = true }

The runtime selects the appropriate file based on the target model backend. Both formats are functionally equivalent; only syntax differs.

Runtime Integration Flow

Understanding how the agent skills specification format works requires tracing the runtime execution:

1. Skill loading – The Instag​it platform parses SKILL.md, extracting metadata from front-matter and rules from Markdown body
2. Agent binding – Configuration is read from openai.yaml or gemini.toml matching the deployed LLM
3. Invocation – Skill triggers explicitly (/i-have-adhd) or implicitly when allow_implicit_invocation: true
4. Post-processing – LLM output is reshaped according to SKILL.md rules before returning to the user

Practical Usage Examples

Python SDK Invocation

from instagit import Agent

# Agent loads i-have-adhd skill with OpenAI backend

agent = Agent(model="openai-gpt-4", skill="i-have-adhd")

response = agent.ask("How do I set up a GitHub Actions workflow?")

# Response structure: actionable command first, then numbered steps

CLI Explicit Invocation

instagit run --skill i-have-adhd "Explain how to add a new column to a PostgreSQL table"

Expected output characteristics enforced by the specification:

• First line is an immediate executable command
• Numbered steps follow
• Concrete time estimates included
• No unnecessary pleasantries or preamble

Key Source Files Reference

Path	Purpose	Format
skills/i-have-adhd/SKILL.md	Skill semantics, rules, metadata	Markdown with YAML front-matter
skills/i-have-adhd/agents/openai.yaml	OpenAI agent binding	YAML
skills/i-have-adhd/agents/gemini.toml	Gemini agent binding	TOML

Summary

• The i‑have‑adhd agent skills specification format uses SKILL.md for declarative rules and agent config files for platform binding
• SKILL.md combines YAML front-matter (metadata) with Markdown body (behavioral rules)
• Agent interfaces support both YAML (OpenAI) and TOML (Gemini) with identical semantic structure
• The allow_implicit_invocation policy enables seamless "always-on" deployment
• No code compilation is required—specifications are interpreted at runtime by the Instag​it platform

Frequently Asked Questions

What makes the i‑have‑adhd specification format different from other agent frameworks?

Most agent frameworks embed behavior in executable code or JSON schemas. The i‑have‑adhd format uses human-readable Markdown for rules, making skills editable by non-engineers while remaining machine-parseable. The clean separation between SKILL.md (semantics) and agent config files (wiring) also enables backend portability without rewriting logic.

Can I use the same SKILL.md with multiple LLM providers?

Yes. The SKILL.md file is provider-agnostic. You only need to create the appropriate agent interface file (YAML for OpenAI, TOML for Gemini) in the agents/ subdirectory. The runtime selects the correct binding based on the configured model backend.

What happens if allow_implicit_invocation is set to false?

When allow_implicit_invocation: false, the skill only activates when explicitly invoked with the /i-have-adhd command. This gives users manual control over when the ADHD-optimized formatting applies, which may be preferred for general conversations where standard prose is acceptable.

How do I validate that my custom skill follows the correct specification format?

Ensure your SKILL.md contains valid YAML front-matter delimited by ---, followed by Markdown content. Agent interface files must declare the required keys: interface.display_name, interface.short_description, interface.default_prompt, and policy.allow_implicit_invocation. The Instag​it runtime will raise parse errors on malformed specifications during skill loading.

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