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

The Skill file (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 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:

"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:

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:

[ ] 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:

{
  "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	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	User-facing /i-have-adhd command documentation

Summary

• The Skill file (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.

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