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

> Discover the role of the skills field in the Pi runtime configuration for i-have-adhd. Learn how it loads skill definition files to expose ADHD-friendly behavioral rules.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: internals
- Published: 2026-09-12

---

**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`](https://github.com/ayghri/i-have-adhd/blob/main/package.json) acts as the critical pointer that tells the runtime where to find the executable skill logic, specifically the [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/package.json). This design centralizes metadata about extensions and skills in a single, declarative location.

### The `pi` Object in package.json

In [`package.json`](https://github.com/ayghri/i-have-adhd/blob/main/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.

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

```

*Source: [`package.json`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/./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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) file describing the new behavioral rules.
3. No changes to [`package.json`](https://github.com/ayghri/i-have-adhd/blob/main/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:

```typescript
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`](https://github.com/ayghri/i-have-adhd/blob/main/package.json) declares the directory path for skill manifests.
- It enables recursive loading of [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) files, including the core ADHD‑friendly rules in [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md).
- Without this field, only the TypeScript extension ([`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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.