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

Fork the repository, edit the skill rules in SKILL.md or agent configs, run the test suite with python -m unittest discover -s tests, and submit a pull request.

The i-have-adhd repository is an open-source skill designed to reshape LLM output for readers with ADHD by enforcing action-first, step-by-step responses. Whether you want to refine the rule set, improve documentation, or extend the evaluation harness, this guide explains exactly how to contribute to the i-have-adhd project following the Instagit plugin model used by Claude Code and Codex.

Understanding the Repository Architecture

The project follows the Instagit plugin model, where plugin.json declares the plugin metadata while the actual skill logic resides under skills/i-have-adhd/.

Key files you will modify when you contribute to the i-have-adhd project include:

• plugin.json – Declares the plugin name, description, and licensing metadata.
• skills/i-have-adhd/SKILL.md – Contains the 10-rule manifesto that drives output style (lead with action, number steps, suppress tangents). This is the primary file for behavioral changes.
• skills/i-have-adhd/agents/openai.yaml – Provides OpenAI-specific metadata including the default_prompt field auto-inserted when the skill invokes.
• skills/i-have-adhd/agents/gemini.toml – Gemini-specific configuration in TOML format.
• scripts/run_evals.py – The evaluation harness that validates skill behavior.
• .github/workflows/plugin-load-check.yml – CI workflow ensuring the skill loads correctly.
• tests/test_run_evals.py – Unit tests for the evaluation pipeline.

Setting Up Your Development Environment

Begin by creating your own fork and local clone:

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

No additional dependencies are required for the core skill. Create a feature branch before making changes:

git checkout -b my-contribution

Making Changes to the Skill

When you contribute to the i-have-adhd project, your changes will typically fall into three categories:

Adding or Updating Rules

Edit skills/i-have-adhd/SKILL.md to modify the behavioral manifesto. Follow the existing markdown structure where each rule starts with 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.

Changing Agent Prompts

Modify agents/openai.yaml or agents/gemini.toml to update the default_prompt field. This text is automatically inserted when the skill is invoked via /i-have-adhd (Claude) or $i-have-adhd (Codex).

Improving Documentation

Edit README.md or language-specific readmes under .github/readme/ to clarify installation or usage instructions.

Testing and Validation

All contributions must pass the automated test suite before submission.

Running Unit Tests

Execute the unit-test suite to verify the evaluation harness and case catalog:

python -m unittest discover -s tests

Validating the Skill

Use the built-in validation command to ensure the skill definition remains well-formed:

# Local validation

python scripts/run_evals.py validate

# CI-style load check (if Claude CLI is available)

claude plugin load-check i-have-adhd

Running the Evaluation Harness

For deeper behavioral testing, execute the full evaluation pipeline:

# Check case catalog validity

python scripts/run_evals.py validate

# Generate evaluation plan

python scripts/run_evals.py plan --trials 2 > plan.jsonl

# Run evaluation with stub runner

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

The harness executes a stub runner (harmless echo) and produces scored rows for analysis.

Submitting Your Contribution

Once tests pass, commit your changes and push to your fork:

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 by clicking Compare & pull request. Describe your changes and reference any related issue numbers. The CI pipelines in .github/workflows/plugin-load-check.yml will run automatically; ensure they succeed. Respond to reviewer feedback, push additional commits as needed, and maintainers will merge once approvals are granted.

Summary

• Fork and clone the repository to your local machine.
• Edit SKILL.md to add or refine rules that shape ADHD-friendly output.
• Modify agent configs in agents/openai.yaml or agents/gemini.toml for prompt adjustments.
• Run python -m unittest discover -s tests to verify the evaluation harness.
• Validate changes using python scripts/run_evals.py validate.
• Submit a PR only after all CI checks pass green.

Frequently Asked Questions

Do I need to install Python dependencies to contribute to the i-have-adhd project?

No. The core skill requires no additional dependencies beyond standard Python. You only need Python installed to run the unit tests in tests/test_run_evals.py and the evaluation harness in scripts/run_evals.py.

Which file should I edit to change how the AI formats its responses?

Edit skills/i-have-adhd/SKILL.md. This file contains the 10-rule manifesto that instructs the LLM to lead with actions, number steps, and suppress tangents. Each rule uses H3 headings (e.g., ### 1. Lead with the next action).

How do I test my changes locally before submitting a PR?

Run the unit tests with python -m unittest discover -s tests to check the evaluation pipeline. Then validate the skill structure with python scripts/run_evals.py validate. If you have Claude CLI installed, you can also run claude plugin load-check i-have-adhd to verify the plugin loads correctly.

Can I contribute documentation improvements without changing code?

Yes. Documentation contributions are welcome. Edit README.md or the language-specific files under .github/readme/ to improve installation instructions or usage examples. Ensure your markdown follows the existing style and validate that links are functional before submitting.

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