pi-skill-fit 0.0.0-stage → 1.1.0

package/README.md

@@ -1,3 +1,145 @@
-# Temporary Holding Version
+# pi-skill-fit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Given a task, print the installed agent skills that fit it, most relevant first, with the absolute path of each `SKILL.md`.
+
+**The problem:** an agent receives a ~130-skill index in its prompt and has to guess which files to load; nothing maps a concrete task to the small set of installed skills worth reading.
+
+```bash
+node bin/pi-skill-fit.js "review the pull request for security issues" --limit 5
+```
+
+```text
+RANK  NAME                 SCORE  PATH
+1     security-audit       5      /root/.agents/skills/security-audit/SKILL.md
+2     code-review          4      /root/.agents/skills/code-review/SKILL.md
+3     contract-review      3      /root/.agents/skills/contract-review/SKILL.md
+4     review-reputation    3      /root/.agents/skills/review-reputation/SKILL.md
+5     gentle-ai-branch-pr  2      /root/.pi/agent/npm/node_modules/gentle-pi/skills/branch-pr/SKILL.md
+5 of 24 candidates, 19 dropped
+```
+
+## Pi extension
+
+The package also ships a Pi extension (`src/extension.js`). At `before_agent_start` it
+ranks the installed skills for the user's prompt in process and appends the selection
+to the system prompt:
+
+```text
+## Selected skills (pi-skill-fit)
+- /root/.agents/skills/security-audit/SKILL.md — security-audit: security, review
+```
+
+Rules: at most 5 entries, the matched tokens (max 4) are shown, the whole block is
+capped at 700 characters, and token lists shrink before entries are dropped. The same
+selection is injected once per session; a later prompt that selects a different set
+injects the new set. Any failure is swallowed and reported once on stderr, so the
+extension can never block the agent start.
+
+Enable it with `pi -e ./src/extension.js`, or install the package and let the `pi`
+manifest in `package.json` load it. Disable it either way:
+
+```bash
+PI_SKILL_FIT=off pi ...
+```
+
+or, in `settings.json`:
+
+```json
+{ "extensionSettings": { "pi-skill-fit": false } }
+```
+
+`false`, `"off"` and `{ "enabled": false }` all disable it. A value of `true` or a
+missing entry leaves it enabled.
+
+Known limitation: the `before_agent_start` context does not expose the active role, so
+the extension cannot apply a role's `skills:` allowlist and uses the global selector.
+The CLI keeps `--role` support. Role-level `extensionSettings` are resolved by
+pi-ext-roles for programmatic consumers but are not delivered to the Pi CLI, so only
+the settings file and the environment variable act as switches today.
+
+## Requirements
+
+Node.js >= 22. No runtime dependencies, no build step.
+
+```bash
+npm test
+```
+
+Optionally expose the `pi-skill-fit` binary: `npm link`.
+
+## Usage
+
+```text
+pi-skill-fit "<task text>" [--role <name>] [--limit <n>] [--json] [--explain] [--roots <dir>] [--overrides <path>]
+```
+
+| Flag | Meaning |
+| --- | --- |
+| `--role <name>` | Restrict candidates to the role's `skills:` allowlist from `/root/.pi/agent/pi-ext-roles/roles/<name>.md`. Only an explicit `!*` entry restricts; a role without `skills:` does not filter. |
+| `--limit <n>` | Maximum selected skills, default 5, must be >= 1. Remaining matches are reported as dropped. |
+| `--json` | Emit `{task, role, limit, selected, dropped, candidates}` instead of the table. Each selected skill includes a `matches` array with `{token, source, weight}`. |
+| `--explain` | In table mode, append per-skill match details showing which task tokens matched and at what weight. |
+| `--roots <dir>` | Skill root to scan; repeatable, replaces the default roots. |
+| `--overrides <path>` | Read trigger overrides from this file instead of the default one. The file must exist and be valid. |
+
+Default roots, in order: `/root/.agents/skills`, `/root/.pi/agent/skills`, then every `*/skills` directory under `/root/.pi/agent/npm/node_modules`. A skill is a directory containing `SKILL.md`.
+
+Exit codes: `0` success, `2` invalid input (empty task, bad limit, missing role, malformed overrides), `1` internal error.
+
+## Scoring model
+
+1. Tokenize the task: lowercase, split on non-alphanumeric, drop tokens shorter than 3 characters, English and Italian stopwords, then apply light suffix normalisation.
+2. A skill's name terms are its `name` split on non-alphanumeric separators; its description terms use the same tokenizer as the task.
+3. For each distinct task token:
+   - `+3` if it matches a name term
+   - `+2` if it matches a `triggers:` alias or an override token (see below)
+   - `+1` if it matches a description term
+   - All three can apply.
+4. Drop skills with score 0.
+5. Sort by score descending, then name ascending, then path ascending; take `--limit`.
+
+### Suffix normalisation
+
+A light, dependency-free suffix stripper collapses common inflections:
+- English: -ing, -tion, -sion, -ment, -ness, -ies, -ed, -er, -ly, -s
+- Italian: -zione, -zioni, -mente, -ione, -ioni, -ando, -endo, -are, -ire, -ere, -ato, -ata, -ati, -ate, -ari
+
+Each suffix has a minimum word length to avoid over-stripping (never below 3 characters).
+
+### Trigger aliases
+
+A skill's SKILL.md frontmatter may include a `triggers:` key (YAML list or comma-separated). These tokens are scored at weight 2 (between name=3 and description=1). Skills without this key behave exactly as before.
+
+```yaml
+---
+name: my-skill
+description: Does something useful.
+triggers: [audit, inspect, check]
+---
+```
+
+### Trigger overrides
+
+A skill's frontmatter belongs to its upstream author, and `skills update` overwrites it. To fix or extend the trigger vocabulary of an installed skill without editing it, keep a local override file instead:
+
+```json
+{
+  "writing-for-agents": ["write", "writing", "documentation", "docs", "README", "guide", "manual"],
+  "research": ["investigate", "sources", "evidence", "paper"]
+}
+```
+
+- Location: `--overrides <path>` if given, else `$XDG_CONFIG_HOME/pi-skill-fit/triggers.json`, else `~/.config/pi-skill-fit/triggers.json`. A missing default file means no overrides; it is not an error.
+- Semantics: override tokens are normalised with the same tokenizer and suffix table as everything else, score at weight 2 (same as `triggers:`), and are added to the skill's own triggers, never replacing them.
+- A name that is not installed is ignored silently.
+- A malformed file (not JSON, not an object of string arrays, missing when named with `--overrides`) exits `2` with the path and the reason. It is never silently ignored.
+- `--json` and `--explain` report these matches with `source: "override"`, distinct from `name`, `trigger` and `description`, so a ranking decision stays auditable.
+
+## What it does NOT do
+
+- It does not discover, install, update, or remove skills upstream. It only reads skill directories that already exist on this machine.
+- It does not call a model, embed anything, or use the network. Scoring is token overlap only.
+- It does not modify any skill, role, or Pi configuration file. Overrides live in its own config file and are read-only input to scoring.
+- It does not judge skill quality and it does not read `SKILL.md` bodies: only `name`, `description` and `triggers` from the frontmatter.
+
+See [docs/design.md](docs/design.md) for the design sources and scoring model.

