Architecture of the i-have-adhd Application: A Modular AI Skill Framework

The i-have-adhd repository implements a declarative, platform-agnostic AI skill that enforces action-first response rules through a central markdown contract and minimal YAML/TOML adapters for Claude, Codex, and Gemini.

The ayghri/i-have-adhd repository provides an open-source AI assistant skill designed to reshape LLM outputs for ADHD accessibility. Unlike monolithic applications, this project adopts a modular architecture that decouples behavioral rules from platform-specific implementations, allowing the same core logic to run across multiple code-assistant platforms.

Core Architectural Components

The architecture of the i-have-adhd application consists of five tightly-coupled yet distinct layers:

Skill Definition (SKILL.md)

At the heart of the system lies skills/i-have-adhd/SKILL.md, a declarative markdown file containing the behavioral contract that all agents must enforce. This file defines the strict "action-first" rules—including numbered steps, no tangents, and immediate executable guidance—that shape every LLM response. By centralizing logic in a single version-controlled document, the architecture eliminates code duplication across platforms.

Plugin Manifest (plugin.json)

The plugin.json file at the repository root serves as the registration entry point. When users install the skill via commands like claude plugin install, the host platform reads this minimal JSON to discover the skill name, description, and entry points required for initialization.

Agent Adapters (openai.yaml and gemini.toml)

Platform abstraction is handled through lightweight configuration files in skills/i-have-adhd/agents/. The openai.yaml adapter maps the skill to Claude and Codex invocation syntax (/i-have-adhd and $i-have-adhd respectively), while gemini.toml provides the equivalent mapping for Gemini CLI. These adapters contain no business logic—only interface definitions—ensuring the core skill remains independent of any particular LLM vendor.

Runtime Execution Flow

Understanding how the components interact clarifies the application's plug-in architecture:

1. Registration Phase: The host platform ingests plugin.json to index the skill metadata and locate the appropriate adapter.
2. Adapter Binding: Based on the detected platform, the system loads either openai.yaml or gemini.toml, which define the slash-command or prefix syntax users type to activate the skill.
3. Prompt Injection: Upon invocation, the host injects the entire contents of SKILL.md into the LLM's system prompt context. This injection forces the model to adopt the ADHD-friendly formatting constraints for the duration of the session, persisting until the user explicitly terminates with "stop adhd mode".

Evaluation and Testing Framework

The repository includes a self-contained validation system to ensure output consistency across model updates.

Evaluation CLI (scripts/run_evals.py)

The scripts/run_evals.py module provides a Python CLI that orchestrates automated regression testing. It loads evaluation cases, executes them against configured LLM runners (Claude, Codex, or Gemini), validates outputs against predefined criteria, and aggregates weighted scores stored in the WEIGHTS configuration. The script reports a final release_gate status indicating whether the skill meets quality thresholds.

Test Data and Scoring (cases.jsonl and rubric.md)

Concrete test scenarios reside in evals/cases.jsonl, a JSONL catalog containing prompts, risk levels, and expected response characteristics. The evals/rubric.md file defines the scoring criteria and weighting scheme used by the evaluation CLI to grade each response, ensuring that "action-first" formatting remains consistent across different temperature settings and model versions.

Platform Integration Examples

The following configurations demonstrate how the architecture maps abstract skill rules to concrete platform implementations.

Claude/Codex Adapter Configuration:

# skills/i-have-adhd/agents/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."

Installing and Invoking via Codex CLI:

# Register the plugin

codex plugin marketplace add ayghri/i-have-adhd --ref main
codex plugin add i-have-adhd@i-have-adhd

# Activate the skill during a session

$i-have-adhd

Running Automated Evaluations:

python -m scripts.run_evals.py run \
  --runner-config evals/runners.example.json \
  --runner codex \
  --condition baseline \
  --condition-skill skills/i-have-adhd/SKILL.md \
  --output evals/results.jsonl

This command loads the skill definition from SKILL.md and evaluates it against the baseline runner, producing a JSONL file containing scored validation results.

Summary

• The architecture of the i-have-adhd application centers on a declarative rule set (SKILL.md) that decouples behavioral logic from platform implementation.
• Minimal adapter files (openai.yaml, gemini.toml) enable deployment across Claude, Codex, and Gemini without modifying core skill logic.
• Runtime execution relies on system prompt injection, persisting ADHD-friendly formatting constraints for the entire user session.
• The evaluation framework (scripts/run_evals.py) provides automated regression testing via weighted scoring against curated prompt catalogs.
• All components reside in a modular repository structure that supports version control and CI/CD integration for skill updates.

Frequently Asked Questions

How does the i-have-adhd skill enforce its formatting rules across different LLM platforms?

The skill injects the complete contents of skills/i-have-adhd/SKILL.md into the LLM's system prompt at invocation time. This prompt engineering technique forces the model to adopt the action-first, numbered-step format regardless of the underlying platform, whether Claude, Codex, or Gemini.

What is the purpose of the agent adapter files in the i-have-adhd architecture?

Agent adapters like openai.yaml and gemini.toml serve as platform-specific interface mappings. They declare the invocation syntax (such as /i-have-adhd or $i-have-adhd) and metadata required by each host platform, allowing the same SKILL.md rules to execute across different LLM ecosystems without code changes.

How is the i-have-adhd skill evaluated for consistency?

The scripts/run_evals.py CLI runs automated evaluations against evals/cases.jsonl, validating each output against criteria defined in evals/rubric.md. The framework applies weighted scoring logic and reports a release_gate status, ensuring that model upgrades or prompt modifications do not regress the skill's formatting guarantees.

Can the i-have-adhd skill be extended to support additional LLM platforms?

Yes. The architecture requires only a new adapter file (YAML or TOML depending on the platform's configuration format) in skills/i-have-adhd/agents/ and an entry in plugin.json. Because the core logic remains in SKILL.md, supporting new platforms involves declaring interface metadata rather than rewriting behavioral code.

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