pi-skill-shiori 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to this project will be documented in this file.
 
 This project follows semantic versioning.
 
+## [0.4.0] - 2026-06-28
+
+### Added
+
+- Always Visible Skill policy: Zero-Catalog Mode now keeps only `alwaysVisible` allowlisted skills in the Skill Catalog instead of hiding every entry.
+- Diagnostics for missing or duplicate `alwaysVisible` policy entries in `/shiori:doctor` and one-time runtime warnings for missing skills.
+- Tests for visible, missing, duplicate, and markdown catalog filtering cases.
+
+### Changed
+
+- `alwaysVisible` policy entries are normalized to a deduplicated allowlist at load time.
+
+## [0.3.2] - 2026-06-24
+
+### Added
+
+- `ROADMAP.md` with maintenance-first phased goals (Month 1–3), template compliance checklist, and maintenance schedule.
+- README links to `ROADMAP.md`.
+- npm package `files` now includes `ROADMAP.md`.
+
 ## [0.3.1] - 2026-06-19
 
 ### Added

package/README.md

@@ -4,6 +4,8 @@ Pi Skill Shiori is a [Pi](https://pi.dev/) package that keeps large Agent Skill
 
 It is built for vaults or projects with many Agent Skills where the default catalog becomes noisy and expensive.
 
+For maintenance priorities and the phased plan, see [`ROADMAP.md`](ROADMAP.md).
+
 ## What it does
 
 - **Zero-Catalog Mode**: hides the normal skill catalog when Pi exposes one in the system prompt.
@@ -15,7 +17,7 @@ It is built for vaults or projects with many Agent Skills where the default cata
 
 ## Status
 
-`0.3.1` 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.
+`0.4.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
 
@@ -37,7 +39,7 @@ Pi core packages are peer dependencies and should be supplied by the Pi runtime:
 After the package is published to npm:
 
 ```bash
-pi install npm:pi-skill-shiori@0.3.1
+pi install npm:pi-skill-shiori@0.4.0
 ```
 
 Without a version pin:
@@ -51,7 +53,7 @@ pi install npm:pi-skill-shiori
 Use `-l` to write the package to the current project’s `.pi/settings.json`:
 
 ```bash
-pi install -l npm:pi-skill-shiori@0.3.1
+pi install -l npm:pi-skill-shiori@0.4.0
 ```
 
 Without a version pin:
@@ -65,7 +67,7 @@ Equivalent pinned manual `.pi/settings.json` entry:
 ```json
 {
   "packages": [
-    "npm:pi-skill-shiori@0.3.1"
+    "npm:pi-skill-shiori@0.4.0"
   ]
 }
 ```
@@ -83,7 +85,7 @@ Equivalent unpinned manual `.pi/settings.json` entry:
 ### Global install from GitHub
 
 ```bash
-pi install git:github.com/eiei114/pi-skill-shiori@v0.3.1
+pi install git:github.com/eiei114/pi-skill-shiori@v0.4.0
 ```
 
 Without a tag pin:
@@ -95,7 +97,7 @@ 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.3.1
+pi install -l git:github.com/eiei114/pi-skill-shiori@v0.4.0
 ```
 
 Without a tag pin:
@@ -166,7 +168,8 @@ 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.
+- `alwaysVisible` lists skills that should remain visible in the Skill Catalog during Zero-Catalog Mode. Use this for a tiny safety-critical allowlist instead of broad trigger rules.
+- Missing `alwaysVisible` entries are reported by `/shiori:doctor` and warned once per session when Zero-Catalog Mode runs.
 - `candidateInjection.maxCandidates` limits how many suggestions enter the prompt.
 - `candidateInjection.minScore` drops weak matches.
 
@@ -278,7 +281,7 @@ npm login
 After publishing, verify the Pi install path:
 
 ```bash
-pi install npm:pi-skill-shiori@0.3.1
+pi install npm:pi-skill-shiori@0.4.0
 pi install npm:pi-skill-shiori
 pi list
 /shiori:doctor

package/ROADMAP.md

@@ -0,0 +1,132 @@
+# Roadmap
+
+Pi Skill Shiori keeps large Agent Skill catalogs out of the model prompt and lets
+the agent load only the skills that match the current task. This roadmap states
+**what we prioritize next** and how the package is maintained.
+
+## Direction
+
+`0.3.x` is a working release. The near-term priority is **stabilization and
+public quality over new feature surface**. Before widening functionality, we
+harden what already ships:
+
+- **Stabilize existing behavior** — make catalog suppression and retrieval reliable.
+- **Speed and token efficiency** — startup cost, index rebuild, and candidate injection footprint.
+- **Explicit design boundaries** — name the contracts (policy file, hook activation, suppression).
+- **Template compliance** — close gaps against the shared Pi extension OSS policy.
+- **Publish quality** — README, CHANGELOG, SECURITY, CI, `npm pack`, and release handoff.
+
+Constraints:
+
+- Existing commands, tools, and the main UX stay unless a compatibility fix is required.
+- `shiori:*` commands stay argument-less; detail is collected after launch via Pi UI.
+- npm publish stays Trusted Publishing / OIDC. Secrets and production actions remain human-owned.
+
+## Skill features vs. template requirements
+
+Two kinds of work are tracked separately so feature work is not confused with
+packaging/hygiene work:
+
+- **Skill features** — Zero-Catalog suppression, policy-based retrieval, candidate
+  injection, on-demand loading, hybrid retrieval. These change what the package does.
+- **Template requirements** — README badges, CI gates, `npm pack` cleanliness, action
+  pinning, version-bump checks. These keep the package publishable and aligned with
+  `pi-extension-template`.
+
+Template gaps are addressed first because they protect every later release.
+
+## Maintenance schedule
+
+- **Patch release** — as needed for fixes, doc/template compliance, and small behavior changes.
+- **Minor release** — retrieval quality or candidate-flow improvements.
+- **Release cadence** — ship per ready slice; no fixed calendar release. Every mergeable
+  change bumps `package.json` and `CHANGELOG.md` so npm can publish.
+- **Dependency review** — monthly; bump `devDependencies`/Pi peers without behavior change.
+- **Release flow** — `npm version <patch|minor>` → push → `auto-release.yml` tags and
+  releases → `publish.yml` publishes via Trusted Publishing (provenance verified).
+
+`/shiori:stats` reports operational counters (token saved, candidate hits, loads,
+zero-candidate turns, explicit invocations) that feed back into this schedule.
+
+## Phased goals (Month 1–3)
+
+Each item is a small, independently verifiable slice (roughly 30–90 minutes) with a
+semver classification. Patches default to `patch`; `none` means no package publish.
+
+### Month 1 — Public quality and template compliance
+
+| # | Slice | Bump | Status |
+|---|---|---|---|
+| 1 | Add README status badges (CI, Publish, npm version, npm downloads, License, Pi package, Trusted Publishing) | patch | planned |
+| 2 | Add `version:check` CI gate (block publishable-path changes without a semver increase) | none | planned |
+| 3 | Pin GitHub Actions to commit SHAs in `ci.yml`, `auto-release.yml`, `publish.yml` | none | planned |
+
+### Month 2 — Stabilization and design boundaries
+
+| # | Slice | Bump | Status |
+|---|---|---|---|
+| 4 | Harden catalog boundary detection and add boundary tests (reduce `failed-pattern-not-found`) | patch | planned |
+| 5 | Integration test for Dual Hook Activation (input-hook explicit pass-through + `before_agent_start` candidate injection) | none | planned |
+
+### Month 3 — Speed and token efficiency
+
+| # | Slice | Bump | Status |
+|---|---|---|---|
+| 6 | Add startup/operation timing instrumentation to `/shiori:stats` (Full Index Rebuild + retrieval baseline) | patch | planned |
+| 7 | Startup index strategy (incremental / lazy / cached) — needs a design decision before implementation | none | blocked (design) |
+
+## Integration testing for skill hooks
+
+Dual Hook Activation is the core discovery path and must be covered end to end:
+
+- **Input hook** — explicit invocation pass-through: `/skill:name` and explicit names load
+  regardless of activation policy, including under Zero-Catalog Mode.
+- **`before_agent_start` hook** — automatic candidate injection for triggerable skills only,
+  bounded by `maxCandidates` and `minScore`, with explicit skills excluded.
+
+The Month 2 integration test asserts both paths together (explicit load still works while
+triggerable candidates are injected) so a regression in one hook surfaces immediately.
+
+## Template compliance checklist
+
+Current status against the shared Pi extension OSS policy. Gaps become Month 1 work.
+
+- [x] `README.md`, `LICENSE`, `SECURITY.md`, `CHANGELOG.md` at repo root
+- [x] CI runs `npm run typecheck`, `npm test`, and `npm pack --dry-run`
+- [x] npm Trusted Publishing (`publish.yml` uses `id-token: write`, no `NPM_TOKEN`)
+- [x] `auto-release.yml` → `publish.yml` release handoff
+- [x] `package.json` `files` is explicit (no `node_modules`, tests, or local state)
+- [x] No template `example-skill` / `example` / `example-theme` resources shipped
+- [ ] **README status badges** (CI, Publish, npm version, npm downloads, License, Pi package, Trusted Publishing) — *Month 1 #1*
+- [ ] **`version:check` CI gate** so publishable-path changes cannot merge without a bump — *Month 1 #2*
+- [ ] **Pin GitHub Actions to commit SHAs** (currently floating `@v4`) — *Month 1 #3*
+
+## Current backlog integration
+
+Feature-track items already shipped (kept here so the roadmap reflects reality, not a
+fresh to-do list):
+
+- Recommendation-first `/shiori:recommend` flow with query expansion and planning intent — shipped (`0.2.0`)
+- CI + auto-release + publish handoff — shipped (`0.1.1`+)
+- `shiori:*` commands use Pi UI flows (argument-less) — shipped (`0.3.0`)
+- `SECURITY.md` and `CHANGELOG.md` — shipped (`0.3.1`)
+
+Remaining feature-track item, deferred behind the maintenance-first direction:
+
+- README/docs alignment with the minimal public-docs policy — open; the Month 1 badge
+  and CI slices advance this track without blocking on the broader docs-policy decision.
+
+## Later (feature track)
+
+- Retrieval quality improvements (embedding candidate added beside SQLite FTS).
+- Cross-vault skill index.
+- ResourceLoader-side catalog replacement (stable-stage Two-stage Catalog Suppression).
+
+These are intentionally **after** the Month 1–3 maintenance work.
+
+## Non-goals
+
+- Rewriting existing commands, tools, or the candidate/recommend UX.
+- Auto-approving npm publish, permission changes, or production actions.
+- Removing the conservative catalog-suppression safety boundary (`not-needed` /
+  `failed-pattern-not-found` stay safe-by-default).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-skill-shiori",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Pi extension that reduces Agent Skill catalog tokens with policy-based skill retrieval and on-demand skill loading.",
   "type": "module",
   "license": "MIT",
@@ -23,6 +23,7 @@
   },
   "files": [
     "README.md",
+    "ROADMAP.md",
     "LICENSE",
     "SECURITY.md",
     "CHANGELOG.md",

package/src/always-visible.ts

@@ -0,0 +1,54 @@
+import type { SkillRecord } from "./types.js";
+
+export interface AlwaysVisibleDiagnostics {
+  missing: string[];
+  duplicates: string[];
+  resolved: string[];
+}
+
+export function normalizeAlwaysVisible(alwaysVisible: string[] | undefined): {
+  allowlist: string[];
+  duplicates: string[];
+} {
+  const duplicates: string[] = [];
+  const seen = new Set<string>();
+  const allowlist: string[] = [];
+
+  for (const entry of alwaysVisible ?? []) {
+    const name = entry.trim();
+    if (!name) continue;
+    if (seen.has(name)) {
+      if (!duplicates.includes(name)) duplicates.push(name);
+      continue;
+    }
+    seen.add(name);
+    allowlist.push(name);
+  }
+
+  return { allowlist, duplicates };
+}
+
+export function evaluateAlwaysVisible(
+  alwaysVisible: string[] | undefined,
+  skills: SkillRecord[],
+): AlwaysVisibleDiagnostics {
+  const { allowlist, duplicates } = normalizeAlwaysVisible(alwaysVisible);
+  const inventory = new Set(skills.map((skill) => skill.name));
+  const missing = allowlist.filter((name) => !inventory.has(name));
+  const resolved = allowlist.filter((name) => inventory.has(name));
+  return { missing, duplicates, resolved };
+}
+
+export function formatAlwaysVisibleDiagnostics(diagnostics: AlwaysVisibleDiagnostics): string[] {
+  const lines: string[] = [];
+  if (diagnostics.resolved.length > 0) {
+    lines.push(`alwaysVisible resolved: ${diagnostics.resolved.join(", ")}`);
+  }
+  if (diagnostics.missing.length > 0) {
+    lines.push(`alwaysVisible missing: ${diagnostics.missing.join(", ")}`);
+  }
+  if (diagnostics.duplicates.length > 0) {
+    lines.push(`alwaysVisible duplicates: ${diagnostics.duplicates.join(", ")}`);
+  }
+  return lines;
+}

package/src/index.ts

@@ -2,6 +2,7 @@ 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 { evaluateAlwaysVisible, formatAlwaysVisibleDiagnostics } from "./always-visible.js";
 import { discoverSkills, findDuplicates } from "./discovery.js";
 import { buildSkillIndex, type SkillIndex } from "./indexer.js";
 import { loadRecommendedSkills } from "./load-skills.js";
@@ -35,6 +36,7 @@ const CANCEL_CHOICE = "Cancel";
 
 export default function piSkillShiori(pi: ExtensionAPI) {
   let index: SkillIndex | undefined;
+  let warnedAlwaysVisibleMissing = new Set<string>();
   const stats = createStats();
 
   async function reload(cwd: string): Promise<SkillIndex> {
@@ -83,7 +85,20 @@ export default function piSkillShiori(pi: ExtensionAPI) {
     const current = await ensureIndex(ctx.cwd);
     if (!current.policy.zeroCatalog.enabled) return;
 
-    const suppression = suppressSkillCatalog(event.systemPrompt);
+    const alwaysVisible = evaluateAlwaysVisible(current.policy.alwaysVisible, current.skills);
+    for (const name of alwaysVisible.missing) {
+      if (warnedAlwaysVisibleMissing.has(name)) continue;
+      warnedAlwaysVisibleMissing.add(name);
+      ctx.ui.notify(
+        `Pi Skill Shiori: always-visible skill not found in inventory: ${name}`,
+        "warning",
+      );
+    }
+
+    const suppression = suppressSkillCatalog(event.systemPrompt, {
+      alwaysVisible: current.policy.alwaysVisible,
+      skills: current.skills,
+    });
     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");
@@ -186,21 +201,26 @@ export default function piSkillShiori(pi: ExtensionAPI) {
     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",
-      );
+      const alwaysVisible = evaluateAlwaysVisible(current.policy.alwaysVisible, current.skills);
+      const doctorLines = [
+        "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"}`,
+        ...formatAlwaysVisibleDiagnostics(alwaysVisible),
+        `retrievalBackend: ${current.retrievalBackend}`,
+        `suppression: ${stats.suppressionStatus}`,
+        `code: ${SHIORI_CODE_MARKER}`,
+        `builtAt: ${current.builtAt}`,
+      ];
+      const hasWarning =
+        duplicates.size > 0 ||
+        stats.suppressionStatus === "failed-pattern-not-found" ||
+        alwaysVisible.missing.length > 0 ||
+        alwaysVisible.duplicates.length > 0;
+      ctx.ui.notify(doctorLines.join("\n"), hasWarning ? "warning" : "info");
     },
   });
 

