pi-skill-shiori 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 eiei114
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,280 @@
+# Pi Skill Shiori
+
+Pi Skill Shiori is a [Pi](https://pi.dev/) package that keeps large Agent Skill catalogs out of the model prompt and lets the agent load only the skills that match the current task.
+
+It is built for vaults or projects with many Agent Skills where the default catalog becomes noisy and expensive.
+
+## What it does
+
+- **Zero-Catalog Mode**: hides the normal skill catalog when Pi exposes one in the system prompt.
+- **Policy-based retrieval**: treats skills as explicit by default and only candidates skills marked as triggerable.
+- **Compact candidate injection**: injects short skill suggestions instead of full `SKILL.md` files.
+- **On-demand loading**: exposes `shiori_load_skill` so the model can load one selected skill body when needed.
+- **SQLite FTS retrieval**: indexes skill names, descriptions, and policy triggers with `node:sqlite` + FTS5, with token-match fallback.
+- **Compact UI output**: keeps skill-load logs short while still passing full skill text to the model.
+
+## Status
+
+`0.1.0` is an early working release. It is useful for local Pi workflows, but the prompt-boundary suppression logic is intentionally conservative: if Shiori cannot safely recognize a catalog boundary, it leaves the prompt untouched and warns instead of deleting too much.
+
+## Requirements
+
+- Pi Coding Agent with package support
+- Node.js `>=22.5`
+- `npm`
+
+Pi core packages are peer dependencies and should be supplied by the Pi runtime:
+
+- `@earendil-works/pi-ai`
+- `@earendil-works/pi-coding-agent`
+- `@earendil-works/pi-tui`
+- `typebox`
+
+## Install
+
+### Global install from npm
+
+After the package is published to npm:
+
+```bash
+pi install npm:pi-skill-shiori@0.1.0
+```
+
+Without a version pin:
+
+```bash
+pi install npm:pi-skill-shiori
+```
+
+### Project-local install from npm
+
+Use `-l` to write the package to the current project’s `.pi/settings.json`:
+
+```bash
+pi install -l npm:pi-skill-shiori@0.1.0
+```
+
+Equivalent manual `.pi/settings.json` entry:
+
+```json
+{
+  "packages": [
+    "npm:pi-skill-shiori@0.1.0"
+  ]
+}
+```
+
+### Global install from GitHub
+
+```bash
+pi install git:github.com/eiei114/pi-skill-shiori@v0.1.0
+```
+
+Without a tag pin:
+
+```bash
+pi install git:github.com/eiei114/pi-skill-shiori
+```
+
+### Project-local install from GitHub
+
+```bash
+pi install -l git:github.com/eiei114/pi-skill-shiori@v0.1.0
+```
+
+### Try without installing
+
+```bash
+pi -e npm:pi-skill-shiori
+pi -e git:github.com/eiei114/pi-skill-shiori
+```
+
+### Local development install
+
+From a project that should use your checkout:
+
+```bash
+pi install -l /absolute/path/to/pi-skill-shiori
+```
+
+Or add a relative local path to `.pi/settings.json`:
+
+```json
+{
+  "packages": [
+    "../../OSS/pi-skill-shiori"
+  ]
+}
+```
+
+> Note: policy/index changes can be refreshed with `/shiori:reload`, but extension code changes require restarting the Pi process because Node keeps imported extension modules cached.
+
+## Configure
+
+Create `.pi/skill-shiori.yml` in the project where Pi runs.
+
+Minimal config:
+
+```yaml
+zeroCatalog:
+  enabled: true
+
+defaults:
+  activation: explicit
+
+candidateInjection:
+  maxCandidates: 3
+  minScore: 0.62
+
+alwaysVisible:
+  - pi-skill-shiori
+
+skills:
+  reddit-research:
+    activation: triggerable
+    triggers:
+      include:
+        - Reddit
+        - Redditで調べて
+        - reputation on Reddit
+      exclude: []
+```
+
+Policy rules:
+
+- `defaults.activation: explicit` is the safe default. Unlisted skills are not auto-candidates.
+- `activation: triggerable` allows Shiori to recommend the skill for matching requests.
+- `alwaysVisible` lists skills that should remain visible/operational in Zero-Catalog workflows.
+- `candidateInjection.maxCandidates` limits how many suggestions enter the prompt.
+- `candidateInjection.minScore` drops weak matches.
+
+Generate a starter policy from discovered skills:
+
+```text
+/shiori:bootstrap
+```
+
+This writes a generated review file next to `.pi/skill-shiori.yml`. Review it before using it as your real policy.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `/shiori:doctor` | Show policy path, inventory count, retrieval backend, suppression status, and code marker. |
+| `/shiori:bootstrap` | Generate a review draft policy from discovered skill descriptions. |
+| `/shiori:reload` | Rebuild Shiori’s skill inventory and retrieval index. |
+| `/shiori:reload --runtime` | Rebuild Shiori and ask Pi to reload runtime resources. Code changes may still need full restart. |
+| `/shiori:test-query <text>` | Preview candidates for a query. |
+| `/shiori:test-query --verbose <text>` | Include full descriptions, scores, paths, and load hints. |
+| `/shiori:stats` | Show operational counters. |
+
+## Tool
+
+Shiori registers one tool:
+
+```ts
+shiori_load_skill({ skill: "reddit-research" })
+```
+
+The model receives the full selected `SKILL.md` content. The Pi UI shows a compact result like:
+
+```text
+✓ Loaded reddit-research (6.3KB)
+```
+
+## Suppression statuses
+
+`/shiori:doctor` reports the last suppression result:
+
+| Status | Meaning |
+|---|---|
+| `disabled` | `zeroCatalog.enabled` is false. |
+| `not-needed` | No normal Skill Catalog marker was present in that turn’s prompt, so nothing needed deletion. |
+| `suppressed` | Shiori recognized and removed the normal Skill Catalog for that turn. |
+| `failed-pattern-not-found` | A catalog-like marker existed, but Shiori could not safely identify its boundary. Prompt left unchanged. |
+
+`not-needed` is not an error. It often means Pi or another configuration already avoided injecting the normal catalog.
+
+## Retrieval backend
+
+Shiori prefers `sqlite-fts` using Node’s built-in `node:sqlite` and FTS5. If that is unavailable, it falls back to `token-match`.
+
+Check backend:
+
+```text
+/shiori:doctor
+```
+
+Example:
+
+```text
+retrievalBackend: sqlite-fts
+code: prompt-boundary-v3
+```
+
+## Development
+
+```bash
+git clone https://github.com/eiei114/pi-skill-shiori.git
+cd pi-skill-shiori
+npm install
+npm run typecheck
+```
+
+Run in a Pi project without installing globally:
+
+```bash
+pi -e /absolute/path/to/pi-skill-shiori
+```
+
+Recommended release checks:
+
+```bash
+npm run typecheck
+npm test
+```
+
+
+## Publish to npm
+
+Release checklist for npm:
+
+```bash
+npm run typecheck
+npm test
+npm run release:npm:dry
+npm whoami
+npm run release:npm
+```
+
+For a first-time publish, login first:
+
+```bash
+npm login
+```
+
+After publishing, verify the Pi install path:
+
+```bash
+pi install npm:pi-skill-shiori@0.1.0
+pi list
+/shiori:doctor
+```
+
+For future versions:
+
+```bash
+npm version patch
+git push --follow-tags
+npm run release:npm
+```
+
+## Security notes
+
+Pi packages execute local code with the same permissions as Pi. Review third-party packages before installing them.
+
+Shiori itself does not sandbox skills. It only changes how skill candidates are discovered and loaded. A loaded skill can still instruct the model to run tools, edit files, or execute commands according to your Pi/tool permissions.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "pi-skill-shiori",
+  "version": "0.1.0",
+  "description": "Pi extension that reduces Agent Skill catalog tokens with policy-based skill retrieval and on-demand skill loading.",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://github.com/eiei114/pi-skill-shiori#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eiei114/pi-skill-shiori.git"
+  },
+  "bugs": {
+    "url": "https://github.com/eiei114/pi-skill-shiori/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "agent-skills",
+    "skill-retrieval"
+  ],
+  "engines": {
+    "node": ">=22.5"
+  },
+  "files": [
+    "README.md",
+    "LICENSE",
+    "src"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsc --noEmit",
+    "test": "npm run typecheck",
+    "prepublishOnly": "npm test",
+    "release:npm:dry": "npm pack --dry-run",
+    "release:npm": "npm publish --access public"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "dependencies": {
+    "yaml": "^2.8.1"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.75.5",
+    "@earendil-works/pi-coding-agent": "^0.75.5",
+    "@earendil-works/pi-tui": "^0.75.5",
+    "@types/node": "^25.9.1",
+    "typebox": "^1.1.38",
+    "typescript": "^6.0.3"
+  }
+}

