How to Integrate i-have-adhd with Pi AI: Complete Agent Skill Setup

To integrate i-have-adhd with Pi AI, install the skill via npx skills add ayghri/i-have-adhd -a pi -y or manually copy it to ~/.pi/agent/skills/, enable slash commands by setting "enableSkillCommands": true in settings.json, and invoke the skill with /skill:i-have-adhd in a fresh Pi session.

The i-have-adhd repository by ayghri provides an Agent Skill designed to integrate with Pi AI and optimize responses for ADHD cognitive styles. This integration leverages Pi's standard skill architecture, where rule definitions in skills/i-have-adhd/SKILL.md are dynamically loaded at runtime without compilation. By placing the skill in Pi's discovery directories and activating skill commands, you enable ADHD-optimized formatting across all conversational interactions.

How Pi AI Discovers Agent Skills

Pi AI locates custom skills in two standard locations according to the source code implementation. The global user directory ~/.pi/agent/skills/ stores system-wide skills available across all Pi sessions, while the project-local path .pi/skills/ provides repository-specific access. When properly installed, Pi reads the skill's metadata from plugin.json and operational rules from SKILL.md during session initialization.

Installing i-have-adhd via the Pi CLI

The recommended integration method uses Pi's official CLI helper to automatically pull the skill from GitHub and place it in the correct directory. According to the INSTALL.md documentation in the ayghri/i-have-adhd repository, this approach ensures proper file structure and permissions.

Run the following command to install the skill globally:

npx skills add ayghri/i-have-adhd -a pi -y

Verify the installation succeeded by listing available skills:

npx skills list

Enabling Skill Commands in Pi Settings

Pi AI disables slash-command skill invocation by default as a security measure. You must explicitly enable this functionality by modifying Pi's settings.json configuration file before you can activate any installed skills.

Add the following entry to your settings.json:

{
  "enableSkillCommands": true
}

After saving this configuration, completely restart Pi AI to apply the setting. The skill framework will not activate without this toggle, even if the files are present in the skills directory.

Manual Installation Method

If you prefer not to use the npx CLI or need to modify skill files before deployment, manually copy the skill directory from the GitHub repository. This method achieves identical runtime functionality but requires careful attention to path nesting.

First, clone the repository and copy the skill folder to Pi's global skills directory:

git clone https://github.com/ayghri/i-have-adhd
mkdir -p ~/.pi/agent/skills
cp -R i-have-adhd/skills/i-have-adhd ~/.pi/agent/skills/

After copying, restart Pi and confirm the skill appears in the output of npx skills list. The SKILL.md file must reside at ~/.pi/agent/skills/i-have-adhd/SKILL.md for Pi's loader to recognize it.

Invoking the Skill and Runtime Behavior

Once installed and enabled, activate the skill by starting a fresh Pi session and typing the slash command:

/skill:i-have-adhd

Pi reads the static JSON-compatible front-matter from skills/i-have-adhd/SKILL.md and applies the ADHD-friendly output rules to every subsequent response in that session. No additional compilation or conversion is required; the skill operates as a runtime configuration overlay that modifies Pi's text generation parameters.

Key Source Files in the Repository

Understanding the skill's architecture helps with troubleshooting and customization. The ayghri/i-have-adhd repository contains several critical files that define the Pi AI integration:

SKILL.md (skills/i-have-adhd/SKILL.md): Contains the rule set that Pi applies once the skill is active. This file uses JSON-compatible front-matter to define output formatting, pacing, and structure preferences optimized for ADHD users.

plugin.json: Defines the skill's metadata including name, version, and description. Pi's skill loader references this file during discovery to validate the skill format and display information in command listings.

INSTALL.md: Documents the exact npx skills command syntax, optional filesystem copy procedures, and the required settings.json configuration toggle for Pi integration.

.github/workflows/plugin-load-check.yml: Implements CI validation that confirms the skill structure matches Pi's expected format, ensuring compatibility before release.

Summary

• Pi AI discovers skills in ~/.pi/agent/skills/ (global) or .pi/skills/ (project-local) directories according to the source code implementation.
• Install via CLI using npx skills add ayghri/i-have-adhd -a pi -y or manually copy the skills/i-have-adhd/ folder from the repository.
• Enable skill commands by setting "enableSkillCommands": true in Pi's settings.json and restarting the application.
• Activate the skill by typing /skill:i-have-adhd in a fresh Pi session to load formatting rules from SKILL.md.
• Runtime operation requires no compilation; Pi dynamically applies the ADHD-optimized rules as a configuration overlay.

Frequently Asked Questions

Where does Pi AI look for custom skills?

Pi AI searches for Agent Skills in two locations: the global user directory at ~/.pi/agent/skills/ and project-local directories named .pi/skills/. The skill must contain a valid plugin.json metadata file and a SKILL.md rule definition to be recognized by the loader.

Why do I need to enable skill commands in settings.json?

Pi AI disables slash-command skill invocation by default as a security safeguard. The enableSkillCommands boolean in settings.json explicitly authorizes Pi to execute external skill code. Without this configuration toggle set to true, Pi will ignore /skill: commands even if the skill files are correctly installed.

Can I modify the skill behavior after installation?

Yes, you can edit the SKILL.md file located in your Pi skills directory (e.g., ~/.pi/agent/skills/i-have-adhd/SKILL.md) to adjust the ADHD-friendly formatting rules. Changes take effect immediately in the next Pi session without requiring reinstallation, as Pi reads this file at runtime during skill invocation.

What is the difference between the CLI and manual installation methods?

The npx skills add CLI command automates downloading the repository and placing files in the correct directory structure, while manual installation via git clone and cp gives you direct control over file placement and allows pre-installation modifications. Both methods require the same settings.json configuration and produce identical runtime behavior once /skill:i-have-adhd is invoked.

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