package/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: pi-skill-fit
+description: "Deterministic selector that ranks installed agent capabilities by relevance to a query. Answers meta-questions about which capability to load or how to route a query to the right one."
+triggers: [routing, selector, selezione, scegli, quale, load]
+---
+
+# pi-skill-fit
+
+Given a task description, select at most 5 of the ~121 installed agent skills
+that are relevant, and print the absolute path of each `SKILL.md`.
+
+## When to use
+
+- An orchestrator needs to decide which skills to inject into a sub-agent.
+- A user asks "which skill should I load for this task" or "pick skills for X".
+- A delegator implements the skill-resolver protocol and needs a deterministic,
+  auditable selection step.
+
+## Commands
+
+```bash
+# Basic usage
+pi-skill-fit "<task text>"
+
+# With options
+pi-skill-fit "<task text>" --limit 5 --json --explain --role <name> --roots <dir>
+```
+
+| Flag | Meaning |
+| --- | --- |
+| `--role <name>` | Restrict candidates to the role's `skills:` allowlist. |
+| `--limit <n>` | Maximum selected skills (default 5, >= 1). |
+| `--json` | JSON output: `{task, role, limit, selected, dropped, candidates}`. |
+| `--explain` | For each selected skill, print the task tokens that matched and their weights. |
+| `--roots <dir>` | Skill root to scan; repeatable, replaces defaults. |
+| `--overrides <path>` | Trigger overrides file; defaults to `$XDG_CONFIG_HOME/pi-skill-fit/triggers.json` or `~/.config/pi-skill-fit/triggers.json`. |
+
+## Pi extension
+
+The same selector ships as a Pi extension. It runs at `before_agent_start` and appends
+the selected `SKILL.md` paths to the system prompt (max 5 entries, 700 characters).
+Disable it with `PI_SKILL_FIT=off` or `extensionSettings: { "pi-skill-fit": false }`
+in `settings.json`.
+
+## Output contract
+
+- **Table mode** (default): `RANK  NAME  SCORE  PATH` rows, then a summary line.
+  With `--explain`: after the table, one line per skill showing `token(source:weight)` pairs.
+- **JSON mode**: `selected[].matches[]` contains `{token, source, weight}` for auditability.
+- Exit codes: `0` success, `2` invalid input, `1` internal error.
+- Two runs with the same input produce byte-identical output (deterministic).
+
+## What this does NOT do
+
+This tool does **not** discover, install, update, or remove skills. It only reads
+skill directories that already exist on this machine. For skill discovery and
+installation, use:
+
+- `skills find <query>` — search for skills upstream.
+- `skills add <source>` — install a skill from a path or repository.
+
+The `skills` CLI (`command -v skills`) owns the supply chain; `pi-skill-fit` owns
+the task-to-skill routing once skills are installed.

package/bin/pi-skill-fit.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.js";
+
+process.exitCode = await main(process.argv.slice(2));

package/docs/design.md