package/src/discovery.ts

@@ -0,0 +1,96 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import type { SkillRecord } from "./types.js";
+
+const SKILL_FILE = "SKILL.md";
+
+export async function discoverSkills(cwd: string): Promise<SkillRecord[]> {
+  const roots = [
+    join(cwd, ".pi", "skills"),
+    join(cwd, ".agents", "skills"),
+    join(homedir(), ".pi", "agent", "skills"),
+  ];
+
+  const records: SkillRecord[] = [];
+  for (const root of roots) {
+    const files = await findSkillFiles(root);
+    for (const file of files) {
+      records.push(await readSkillRecord(file, root));
+    }
+  }
+  return dedupeByDiscoveryOrder(records);
+}
+
+export function findDuplicates(records: SkillRecord[]): Map<string, SkillRecord[]> {
+  const groups = new Map<string, SkillRecord[]>();
+  for (const record of records) {
+    const current = groups.get(record.name) ?? [];
+    current.push(record);
+    groups.set(record.name, current);
+  }
+  return new Map([...groups].filter(([, items]) => items.length > 1));
+}
+
+async function findSkillFiles(root: string): Promise<string[]> {
+  try {
+    const info = await stat(root);
+    if (!info.isDirectory()) return [];
+  } catch {
+    return [];
+  }
+
+  const result: string[] = [];
+  await walk(root, result);
+  return result;
+}
+
+async function walk(dir: string, result: string[]): Promise<void> {
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      await walk(fullPath, result);
+    } else if (entry.isFile() && entry.name === SKILL_FILE) {
+      result.push(fullPath);
+    }
+  }
+}
+
+async function readSkillRecord(path: string, root: string): Promise<SkillRecord> {
+  const raw = await readFile(path, "utf8");
+  const frontmatter = raw.match(/^---\s*\n([\s\S]*?)\n---/);
+  const block = frontmatter?.[1] ?? "";
+  const name = matchYamlScalar(block, "name") ?? basename(dirname(path));
+  const description = matchYamlScalar(block, "description") ?? firstParagraph(raw) ?? "No description.";
+  return {
+    name,
+    description,
+    path: resolve(path),
+    source: root,
+  };
+}
+
+function matchYamlScalar(block: string, key: string): string | undefined {
+  const match = block.match(new RegExp(`^${key}:\s*(.+)$`, "m"));
+  return match?.[1]?.trim().replace(/^['\"]|['\"]$/g, "");
+}
+
+function firstParagraph(raw: string): string | undefined {
+  return raw
+    .replace(/^---\s*\n[\s\S]*?\n---/, "")
+    .split(/\n\s*\n/)
+    .map((part) => part.trim())
+    .find(Boolean);
+}
+
+function dedupeByDiscoveryOrder(records: SkillRecord[]): SkillRecord[] {
+  const seen = new Set<string>();
+  const result: SkillRecord[] = [];
+  for (const record of records) {
+    if (seen.has(record.name)) continue;
+    seen.add(record.name);
+    result.push(record);
+  }
+  return result;
+}

package/src/index.ts

@@ -0,0 +1,233 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { readFile, writeFile } from "node:fs/promises";
+import { discoverSkills, findDuplicates } from "./discovery.js";
+import { buildSkillIndex, type SkillIndex } from "./indexer.js";
+import { createStats } from "./metrics.js";
+import { getPolicyPath, loadPolicy } from "./policy.js";
+import { formatCandidateInjection, suppressSkillCatalog } from "./prompt.js";
+import { retrieveCandidates } from "./retrieval.js";
+import type { SkillRecord } from "./types.js";
+
+interface ShioriLoadDetails {
+  skill: string;
+  path: string;
+  bytes: number;
+  loadedAt: string;
+}
+
+const SHIORI_CODE_MARKER = "prompt-boundary-v3";
+
+export default function piSkillShiori(pi: ExtensionAPI) {
+  let index: SkillIndex | undefined;
+  const stats = createStats();
+
+  async function reload(cwd: string): Promise<SkillIndex> {
+    const [policy, skills] = await Promise.all([loadPolicy(cwd), discoverSkills(cwd)]);
+    index?.close?.();
+    index = await buildSkillIndex(cwd, skills, policy);
+    stats.inventoryCount = skills.length;
+    stats.duplicateCount = findDuplicates(skills).size;
+    stats.lastReloadAt = index.builtAt;
+    stats.retrievalBackend = index.retrievalBackend;
+    stats.suppressionStatus = policy.zeroCatalog.enabled ? "not-needed" : "disabled";
+    return index;
+  }
+
+  async function ensureIndex(cwd: string): Promise<SkillIndex> {
+    return index ?? reload(cwd);
+  }
+
+  pi.on("session_start", async (_event, ctx) => {
+    await reload(ctx.cwd);
+  });
+
+  pi.on("input", async (event) => {
+    if (/^\/(skill:|shiori:)/.test(event.text.trim())) {
+      stats.explicitInvocationCount += 1;
+    }
+    return { action: "continue" };
+  });
+
+  pi.on("before_agent_start", async (event, ctx) => {
+    const current = await ensureIndex(ctx.cwd);
+    if (!current.policy.zeroCatalog.enabled) return;
+
+    const suppression = suppressSkillCatalog(event.systemPrompt);
+    stats.suppressionStatus = suppression.status;
+    if (suppression.status === "failed-pattern-not-found") {
+      ctx.ui.notify("Pi Skill Shiori: Skill Catalog suppression pattern not found; leaving system prompt unchanged.", "warning");
+    }
+
+    const candidates = retrieveCandidates(event.prompt, current.skills, current.policy, current);
+    if (candidates.length === 0) stats.zeroCandidateCount += 1;
+    else stats.candidateHitCount += 1;
+
+    const injection = formatCandidateInjection(candidates);
+    const candidateSection = injection ? `\n\n## Pi Skill Shiori Candidates\n\n${injection}\n` : "";
+
+    return {
+      systemPrompt: `${suppression.systemPrompt}${candidateSection}`,
+    };
+  });
+
+  pi.registerTool({
+    name: "shiori_load_skill",
+    label: "Shiori Load Skill",
+    description: "Load one Agent Skill by name from the Pi Skill Shiori inventory.",
+    promptSnippet: "Load an Agent Skill by name after Pi Skill Shiori recommends it.",
+    promptGuidelines: [
+      "Use shiori_load_skill only when a Pi Skill Shiori candidate is relevant to the user's current request.",
+    ],
+    parameters: Type.Object({
+      skill: Type.String({ description: "Agent Skill name to load" }),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const current = await ensureIndex(ctx.cwd);
+      const record = findSkill(params.skill, current.skills);
+      if (!record) throw new Error(`Skill not found: ${params.skill}`);
+      const content = await readFile(record.path, "utf8");
+      stats.loadedSkillCount += 1;
+      const details: ShioriLoadDetails = {
+        skill: record.name,
+        path: record.path,
+        bytes: Buffer.byteLength(content, "utf8"),
+        loadedAt: new Date().toISOString(),
+      };
+      return {
+        content: [{ type: "text", text: `Loaded ${record.name} from ${record.path}\n\n${content}` }],
+        details,
+      };
+    },
+    renderResult(result, { expanded }, theme) {
+      const details = result.details as Partial<ShioriLoadDetails> | undefined;
+      if (!details?.skill) {
+        return new Text(theme.fg("success", "Loaded skill"), 0, 0);
+      }
+      const size = typeof details.bytes === "number" ? formatBytes(details.bytes) : "unknown size";
+      const collapsed = `${theme.fg("success", "✓ Loaded")} ${theme.bold(details.skill)} ${theme.fg("muted", `(${size})`)}`;
+      if (!expanded) return new Text(collapsed, 0, 0);
+      const path = details.path ? `\n${theme.fg("dim", details.path)}` : "";
+      return new Text(`${collapsed}${path}`, 0, 0);
+    },
+  });
+
+  pi.registerCommand("shiori:doctor", {
+    description: "Show Pi Skill Shiori configuration and inventory status",
+    handler: async (_args, ctx) => {
+      const current = await ensureIndex(ctx.cwd);
+      const duplicates = findDuplicates(current.skills);
+      ctx.ui.notify(
+        [
+          "Pi Skill Shiori doctor",
+          `policy: ${getPolicyPath(ctx.cwd)}`,
+          `zeroCatalog: ${current.policy.zeroCatalog.enabled ? "enabled" : "disabled"}`,
+          `skills: ${current.skills.length}`,
+          `duplicates: ${duplicates.size}`,
+          `alwaysVisible: ${current.policy.alwaysVisible.join(", ") || "none"}`,
+          `retrievalBackend: ${current.retrievalBackend}`,
+          `suppression: ${stats.suppressionStatus}`,
+          `code: ${SHIORI_CODE_MARKER}`,
+          `builtAt: ${current.builtAt}`,
+        ].join("\n"),
+        duplicates.size > 0 || stats.suppressionStatus === "failed-pattern-not-found" ? "warning" : "info",
+      );
+    },
+  });
+
+  pi.registerCommand("shiori:reload", {
+    description: "Rebuild Pi Skill Shiori inventory and optional Pi runtime resources",
+    handler: async (args, ctx) => {
+      await reload(ctx.cwd);
+      if (args.includes("--runtime")) {
+        await ctx.reload();
+        return;
+      }
+      ctx.ui.notify(`Pi Skill Shiori reloaded: ${stats.inventoryCount} skills (${stats.retrievalBackend})`, "info");
+    },
+  });
+
+  pi.registerCommand("shiori:test-query", {
+    description: "Test Pi Skill Shiori candidate retrieval for arbitrary text",
+    handler: async (args, ctx) => {
+      const current = await ensureIndex(ctx.cwd);
+      const { query, verbose } = parseTestQueryArgs(args);
+      const candidates = retrieveCandidates(query, current.skills, current.policy, current);
+      ctx.ui.notify(
+        formatCandidateInjection(candidates, { verbose }) || "No candidates",
+        candidates.length ? "info" : "warning",
+      );
+    },
+  });
+
+  pi.registerCommand("shiori:stats", {
+    description: "Show Pi Skill Shiori operational counters",
+    handler: async (_args, ctx) => {
+      ctx.ui.notify(JSON.stringify(stats, null, 2), "info");
+    },
+  });
+
+  pi.registerCommand("shiori:bootstrap", {
+    description: "Generate a review policy draft from discovered skill descriptions",
+    handler: async (_args, ctx) => {
+      const current = await ensureIndex(ctx.cwd);
+      const draft = renderGeneratedPolicy(current.skills);
+      const outputPath = getPolicyPath(ctx.cwd).replace(/\.yml$/, ".generated.yml");
+      await writeFile(outputPath, draft, "utf8");
+      ctx.ui.notify(`Generated ${outputPath}`, "info");
+    },
+  });
+}
+
+function findSkill(name: string, skills: SkillRecord[]): SkillRecord | undefined {
+  return skills.find((skill) => skill.name === name);
+}
+
+function parseTestQueryArgs(args: string): { query: string; verbose: boolean } {
+  const verbose = /(^|\s)--verbose(\s|$)/.test(args);
+  return {
+    verbose,
+    query: args.replace(/(^|\s)--verbose(\s|$)/g, " ").trim(),
+  };
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes}B`;
+  return `${(bytes / 1024).toFixed(1)}KB`;
+}
+
+
+function renderGeneratedPolicy(skills: SkillRecord[]): string {
+  const lines = [
+    "zeroCatalog:",
+    "  enabled: false",
+    "defaults:",
+    "  activation: explicit",
+    "candidateInjection:",
+    "  maxCandidates: 3",
+    "  minScore: 0.62",
+    "alwaysVisible:",
+    "  - pi-skill-shiori",
+    "skills:",
+  ];
+
+  for (const skill of skills) {
+    const triggerable = /proactively activate|triggers?:|use when/i.test(skill.description);
+    lines.push(`  ${skill.name}:`);
+    lines.push(`    activation: ${triggerable ? "triggerable" : "explicit"}`);
+    if (triggerable) {
+      lines.push("    triggers:");
+      lines.push("      include:");
+      lines.push(`        - ${JSON.stringify(skill.name)}`);
+      lines.push("      exclude: []");
+    }
+    lines.push(`    path: ${JSON.stringify(relativeForYaml(skill.path))}`);
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+function relativeForYaml(path: string): string {
+  return path.replace(/\\/g, "/");
+}

package/src/indexer.ts

@@ -0,0 +1,80 @@
+import { mkdir } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import type { RetrievalBackend, ShioriPolicy, SkillRecord } from "./types.js";
+
+export interface SkillIndex {
+  skills: SkillRecord[];
+  policy: ShioriPolicy;
+  builtAt: string;
+  retrievalBackend: RetrievalBackend;
+  search(query: string, limit: number): SkillRecord[];
+  close(): void;
+}
+
+export async function buildSkillIndex(cwd: string, skills: SkillRecord[], policy: ShioriPolicy): Promise<SkillIndex> {
+  const builtAt = new Date().toISOString();
+  const byName = new Map(skills.map((skill) => [skill.name, skill]));
+
+  try {
+    const require = createRequire(import.meta.url);
+    const sqlite = require("node:sqlite") as typeof import("node:sqlite");
+    const cacheDir = join(cwd, ".pi", "cache", "skill-shiori");
+    const dbPath = join(cacheDir, `index-${process.pid}-${Date.now()}.sqlite`);
+    await mkdir(cacheDir, { recursive: true });
+
+    const db = new sqlite.DatabaseSync(dbPath);
+    db.exec("CREATE VIRTUAL TABLE skill_fts USING fts5(name, description, triggers, path)");
+    const insert = db.prepare("INSERT INTO skill_fts(name, description, triggers, path) VALUES (?, ?, ?, ?)");
+    for (const skill of skills) {
+      const triggers = [
+        ...(policy.skills[skill.name]?.triggers?.include ?? []),
+        ...(policy.skills[skill.name]?.triggers?.exclude ?? []),
+      ].join(" ");
+      insert.run(skill.name, skill.description, triggers, skill.path);
+    }
+
+    return {
+      skills,
+      policy,
+      builtAt,
+      retrievalBackend: "sqlite-fts",
+      search(query: string, limit: number): SkillRecord[] {
+        const ftsQuery = buildFtsQuery(query);
+        if (!ftsQuery) return [];
+        try {
+          const rows = db
+            .prepare("SELECT name FROM skill_fts WHERE skill_fts MATCH ? LIMIT ?")
+            .all(ftsQuery, limit) as Array<{ name: string }>;
+          return rows.map((row) => byName.get(row.name)).filter((skill): skill is SkillRecord => Boolean(skill));
+        } catch {
+          return [];
+        }
+      },
+      close(): void {
+        db.close();
+      },
+    };
+  } catch {
+    return {
+      skills,
+      policy,
+      builtAt,
+      retrievalBackend: "token-match",
+      search(): SkillRecord[] {
+        return [];
+      },
+      close(): void {},
+    };
+  }
+}
+
+function buildFtsQuery(query: string): string {
+  const terms = query.match(/[A-Za-z0-9_-]{2,}/g) ?? [];
+  const uniqueTerms = [...new Set(terms.map((term) => term.toLowerCase()))].slice(0, 8);
+  return uniqueTerms.map((term) => `${escapeFtsTerm(term)}*`).join(" OR ");
+}
+
+function escapeFtsTerm(term: string): string {
+  return term.replace(/[^A-Za-z0-9_-]/g, "");
+}

package/src/metrics.ts

@@ -0,0 +1,14 @@
+import type { ShioriStats } from "./types.js";
+
+export function createStats(): ShioriStats {
+  return {
+    inventoryCount: 0,
+    duplicateCount: 0,
+    candidateHitCount: 0,
+    zeroCandidateCount: 0,
+    loadedSkillCount: 0,
+    explicitInvocationCount: 0,
+    retrievalBackend: "token-match",
+    suppressionStatus: "disabled",
+  };
+}

package/src/policy.ts

@@ -0,0 +1,46 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse } from "yaml";
+import type { ShioriPolicy } from "./types.js";
+
+export const DEFAULT_POLICY: ShioriPolicy = {
+  zeroCatalog: { enabled: false },
+  defaults: { activation: "explicit" },
+  candidateInjection: { maxCandidates: 3, minScore: 0.62 },
+  alwaysVisible: ["pi-skill-shiori"],
+  skills: {},
+};
+
+export function getPolicyPath(cwd: string): string {
+  return join(cwd, ".pi", "skill-shiori.yml");
+}
+
+export async function loadPolicy(cwd: string): Promise<ShioriPolicy> {
+  try {
+    const raw = await readFile(getPolicyPath(cwd), "utf8");
+    const parsed = parse(raw) as Partial<ShioriPolicy> | undefined;
+    return normalizePolicy(parsed);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return DEFAULT_POLICY;
+    }
+    throw error;
+  }
+}
+
+function normalizePolicy(policy: Partial<ShioriPolicy> | undefined): ShioriPolicy {
+  return {
+    zeroCatalog: {
+      enabled: policy?.zeroCatalog?.enabled ?? DEFAULT_POLICY.zeroCatalog.enabled,
+    },
+    defaults: {
+      activation: policy?.defaults?.activation ?? DEFAULT_POLICY.defaults.activation,
+    },
+    candidateInjection: {
+      maxCandidates: policy?.candidateInjection?.maxCandidates ?? DEFAULT_POLICY.candidateInjection.maxCandidates,
+      minScore: policy?.candidateInjection?.minScore ?? DEFAULT_POLICY.candidateInjection.minScore,
+    },
+    alwaysVisible: policy?.alwaysVisible ?? DEFAULT_POLICY.alwaysVisible,
+    skills: policy?.skills ?? DEFAULT_POLICY.skills,
+  };
+}

package/src/prompt.ts

@@ -0,0 +1,74 @@
+import type { SkillCandidate, SuppressionStatus } from "./types.js";
+
+interface CandidateFormatOptions {
+  verbose?: boolean;
+}
+
+export interface CatalogSuppressionResult {
+  systemPrompt: string;
+  status: SuppressionStatus;
+}
+
+const COMPACT_DESCRIPTION_LIMIT = 120;
+
+export function formatCandidateInjection(candidates: SkillCandidate[], options: CandidateFormatOptions = {}): string {
+  if (candidates.length === 0) return "";
+  const lines = ["Relevant skills:"];
+  for (const candidate of candidates) {
+    const desc = compactDescription(candidate.skill.description, COMPACT_DESCRIPTION_LIMIT);
+    if (options.verbose) {
+      lines.push(`- ${candidate.skill.name}`);
+      lines.push(`  desc: ${candidate.skill.description}`);
+      lines.push(`  score: ${candidate.score.toFixed(2)}`);
+      lines.push(`  why: ${candidate.why}`);
+      lines.push(`  path: ${candidate.skill.path}`);
+      lines.push(`  load: shiori_load_skill({ skill: "${candidate.skill.name}" })`);
+    } else {
+      lines.push(
+        `- ${candidate.skill.name}: ${desc} Reason: ${candidate.why}. Load: shiori_load_skill({ skill: "${candidate.skill.name}" })`,
+      );
+    }
+  }
+  return lines.join("\n");
+}
+
+export function compactDescription(description: string, maxChars = COMPACT_DESCRIPTION_LIMIT): string {
+  const singleLine = description.replace(/\s+/g, " ").trim();
+  if (singleLine.length <= maxChars) return singleLine;
+  return `${singleLine.slice(0, Math.max(0, maxChars - 1)).trimEnd()}…`;
+}
+
+export function suppressSkillCatalog(systemPrompt: string): CatalogSuppressionResult {
+  const replacement = [
+    "### Available skills",
+    "Normal Skill Catalog hidden by Pi Skill Shiori.",
+    "Use injected candidates or shiori_load_skill when relevant.",
+    "Explicit /skill:name invocation remains allowed.",
+  ].join("\n");
+
+  const patterns = [
+    /\r?\n\r?\nThe following skills provide specialized instructions for specific tasks\.\r?\n[\s\S]*?\r?\n<available_skills>[\s\S]*?\r?\n<\/available_skills>/,
+    /(^|\r?\n)<available_skills>[\s\S]*?<\/available_skills>/i,
+    /(^|\r?\n)#{2,4}\s*Available skills\b[\s\S]*?(?=\r?\n#{2,4}\s*How to use skills\b)/i,
+    /(^|\r?\n)#{2,4}\s*Available skills\b[\s\S]*?(?=\r?\n#{2,4}\s*Fallback\b)/i,
+  ];
+  for (const pattern of patterns) {
+    if (!pattern.test(systemPrompt)) continue;
+    return {
+      systemPrompt: systemPrompt.replace(pattern, `${replacement}\n`),
+      status: "suppressed",
+    };
+  }
+
+  if (!hasSkillCatalogSignal(systemPrompt)) {
+    return { systemPrompt, status: "not-needed" };
+  }
+
+  return { systemPrompt, status: "failed-pattern-not-found" };
+}
+
+function hasSkillCatalogSignal(systemPrompt: string): boolean {
+  return /<\/?available_skills>|The following skills provide specialized instructions|#{2,4}\s*Available skills\b/i.test(
+    systemPrompt,
+  );
+}

package/src/retrieval.ts

@@ -0,0 +1,88 @@
+import type { ShioriPolicy, SkillCandidate, SkillRecord } from "./types.js";
+
+interface RetrievalIndex {
+  search(query: string, limit: number): SkillRecord[];
+}
+
+export function retrieveCandidates(
+  query: string,
+  skills: SkillRecord[],
+  policy: ShioriPolicy,
+  index?: RetrievalIndex,
+): SkillCandidate[] {
+  const normalizedQuery = normalize(query);
+  const candidatesByName = new Map<string, SkillCandidate>();
+  const triggerableSkills = skills.filter(
+    (skill) => (policy.skills[skill.name]?.activation ?? policy.defaults.activation) === "triggerable",
+  );
+
+  for (const skill of triggerableSkills) {
+    const triggerCandidate = evaluateSkill(skill, normalizedQuery, policy, true);
+    if (triggerCandidate) candidatesByName.set(skill.name, triggerCandidate);
+  }
+
+  const ftsMatches = index?.search(query, policy.candidateInjection.maxCandidates * 4) ?? [];
+  const scoringPool = ftsMatches.length > 0 ? ftsMatches : triggerableSkills;
+  for (const skill of scoringPool) {
+    const candidate = evaluateSkill(skill, normalizedQuery, policy, false);
+    if (!candidate) continue;
+    const previous = candidatesByName.get(skill.name);
+    if (!previous || candidate.score > previous.score) {
+      candidatesByName.set(skill.name, candidate);
+    }
+  }
+
+  return [...candidatesByName.values()]
+    .sort((a, b) => b.score - a.score || a.skill.name.localeCompare(b.skill.name))
+    .slice(0, policy.candidateInjection.maxCandidates);
+}
+
+function evaluateSkill(
+  skill: SkillRecord,
+  normalizedQuery: string,
+  policy: ShioriPolicy,
+  exactTriggerOnly: boolean,
+): SkillCandidate | undefined {
+  const skillPolicy = policy.skills[skill.name];
+  const excludes = skillPolicy?.triggers?.exclude ?? [];
+  const matchedExclude = excludes.find((trigger) => includesNormalized(normalizedQuery, trigger));
+  if (matchedExclude) return undefined;
+
+  const includes = skillPolicy?.triggers?.include ?? [];
+  const matchedInclude = includes.find((trigger) => includesNormalized(normalizedQuery, trigger));
+  if (matchedInclude) {
+    return {
+      skill,
+      score: 0.95,
+      why: `matched trigger "${matchedInclude}"`,
+    };
+  }
+  if (exactTriggerOnly) return undefined;
+
+  const text = normalize(`${skill.name} ${skill.description} ${includes.join(" ")}`);
+  const tokenScore = scoreTokens(normalizedQuery, text);
+  if (tokenScore < policy.candidateInjection.minScore) return undefined;
+  return {
+    skill,
+    score: tokenScore,
+    why: "matched skill description",
+  };
+}
+
+function normalize(input: string): string {
+  return input.toLowerCase().replace(/\s+/g, " ").trim();
+}
+
+function includesNormalized(query: string, trigger: string): boolean {
+  return query.includes(normalize(trigger));
+}
+
+function scoreTokens(query: string, text: string): number {
+  const tokens = new Set(query.split(/[^\p{L}\p{N}_-]+/u).filter((token) => token.length >= 2));
+  if (tokens.size === 0) return 0;
+  let hits = 0;
+  for (const token of tokens) {
+    if (text.includes(token)) hits += 1;
+  }
+  return hits / tokens.size;
+}

package/src/types.ts

@@ -0,0 +1,52 @@
+export type SkillActivation = "explicit" | "triggerable";
+export type RetrievalBackend = "sqlite-fts" | "token-match";
+export type SuppressionStatus = "disabled" | "not-needed" | "suppressed" | "failed-pattern-not-found";
+
+export interface ShioriPolicy {
+  zeroCatalog: {
+    enabled: boolean;
+  };
+  defaults: {
+    activation: SkillActivation;
+  };
+  candidateInjection: {
+    maxCandidates: number;
+    minScore: number;
+  };
+  alwaysVisible: string[];
+  skills: Record<string, SkillPolicy>;
+}
+
+export interface SkillPolicy {
+  activation?: SkillActivation;
+  path?: string;
+  triggers?: {
+    include?: string[];
+    exclude?: string[];
+  };
+}
+
+export interface SkillRecord {
+  name: string;
+  description: string;
+  path: string;
+  source: string;
+}
+
+export interface SkillCandidate {
+  skill: SkillRecord;
+  score: number;
+  why: string;
+}
+
+export interface ShioriStats {
+  inventoryCount: number;
+  duplicateCount: number;
+  candidateHitCount: number;
+  zeroCandidateCount: number;
+  loadedSkillCount: number;
+  explicitInvocationCount: number;
+  retrievalBackend: RetrievalBackend;
+  suppressionStatus: SuppressionStatus;
+  lastReloadAt?: string;
+}