pi-skill-shiori 0.1.1 → 0.2.1

package/README.md

@@ -15,7 +15,7 @@ It is built for vaults or projects with many Agent Skills where the default cata
 
 ## 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.
+`0.2.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.
 
 ## Requirements
 
@@ -37,7 +37,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.1.0
+pi install npm:pi-skill-shiori@0.2.1
 ```
 
 Without a version pin:
@@ -51,7 +51,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.1.0
+pi install -l npm:pi-skill-shiori@0.2.1
 ```
 
 Without a version pin:
@@ -65,7 +65,7 @@ Equivalent pinned manual `.pi/settings.json` entry:
 ```json
 {
   "packages": [
-    "npm:pi-skill-shiori@0.1.0"
+    "npm:pi-skill-shiori@0.2.1"
   ]
 }
 ```
@@ -83,7 +83,7 @@ Equivalent unpinned manual `.pi/settings.json` entry:
 ### Global install from GitHub
 
 ```bash
-pi install git:github.com/eiei114/pi-skill-shiori@v0.1.0
+pi install git:github.com/eiei114/pi-skill-shiori@v0.2.1
 ```
 
 Without a tag pin:
@@ -95,7 +95,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.1.0
+pi install -l git:github.com/eiei114/pi-skill-shiori@v0.2.1
 ```
 
 Without a tag pin:
@@ -186,8 +186,9 @@ This writes a generated review file next to `.pi/skill-shiori.yml`. Review it be
 | `/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:recommend <text>` | Pre-load up to 5 matching skills and queue the task for the agent in one shot. Planning phrases (e.g. `計画を立てたい`) return the dev-plan intake template without dumping SKILL bodies. |
+| `/shiori:recommend` | Ask what you need help with, then pre-load matches and queue for the agent (Pi UI input). |
+| `/shiori:recommend --pick <text>` | Recommend skills only (compact list + manual pick UI, no agent turn). |
 | `/shiori:stats` | Show operational counters. |
 
 ## Tool
