# Skill File Relationship with Agent Task and Plan Tools: A Deep Dive into `ayghri/i-have-adhd`

> Understand the skill file's role in agent task and plan tools. Discover how it separates presentation from execution for efficient delegation in i-have-adhd.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: deep-dive
- Published: 2026-08-18

---

**The Skill file ([`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md)) acts as the behavioral specification that directs the agent to delegate multi-step work to the harness's task/plan tools when available, separating presentation rules from execution mechanics.**

The `ayghri/i-have-adhd` repository implements an ADHD-friendly interaction pattern for AI agents. Understanding how the **Skill file coordinates with task/plan tools** is essential for developers building similar agent behaviors or customizing this skill for their own harnesses.

## How the Skill File Defines Agent Behavior

The Skill file sits at [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) and serves as the single source of truth for the *i-have-adhd* behavior. It encodes rules that govern:

- **Persistence mechanisms** — how the agent remembers context across turns
- **Action-first output** — leading with concrete next steps
- **Numbered step formatting** — breaking complex work into discrete items
- **State visibility** — ensuring the user always knows where they are in a workflow

These rules are injected into every system prompt via the always-on hook system, making them omnipresent once a user opts in.

## The Delegation Clause: When Skills Meet Tools

The core relationship between the Skill file and task/plan tools is captured in a specific instruction at lines 80-81 of [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md):

> "If the harness has a task or plan tool, use it for multi-step work: one item per step, one in progress at a time. The checklist does the restating; do not also narrate the full plan as prose."

This clause establishes a **clean separation of concerns**:

| Layer | Responsibility |
|-------|--------------|
| **Skill file** | Determines *when* to break work into steps and *how* to present each step |
| **Task/Plan tools** | Handle *execution tracking* — maintaining the checklist, marking progress, and restating state |

The Skill file does not implement task management logic. Instead, it detects tool availability and instructs the agent to hand off step enumeration to the harness-provided facilities.

## The Always-On Hook: Ensuring Consistent Application

The `.opencode/plugins/i-have-adhd.mjs` file registers this skill with the OpenCode harness and implements the injection mechanism. When a user has opted in, the `hooks/always-on.mjs` module inserts the Skill's full rule body into each turn's system prompt.

This guarantees that the delegation instruction is **always present** when processing multi-step requests, creating reliable behavior without requiring the user to manually invoke tools.

## Practical Example: Multi-Step Request Handling

Consider a user request that spans multiple actions:

```text
User: "Add a new column to the orders table, migrate existing data, and update the API."

```

### Skill-Driven Execution Flow

1. **Analysis** — The Skill file determines this requires >1 step
2. **Formatting** — The agent produces a numbered list per Skill rules
3. **Delegation** — Each item feeds to the task tool instead of prose narration
4. **Rendering** — The harness displays a checklist UI:

```text
[ ] 1️⃣ Open migration file
[ ] 2️⃣ Add new column definition
[ ] 3️⃣ Write data-migration script
[ ] 4️⃣ Update API handler

```

The agent's response begins with the immediate action (per Skill Rule 1: action-first output), while the checklist satisfies Rule 5 (state restating) automatically.

## Direct Plan Tool Invocation

Developers or advanced users can also invoke the plan tool explicitly:

```json
{
  "tool": "plan",
  "arguments": {
    "steps": [
      "Create migration file",
      "Add column to schema",
      "Write data copy logic",
      "Run migration"
    ]
  }
}

```

The Skill file ensures the response format adheres to ADHD-friendly principles: concrete, immediate, and non-overwhelming, while the tool manages the step sequence.

## Key Files and Their Roles

| File | Path | Purpose |
|------|------|---------|
| [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) | [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) | Canonical rule set; contains the delegation clause at lines 80-81 |
| Plugin entry | `.opencode/plugins/i-have-adhd.mjs` | Registers skill; implements always-on injection |
| Hook implementation | `hooks/always-on.mjs` | Injects rules each turn when opt-in flag present |
| Command docs | [`.opencode/command/i-have-adhd.md`](https://github.com/ayghri/i-have-adhd/blob/main/.opencode/command/i-have-adhd.md) | User-facing `/i-have-adhd` command documentation |

## Summary

- The **Skill file** ([`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md)) defines *behavioral rules* including when and how to use task/plan tools
- The **delegation clause** (lines 80-81) explicitly instructs agents to prefer harness tools for multi-step work
- **Task/plan tools** provide the *execution mechanism*: checklist UI, progress tracking, and automatic state restating
- The **always-on hook system** ensures these rules persist across every interaction without manual invocation
- The Skill file never implements task logic directly—it *uses* available tools, creating portable, harness-agnostic behavior definitions

## Frequently Asked Questions

### How does the agent know when to use task/plan tools versus plain text?

The agent consults the Skill file on every turn due to the always-on hook. If the harness registers a `task` or `plan` tool and the current request involves multiple steps, the Skill file's rule at lines 80-81 triggers delegation. Single-step or conversational responses proceed with standard formatting.

### Can this Skill file work with other agent harnesses besides OpenCode?

Yes—the Skill file is **harness-agnostic** in its rule definitions. The delegation clause uses conditional language ("If the harness has a task or plan tool..."), so it adapts gracefully. However, the always-on injection mechanism in `.opencode/plugins/i-have-adhd.mjs` and `hooks/always-on.mjs` is OpenCode-specific and would need porting to other platforms.

### What happens if the task tool is unavailable?

The Skill file's core rules still apply. The agent falls back to **manual step formatting**: producing numbered lists in prose, explicitly restating state each turn, and maintaining action-first output. The user experience degrades slightly (more text to parse) but remains ADHD-friendly.

### Where is the "restating state" requirement implemented—Skill file or tool?

**Both, collaboratively.** The Skill file mandates state visibility as Rule 5. When task/plan tools are present, their checklist UI handles this automatically. When absent, the agent must generate restatement prose itself. This dual implementation ensures consistent user experience regardless of tool availability.