@@ -0,0 +1,121 @@
+# Design
+
+## Sources
+
+This tool exists to implement, locally and deterministically, a selection step that three documents already describe by contract.
+
+### 1. `~/.agents/skills/_shared/skill-resolver.md` (Gentle selection contract)
+
+- Match on two dimensions: code/file context and task/action keywords.
+- Prefer the smallest useful set; hard cap of five skills.
+- Inject absolute `SKILL.md` paths, never summaries: the skill file stays the runtime contract.
+- The delegator reports what it injected, so selection must name exact files.
+
+Dictates: five-skill default cap, path-only output, trigger/description matching, no rewriting of skill content.
+
+### 2. `~/git/personale/pi.dev/dotenv/docs/agent-skill-priority.md` (priority tiers)
+
+- P0-P3 tiers bias which skills should load for a kind of work.
+- Per-role required skills are declared, not inferred.
+- Ownership rows say a selection aid must not duplicate workflow execution or model routing.
+
+Diktat for v1: role assignment is read from the role files, and pi-skill-fit owns none of the work it recommends. Priority tiers are not scored in v1 because the tiers are prose, not machine-readable metadata.
+
+### 3. `~/.pi/agent/pi-ext-roles/roles/*.md` (role allowlists)
+
+- Each role frontmatter may declare `skills: [ ... ]`.
+- `!*` is a selector meaning "start from nothing"; the remaining bare names are the allowlist.
+- Roles without the field inherit everything.
+
+Dictates: `--role` reads that file, applies only when `!*` is present, and errors (exit 2) naming the path when the role does not exist.
+
+## Pi extension
+
+The CLI selection is exposed to Pi through `src/extension.js`, a `before_agent_start`
+handler that imports the same modules in process. It appends at most five entries and
+four matched tokens per entry to `event.systemPromptOptions.appendSystemPrompt`, which
+is the documented prompt-append surface; it does not force or replace the prompt, so the
+structured sections and the prompt-cache prefix stay intact. The block is capped at 700
+characters including its heading: token lists are shortened first, entries are dropped
+after that.
+
+State is per extension instance and keyed by session id. A selection signature is stored
+when the block is injected, so an unchanged selection is not injected again. Selection
+errors, a missing skill root, malformed overrides and unexpected prompt shapes are all
+caught; the first one is logged on stderr and nothing reaches the agent start.
+
+Switches: `PI_SKILL_FIT=off`, or `extensionSettings["pi-skill-fit"]` set to `false`,
+`"off"` or `{ "enabled": false }` in `settings.json`.
+
+Known limitation: the hook context does not carry the active role, so a role's `skills:`
+allowlist cannot be applied here. The extension deliberately uses the global selector
+rather than guessing a role; the CLI keeps `--role`. Role `extensionSettings` are a
+pi-ext-roles contract for programmatic consumers and are not delivered to the Pi CLI, so
+the settings file and the environment variable are the effective switches.
+
+## Scoring model
+
+1. Tokenize the task: lowercase, split on non-alphanumeric, drop tokens shorter than 3 characters, English and Italian stopwords, then normalise suffixes.
+2. A skill's name terms are its `name` split on non-alphanumeric separators; its description terms use the same tokenizer as the task.
+3. For each distinct task token: `+3` if it matches a name term, `+2` if it matches a `triggers:` alias, `+1` if it matches a description term. All three can apply.
+4. Drop skills with score 0.
+5. Sort by score descending, then name ascending, then path ascending; take `--limit`.
+
+### Suffix normalisation
+
+A light, dependency-free suffix stripper collapses common inflections so that e.g. "reviewing/reviews" match "review" and "documentazione/documenti" collapse. Each rule has a minimum word length threshold to avoid over-stripping (never below 3 characters).
+
+| Suffix | Min length | Language |
+| --- | --- | --- |
+| -zione, -zioni | 8 | IT |
+| -mente | 8 | IT |
+| -ione, -ioni | 7 | IT |
+| -ando, -endo | 7 | IT |
+| -are, -ire, -ere | 6 | IT |
+| -ato, -ata, -ati, -ate, -ari | 6 | IT |
+| -tion, -sion, -ment, -ness | 7 | EN |
+| -ying | 7 | EN |
+| -ing | 6 | EN |
+| -ies, -ily | 6 | EN |
+| -ed, -er, -ly | 5 | EN |
+| -s | 4 | EN |
+
+Rules are tried in order (longest suffix first). Only one suffix is stripped per token.
+
+### Trigger aliases
+
+A skill's SKILL.md frontmatter may include a `triggers:` key — a YAML inline list or comma-separated values. These tokens are scored at weight 2 (between name=3 and description=1). Skills without the key behave exactly as before.
+
+### Trigger overrides
+
+The same weight-2 tier is fed by a local override file: `{ "skill-name": ["term", ...] }` at `--overrides <path>`, else `$XDG_CONFIG_HOME/pi-skill-fit/triggers.json`, else `~/.config/pi-skill-fit/triggers.json`. Tokens are added to the skill's own triggers, never replacing them, and `matches[].source` is `override` so the decision is auditable.
+
+Why a separate file and not more frontmatter: the frontmatter of an installed skill is third-party content. A selector that needs a producer's skill to carry a `write` trigger cannot wait for that producer, cannot edit `/root/.agents/skills` (a `skills update` overwrites it), and must not fork the skill. The overlay is local, outside every skill root, survives updates, and is the user's own statement of how they look for work. Weight 2 keeps it in the existing tier: an override is as strong as an author-declared trigger, weaker than a name, and cannot invent relevance for a skill that is not installed.
+
+### Bilingual stopwords
+
+Both English and Italian stopword lists are applied during tokenisation. This allows tasks written in Italian to match Italian-described skills without function words inflating scores.
+
+Why deterministic: the input is the task string plus file contents on disk. There is no model, no sampling, no network, no randomness, no time or locale input beyond `localeCompare` on ASCII skill names. Two runs over the same tree produce byte-identical output, which the test suite asserts. The score is a coarse keyword-overlap heuristic; it is meant to narrow a large index to a handful of files a human or agent then reads, not to rank skills by quality.
+
+## Open decisions
+
+| Decision | Chosen default | Reasoning |
+| --- | --- | --- |
+| Skill identity | Frontmatter `name` wins, directory name fallback | Roles reference skills by frontmatter name, so selection must use the same key. |
+| Missing `SKILL.md` | Not a skill | The contract is the file; a bare directory is not loadable. |
+| Missing root | Skipped silently | Installations differ per machine; a missing optional root is not invalid input. |
+| Symlinked duplicates | Deduplicated by real path, first root wins | Prevents the same skill appearing twice with two root-relative paths. |
+| Frontmatter parsing | Single-line `name`/`description` only, no YAML dependency | Both keys are single-line in every installed skill; a parser dependency is not justified. |
+| Name token filter | Name parts are not stopword/min-length filtered | A short or common name part (e.g. `ai`) is still a deliberate identity signal. |
+| Weights | 3 for name, 1 for description | A skill named after the task is a stronger trigger than prose that mentions it. |
+| Tie-break | Score, then name, then path | Name alone can collide across roots; path keeps the order total. |
+| Role filter stage | Applied before scoring | Cheaper and equivalent, since the allowlist does not depend on the task. |
+| `candidates` count | Skills with score > 0 after the role filter | Makes `selected + dropped == candidates` hold and keeps the report honest. |
+| Priority tiers (P0-P3) | Not scored in v1 | The tiers are prose; encoding them would invent metadata the skills do not carry. |
+| Description stemming | Light suffix normalisation, no dependency | Full stemming needs a dictionary; a short suffix table is auditable and deterministic. |
+| Trigger aliases | `triggers:` frontmatter key, weight 2 | Between name (3) and description (1); allows skill authors to declare activation phrases. |
+| Bilingual stopwords | English + Italian | Operator writes tasks in both languages; IT stopwords prevent function words from scoring. |
+| Override weight | 2, same as `triggers:` | The overlay is an authoring substitute, not a stronger signal: it should fix vocabulary, not overpower a skill named after the task. |
+| Override location | Own config file, never a skill root | Third-party frontmatter is overwritten by `skills update`; a file outside every root survives it and modifies no installed skill. |
+| Missing default override file | No overrides, no warning | A missing optional file is the normal state on a fresh machine; only `--overrides <path>` is a promise the tool must keep. |

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "pi-skill-fit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "Deterministic selection of the installed skills relevant to a task",
+  "type": "module",
+  "bin": {
+    "pi-skill-fit": "bin/pi-skill-fit.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "SKILL.md",
+    "README.md",
+    "docs"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/extension.js"
+    ]
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "license": "MIT"
+}

