How SKILL.md and AGENTS.md Configure Always-On Behavior in the i-have-adhd Skill

SKILL.md serves as the authoritative rule definition stored inside the repository, while AGENTS.md acts as the external runtime container that makes the ADHD-friendly formatting persistent across all agent responses without requiring explicit invocation.

The ayghri/i-have-adhd repository provides structured output rules designed for users with ADHD. Understanding the relationship between SKILL.md and AGENTS.md is essential for configuring always-on behavior that applies the skill's formatting guidelines automatically, eliminating the need to type /i-have-adhd before every request.

SKILL.md: The Authoritative Skill Definition

Located at skills/i-have-adhd/SKILL.md, this file contains the complete set of rules that shape ADHD-friendly output. It defines ten core principles: leading with actionable answers, numbering multi-step work, providing concrete time estimates, and capping lists at five items. When explicitly invoked via the /i-have-adhd command, agents load these rules from the repository to format their responses according to the skill's specifications.

AGENTS.md: The Always-On Configuration Layer

Unlike SKILL.md, AGENTS.md does not reside within the repository. Instead, it lives in agent-specific configuration directories such as ~/.codex/AGENTS.md, ~/.config/zed/AGENTS.md, or as a project-level AGENTS.md file in your workspace root. According to the ayghri/i-have-adhd source code, when this file contains the rule block from SKILL.md, the agent automatically applies the ADHD-friendly style to every response upon startup—no explicit /i-have-adhd invocation required.

How the Files Work Together

The relationship is straightforward: SKILL.md defines the rules; AGENTS.md persists them. The INSTALL.md file (specifically lines 91-108) contains the exact rule block that bridges these two files. To enable always-on behavior, you copy the content from skills/i-have-adhd/SKILL.md into your chosen agent's AGENTS.md location. This creates a persistent runtime configuration based on the static skill definition.

When the agent initializes, it reads AGENTS.md as persistent system rules, effectively making the ADHD-friendly formatting the default output style for the entire session. Updating the skill requires refreshing the content in your AGENTS.md file to match any changes in the repository's SKILL.md.

Configuring Always-On Behavior for Different Agents

To activate always-on mode, place the rule block from SKILL.md into the appropriate configuration file for your coding agent.

Codex Configuration

Create or append to ~/.codex/AGENTS.md:

touch ~/.codex/AGENTS.md
cat <<'EOF' >> ~/.codex/AGENTS.md

## Output style

The reader has ADHD. Shape every response so it can be acted on:

1. Lead with the answer or next action: command, path, or snippet first.
2. Number multi‑step work; one bounded action per step.
3. End with one next action doable in under two minutes.
4. Finish the current issue before raising a new one.
5. Restate progress each turn ("step 3 of 5 done").
6. Give time estimates in concrete units, never "a bit".
7. After a change, show what now works.
8. Errors: state location, cause, and fix. No drama.
9. Cap lists at 5 items.
10. No preamble, no recaps, no closers.

Exceptions: explain fully when asked to explain. Confirm before destructive actions. After three failed fixes, stop and name the doubtful assumption. If the request is ambiguous, ask one short question.
EOF

Zed Configuration

For user-level persistence in Zed:

mkdir -p ~/.config/zed
cat <<'EOF' > ~/.config/zed/AGENTS.md

## Output style

The reader has ADHD. Shape every response so it can be acted on:

1. Lead with the answer or next action: command, path, or snippet first.
2. Number multi‑step work; one bounded action per step.
3. End with one next action doable in under two minutes.
4. Finish the current issue before raising a new one.
5. Restate progress each turn ("step 3 of 5 done").
6. Give time estimates in concrete units, never "a bit".
7. After a change, show what now works.
8. Errors: state location, cause, and fix. No drama.
9. Cap lists at 5 items.
10. No preamble, no recaps, no closers.

Exceptions: explain fully when asked to explain. Confirm before destructive actions. After three failed fixes, stop and name the doubtful assumption. If the request is ambiguous, ask one short question.
EOF

Project-Level Configuration

For team-wide or project-specific always-on behavior, create an AGENTS.md file in the project root:

## Output style

The reader has ADHD. Shape every response so it can be acted on:

1. Lead with the answer or next action: command, path, or snippet first.
2. Number multi‑step work; one bounded action per step.
3. End with one next action doable in under two minutes.
4. Finish the current issue before raising a new one.
5. Restate progress each turn ("step 3 of 5 done").
6. Give time estimates in concrete units, never "a bit".
7. After a change, show what now works.
8. Errors: state location, cause, and fix. No drama.
9. Cap lists at 5 items.
10. No preamble, no recaps, no closers.

Exceptions: explain fully when asked to explain. Confirm before destructive actions. After three failed fixes, stop and name the doubtful assumption. If the request is ambiguous, ask one short question.

When any of these AGENTS.md files exist, the corresponding agent automatically applies the ADHD-friendly style to all outputs, eliminating the need to type /i-have-adhd each time.

Summary

• SKILL.md at skills/i-have-adhd/SKILL.md contains the canonical rule definitions and is loaded only when explicitly invoking /i-have-adhd.
• AGENTS.md lives outside the repository (e.g., ~/.codex/AGENTS.md, ~/.config/zed/AGENTS.md, or ./AGENTS.md) and makes the skill persistent across all interactions.
• Copy the rule block from SKILL.md (referenced in INSTALL.md lines 91-108) into your agent's AGENTS.md file to enable always-on behavior.
• Update your local AGENTS.md whenever SKILL.md changes in the repository to maintain current behavior.

Frequently Asked Questions

What is the difference between invoking /i-have-adhd and using AGENTS.md?

Explicitly typing /i-have-adhd triggers the agent to load rules from skills/i-have-adhd/SKILL.md for that specific conversation. By contrast, placing the rules in AGENTS.md causes the agent to automatically apply the ADHD-friendly formatting to every response from session start without requiring the invocation command.

Where should I place AGENTS.md for Codex?

For Codex, create the file at ~/.codex/AGENTS.md in your home directory. This user-level configuration ensures the ADHD-friendly rules persist across all Codex sessions for your account.

Do I need to update AGENTS.md when SKILL.md changes?

Yes. Since AGENTS.md is a copy of the rules from SKILL.md stored outside the repository, it does not automatically sync with repository updates. When the ayghri/i-have-adhd maintainers update SKILL.md, you must manually refresh your AGENTS.md file with the new rule block to receive the latest always-on behavior.

Can I use AGENTS.md for project-specific configuration only?

Yes. While most agents support user-level configuration files like ~/.codex/AGENTS.md, you can also place an AGENTS.md file in your project root directory. This project-level configuration applies the ADHD-friendly rules only when working within that specific codebase, making it ideal for team environments where consistent formatting is required.

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