What Is the Role of the `skills` Field in the Pi Runtime Configuration for i-have-adhd

The skills field in the Pi runtime configuration specifies the directory path where the Pi runtime locates and loads skill definition files, enabling the plugin to expose its ADHD‑friendly behavioral rules to host assistants.

In the ayghri/i-have-adhd repository, the Pi runtime bridges static configuration with dynamic behavior loading. The skills field inside the pi object in package.json acts as the critical pointer that tells the runtime where to find the executable skill logic, specifically the SKILL.md manifest containing the ten ADHD‑friendly response rules.

Understanding the Pi Runtime Configuration Structure

The Pi runtime consumes a dedicated configuration namespace within package.json. This design centralizes metadata about extensions and skills in a single, declarative location.

The pi Object in package.json

In package.json (lines 12‑15), the pi object contains two primary keys: extensions and skills. While extensions registers the TypeScript implementation hooks, the skills array declares one or more directories containing skill manifests.

{
  "pi": {
    "extensions": ["./extensions/i-have-adhd.ts"],
    "skills": ["./skills"]
  }
}

Source: package.json

When the Pi runtime initializes, it resolves the relative path ./skills against the package root. It then recursively scans this directory for skill definitions, automatically ingesting any SKILL.md files it discovers.

How the skills Field Directs Runtime Loading

The skills field functions as a discovery mechanism. By pointing to ./skills, the runtime knows exactly which behavior‑defining artifacts to expose to host assistants like Claude or Codex.

For i-have-adhd, the ./skills directory contains the subdirectory i-have-adhd/, which houses SKILL.md. This manifest encodes the ten ADHD‑friendly response rules that constitute the plugin’s core functionality. The Pi runtime loads this file at startup, making the rules available through the package’s API.

Path Resolution Behavior

The Pi runtime treats entries in the skills array as relative path specifiers. It performs the following operations:

1. Resolves each path against the package root directory.
2. Recursively traverses the target directory tree.
3. Loads every skill manifest (typically SKILL.md) found within the hierarchy.
4. Registers the loaded rules with the host assistant’s context window.

Consequences of Omitting the skills Field

If the skills field were absent from the pi configuration, the runtime would load only the TypeScript extension specified in extensions (./extensions/i-have-adhd.ts). Without the corresponding skill definitions, the extension would lack the behavioral logic required to modify responses, rendering the plugin inert. The TypeScript code provides the runtime hooks, but the SKILL.md file provides the actual instruction set; the skills field is the necessary link between them.

Working with Skill Definitions in Practice

The modular design allows developers to add new capabilities without modifying package.json once the initial skills path is configured.

Adding a New Skill Directory

To extend the plugin with additional behaviors:

1. Create a new subdirectory under ./skills/, such as ./skills/new-behavior/.
2. Add a SKILL.md file describing the new behavioral rules.
3. No changes to package.json are required—the existing skills entry automatically picks up the new folder on the next runtime start.

Runtime Loading Pattern

While the actual loading is handled internally by the Pi runtime, the conceptual flow follows this pattern:

import { loadPiPackage } from '@pi/runtime';

// Loads both the extension and the skill definitions
const adhdPlugin = loadPiPackage('i-have-adhd');

// The skill rules become accessible via the package API
adhdPlugin.runSkill('SKILL.md');  // Executes ADHD‑friendly response logic

Note: This represents the logical API surface; actual implementation details may vary by Pi runtime version.

Summary

• The skills field in package.json declares the directory path for skill manifests.
• It enables recursive loading of SKILL.md files, including the core ADHD‑friendly rules in skills/i-have-adhd/SKILL.md.
• Without this field, only the TypeScript extension (extensions/i-have-adhd.ts) loads, leaving the plugin without behavioral logic.
• The field supports multiple paths and automatically discovers new subdirectories without configuration changes.

Frequently Asked Questions

What file format does the skills field expect to find?

The Pi runtime expects to find SKILL.md files within the specified directories. These markdown files contain structured behavioral rules and instructions that the runtime parses and exposes to AI assistants. For i-have-adhd, this file lives at skills/i-have-adhd/SKILL.md.

Can I specify multiple directories in the skills array?

Yes, the skills field accepts an array of path strings. You can configure ["./skills", "./custom-skills"] to load skill definitions from multiple locations simultaneously. The runtime resolves and scans each path recursively during initialization.

What happens if the skills directory exists but is empty?

If the directory specified in the skills field exists but contains no SKILL.md files (or valid skill manifests), the Pi runtime will start successfully but the plugin will operate without loaded behavioral rules. The TypeScript extension will execute, though it may have no instructions to apply to responses.

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