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

> Learn the i-have-adhd agent skills specification format a declarative way to shape LLM output for ADHD readers using Markdown and YAML/TOML files.

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

---

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

```yaml
---
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)

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

```toml
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`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md), extracting metadata from front-matter and rules from Markdown body
2. **Agent binding** – Configuration is read from [`openai.yaml`](https://github.com/ayghri/i-have-adhd/blob/main/openai.yaml) or [`gemini.toml`](https://github.com/ayghri/i-have-adhd/blob/main/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

```python
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

```bash
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`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) | Skill semantics, rules, metadata | Markdown with YAML front-matter |
| [`skills/i-have-adhd/agents/openai.yaml`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/agents/openai.yaml) | OpenAI agent binding | YAML |
| [`skills/i-have-adhd/agents/gemini.toml`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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.