i-have-adhd: How a 10-Rule SKILL Stops Coding Agents from Burying the Answer

Coding agents produce verbose, meandering responses. They explain context, suggest alternatives, and end with “Hope this helps!” when you need a file path and a line number. The i-have-adhd project (41K+ stars, trending #1 on GitHub for Python) solves this with a SKILL file: a prompt injection layer that enforces structured, action-first output without touching the orchestration harness.

This is not a new agent framework. It is a constraint file that sits between the user and the LLM, rewriting how the agent formats its responses. The pattern generalizes beyond Claude Code to any agent that accepts system prompts or tool-level instructions.

The Problem: Agent Verbosity as a Failure Mode

Agents trained on conversational data default to explanatory prose. When you ask “Why is my auth test failing?”, a typical agent response includes:

Background on JWT libraries
A paragraph about middleware patterns
Three possible approaches
A suggestion to “explore further”
No concrete next step

For someone debugging a production issue or context-switching between tasks, this output pattern is a tax. You have to parse the response, extract the action, and infer the file path. The agent has the information but buries it in narrative.

The i-have-adhd SKILL file treats this as a formatting problem, not a model problem. It injects 10 rules into the agent’s system prompt that constrain output structure.

The 10 Rules: Output Contract as Prompt Engineering

The SKILL file defines a contract. Every agent response must:

Lead with the next action. The first sentence is a command: “Run npm install” or “Edit src/auth.ts:42.”
Number multi-step tasks. If the action has substeps, use a numbered list.
End with one concrete next step. The last line tells the user what to do after completing the current action.
Suppress tangents. No background, no alternatives, no “by the way” clauses.
Restate state every turn. Remind the user where they are in the task: “You are updating the auth middleware.”
Specific time estimates. Say “5 minutes” instead of “a bit” or “quickly.”
File paths with line numbers. Always include filename:line when referencing code.
Paste-ready snippets. Code blocks should run without modification.
Error-first debugging. If something fails, ask for the exact error message before suggesting fixes.
No filler. Remove “Great question!”, “Let me think”, and “Hope this helps!”

These rules map to common agent failure modes:

Failure Mode	Rule	Effect
Vague next steps	Rule 3	Forces a single, actionable instruction
Missing context on turn N+1	Rule 5	Agent restates task state each response
Time estimation drift	Rule 6	Replaces “should be quick” with “3 minutes”
Copy-paste errors	Rule 8	Code snippets include imports and are runnable
Premature solution suggestions	Rule 9	Agent waits for error output before diagnosing

How It Works: Prompt Injection at the Tool Boundary

The SKILL file is a Markdown document that lives in the agent’s workspace. When the agent starts, it reads the file and appends its contents to the system prompt. This is not a fine-tuned model or a custom orchestration layer. It is a text file that modifies the prompt context.

For Claude Code, the installation is:

# Clone the repo
git clone https://github.com/ayghri/i-have-adhd.git

# Copy the SKILL file to Claude's workspace
cp i-have-adhd/skills/i-have-adhd/SKILL.md ~/.claude/skills/

# Restart Claude Code

The agent now sees the 10 rules as part of its system instructions. Every response is filtered through this contract.

The pattern works because:

No orchestration changes. The agent harness (Claude Code, Cursor, Aider) does not need to know about the SKILL file. It is just another document in the workspace.
Stateless enforcement. Each turn, the agent re-reads the rules. There is no memory or state tracking required.
Composable with other tools. The SKILL file does not conflict with linters, test runners, or other agent plugins. It only affects output formatting.

Before and After: Output Diff

Here is a real example from the repo’s README:

Before (default agent output):

Great question! Let me think about this. Your auth flow has a few moving pieces: the middleware, the token verification, and the cookie handling. Looking at src/auth.ts, the verifyToken function (around lines 42-58) seems to be using an older jsonwebtoken API. One approach would be to update the package and rewrite that function. After making the change, you’d want to run the auth tests to confirm nothing breaks. By the way, you might also want to look at your dependency versions overall. Hope this helps! Let me know if you want to dig deeper.

After (with i-have-adhd SKILL):

Run npm install jsonwebtoken@latest, then edit src/auth.ts:42.

Open src/auth.ts

Replace verifyToken (lines 42-58) with the snippet below

Run npm test -- auth.spec.ts

Next: paste the first failing line if any test fails.

The second response is 60% shorter, includes a file path with line numbers, and ends with a concrete next step. The agent has the same information but formats it for action instead of explanation.

Generalizing the Pattern: Vendor-Neutral Output Contracts

The i-have-adhd SKILL is specific to Claude Code, but the pattern applies to any agent that accepts system prompts. A vendor-neutral implementation would:

Define a JSON schema for output structure. Instead of prose rules, specify fields like action, steps, next, and context.
Inject the schema into the system prompt. The agent sees the schema and formats responses as structured data.
Parse and render the output. The orchestration layer converts the JSON into UI elements (buttons, code blocks, progress indicators).

This moves the constraint from prompt engineering to a type system. The agent’s output becomes a data structure, not a string.

Example schema:

{
  "action": "Run npm install jsonwebtoken@latest",
  "steps": [
    "Open src/auth.ts",
    "Replace verifyToken (lines 42-58)",
    "Run npm test -- auth.spec.ts"
  ],
  "next": "Paste the first failing line if any test fails",
  "context": "You are updating the auth middleware",
  "time_estimate_minutes": 5
}

The orchestration layer would render this as:

A command button for action
A checklist for steps
A highlighted next step
A progress bar based on time_estimate_minutes

This approach requires more plumbing than a SKILL file, but it makes the output contract explicit and testable.

Failure Modes and Observability

The SKILL file is a soft constraint. The agent can ignore it, especially if the user’s prompt contradicts the rules. Common failure modes:

Rule drift. After 10+ turns, the agent forgets the rules and reverts to verbose output. Fix: re-inject the SKILL file every N turns.
Conflicting instructions. If the user says “Explain the auth flow in detail,” the agent will violate Rule 4 (suppress tangents). Fix: add a meta-rule that user instructions override SKILL rules.
Model-specific quirks. Some models (GPT-4, Gemini) are more prone to filler phrases than others. Fix: add model-specific rule variants (e.g., “Never use the phrase ‘Let me think’”).

Observability is manual. You know the SKILL is working when responses are shorter, numbered, and end with a next step. There is no telemetry or compliance score. To measure effectiveness:

Token count per response. Track average tokens before and after SKILL adoption. Expect a 30-50% reduction.
User follow-up rate. If users ask “What do I do next?” less often, the SKILL is working.
Task completion time. Measure time from first prompt to task done. Structured output should reduce this by 20-30%.

Deployment Shape: SKILL Files as Portable Configs

The i-have-adhd SKILL is a single Markdown file. This makes it portable across projects and teams. Deployment options:

Per-project SKILL. Drop SKILL.md in the repo root. The agent reads it on startup.
User-level SKILL. Store in ~/.config/agent/skills/. Applies to all projects.
Team-shared SKILL. Commit to a shared repo. Engineers clone and symlink to their agent workspace.

For teams, the SKILL file becomes a style guide for agent output. You can version it, diff it, and enforce it in CI (by checking that agent logs match the output schema).

When to Use This Pattern

Use a SKILL file or output contract when:

Agent verbosity is a bottleneck. If you spend more time parsing agent responses than acting on them, structured output helps.
You have task-switching costs. ADHD-friendly output is useful for anyone who context-switches frequently (on-call engineers, support teams, side-hustlers).
You want agent output to be auditable. Numbered steps and concrete next actions make it easier to trace what the agent suggested and what the user did.

Avoid this pattern when:

You need explanatory output. If the user is learning a new codebase, verbose responses with background context are valuable.
The agent is a research tool. For exploratory tasks (architecture design, trade-off analysis), you want the agent to show its reasoning.
You cannot control the system prompt. Some hosted agents (ChatGPT web, Copilot) do not expose system prompt injection. The SKILL pattern will not work.

Technical Verdict

The i-have-adhd SKILL is a lightweight, reusable pattern for constraining agent output. It works because it treats verbosity as a formatting problem, not a model problem. The 10 rules are specific enough to change behavior but general enough to apply across tasks.

For teams building agent harnesses, the lesson is: output format is part of the agent’s API. You can enforce it with prompt engineering (SKILL files), structured output (JSON schemas), or UI constraints (rendering only numbered steps). The i-have-adhd project proves that a text file in the workspace is enough to make agents more useful.

If your agents bury the answer, start here. Copy the SKILL file, adapt the rules to your workflow, and measure token count per response. The plumbing is simple. The impact is immediate.

Agentic AI, minus the noise.