# How to Contribute to the i-have-adhd Project: A Complete Guide for Developers

> Learn how to contribute to the i-have-adhd project. Fork the repository, edit skill rules for agent configurations, run unit tests, and submit a pull request. A complete guide for developers.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: how-to-guide
- Published: 2026-07-30

---

**Contribute to the i-have-adhd project by forking the repository, editing the skill rules in [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) or agent configurations, running the unittest suite, and submitting a pull request with passing CI checks.**

The **i-have-adhd** repository is an open-source LLM skill that reshapes coding assistant outputs into ADHD-friendly formats—prioritizing action-first, step-by-step guidance. Learning how to contribute to the i-have-adhd project allows you to refine the rule set, improve documentation, or extend the evaluation harness used by the Claude and Codex agent ecosystems.

## Setting Up Your Development Environment

Start by creating your own fork of the repository on GitHub. Then clone your local copy:

```bash
git clone https://github.com/<your-username>/i-have-adhd.git
cd i-have-adhd

```

The project requires **no additional dependencies** for core skill development, making the barrier to entry minimal. Create a feature branch before making changes:

```bash
git checkout -b my-contribution

```

## Understanding the Repository Architecture

The repository follows the **Instagit** plugin model, where [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json) declares the plugin metadata and the skill logic resides under the `skills/` directory. Key components include:

| Component | Purpose | Key File |
|-----------|---------|----------|
| **Skill definition** | Declares name, description, and licensing | [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json) |
| **Skill rules** | The 10-rule manifesto driving output style | [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) |
| **OpenAI agent config** | Metadata and default prompt for OpenAI agents | [`skills/i-have-adhd/agents/openai.yaml`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/agents/openai.yaml) |
| **Gemini agent config** | TOML-format configuration for Gemini | [`skills/i-have-adhd/agents/gemini.toml`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/agents/gemini.toml) |
| **Evaluation harness** | Scripts validating skill behavior | [`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py) |
| **CI workflows** | Automated health checks | [`.github/workflows/plugin-load-check.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/plugin-load-check.yml) |

When installed, the skill is invoked via `/i-have-adhd` in Claude or `$i-have-adhd` in Codex.

## Types of Contributions You Can Make

### Adding or Updating Skill Rules

To modify how the assistant formats responses, edit [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md). Follow the existing markdown structure where each rule uses an H3 heading:

```markdown

### 11. Highlight success immediately

The first line after the solution should show a concrete success cue, e.g. "✅ Build succeeded". This reinforces dopamine for the reader.

```

### Modifying Agent Prompts

To change how the skill initializes in specific LLM environments, edit the agent interface files:

- **[`skills/i-have-adhd/agents/openai.yaml`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/agents/openai.yaml)** – Modify the `default_prompt` field for OpenAI-based agents
- **[`skills/i-have-adhd/agents/gemini.toml`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/agents/gemini.toml)** – Update the TOML configuration for Gemini integration

### Improving Documentation

Documentation contributions should target [`README.md`](https://github.com/ayghri/i-have-adhd/blob/main/README.md), [`INSTALL.md`](https://github.com/ayghri/i-have-adhd/blob/main/INSTALL.md), or the language-specific readmes under `.github/readme/`.

### Extending the Evaluation Harness

The evaluation pipeline in [`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py) supports validation and test execution. You can add new evaluation cases or improve the runner logic to better validate skill adherence to the ADHD-friendly formatting rules.

## Testing and Validation

Before submitting changes, run the unit test suite to verify the evaluation harness remains functional:

```bash
python -m unittest discover -s tests

```

Validate that the skill loads correctly using the built-in validation command:

```bash

# Option 1: Via the CI workflow mechanism

claude plugin load-check i-have-adhd

# Option 2: Local validation script

python scripts/run_evals.py validate

```

The validation command checks the case catalog and ensures the skill definition remains well-formed.

## Submitting Your Pull Request

Once your changes pass local testing, commit and push your branch:

```bash
git add .
git commit -m "Add new rule: Highlight success immediately / Fix typo in SKILL.md"
git push origin my-contribution

```

Open a Pull Request on GitHub via **Compare & pull request**, describing your changes and referencing any related issue numbers. The CI pipelines in [`.github/workflows/plugin-load-check.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/plugin-load-check.yml) will run automatically—ensure all checks succeed. Respond to reviewer feedback promptly and push additional commits as needed.

## Summary

- **Fork and clone** the repository to begin contributing to this open-source LLM skill
- **Edit [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md)** to add or refine the 10-rule manifesto governing ADHD-friendly output formatting
- **Modify [`agents/openai.yaml`](https://github.com/ayghri/i-have-adhd/blob/main/agents/openai.yaml) or [`agents/gemini.toml`](https://github.com/ayghri/i-have-adhd/blob/main/agents/gemini.toml)** to adjust agent-specific prompts and metadata
- **Run `python -m unittest discover -s tests`** to verify the evaluation harness remains intact
- **Validate with `python scripts/run_evals.py validate`** before submitting to ensure the skill loads correctly
- **Submit PRs** only after CI checks pass in [`.github/workflows/plugin-load-check.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/plugin-load-check.yml)

## Frequently Asked Questions

### What programming languages do I need to know to contribute to the i-have-adhd project?

You primarily need familiarity with **Markdown** for editing skill rules and **YAML/TOML** for agent configurations. The evaluation harness in [`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py) is written in Python, so Python knowledge is helpful if you want to extend the testing infrastructure or modify the validation logic.

### How do I test my changes locally before submitting a pull request?

Run the unit test suite with `python -m unittest discover -s tests` to ensure the evaluation pipeline works correctly. Use `python scripts/run_evals.py validate` to check that your skill modifications remain well-formed. You can also run the full evaluation plan locally using `python scripts/run_evals.py plan --trials 2` followed by the run command to verify behavior.

### Can I contribute documentation improvements without coding?

Yes. Documentation contributions targeting [`README.md`](https://github.com/ayghri/i-have-adhd/blob/main/README.md), [`INSTALL.md`](https://github.com/ayghri/i-have-adhd/blob/main/INSTALL.md), or files under `.github/readme/` are valuable community contributions. Simply fork the repository, edit the markdown files following the existing style, and submit a pull request. These changes should still pass the CI checks, though they typically only require validation that files remain properly formatted.

### What is the difference between the Claude and Codex agent configurations?

The **Claude** configuration in [`agents/openai.yaml`](https://github.com/ayghri/i-have-adhd/blob/main/agents/openai.yaml) uses YAML format and triggers with the `/i-have-adhd` slash command, while the **Codex** setup uses similar YAML structures but responds to `$i-have-adhd`. The **Gemini** configuration in [`agents/gemini.toml`](https://github.com/ayghri/i-have-adhd/blob/main/agents/gemini.toml) uses TOML format instead. Each file contains a `default_prompt` field that controls how the skill initializes in its respective environment.