package/src/policy.ts

@@ -1,6 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { parse } from "yaml";
+import { normalizeAlwaysVisible } from "./always-visible.js";
 import type { ShioriPolicy } from "./types.js";
 
 export const DEFAULT_POLICY: ShioriPolicy = {
@@ -40,7 +41,7 @@ function normalizePolicy(policy: Partial<ShioriPolicy> | undefined): ShioriPolic
       maxCandidates: policy?.candidateInjection?.maxCandidates ?? DEFAULT_POLICY.candidateInjection.maxCandidates,
       minScore: policy?.candidateInjection?.minScore ?? DEFAULT_POLICY.candidateInjection.minScore,
     },
-    alwaysVisible: policy?.alwaysVisible ?? DEFAULT_POLICY.alwaysVisible,
+    alwaysVisible: normalizeAlwaysVisible(policy?.alwaysVisible ?? DEFAULT_POLICY.alwaysVisible).allowlist,
     skills: policy?.skills ?? DEFAULT_POLICY.skills,
   };
 }

package/src/prompt.ts

@@ -1,119 +1,289 @@
-import type { SkillCandidate, SuppressionStatus } from "./types.js";
-
-export interface CatalogSuppressionResult {
-  systemPrompt: string;
-  status: SuppressionStatus;
-}
-
-const COMPACT_DESCRIPTION_LIMIT = 120;
-
-export function formatCandidateInjection(candidates: SkillCandidate[]): string {
-  if (candidates.length === 0) return "";
-  const lines = ["Relevant skills:"];
-  for (const candidate of candidates) {
-    const desc = compactDescription(candidate.skill.description, COMPACT_DESCRIPTION_LIMIT);
-    lines.push(
-      `- ${candidate.skill.name}: ${desc} Reason: ${candidate.why}. Load: shiori_load_skill({ skill: "${candidate.skill.name}" })`,
-    );
-  }
-  return lines.join("\n");
-}
-
-export function formatRecommendKickoffMessage(
-  query: string,
-  loaded: Array<{ candidate: SkillCandidate; content: string }>,
-): string {
-  const lines = [query.trim(), ""];
-
-  if (loaded.length === 0) {
-    lines.push(
-      "---",
-      "Pi Skill Shiori: no matching skills for this task.",
-      "Continue without a dedicated skill, or refine the task description and run /shiori:recommend again.",
-    );
-    return lines.join("\n");
-  }
-
-  const names = loaded.map(({ candidate }) => candidate.skill.name).join(", ");
-  lines.push(
-    "---",
-    `Pi Skill Shiori: pre-loaded ${loaded.length} skill(s): ${names}`,
-    "Follow the skill instructions below and continue with the task above.",
-    "",
-  );
-
-  for (const { candidate, content } of loaded) {
-    lines.push(
-      `### Skill: ${candidate.skill.name}`,
-      `Score: ${candidate.score.toFixed(2)} | Why: ${candidate.why}`,
-      `Path: ${candidate.skill.path}`,
-      "",
-      content.trim(),
-      "",
-    );
-  }
-
-  return lines.join("\n");
-}
-
-export function formatLoadedSkillsSummary(loaded: Array<{ candidate: SkillCandidate; content: string }>): string {
-  if (loaded.length === 0) return "";
-  const lines = [`Pre-loaded ${loaded.length} skill(s):`];
-  for (const { candidate } of loaded) {
-    const desc = compactDescription(candidate.skill.description, COMPACT_DESCRIPTION_LIMIT);
-    lines.push(`- ${candidate.skill.name} (${candidate.score.toFixed(2)}): ${desc}`);
-  }
-  return lines.join("\n");
-}
-
-export function formatCandidateDetail(candidate: SkillCandidate): string {
-  return [
-    candidate.skill.name,
-    `Description: ${candidate.skill.description}`,
-    `Score: ${candidate.score.toFixed(2)}`,
-    `Why: ${candidate.why}`,
-    `Path: ${candidate.skill.path}`,
-    `Load: shiori_load_skill({ skill: "${candidate.skill.name}" })`,
-  ].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,
-  );
-}
+import { normalizeAlwaysVisible } from "./always-visible.js";
+import type { SkillCandidate, SkillRecord, SuppressionStatus } from "./types.js";
+
+export interface CatalogSuppressionResult {
+  systemPrompt: string;
+  status: SuppressionStatus;
+}
+
+export interface SuppressCatalogOptions {
+  alwaysVisible: string[];
+  skills: SkillRecord[];
+}
+
+const COMPACT_DESCRIPTION_LIMIT = 120;
+
+const CATALOG_BOUNDARY_PATTERNS: Array<{ pattern: RegExp; format: "xml" | "markdown" }> = [
+  {
+    pattern:
+      /\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>/,
+    format: "xml",
+  },
+  {
+    pattern: /(^|\r?\n)<available_skills>[\s\S]*?<\/available_skills>/i,
+    format: "xml",
+  },
+  {
+    pattern: /(^|\r?\n)#{2,4}\s*Available skills\b[\s\S]*?(?=\r?\n#{2,4}\s*How to use skills\b)/i,
+    format: "markdown",
+  },
+  {
+    pattern: /(^|\r?\n)#{2,4}\s*Available skills\b[\s\S]*?(?=\r?\n#{2,4}\s*Fallback\b)/i,
+    format: "markdown",
+  },
+];
+
+export function formatCandidateInjection(candidates: SkillCandidate[]): string {
+  if (candidates.length === 0) return "";
+  const lines = ["Relevant skills:"];
+  for (const candidate of candidates) {
+    const desc = compactDescription(candidate.skill.description, COMPACT_DESCRIPTION_LIMIT);
+    lines.push(
+      `- ${candidate.skill.name}: ${desc} Reason: ${candidate.why}. Load: shiori_load_skill({ skill: "${candidate.skill.name}" })`,
+    );
+  }
+  return lines.join("\n");
+}
+
+export function formatRecommendKickoffMessage(
+  query: string,
+  loaded: Array<{ candidate: SkillCandidate; content: string }>,
+): string {
+  const lines = [query.trim(), ""];
+
+  if (loaded.length === 0) {
+    lines.push(
+      "---",
+      "Pi Skill Shiori: no matching skills for this task.",
+      "Continue without a dedicated skill, or refine the task description and run /shiori:recommend again.",
+    );
+    return lines.join("\n");
+  }
+
+  const names = loaded.map(({ candidate }) => candidate.skill.name).join(", ");
+  lines.push(
+    "---",
+    `Pi Skill Shiori: pre-loaded ${loaded.length} skill(s): ${names}`,
+    "Follow the skill instructions below and continue with the task above.",
+    "",
+  );
+
+  for (const { candidate, content } of loaded) {
+    lines.push(
+      `### Skill: ${candidate.skill.name}`,
+      `Score: ${candidate.score.toFixed(2)} | Why: ${candidate.why}`,
+      `Path: ${candidate.skill.path}`,
+      "",
+      content.trim(),
+      "",
+    );
+  }
+
+  return lines.join("\n");
+}
+
+export function formatLoadedSkillsSummary(loaded: Array<{ candidate: SkillCandidate; content: string }>): string {
+  if (loaded.length === 0) return "";
+  const lines = [`Pre-loaded ${loaded.length} skill(s):`];
+  for (const { candidate } of loaded) {
+    const desc = compactDescription(candidate.skill.description, COMPACT_DESCRIPTION_LIMIT);
+    lines.push(`- ${candidate.skill.name} (${candidate.score.toFixed(2)}): ${desc}`);
+  }
+  return lines.join("\n");
+}
+
+export function formatCandidateDetail(candidate: SkillCandidate): string {
+  return [
+    candidate.skill.name,
+    `Description: ${candidate.skill.description}`,
+    `Score: ${candidate.score.toFixed(2)}`,
+    `Why: ${candidate.why}`,
+    `Path: ${candidate.skill.path}`,
+    `Load: shiori_load_skill({ skill: "${candidate.skill.name}" })`,
+  ].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,
+  options?: SuppressCatalogOptions,
+): CatalogSuppressionResult {
+  for (const { pattern, format } of CATALOG_BOUNDARY_PATTERNS) {
+    const match = systemPrompt.match(pattern);
+    if (!match) continue;
+    const replacement = buildFilteredCatalogReplacement(match[0], format, options);
+    return {
+      systemPrompt: systemPrompt.replace(pattern, replacement),
+      status: "suppressed",
+    };
+  }
+
+  if (!hasSkillCatalogSignal(systemPrompt)) {
+    return { systemPrompt, status: "not-needed" };
+  }
+
+  return { systemPrompt, status: "failed-pattern-not-found" };
+}
+
+function buildFilteredCatalogReplacement(
+  catalogSection: string,
+  format: "xml" | "markdown",
+  options?: SuppressCatalogOptions,
+): string {
+  if (!options) {
+    return [
+      "### 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 { allowlist } = normalizeAlwaysVisible(options.alwaysVisible);
+  const allowSet = new Set(allowlist);
+  const skillsByName = new Map(options.skills.map((skill) => [skill.name, skill]));
+
+  if (format === "xml") {
+    return buildFilteredXmlCatalog(catalogSection, allowSet, allowlist, skillsByName);
+  }
+
+  return buildFilteredMarkdownCatalog(catalogSection, allowSet, allowlist, skillsByName);
+}
+
+function buildFilteredXmlCatalog(
+  catalogSection: string,
+  allowSet: Set<string>,
+  allowlist: string[],
+  skillsByName: Map<string, SkillRecord>,
+): string {
+  const prefix = extractXmlCatalogPrefix(catalogSection);
+  const keptBlocks: string[] = [];
+  const keptNames = new Set<string>();
+
+  for (const block of extractXmlSkillBlocks(catalogSection)) {
+    const name = parseXmlSkillName(block);
+    if (!name || !allowSet.has(name)) continue;
+    keptBlocks.push(block);
+    keptNames.add(name);
+  }
+
+  for (const name of allowlist) {
+    if (keptNames.has(name)) continue;
+    const record = skillsByName.get(name);
+    if (!record) continue;
+    keptBlocks.push(formatXmlSkillBlock(record));
+    keptNames.add(name);
+  }
+
+  if (keptBlocks.length === 0) {
+    return buildHiddenCatalogStub();
+  }
+
+  const lines = [...prefix, "<available_skills>"];
+  for (const block of keptBlocks) {
+    lines.push(block);
+  }
+  lines.push("</available_skills>");
+  return lines.join("\n");
+}
+
+function buildFilteredMarkdownCatalog(
+  catalogSection: string,
+  allowSet: Set<string>,
+  allowlist: string[],
+  skillsByName: Map<string, SkillRecord>,
+): string {
+  const headerMatch = catalogSection.match(/(^|\r?\n)(#{2,4}\s*Available skills\b[^\n]*)/i);
+  const header = headerMatch?.[2] ?? "### Available skills";
+  const keptLines: string[] = [];
+  const keptNames = new Set<string>();
+
+  for (const line of catalogSection.split(/\r?\n/)) {
+    const match = line.match(/^\s*[-*]\s+\*\*([^*]+)\*\*:\s*(.*)$/);
+    if (!match) continue;
+    const name = match[1].trim();
+    if (!allowSet.has(name)) continue;
+    keptLines.push(`- **${name}**: ${match[2].trim()}`);
+    keptNames.add(name);
+  }
+
+  for (const name of allowlist) {
+    if (keptNames.has(name)) continue;
+    const record = skillsByName.get(name);
+    if (!record) continue;
+    keptLines.push(`- **${record.name}**: ${compactDescription(record.description, 240)}`);
+    keptNames.add(name);
+  }
+
+  if (keptLines.length === 0) {
+    return buildHiddenCatalogStub();
+  }
+
+  return [`${header}`, "Pi Skill Shiori: only always-visible skills remain in the Skill Catalog.", ...keptLines].join(
+    "\n",
+  );
+}
+
+function buildHiddenCatalogStub(): string {
+  return [
+    "### 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");
+}
+
+function extractXmlCatalogPrefix(catalogSection: string): string[] {
+  const marker = catalogSection.search(/<available_skills>/i);
+  if (marker <= 0) return [];
+  return catalogSection.slice(0, marker).replace(/\r?\n$/, "").split(/\r?\n/).filter(Boolean);
+}
+
+function extractXmlSkillBlocks(catalogSection: string): string[] {
+  return [...catalogSection.matchAll(/<skill>[\s\S]*?<\/skill>/gi)].map((match) => match[0]);
+}
+
+function parseXmlSkillName(block: string): string | undefined {
+  const match = block.match(/<name>([\s\S]*?)<\/name>/i);
+  if (!match) return undefined;
+  return unescapeXml(match[1].trim());
+}
+
+function formatXmlSkillBlock(skill: SkillRecord): string {
+  return [
+    "  <skill>",
+    `    <name>${escapeXml(skill.name)}</name>`,
+    `    <description>${escapeXml(skill.description)}</description>`,
+    `    <location>${escapeXml(skill.path)}</location>`,
+    "  </skill>",
+  ].join("\n");
+}
+
+function escapeXml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+function unescapeXml(value: string): string {
+  return value
+    .replace(/&apos;/g, "'")
+    .replace(/&quot;/g, '"')
+    .replace(/&gt;/g, ">")
+    .replace(/&lt;/g, "<")
+    .replace(/&amp;/g, "&");
+}
+
+function hasSkillCatalogSignal(systemPrompt: string): boolean {
+  return /<\/?available_skills>|The following skills provide specialized instructions|#{2,4}\s*Available skills\b/i.test(
+    systemPrompt,
+  );
+}