How to Configure the i-have-adhd Skill for the OpenCode Runtime

To configure the i-have-adhd skill for OpenCode, declare the plugin in opencode.json, ensure .opencode/plugins/i-have-adhd.mjs exports a handler function, and verify the command documentation exists at .opencode/command/i-have-adhd.md.

The i-have-adhd repository provides an ADHD-friendly response skill that integrates with the OpenCode runtime environment. This skill applies ten specific rules to generate concise, actionable responses tailored for users with ADHD. According to the ayghri/i-have-adhd source code, the integration relies on a three-file architecture that connects the runtime manifest to the skill implementation.

Understanding the Configuration Architecture

The OpenCode runtime discovers and loads the i-have-adhd skill through a specific hierarchy of configuration files. Each file serves a distinct purpose in registering the command and exposing the skill's functionality.

The Runtime Manifest (opencode.json)

The opencode.json file serves as the primary entry point that OpenCode reads when loading the project. This manifest declares available plugins and their entry points.

The file must contain a plugins array where each element specifies the plugin name, module path, and available commands:

{
  "plugins": [
    {
      "name": "i-have-adhd",
      "module": "./.opencode/plugins/i-have-adhd.mjs",
      "commands": ["i-have-adhd"]
    }
  ]
}

The Plugin Module (.opencode/plugins/i-have-adhd.mjs)

This JavaScript module implements the bridge between OpenCode and the skill logic. The file imports the canonical skill definition and registers a handler that the runtime invokes when users execute the i-have-adhd command.

The module exports an async handle function that receives the runtime context and command arguments:

import { loadSkill } from "../utils/skill-loader.js";
const skill = loadSkill("skills/i-have-adhd/SKILL.md");

export async function handle(context, args) {
  // `context` holds runtime information (e.g., user request)
  // `args` contains any CLI flags passed to the command
  return skill.apply(context, args);
}

The loadSkill utility reads the markdown file at skills/i-have-adhd/SKILL.md, parses the ten ADHD-friendly response rules, and transforms them into a callable skill object.

The Command Documentation (.opencode/command/i-have-adhd.md)

This markdown file provides user-facing help text that appears when running opencode help i-have-adhd. It defines the command syntax, available options, and usage examples.

The documentation supports optional flags for customizing response behavior:

# i-have-adhd

A skill that replies using the 10 ADHD-friendly response rules.

## Usage

```bash
opencode i-have-adhd [options] <prompt>

Options

• --tone <style> – Choose a response tone (friendly, direct, brief).
• --concise – Force a concise answer (overrides default verbosity).

The Skill Definition (skills/i-have-adhd/SKILL.md)

This file contains the canonical ten ADHD-friendly response rules that the plugin consumes. The loadSkill utility parses this markdown to instantiate the skill logic that the handle function applies to incoming requests.

Step-by-Step Configuration Guide

Follow these steps to enable the i-have-adhd skill in your OpenCode environment.

1. Verify OpenCode Installation

   Ensure the OpenCode runtime is installed and accessible in your environment. Refer to the repository's installation documentation for platform-specific requirements.

2. Configure the Runtime Manifest

   Open opencode.json in the project root. Add the i-have-adhd plugin entry to the plugins array if it does not exist:

   {
     "plugins": [
       {
         "name": "i-have-adhd",
         "module": "./.opencode/plugins/i-have-adhd.mjs",
         "commands": ["i-have-adhd"]
       }
     ]
   }

3. Verify the Plugin Module

   Confirm that .opencode/plugins/i-have-adhd.mjs exists and exports the handle function. The function must accept context and args parameters and return the skill's output. If you require custom behavior, edit this module while maintaining the exported function signature and import statements.

4. Review Command Documentation

   Check that .opencode/command/i-have-adhd.md contains accurate usage information. Update this file if you modify available flags or change the command interface.

Customizing the Skill Behavior

The core ADHD-friendly rules reside in skills/i-have-adhd/SKILL.md. To customize responses:

• Edit the markdown file to adjust the ten response rules
• Modify phrasing or add specific constraints relevant to your use case
• Save changes to automatically update the skill behavior (the plugin loads this file at runtime via loadSkill)

Verifying Your Configuration

Test the configuration by invoking the skill from the repository root:

opencode i-have-adhd "Explain the Pomodoro technique"

A correctly configured installation returns a response following the ADHD-friendly style: short paragraphs, actionable steps, and clear next actions. If the command returns a "plugin not found" error, verify the path in opencode.json points to the correct location of .opencode/plugins/i-have-adhd.mjs.

Commit all changes to opencode.json and the plugin files to ensure the skill loads automatically in fresh clones of the repository.

Summary

• Declare the plugin in opencode.json with the correct module path and command name to register the skill with the OpenCode runtime
• Maintain the handler in .opencode/plugins/i-have-adhd.mjs with the exported handle function that processes context and arguments
• Document usage in .opencode/command/i-have-adhd.md to support the built-in help system and define CLI options like --tone and --concise
• Customize rules by editing skills/i-have-adhd/SKILL.md to modify the ten ADHD-friendly response guidelines that loadSkill parses
• Test the integration by running opencode i-have-adhd with a sample prompt to verify the skill returns formatted responses

Frequently Asked Questions

What file does OpenCode read first to discover the i-have-adhd skill?

OpenCode reads opencode.json in the project root to discover available plugins. This manifest file contains the plugins array that registers the i-have-adhd skill and points to its implementation in .opencode/plugins/i-have-adhd.mjs.

How do I change the response style of the i-have-adhd skill?

Edit the skills/i-have-adhd/SKILL.md file to modify the ten ADHD-friendly response rules. The plugin module loads this markdown file at runtime using the loadSkill utility, so changes take effect immediately without rebuilding the JavaScript module.

Can I add custom flags to the i-have-adhd command?

Yes. Update the .opencode/command/i-have-adhd.md file to document new flags, then modify the handle function in .opencode/plugins/i-have-adhd.mjs to parse additional properties from the args parameter. The runtime passes command-line flags directly to the handler's args object.

Why does my skill return "module not found" errors?

Verify that the module path in opencode.json correctly points to .opencode/plugins/i-have-adhd.mjs relative to the project root. Ensure the plugin file exists and contains a valid JavaScript export statement. Check that the file extension matches exactly (.mjs for ES modules) and that the loadSkill import path resolves correctly from the plugin directory.

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