package/src/cli.js

@@ -0,0 +1,100 @@
+import { discoverSkills, defaultRoots } from "./skills.js";
+import { rankSkills } from "./score.js";
+import { filterByRole, readRoleSkills } from "./role.js";
+import { applyOverrides, defaultOverridesPath, loadOverrides } from "./overrides.js";
+
+const USAGE =
+  'usage: pi-skill-fit "<task text>" [--role <name>] [--limit <n>] [--json] [--explain] [--roots <dir>] [--overrides <path>]';
+
+function invalid(message) {
+  const error = new Error(`${message}\n${USAGE}`);
+  error.exitCode = 2;
+  throw error;
+}
+
+/** Parse CLI arguments into an options object. */
+export function parseArgs(argv) {
+  const options = { task: null, role: null, limit: 5, json: false, explain: false, roots: [], overrides: null };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    const value = () => {
+      const next = argv[index + 1];
+      if (next === undefined || next.startsWith("--")) invalid(`${arg} requires a value`);
+      index += 1;
+      return next;
+    };
+    if (arg === "--json") options.json = true;
+    else if (arg === "--explain") options.explain = true;
+    else if (arg === "--role") options.role = value();
+    else if (arg === "--limit") {
+      const raw = value();
+      if (!/^\d+$/.test(raw) || Number(raw) < 1) invalid(`--limit must be an integer >= 1, got ${raw}`);
+      options.limit = Number(raw);
+    } else if (arg === "--roots") options.roots.push(value());
+    else if (arg === "--overrides") options.overrides = value();
+    else if (arg.startsWith("--")) invalid(`unknown flag: ${arg}`);
+    else if (options.task === null) options.task = arg;
+    else invalid(`unexpected argument: ${arg}`);
+  }
+  if (options.task === null || options.task.trim() === "") invalid("task text is required");
+  return options;
+}
+
+function renderTable(selected, explain) {
+  const rows = [
+    ["RANK", "NAME", "SCORE", "PATH"],
+    ...selected.map((skill, index) => [String(index + 1), skill.name, String(skill.score), skill.path]),
+  ];
+  const widths = rows[0].map((_, column) => Math.max(...rows.map((row) => row[column].length)));
+  let output = rows
+    .map((row) => row.map((cell, column) => (column === 3 ? cell : cell.padEnd(widths[column]))).join("  ").trimEnd())
+    .join("\n");
+  if (explain) {
+    output += "\n";
+    for (const skill of selected) {
+      const parts = skill.matches.map((m) => `${m.token}(${m.source}:${m.weight})`);
+      output += `\n  ${skill.name}: ${parts.join(", ")}`;
+    }
+  }
+  return output;
+}
+
+/** @param {string[]} argv @returns {Promise<number>} exit code */
+export async function main(argv) {
+  try {
+    const options = parseArgs(argv);
+    const allowlist = options.role === null ? null : await readRoleSkills(options.role);
+    const roots = options.roots.length > 0 ? options.roots : await defaultRoots();
+    const overrides = await loadOverrides(options.overrides ?? defaultOverridesPath(), {
+      required: options.overrides !== null,
+    });
+    const skills = applyOverrides(filterByRole(await discoverSkills(roots), allowlist), overrides);
+    const { candidates, selected, dropped } = rankSkills(skills, options.task, options.limit);
+
+    if (options.json) {
+      const selectedOut = selected.map((s) => ({
+        name: s.name,
+        score: s.score,
+        path: s.path,
+        matches: s.matches,
+      }));
+      process.stdout.write(
+        `${JSON.stringify({
+          task: options.task,
+          role: options.role,
+          limit: options.limit,
+          selected: selectedOut,
+          dropped,
+          candidates: candidates.length,
+        })}\n`,
+      );
+    } else {
+      if (selected.length > 0) process.stdout.write(`${renderTable(selected, options.explain)}\n`);
+      process.stdout.write(`${selected.length} of ${candidates.length} candidates, ${dropped} dropped\n`);
+    }
+    return 0;
+  } catch (error) {
+    process.stderr.write(`pi-skill-fit: ${error.message}\n`);
+    return error.exitCode === 2 ? 2 : 1;
+  }
+}