@@ -278,7 +279,7 @@ npm login
 After publishing, verify the Pi install path:
 
 ```bash
-pi install npm:pi-skill-shiori@0.1.0
+pi install npm:pi-skill-shiori@0.2.1
 pi install npm:pi-skill-shiori
 pi list
 /shiori:doctor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-skill-shiori",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Pi extension that reduces Agent Skill catalog tokens with policy-based skill retrieval and on-demand skill loading.",
   "type": "module",
   "license": "MIT",
@@ -29,7 +29,7 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "build": "tsc --noEmit",
-    "test": "npm run typecheck",
+    "test": "npm run typecheck && tsx --test tests/*.test.mjs",
     "prepublishOnly": "npm test",
     "release:npm:dry": "npm pack --dry-run",
     "release:npm": "npm publish --access public"
@@ -53,6 +53,7 @@
     "@earendil-works/pi-coding-agent": "^0.75.5",
     "@earendil-works/pi-tui": "^0.75.5",
     "@types/node": "^25.9.1",
+    "tsx": "^4.22.4",
     "typebox": "^1.1.38",
     "typescript": "^6.0.3"
   }

package/src/discovery.ts

@@ -1,6 +1,7 @@
 import { readdir, readFile, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
+import { parse as parseYaml } from "yaml";
 import type { SkillRecord } from "./types.js";
 
 const SKILL_FILE = "SKILL.md";
@@ -60,9 +61,29 @@ async function walk(dir: string, result: string[]): Promise<void> {
 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.";
+  let name = basename(dirname(path));
+  let description: string | undefined;
+
+  if (frontmatter?.[1]) {
+    try {
+      const meta = parseYaml(frontmatter[1]) as Record<string, unknown> | null;
+      if (meta && typeof meta === "object") {
+        if (typeof meta.name === "string" && meta.name.trim()) {
+          name = meta.name.trim();
+        }
+        if (typeof meta.description === "string" && meta.description.trim()) {
+          description = meta.description.trim();
+        }
+      }
+    } catch {
+      // Fall back to body text when frontmatter is malformed.
+    }
+  }
+
+  if (!description) {
+    description = firstParagraph(raw) ?? "No description.";
+  }
+
   return {
     name,
     description,
@@ -71,11 +92,6 @@ async function readSkillRecord(path: string, root: string): Promise<SkillRecord>
   };
 }
 
-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---/, "")

package/src/index.ts

@@ -4,20 +4,29 @@ 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 { loadRecommendedSkills } from "./load-skills.js";
+import { formatPlanningKickoffMessage, isPlanningIntent } from "./planning-kickoff.js";
 import { createStats } from "./metrics.js";
 import { getPolicyPath, loadPolicy } from "./policy.js";
-import { formatCandidateInjection, suppressSkillCatalog } from "./prompt.js";
-import { retrieveCandidates } from "./retrieval.js";
+import {
+  formatCandidateDetail,
+  formatCandidateInjection,
+  formatLoadedSkillsSummary,
+  formatRecommendKickoffMessage,
+  suppressSkillCatalog,
+} from "./prompt.js";
+import { retrieveCandidatesExpanded } from "./retrieval-expanded.js";
 import type { SkillRecord } from "./types.js";
 
-interface ShioriLoadDetails {
+interface ShioriLoadDetails {
   skill: string;
   path: string;
   bytes: number;
   loadedAt: string;
-}
-
-const SHIORI_CODE_MARKER = "prompt-boundary-v3";
+}
+
+const SHIORI_CODE_MARKER = "prompt-boundary-v3";
+const RECOMMEND_MAX_CANDIDATES = 5;
 
 export default function piSkillShiori(pi: ExtensionAPI) {
   let index: SkillIndex | undefined;
@@ -39,6 +48,16 @@ export default function piSkillShiori(pi: ExtensionAPI) {
     return index ?? reload(cwd);
   }
 
+  function withRecommendLimits(current: SkillIndex) {
+    return {
+      ...current.policy,
+      candidateInjection: {
+        ...current.policy.candidateInjection,
+        maxCandidates: Math.max(current.policy.candidateInjection.maxCandidates, RECOMMEND_MAX_CANDIDATES),
+      },
+    };
+  }
+
   pi.on("session_start", async (_event, ctx) => {
     await reload(ctx.cwd);
   });
@@ -60,7 +79,7 @@ export default function piSkillShiori(pi: ExtensionAPI) {
       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);
+    const candidates = retrieveCandidatesExpanded(event.prompt, current.skills, current.policy, current);
     if (candidates.length === 0) stats.zeroCandidateCount += 1;
     else stats.candidateHitCount += 1;
 
@@ -72,6 +91,45 @@ export default function piSkillShiori(pi: ExtensionAPI) {
     };
   });
 
+  pi.registerTool({
+    name: "shiori_recommend",
+    label: "Shiori Recommend",
+    description: "Find Agent Skills that match a natural-language task description.",
+    promptSnippet: "Search the skill inventory for skills matching a task description",
+    promptGuidelines: [
+      "Use shiori_recommend when you need to discover which Agent Skills fit a task before loading them.",
+      "shiori_recommend may return multiple pre-loaded skills; follow all relevant ones.",
+    ],
+    parameters: Type.Object({
+      task: Type.String({ description: "Natural-language description of what you want to do" }),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const current = await ensureIndex(ctx.cwd);
+      const policy = withRecommendLimits(current);
+      const candidates = retrieveCandidatesExpanded(params.task, current.skills, policy, current);
+      const loaded = await loadRecommendedSkills(candidates);
+      const summary = formatLoadedSkillsSummary(loaded);
+      const blocks = loaded.map(({ candidate, content }) => ({
+        type: "text" as const,
+        text: `## ${candidate.skill.name}\n\n${content}`,
+      }));
+      return {
+        content: summary
+          ? [{ type: "text", text: summary }, ...blocks]
+          : [{ type: "text", text: "No matching skills for that task." }],
+        details: { query: params.task, matches: candidates.map((c) => c.skill.name) },
+      };
+    },
+    renderResult(result, { expanded }, theme) {
+      const details = result.details as { query?: string; matches?: string[] } | undefined;
+      const names = details?.matches?.join(", ") ?? "none";
+      const collapsed = `${theme.fg("success", "✓ Shiori")} ${theme.bold(names)}`;
+      if (!expanded) return new Text(collapsed, 0, 0);
+      const query = details?.query ? `\n${theme.fg("dim", details.query)}` : "";
+      return new Text(`${collapsed}${query}`, 0, 0);
+    },
+  });
+
   pi.registerTool({
     name: "shiori_load_skill",
     label: "Shiori Load Skill",
@@ -126,10 +184,10 @@ export default function piSkillShiori(pi: ExtensionAPI) {
           `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}`,
+          `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",
       );
@@ -148,16 +206,93 @@ export default function piSkillShiori(pi: ExtensionAPI) {
     },
   });
 
-  pi.registerCommand("shiori:test-query", {
-    description: "Test Pi Skill Shiori candidate retrieval for arbitrary text",
+  pi.registerCommand("shiori:recommend", {
+    description: "Recommend Agent Skills for a natural-language task and queue it for the agent",
     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",
+      const pickOnly = args.trimStart().startsWith("--pick");
+      let query = (pickOnly ? args.replace(/^--pick\s*/, "") : args).trim();
+
+      if (!query) {
+        if (!ctx.hasUI) {
+          ctx.ui.notify(
+            "Provide a task description: /shiori:recommend <what you want to do>",
+            "warning",
+          );
+          return;
+        }
+        const input = await ctx.ui.input(
+          "What do you want help with?",
+          "Describe your task in natural language…",
+        );
+        if (!input?.trim()) {
+          ctx.ui.notify("Recommendation cancelled.", "info");
+          return;
+        }
+        query = input.trim();
+      }
+
+      const policy = withRecommendLimits(current);
+      const candidates = retrieveCandidatesExpanded(query, current.skills, policy, current);
+      const planning = isPlanningIntent(query);
+      const loaded = planning ? [] : await loadRecommendedSkills(candidates);
+      const summary = planning
+        ? candidates.length > 0
+          ? `Matched ${candidates.length} skill(s): ${candidates.map((c) => c.skill.name).join(", ")}`
+          : ""
+        : formatLoadedSkillsSummary(loaded);
+
+      if (summary) {
+        ctx.ui.notify(summary, "info");
+      } else {
+        ctx.ui.notify("No matching skills for that request.", "warning");
+      }
+
+      if (!pickOnly) {
+        const kickoff = isPlanningIntent(query)
+          ? formatPlanningKickoffMessage(query, candidates)
+          : formatRecommendKickoffMessage(query, loaded);
+        pi.sendUserMessage(kickoff);
+        ctx.ui.notify(
+          isPlanningIntent(query)
+            ? "Queued dev-plan intake for the agent."
+            : loaded.length > 0
+              ? `Pre-loaded ${loaded.length} skill(s) and queued task for the agent.`
+              : "Queued task for the agent.",
+          "info",
+        );
+        return;
+      }
+
+      if (candidates.length === 0 || !ctx.hasUI) {
+        return;
+      }
+
+      const choice = await ctx.ui.select("Follow up on a recommendation:", [
+        ...candidates.map((candidate) => candidate.skill.name),
+        "Done",
+      ]);
+      if (!choice || choice === "Done") {
+        return;
+      }
+
+      const selected = candidates.find((candidate) => candidate.skill.name === choice);
+      if (!selected) {
+        return;
+      }
+
+      ctx.ui.notify(formatCandidateDetail(selected), "info");
+
+      const shouldLoad = await ctx.ui.confirm(
+        "Load this skill?",
+        `The agent can call shiori_load_skill({ skill: "${selected.skill.name}" }) to read the full SKILL.md.`,
       );
+      if (shouldLoad) {
+        ctx.ui.notify(
+          `Ask the agent to run: shiori_load_skill({ skill: "${selected.skill.name}" })`,
+          "info",
+        );
+      }
     },
   });
 
@@ -184,14 +319,6 @@ 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`;
@@ -205,7 +332,7 @@ function renderGeneratedPolicy(skills: SkillRecord[]): string {
     "defaults:",
     "  activation: explicit",
     "candidateInjection:",
-    "  maxCandidates: 3",
+    "  maxCandidates: 5",
     "  minScore: 0.62",
     "alwaysVisible:",
     "  - pi-skill-shiori",

package/src/indexer.ts

@@ -24,7 +24,9 @@ export async function buildSkillIndex(cwd: string, skills: SkillRecord[], policy
     await mkdir(cacheDir, { recursive: true });
 
     const db = new sqlite.DatabaseSync(dbPath);
-    db.exec("CREATE VIRTUAL TABLE skill_fts USING fts5(name, description, triggers, path)");
+    db.exec(
+      "CREATE VIRTUAL TABLE skill_fts USING fts5(name, description, triggers, path, tokenize='unicode61 remove_diacritics 2')",
+    );
     const insert = db.prepare("INSERT INTO skill_fts(name, description, triggers, path) VALUES (?, ?, ?, ?)");
     for (const skill of skills) {
       const triggers = [
@@ -69,12 +71,38 @@ export async function buildSkillIndex(cwd: string, skills: SkillRecord[], policy
   }
 }
 
-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 ");
+export function buildFtsQuery(query: string): string {
+  const terms = extractSearchTerms(query);
+  if (terms.length === 0) return "";
+  return terms.map((term) => `${escapeFtsTerm(term)}*`).join(" OR ");
+}
+
+export function extractSearchTerms(query: string): string[] {
+  const terms = new Set<string>();
+  const chunks = query.split(/[^\p{L}\p{N}_-]+/u).filter(Boolean);
+
+  for (const chunk of chunks) {
+    if (chunk.length < 2) continue;
+
+    const isJapanese =
+      /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}]/u.test(chunk) &&
+      !/[A-Za-z]/u.test(chunk);
+
+    if (isJapanese) {
+      const segments = chunk.split(/(?:の|を|に|で|と|が|は|して|から|へ|も|など|まわり)/u);
+      for (const segment of segments) {
+        if (segment.length >= 2) terms.add(segment.toLocaleLowerCase());
+      }
+      if (terms.size === 0) terms.add(chunk.toLocaleLowerCase());
+      continue;
+    }
+
+    terms.add(chunk.toLocaleLowerCase());
+  }
+
+  return [...terms].slice(0, 8);
 }
 
 function escapeFtsTerm(term: string): string {
-  return term.replace(/[^A-Za-z0-9_-]/g, "");
+  return term.replace(/["'*():^]/g, "");
 }

package/src/load-skills.ts

@@ -0,0 +1,16 @@
+import { readFile } from "node:fs/promises";
+import type { SkillCandidate } from "./types.js";
+
+export interface LoadedSkill {
+  candidate: SkillCandidate;
+  content: string;
+}
+
+export async function loadRecommendedSkills(candidates: SkillCandidate[]): Promise<LoadedSkill[]> {
+  const loaded: LoadedSkill[] = [];
+  for (const candidate of candidates) {
+    const content = await readFile(candidate.skill.path, "utf8");
+    loaded.push({ candidate, content });
+  }
+  return loaded;
+}

package/src/planning-kickoff.ts

@@ -0,0 +1,50 @@
+import type { SkillCandidate } from "./types.js";
+
+const PLANNING_INTENT = /計画|プラン|立てたい|planning|開発計画|タスク分解|実装計画/i;
+
+export function isPlanningIntent(query: string): boolean {
+  return PLANNING_INTENT.test(query.trim());
+}
+
+export function formatPlanningKickoffMessage(query: string, candidates: SkillCandidate[]): string {
+  const skillLine =
+    candidates.length > 0
+      ? `参考 skill: ${candidates.map((c) => c.skill.name).join(", ")}（必要なら shiori_load_skill で読む）`
+      : "参考 skill: なし（to-prd / to-issues / grill-me を検討）";
+
+  return [
+    query.trim(),
+    "",
+    "OK。今日やる開発計画の型で進める。",
+    "",
+    "まずこれ埋めて：",
+    "",
+    "```text",
+    "  対象:",
+    "  やりたい変更:",
+    "  使える時間:",
+    "  完了条件:",
+    "  不安点:",
+    "```",
+    "",
+    "未定なら、これだけでOK：",
+    "",
+    "```text",
+    "  対象:",
+    "  変更:",
+    "```",
+    "",
+    "受け取ったら、こう分解する：",
+    "",
+    "1. 現状確認",
+    "2. 最小実装スコープ決定",
+    "3. タスク分解",
+    "4. 実行順",
+    "5. テスト/確認",
+    "6. 今日の完了ライン",
+    "7. 余った時間の追加作業",
+    "",
+    "---",
+    skillLine,
+  ].join("\n");
+}

package/src/prompt.ts

@@ -1,9 +1,5 @@
 import type { SkillCandidate, SuppressionStatus } from "./types.js";
 
-interface CandidateFormatOptions {
-  verbose?: boolean;
-}
-
 export interface CatalogSuppressionResult {
   systemPrompt: string;
   status: SuppressionStatus;
@@ -11,34 +7,83 @@ export interface CatalogSuppressionResult {
 
 const COMPACT_DESCRIPTION_LIMIT = 120;
 
-export function formatCandidateInjection(candidates: SkillCandidate[], options: CandidateFormatOptions = {}): string {
+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);
-    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}" })`,
-      );
-    }
+    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 {
+export function suppressSkillCatalog(systemPrompt: string): CatalogSuppressionResult {
   const replacement = [
     "### Available skills",
     "Normal Skill Catalog hidden by Pi Skill Shiori.",
@@ -46,29 +91,29 @@ export function suppressSkillCatalog(systemPrompt: string): CatalogSuppressionRe
     "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,
-  ];
+  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,
-  );
-}
+  }
+
+  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/query.ts

@@ -0,0 +1,83 @@
+import { extractSearchTerms } from "./indexer.js";
+
+/** Japanese/English aliases to improve natural-language retrieval. */
+const TERM_ALIASES: Record<string, string[]> = {
+  認証: ["auth", "authentication", "login"],
+  ログイン: ["login", "auth"],
+  スキル: ["skill"],
+  ブラウザ: ["browser"],
+  スクレイピング: ["scraping", "scrape"],
+  スクリーンショット: ["screenshot"],
+  ノート: ["note", "vault", "markdown"],
+  検索: ["search"],
+  デバッグ: ["debug", "diagnose"],
+  バグ: ["bug", "debug"],
+  朝: ["morning"],
+  ルーティン: ["routine"],
+  コミット: ["commit", "git"],
+  プッシュ: ["push", "git"],
+  リファクタ: ["refactor"],
+  調査: ["research", "investigate"],
+  論文: ["paper", "research"],
+  投稿: ["post", "tweet"],
+  計画: ["plan", "prd", "planning"],
+  プラン: ["plan", "prd"],
+  設計: ["design", "plan"],
+  タスク: ["task", "issues"],
+  分解: ["breakdown", "issues"],
+};
+
+/** Whole-prompt intents → English queries that match planning skills in descriptions. */
+const INTENT_QUERY_PACKS: Array<{ test: RegExp; queries: string[] }> = [
+  {
+    test: /計画|プラン|立てたい|planning/i,
+    queries: [
+      "to-prd PRD plan",
+      "to-issues breakdown plan",
+      "grill me plan design",
+      "request refactor plan",
+      "to-prd-for-oss plan",
+    ],
+  },
+  {
+    test: /開発計画|今日.*(やる|進める)|タスク分解|実装計画/i,
+    queries: ["to-prd plan", "to-issues breakdown", "refactor plan", "grill me plan"],
+  },
+];
+
+/** Build alternate queries for FTS + token scoring from one natural-language prompt. */
+export function buildRetrievalQueries(query: string): string[] {
+  const trimmed = query.trim();
+  if (!trimmed) return [];
+
+  const queries = new Set<string>([trimmed]);
+  const terms = extractSearchTerms(trimmed);
+  const englishAliases: string[] = [];
+
+  for (const pack of INTENT_QUERY_PACKS) {
+    if (pack.test.test(trimmed)) {
+      for (const intentQuery of pack.queries) {
+        queries.add(intentQuery);
+      }
+    }
+  }
+
+  for (const term of terms) {
+    queries.add(term);
+    for (const alias of TERM_ALIASES[term] ?? []) {
+      englishAliases.push(alias);
+      queries.add(alias);
+      const swapped = terms.map((t) => (t === term ? alias : t)).join(" ");
+      if (swapped.trim()) queries.add(swapped.trim());
+    }
+  }
+
+  if (englishAliases.length > 0) {
+    queries.add(englishAliases.join(" "));
+    if (terms.length > 0) {
+      queries.add([...terms, ...englishAliases].join(" "));
+    }
+  }
+
+  return [...queries];
+}

package/src/retrieval-expanded.ts

@@ -0,0 +1,30 @@
+import { buildRetrievalQueries } from "./query.js";
+import { retrieveCandidates } from "./retrieval.js";
+import type { ShioriPolicy, SkillCandidate, SkillRecord } from "./types.js";
+
+interface RetrievalIndex {
+  search(query: string, limit: number): SkillRecord[];
+}
+
+export function retrieveCandidatesExpanded(
+  query: string,
+  skills: SkillRecord[],
+  policy: ShioriPolicy,
+  index?: RetrievalIndex,
+): SkillCandidate[] {
+  const byName = new Map<string, SkillCandidate>();
+  const max = policy.candidateInjection.maxCandidates;
+
+  for (const variant of buildRetrievalQueries(query)) {
+    for (const candidate of retrieveCandidates(variant, skills, policy, index)) {
+      const previous = byName.get(candidate.skill.name);
+      if (!previous || candidate.score > previous.score) {
+        byName.set(candidate.skill.name, candidate);
+      }
+    }
+  }
+
+  return [...byName.values()]
+    .sort((a, b) => b.score - a.score || a.skill.name.localeCompare(b.skill.name))
+    .slice(0, max);
+}

package/src/retrieval.ts

@@ -22,7 +22,7 @@ export function retrieveCandidates(
   }
 
   const ftsMatches = index?.search(query, policy.candidateInjection.maxCandidates * 4) ?? [];
-  const scoringPool = ftsMatches.length > 0 ? ftsMatches : triggerableSkills;
+  const scoringPool = ftsMatches.length > 0 ? ftsMatches : skills;
   for (const skill of scoringPool) {
     const candidate = evaluateSkill(skill, normalizedQuery, policy, false);
     if (!candidate) continue;