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

Contribute to the i-have-adhd project by forking the repository, editing the skill rules in 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:

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:

git checkout -b my-contribution

Understanding the Repository Architecture

The repository follows the Instagit plugin model, where 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
Skill rules	The 10-rule manifesto driving output style	skills/i-have-adhd/SKILL.md
OpenAI agent config	Metadata and default prompt for OpenAI agents	skills/i-have-adhd/agents/openai.yaml
Gemini agent config	TOML-format configuration for Gemini	skills/i-have-adhd/agents/gemini.toml
Evaluation harness	Scripts validating skill behavior	scripts/run_evals.py
CI workflows	Automated health checks	.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. Follow the existing markdown structure where each rule uses an H3 heading:

### 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 – Modify the default_prompt field for OpenAI-based agents
• skills/i-have-adhd/agents/gemini.toml – Update the TOML configuration for Gemini integration

Improving Documentation

Documentation contributions should target README.md, INSTALL.md, or the language-specific readmes under .github/readme/.

Extending the Evaluation Harness

The evaluation pipeline in 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:

python -m unittest discover -s tests

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

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

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 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 to add or refine the 10-rule manifesto governing ADHD-friendly output formatting
• Modify agents/openai.yaml or 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

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 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, 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 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 uses TOML format instead. Each file contains a default_prompt field that controls how the skill initializes in its respective environment.

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