package/src/extension.js

@@ -0,0 +1,101 @@
+import { defaultOverridesPath, applyOverrides, loadOverrides } from "./overrides.js";
+import { rankSkills } from "./score.js";
+import { defaultRoots, discoverSkills } from "./skills.js";
+
+export const HEADING = "## Selected skills (pi-skill-fit)";
+export const MAX_BLOCK_CHARS = 700;
+const MAX_ENTRIES = 5;
+const MAX_TOKENS = 4;
+const MAX_SESSIONS = 64;
+
+function render(entries, tokenLimit) {
+  const lines = entries.map((entry) => {
+    const tokens = entry.tokens.slice(0, tokenLimit);
+    return `- ${entry.path} — ${entry.name}${tokens.length > 0 ? `: ${tokens.join(", ")}` : ""}`;
+  });
+  return [HEADING, ...lines].join("\n");
+}
+
+/** Build the prompt block. Token lists shrink before entries are dropped. */
+export function buildBlock(selected, { maxChars = MAX_BLOCK_CHARS } = {}) {
+  const entries = selected
+    .slice(0, MAX_ENTRIES)
+    .map((skill) => ({
+      path: skill.path,
+      name: skill.name,
+      tokens: [...new Set((skill.matches ?? []).map((match) => match.token))].slice(0, MAX_TOKENS),
+    }));
+  if (entries.length === 0) return "";
+  for (let tokenLimit = MAX_TOKENS; tokenLimit >= 0; tokenLimit -= 1) {
+    const block = render(entries, tokenLimit);
+    if (block.length <= maxChars) return block;
+  }
+  const kept = entries.slice();
+  while (kept.length > 0 && render(kept, 0).length > maxChars) kept.pop();
+  return kept.length === 0 ? "" : render(kept, 0).slice(0, maxChars);
+}
+
+/** Rank installed skills for a prompt without spawning a process. */
+export async function selectSkills(prompt, { roots, overrides } = {}) {
+  const skillRoots = roots ?? (await defaultRoots());
+  const overrideMap = overrides ?? (await loadOverrides(defaultOverridesPath()));
+  const skills = applyOverrides(await discoverSkills(skillRoots), overrideMap);
+  return rankSkills(skills, prompt, MAX_ENTRIES).selected;
+}
+
+function disabledBySettings(getSettings) {
+  try {
+    const namespace = getSettings()?.extensionSettings?.["pi-skill-fit"];
+    return namespace === false || namespace === "off" || namespace?.enabled === false;
+  } catch {
+    return false;
+  }
+}
+
+function sessionKey(ctx) {
+  try {
+    const id = ctx?.sessionManager?.getSessionId?.();
+    return typeof id === "string" ? id : "default";
+  } catch {
+    return "default";
+  }
+}
+
+/**
+ * Create the `before_agent_start` handler. Every failure is swallowed and
+ * reported at most once so selection can never block the agent start.
+ */
+export function createHandler({ select = selectSkills, getSettings = () => undefined, warn } = {}) {
+  const lastSelection = new Map();
+  let warned = false;
+  const report = warn ?? ((error) => process.stderr.write(`pi-skill-fit: ${error?.message ?? error}\n`));
+  return async function beforeAgentStart(event, ctx) {
+    try {
+      if (process.env.PI_SKILL_FIT === "off" || disabledBySettings(getSettings)) return;
+      if (event?.messageType !== "user" || typeof event.prompt !== "string" || event.prompt.trim() === "") return;
+      if (!event.systemPromptOptions || typeof event.systemPromptOptions !== "object") return;
+      // NOTE: the active role is not exposed by the hook context, so the role allowlist cannot
+      // be applied here; the CLI keeps it. See README for the limitation.
+      const selected = await select(event.prompt);
+      if (!Array.isArray(selected) || selected.length === 0) return;
+      const key = selected.map((skill) => `${skill.name}\u0000${skill.path}`).join("\n");
+      const session = sessionKey(ctx);
+      if (lastSelection.get(session) === key) return;
+      const block = buildBlock(selected);
+      if (block === "") return;
+      lastSelection.set(session, key);
+      if (lastSelection.size > MAX_SESSIONS) lastSelection.delete(lastSelection.keys().next().value);
+      const current = event.systemPromptOptions.appendSystemPrompt;
+      event.systemPromptOptions.appendSystemPrompt =
+        typeof current === "string" && current !== "" ? `${current}\n\n${block}` : block;
+    } catch (error) {
+      if (warned) return;
+      warned = true;
+      report(error);
+    }
+  };
+}
+
+export default function piSkillFit(pi) {
+  pi.on("before_agent_start", createHandler({ getSettings: () => pi.getSettings?.() }));
+}

