# How SKILL.md and AGENTS.md Configure Always-On Behavior in the i-have-adhd Skill > Discover how SKILL.md and AGENTS.md configure always-on behavior in the i-have-adhd skill. Learn how SKILL.md defines rules and AGENTS.md ensures persistent ADHD formatting. - Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd) - Tags: internals - Published: 2026-07-22 --- **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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`: ```bash 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: ```bash 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`](https://github.com/ayghri/i-have-adhd/blob/main/AGENTS.md) file in the project root: ```markdown ## 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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/./AGENTS.md)) and makes the skill persistent across all interactions. - Copy the rule block from SKILL.md (referenced in [`INSTALL.md`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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.