package/src/overrides.js

@@ -0,0 +1,58 @@
+import { readFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+/** Override file location: `$XDG_CONFIG_HOME/pi-skill-fit/triggers.json`, else `~/.config/...`. */
+export function defaultOverridesPath(env = process.env) {
+  const base = env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+  return path.join(base, "pi-skill-fit", "triggers.json");
+}
+
+function invalid(file, reason) {
+  const error = new Error(`invalid overrides file ${file}: ${reason}`);
+  error.exitCode = 2;
+  return error;
+}
+
+/** Validate the `{ "skill-name": ["term", ...] }` shape. */
+export function parseOverrides(text, file) {
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch (error) {
+    throw invalid(file, error.message);
+  }
+  if (data === null || typeof data !== "object" || Array.isArray(data)) {
+    throw invalid(file, "expected an object mapping skill names to arrays of strings");
+  }
+  for (const [name, tokens] of Object.entries(data)) {
+    if (!Array.isArray(tokens)) throw invalid(file, `"${name}" must be an array of strings`);
+    for (const token of tokens) {
+      if (typeof token !== "string") throw invalid(file, `"${name}" contains a non-string entry`);
+    }
+  }
+  return data;
+}
+
+/**
+ * Read the override map. A missing file is `{}` unless it was named explicitly,
+ * which is a user error worth reporting.
+ */
+export async function loadOverrides(file, { required = false } = {}) {
+  let text;
+  try {
+    text = await readFile(file, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT" && !required) return {};
+    if (error.code === "ENOENT") throw invalid(file, "file not found");
+    throw error;
+  }
+  return parseOverrides(text, file);
+}
+
+/** Attach override tokens to installed skills; names that are not installed are ignored. */
+export function applyOverrides(skills, overrides) {
+  return skills.map((skill) =>
+    Object.hasOwn(overrides, skill.name) ? { ...skill, overrides: overrides[skill.name] } : skill,
+  );
+}

package/src/role.js

@@ -0,0 +1,47 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+export const DEFAULT_ROLE_DIR = "/root/.pi/agent/pi-ext-roles/roles";
+
+function unquote(value) {
+  const trimmed = value.trim();
+  if (trimmed.length < 2) return trimmed;
+  const quote = trimmed[0];
+  if ((quote !== '"' && quote !== "'") || trimmed.at(-1) !== quote) return trimmed;
+  return trimmed.slice(1, -1).replace(/\\(["'\\])/g, "$1");
+}
+
+/**
+ * Read the `skills:` allowlist from a role prompt.
+ * `null` means the role declares no allowlist, so no filtering applies.
+ */
+export async function readRoleSkills(role, roleDir = DEFAULT_ROLE_DIR) {
+  if (/[\\/]/.test(role) || role === "." || role === "..") {
+    const error = new Error(`invalid role name: ${role}`);
+    error.exitCode = 2;
+    throw error;
+  }
+  const file = path.join(roleDir, `${role}.md`);
+  const text = await readFile(file, "utf8").catch(() => {
+    const error = new Error(`role file not found: ${file}`);
+    error.exitCode = 2;
+    throw error;
+  });
+  const end = text.startsWith("---") ? text.indexOf("\n---", 3) : -1;
+  const block = end === -1 ? "" : text.slice(3, end);
+  const match = /^skills:\s*(.*)$/m.exec(block);
+  if (!match) return null;
+  const inner = match[1].trim().replace(/^\[/, "").replace(/\]$/, "").trim();
+  if (!inner) return null;
+  return inner
+    .split(",")
+    .map((entry) => unquote(entry))
+    .filter(Boolean);
+}
+
+/** Apply a role allowlist. Only an explicit `!*` restricts candidates. */
+export function filterByRole(skills, allowlist) {
+  if (!allowlist || !allowlist.includes("!*")) return skills;
+  const allowed = new Set(allowlist.filter((entry) => !entry.startsWith("!")));
+  return skills.filter((skill) => allowed.has(skill.name));
+}

package/src/score.js

@@ -0,0 +1,145 @@
+const STOPWORDS_EN = new Set(
+  "the and for with that this from into are was were you your its not but all any can had has have how our out use when where which who will would should could about after before also than then them they there these those their been being does did doing each more most other some such only over just like make made may much must need same him his her one two get got per via onto off own yet".split(
+    " ",
+  ),
+);
+
+const STOPWORDS_IT = new Set(
+  "che non con per una gli del delle della dei sono stato essere dalla anche come alla alle degli delle nella nelle nella negli questo questa questi queste quello quella quelli quelle suo sua suoi sue loro quel nel sul dal dal tutto tutti tutta tutte fare fatto era erano uno dei tra fra dove quando poi ancora molto piu suoi miei senza verso dopo prima sopra sotto".split(
+    " ",
+  ),
+);
+
+/**
+ * Light suffix normalisation table. Strips inflectional suffixes to collapse
+ * common variants. Never produces a stem shorter than 4 characters.
+ * Applied after lowercasing; longest matching suffix wins.
+ *
+ * English: -ation, -tion, -sion, -ment, -ness, -ing, -ying, -ies, -ily, -ed, -er, -ly, -s
+ * Italian: -azione, -zione, -zioni, -mente, -ione, -ioni, -ando, -endo,
+ *          -are, -ire, -ere, -ato, -ata, -ati, -ate, -ari, -i
+ */
+const SUFFIX_RULES = [
+  // Italian first (longer suffixes before shorter)
+  { suffix: "azione", min: 10 },
+  { suffix: "zione", min: 8 },
+  { suffix: "zioni", min: 8 },
+  { suffix: "mente", min: 8 },
+  { suffix: "ione", min: 7 },
+  { suffix: "ioni", min: 7 },
+  { suffix: "ando", min: 7 },
+  { suffix: "endo", min: 7 },
+  { suffix: "are", min: 6 },
+  { suffix: "ire", min: 6 },
+  { suffix: "ere", min: 6 },
+  { suffix: "ato", min: 6 },
+  { suffix: "ata", min: 6 },
+  { suffix: "ati", min: 6 },
+  { suffix: "ate", min: 6 },
+  { suffix: "ari", min: 6 },
+  { suffix: "i", min: 8 },
+  // English (longer before shorter)
+  { suffix: "ation", min: 8 },
+  { suffix: "tion", min: 7 },
+  { suffix: "sion", min: 7 },
+  { suffix: "ment", min: 7 },
+  { suffix: "ness", min: 7 },
+  { suffix: "ying", min: 7 },
+  { suffix: "ing", min: 6 },
+  { suffix: "ies", min: 6 },
+  { suffix: "ily", min: 6 },
+  { suffix: "ed", min: 5 },
+  { suffix: "er", min: 5 },
+  { suffix: "ly", min: 5 },
+  { suffix: "s", min: 4 },
+];
+
+const MIN_STEM_LENGTH = 4;
+
+/** Strip one inflectional suffix if the stem stays >= 4 chars. */
+export function normalizeSuffix(token) {
+  for (const { suffix, min } of SUFFIX_RULES) {
+    if (token.length >= min && token.endsWith(suffix)) {
+      const stem = token.slice(0, -suffix.length);
+      if (stem.length < MIN_STEM_LENGTH) return token;
+      return stem;
+    }
+  }
+  return token;
+}
+
+/** Lowercase, split on non-alphanumeric, drop short tokens and stopwords, normalize suffixes. */
+export function tokenize(text) {
+  const tokens = new Set();
+  for (const raw of text.toLowerCase().split(/[^a-z0-9]+/)) {
+    if (raw.length < 3) continue;
+    if (STOPWORDS_EN.has(raw) || STOPWORDS_IT.has(raw)) continue;
+    tokens.add(normalizeSuffix(raw));
+  }
+  return tokens;
+}
+
+function nameTokens(name) {
+  return new Set(name.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean));
+}
+
+/** Trigger and override aliases: same tokenizer and suffix table as the task text. */
+function aliasTokens(values) {
+  const tokens = new Set();
+  for (const value of values ?? []) {
+    for (const part of value.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean)) {
+      tokens.add(normalizeSuffix(part));
+    }
+  }
+  return tokens;
+}
+
+/**
+ * Score a skill against task tokens.
+ * Weights: name=3, triggers/overrides=2, description=1.
+ * Returns { score, matches } where matches is an array of { token, source, weight }.
+ */
+export function scoreSkill(taskTokens, skill) {
+  const names = nameTokens(skill.name);
+  const triggers = aliasTokens(skill.triggers);
+  const overrides = aliasTokens(skill.overrides);
+  const descriptions = tokenize(skill.description);
+  let score = 0;
+  const matches = [];
+  for (const token of taskTokens) {
+    if (names.has(token)) {
+      score += 3;
+      matches.push({ token, source: "name", weight: 3 });
+    }
+    // NOTE: a token in both a frontmatter trigger and an override scores once, as an override.
+    if (overrides.has(token)) {
+      score += 2;
+      matches.push({ token, source: "override", weight: 2 });
+    } else if (triggers.has(token)) {
+      score += 2;
+      matches.push({ token, source: "trigger", weight: 2 });
+    }
+    if (descriptions.has(token)) {
+      score += 1;
+      matches.push({ token, source: "description", weight: 1 });
+    }
+  }
+  return { score, matches };
+}
+
+/**
+ * Score, drop zeros, order by score descending then name ascending.
+ * Returns the ranked candidates and the selected page.
+ */
+export function rankSkills(skills, task, limit) {
+  const taskTokens = tokenize(task);
+  const candidates = skills
+    .map((skill) => {
+      const { score, matches } = scoreSkill(taskTokens, skill);
+      return { name: skill.name, score, path: skill.path, matches };
+    })
+    .filter((skill) => skill.score > 0)
+    .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name) || a.path.localeCompare(b.path));
+  const selected = candidates.slice(0, limit);
+  return { candidates, selected, dropped: candidates.length - selected.length };
+}

package/src/skills.js

@@ -0,0 +1,90 @@
+import { readdir, readFile, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+
+/** Fixed roots, in resolution order. @type {string[]} */
+export const DEFAULT_ROOTS = ["/root/.agents/skills", "/root/.pi/agent/skills"];
+
+const NPM_ROOT = "/root/.pi/agent/npm/node_modules";
+
+async function isDirectory(target) {
+  try {
+    return (await stat(target)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** Default roots plus every skills directory under each Pi npm package. */
+export async function defaultRoots() {
+  const roots = [...DEFAULT_ROOTS];
+  const entries = await readdir(NPM_ROOT, { withFileTypes: true }).catch(() => []);
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+    const dir = path.join(NPM_ROOT, entry.name, "skills");
+    if (await isDirectory(dir)) roots.push(dir);
+  }
+  return roots;
+}
+
+function unquote(value) {
+  const trimmed = value.trim();
+  if (trimmed.length < 2) return trimmed;
+  const quote = trimmed[0];
+  if ((quote !== '"' && quote !== "'") || trimmed.at(-1) !== quote) return trimmed;
+  return trimmed.slice(1, -1).replace(/\\(["'\\])/g, "$1");
+}
+
+/**
+ * Minimal YAML frontmatter reader: only the single-line `name` and
+ * `description` keys are understood.
+ */
+export function parseFrontmatter(text) {
+  if (!text.startsWith("---")) return {};
+  const end = text.indexOf("\n---", 3);
+  if (end === -1) return {};
+  const fields = {};
+  for (const line of text.slice(3, end).split(/\r?\n/)) {
+    // NOTE: multi-line YAML scalars are not supported; v1 reads single-line keys.
+    const match = /^(name|description|triggers):\s*(.*)$/.exec(line);
+    if (match) {
+      if (match[1] === "triggers") {
+        // Parse as comma-separated or YAML inline list: triggers: [a, b] or triggers: a, b
+        const raw = match[2].trim().replace(/^\[/, "").replace(/\]$/, "").trim();
+        fields.triggers = raw ? raw.split(",").map((t) => unquote(t)).filter(Boolean) : [];
+      } else {
+        fields[match[1]] = unquote(match[2]);
+      }
+    }
+  }
+  return fields;
+}
+
+/**
+ * Discover skill directories under each root. A skill directory is a
+ * directory containing `SKILL.md`; a missing root is skipped silently.
+ */
+export async function discoverSkills(roots) {
+  const skills = [];
+  const seen = new Set();
+  for (const root of roots) {
+    const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      const dir = path.join(root, entry.name);
+      if (!(await isDirectory(dir))) continue;
+      const file = path.join(dir, "SKILL.md");
+      const text = await readFile(file, "utf8").catch(() => null);
+      if (text === null) continue;
+      const realDir = await realpath(dir).catch(() => dir);
+      if (seen.has(realDir)) continue;
+      seen.add(realDir);
+      const front = parseFrontmatter(text);
+      skills.push({
+        name: front.name || path.basename(dir),
+        description: front.description || "",
+        triggers: front.triggers || null,
+        path: path.join(realDir, "SKILL.md"),
+      });
+    }
+  }
+  return skills;
+}