pi-skill-shiori 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to this project will be documented in this file.
 
 This project follows semantic versioning.
 
+## [0.6.0] - 2026-06-29
+
+### Added
+
+- Bounded recommendation reason badges (`[trigger]`, `[description]`, `[low match]`) on recommended skills in auto-inject, `/shiori:recommend`, and `shiori_recommend` surfaces.
+- `Docs/recommendation-surface.md` describing badge vocabulary, a multi-skill example, and how badges relate to Always Visible Skill policy and recommendation metrics.
+- Tests for reason present, absent, low-confidence, and badge formatting.
+
+### Changed
+
+- Candidate summaries use compact badges instead of freeform `Why:` lines in the default Shiori surfaces.
+
+## [0.5.0] - 2026-06-28
+
+### Added
+
+- Vault-wide skill inventory: Shiori indexes skills from project `.pi/skills`, `.agents/skills`, the user-global `~/.pi/agent/skills` root, and optional policy `inventory.roots`.
+- Automatic inventory refresh when skill files change under any indexed root (enabled by default; disable with `inventory.autoRefreshOnChange: false`).
+- `/shiori:doctor` now lists indexed roots with per-root skill counts and auto-refresh status.
+- `/shiori:stats` counters for manual and automatic inventory refreshes.
+- Tests for multi-root discovery, refresh after local changes, and policy-aware retrieval.
+
+### Changed
+
+- `/shiori:reload` rebuilds the vault-wide inventory and SQLite FTS index instead of relying on the session-start snapshot only.
+
 ## [0.4.0] - 2026-06-28
 
 ### Added

package/Docs/recommendation-surface.md

@@ -0,0 +1,62 @@
+# Recommendation surface
+
+This document describes how Pi Skill Shiori surfaces recommended skills and the bounded reason badges shown with each match.
+
+## Reason badges
+
+Shiori attaches a compact reason badge to each recommended skill. The vocabulary is intentionally small:
+
+| Badge | Meaning |
+|---|---|
+| `[trigger]` | A policy `triggers.include` phrase matched the user task. |
+| `[description]` | Skill name/description tokens matched strongly enough to pass `candidateInjection.minScore`. |
+| `[low match]` | The skill passed `minScore` but sits near the threshold; treat as a weaker suggestion. |
+
+When Shiori cannot classify a match, it omits the badge instead of inventing a freeform explanation.
+
+## Where badges appear
+
+- **Auto-inject candidates** in the system prompt (`## Pi Skill Shiori Candidates`)
+- **`/shiori:recommend` review mode** notifications and follow-up picker labels
+- **`shiori_recommend` tool** collapsed result line (badges only, no long reports)
+- **Pre-load summaries** when skills are queued for the agent
+
+Badges are labels, not confidence scores. Numeric scores remain available in expanded detail views when needed.
+
+## Example: multiple surfaced skills
+
+Task: `browser scraping screenshot`
+
+Possible matches:
+
+```text
+Matched 2 skill(s): playwright-cli [trigger], gstack-browse [description]
+```
+
+Auto-inject candidate block:
+
+```text
+## Pi Skill Shiori Candidates
+
+Relevant skills:
+- playwright-cli [trigger]: Browser automation, web scraping, screenshots. Load: shiori_load_skill({ skill: "playwright-cli" })
+- gstack-browse [description]: Headless browser QA for scripted flows. Load: shiori_load_skill({ skill: "gstack-browse" })
+```
+
+A near-threshold match degrades gracefully:
+
+```text
+- notes-helper [low match]: Search markdown notes in the vault. Load: shiori_load_skill({ skill: "notes-helper" })
+```
+
+## Relation to Always Visible Skill
+
+`alwaysVisible` controls which skills stay in the Skill Catalog during Zero-Catalog Mode. Reason badges apply only to **recommended** (`triggerable`) skills surfaced by retrieval — not to always-visible catalog entries.
+
+Always-visible skills may still appear as recommendations when they match a task; their badge explains the retrieval reason, not catalog visibility.
+
+## Relation to recommendation metrics
+
+`/shiori:stats` recommendation feedback records offers, loads, and follow-through by source (`auto-inject`, `command`, `tool`). Metrics do **not** store reason badges or per-reason tallies.
+
+Use badges to understand individual suggestions during a session. Use metrics to see whether recommendations are being loaded after they are offered.

package/README.md

@@ -12,12 +12,13 @@ For maintenance priorities and the phased plan, see [`ROADMAP.md`](ROADMAP.md).
 - **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.
+- **Vault-wide skill inventory**: indexes skills from project and user-global roots, with optional extra roots in policy.
 - **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.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.
+`0.5.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
 
@@ -39,7 +40,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.4.0
+pi install npm:pi-skill-shiori@0.5.0
 ```
 
 Without a version pin:
@@ -53,7 +54,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.4.0
+pi install -l npm:pi-skill-shiori@0.5.0
 ```
 
 Without a version pin:
@@ -67,7 +68,7 @@ Equivalent pinned manual `.pi/settings.json` entry:
 ```json
 {
   "packages": [
-    "npm:pi-skill-shiori@0.4.0"
+    "npm:pi-skill-shiori@0.5.0"
   ]
 }
 ```
@@ -85,7 +86,7 @@ Equivalent unpinned manual `.pi/settings.json` entry:
 ### Global install from GitHub
 
 ```bash
-pi install git:github.com/eiei114/pi-skill-shiori@v0.4.0
+pi install git:github.com/eiei114/pi-skill-shiori@v0.5.0
 ```
 
 Without a tag pin:
@@ -97,7 +98,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.4.0
+pi install -l git:github.com/eiei114/pi-skill-shiori@v0.5.0
 ```
 
 Without a tag pin:
@@ -131,7 +132,38 @@ Or add a relative local path to `.pi/settings.json`:
 }
 ```
 
-> 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.
+> Note: policy/index changes can be refreshed with `/shiori:reload`, and Shiori auto-refreshes the vault-wide inventory when skill files change under indexed roots. Extension code changes still require restarting the Pi process because Node keeps imported extension modules cached.
+
+## Vault-wide skill inventory
+
+Shiori builds a searchable inventory from these roots (in discovery order; first match wins on duplicate skill names):
+
+| Root | Scope |
+|---|---|
+| `<cwd>/.pi/skills` | Project-local Pi skills |
+| `<cwd>/.agents/skills` | Project-local Agent skills |
+| `~/.pi/agent/skills` | User-global Pi agent skills |
+| `inventory.roots` entries | Optional extra roots (relative to `<cwd>` or absolute) |
+
+Refresh behavior:
+
+- **Session start** builds the initial inventory and SQLite FTS index.
+- **Auto-refresh** (default) rescans roots before retrieval when any `SKILL.md` path changes. This is a directory walk only; it rebuilds the FTS index when the fingerprint changes.
+- **Manual refresh** via `/shiori:reload` always rebuilds the inventory and FTS index immediately.
+- Disable auto-refresh when you prefer a fixed snapshot:
+
+```yaml
+inventory:
+  autoRefreshOnChange: false
+  roots:
+    - custom-skills
+```
+
+Cost/latency trade-offs:
+
+- Auto-refresh adds a shallow filesystem walk on each agent turn while enabled. It avoids stale search results after local skill edits without restarting Pi.
+- A full refresh rebuilds the SQLite FTS database and scales with total indexed skills and description length. Large vaults with many roots may prefer `autoRefreshOnChange: false` plus explicit `/shiori:reload` after bulk imports.
+- Search stays description-first and policy-aware: only `triggerable` skills become candidates, with FTS ranking over names, descriptions, and policy triggers.
 
 ## Configure
 
@@ -185,11 +217,11 @@ This writes a generated review file next to `.pi/skill-shiori.yml`. Review it be
 
 | Command | Purpose |
 |---|---|
-| `/shiori:doctor` | Show policy path, inventory count, retrieval backend, suppression status, and code marker. |
+| `/shiori:doctor` | Show policy path, indexed roots, inventory count, retrieval backend, suppression status, and code marker. |
 | `/shiori:bootstrap` | Generate a review draft policy from discovered skill descriptions. |
 | `/shiori:reload` | Ask what to reload, then rebuild Shiori’s skill inventory and optionally ask Pi to reload runtime resources. Code changes may still need full restart. |
 | `/shiori:recommend` | Ask what you need help with, then either pre-load matches and queue the task for the agent or review recommendations only. Planning phrases (e.g. `計画を立てたい`) return the dev-plan intake template without dumping SKILL bodies. |
-| `/shiori:stats` | Show operational counters. |
+| `/shiori:stats` | Show operational counters and a compact recommendation quality summary. |
 
 ## Tool
 
@@ -235,6 +267,59 @@ retrievalBackend: sqlite-fts
 code: prompt-boundary-v3
 ```
 
+## Recommendation reason badges
+
+Recommended skills show compact reason badges so you can see why Shiori surfaced them:
+
+- `[trigger]` — a policy trigger phrase matched
+- `[description]` — skill name/description tokens matched strongly
+- `[low match]` — passed `minScore` but near the threshold
+
+Badges appear in auto-inject candidates, `/shiori:recommend` review mode, pre-load summaries, and the `shiori_recommend` tool line. Unclassified matches omit the badge instead of showing a long explanation.
+
+Example with multiple surfaced skills:
+
+```text
+Matched 2 skill(s): playwright-cli [trigger], gstack-browse [description]
+```
+
+See [`Docs/recommendation-surface.md`](Docs/recommendation-surface.md) for how badges relate to Always Visible Skill policy and recommendation feedback metrics.
+
+## Recommendation feedback metrics
+
+`/shiori:stats` includes session-local recommendation feedback so operators can tune trigger rules from real outcomes instead of guesswork.
+
+Recorded (bounded, in-memory for the current Pi session):
+
+- recommendation offers and candidate slot counts per source (`auto-inject`, `command`, `tool`)
+- load follow-through when recommended skills are pre-loaded or later loaded via `shiori_load_skill`
+- abandoned recommendation flows (candidates shown but not loaded, e.g. review-only mode)
+- zero-candidate queries (obvious misses)
+- per-skill offered/loaded tallies (up to 50 skill names, oldest entries dropped first)
+
+Not recorded:
+
+- user prompts, task descriptions, or transcript bodies
+- skill `SKILL.md` contents
+- filesystem paths beyond skill names already visible in policy/inventory
+
+Retention boundary:
+
+- counters reset when the Pi session ends
+- no disk persistence or cross-session analytics in this slice
+- inspect the compact summary at the top of `/shiori:stats`, with full JSON below
+
+Example summary line:
+
+```text
+Recommendation feedback (session-local, no prompts stored)
+offers: 4 | candidate slots: 7 | loaded: 3
+abandoned: 1 | zero-candidate queries: 2 | follow-through: 42.9%
+auto-inject: offers=2, loaded=1, zeroHits=1
+command: offers=1, loaded=2, zeroHits=1
+top skills: auth-helper(1/2), deploy-kit(1/1)
+```
+
 ## Development
 
 ```bash
@@ -281,7 +366,7 @@ npm login
 After publishing, verify the Pi install path:
 
 ```bash
-pi install npm:pi-skill-shiori@0.4.0
+pi install npm:pi-skill-shiori@0.5.0
 pi install npm:pi-skill-shiori
 pi list
 /shiori:doctor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-skill-shiori",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Pi extension that reduces Agent Skill catalog tokens with policy-based skill retrieval and on-demand skill loading.",
   "type": "module",
   "license": "MIT",
@@ -27,6 +27,7 @@
     "LICENSE",
     "SECURITY.md",
     "CHANGELOG.md",
+    "Docs",
     "src"
   ],
   "scripts": {

package/src/discovery.ts

@@ -1,18 +1,42 @@
 import { readdir, readFile, stat } from "node:fs/promises";
 import { homedir } from "node:os";
-import { basename, dirname, join, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { parse as parseYaml } from "yaml";
-import type { SkillRecord } from "./types.js";
+import type { ShioriPolicy, SkillRecord } from "./types.js";
 
 const SKILL_FILE = "SKILL.md";
 
-export async function discoverSkills(cwd: string): Promise<SkillRecord[]> {
+/** Project-local skill roots scanned on every vault-wide inventory build. */
+export const VAULT_LOCAL_SKILL_ROOT_SEGMENTS = [".pi/skills", ".agents/skills"] as const;
+
+/** User-global Pi agent skills root (lowest discovery precedence). */
+export const GLOBAL_AGENT_SKILL_ROOT_SEGMENTS = ".pi/agent/skills";
+
+export function resolveVaultSkillRoots(cwd: string, policy?: Pick<ShioriPolicy, "inventory">): string[] {
   const roots = [
     join(cwd, ".pi", "skills"),
     join(cwd, ".agents", "skills"),
     join(homedir(), ".pi", "agent", "skills"),
   ];
 
+  for (const entry of policy?.inventory?.roots ?? []) {
+    const trimmed = entry.trim();
+    if (!trimmed) continue;
+    const resolved = isAbsolute(trimmed) ? resolve(trimmed) : resolve(cwd, trimmed);
+    if (!roots.includes(resolved)) {
+      roots.push(resolved);
+    }
+  }
+
+  return roots;
+}
+
+export async function discoverSkills(cwd: string, policy?: ShioriPolicy): Promise<SkillRecord[]> {
+  const roots = resolveVaultSkillRoots(cwd, policy);
+  return discoverSkillsFromRoots(roots);
+}
+
+export async function discoverSkillsFromRoots(roots: string[]): Promise<SkillRecord[]> {
   const records: SkillRecord[] = [];
   for (const root of roots) {
     const files = await findSkillFiles(root);
@@ -23,6 +47,15 @@ export async function discoverSkills(cwd: string): Promise<SkillRecord[]> {
   return dedupeByDiscoveryOrder(records);
 }
 
+export async function computeInventoryFingerprint(roots: string[]): Promise<string> {
+  const parts: string[] = [];
+  for (const root of roots) {
+    const files = await findSkillFiles(root);
+    parts.push(`${root}:${files.sort().join(",")}`);
+  }
+  return parts.join("|");
+}
+
 export function findDuplicates(records: SkillRecord[]): Map<string, SkillRecord[]> {
   const groups = new Map<string, SkillRecord[]>();
   for (const record of records) {

package/src/index.ts

@@ -3,11 +3,12 @@ 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 { findDuplicates, formatInventoryRoots, isAutoRefreshEnabled, isInventoryStale, refreshSkillInventory } from "./inventory.js";
+import type { SkillIndex } from "./indexer.js";
 import { loadRecommendedSkills } from "./load-skills.js";
 import { formatPlanningKickoffMessage, isPlanningIntent } from "./planning-kickoff.js";
 import { createStats } from "./metrics.js";
+import { createRecommendationFeedback } from "./recommendation-feedback.js";
 import { getPolicyPath, loadPolicy } from "./policy.js";
 import {
   formatCandidateDetail,
@@ -16,6 +17,7 @@ import {
   formatRecommendKickoffMessage,
   suppressSkillCatalog,
 } from "./prompt.js";
+import { formatReasonBadgeSuffix } from "./recommendation-reason.js";
 import { retrieveCandidatesExpanded } from "./retrieval-expanded.js";
 import type { SkillRecord } from "./types.js";
 
@@ -36,23 +38,43 @@ const CANCEL_CHOICE = "Cancel";
 
 export default function piSkillShiori(pi: ExtensionAPI) {
   let index: SkillIndex | undefined;
+  let inventoryFingerprint: string | undefined;
+  let inventoryRoots: string[] = [];
   let warnedAlwaysVisibleMissing = new Set<string>();
   const stats = createStats();
+  const recommendationFeedback = createRecommendationFeedback();
 
   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;
+    const policy = await loadPolicy(cwd);
+    const inventory = await refreshSkillInventory(cwd, policy, index);
+    index = inventory.index;
+    inventoryFingerprint = inventory.fingerprint;
+    inventoryRoots = inventory.roots;
+    stats.inventoryCount = index.skills.length;
+    stats.duplicateCount = findDuplicates(index.skills).size;
     stats.lastReloadAt = index.builtAt;
     stats.retrievalBackend = index.retrievalBackend;
     stats.suppressionStatus = policy.zeroCatalog.enabled ? "not-needed" : "disabled";
+    stats.inventoryRefreshCount += 1;
     return index;
   }
 
   async function ensureIndex(cwd: string): Promise<SkillIndex> {
-    return index ?? reload(cwd);
+    if (!index || !inventoryFingerprint) {
+      return reload(cwd);
+    }
+
+    const policy = await loadPolicy(cwd);
+    if (!isAutoRefreshEnabled(policy)) {
+      return index;
+    }
+
+    if (await isInventoryStale(cwd, policy, inventoryFingerprint)) {
+      stats.inventoryAutoRefreshCount += 1;
+      return reload(cwd);
+    }
+
+    return index;
   }
 
   function withRecommendLimits(current: SkillIndex) {
@@ -72,6 +94,8 @@ export default function piSkillShiori(pi: ExtensionAPI) {
   pi.on("session_shutdown", () => {
     index?.close?.();
     index = undefined;
+    inventoryFingerprint = undefined;
+    inventoryRoots = [];
   });
 
   pi.on("input", async (event) => {
@@ -105,8 +129,16 @@ export default function piSkillShiori(pi: ExtensionAPI) {
     }
 
     const candidates = retrieveCandidatesExpanded(event.prompt, current.skills, current.policy, current);
-    if (candidates.length === 0) stats.zeroCandidateCount += 1;
-    else stats.candidateHitCount += 1;
+    if (candidates.length === 0) {
+      stats.zeroCandidateCount += 1;
+      recommendationFeedback.recordZeroCandidates("auto-inject");
+    } else {
+      stats.candidateHitCount += 1;
+      recommendationFeedback.recordRecommendation(
+        "auto-inject",
+        candidates.map((candidate) => candidate.skill.name),
+      );
+    }
 
     const injection = formatCandidateInjection(candidates);
     const candidateSection = injection ? `\n\n## Pi Skill Shiori Candidates\n\n${injection}\n` : "";
@@ -132,7 +164,13 @@ export default function piSkillShiori(pi: ExtensionAPI) {
       const current = await ensureIndex(ctx.cwd);
       const policy = withRecommendLimits(current);
       const candidates = retrieveCandidatesExpanded(params.task, current.skills, policy, current);
+      const candidateNames = candidates.map((candidate) => candidate.skill.name);
       const loaded = await loadRecommendedSkills(candidates);
+      recommendationFeedback.recordRecommendation(
+        "tool",
+        candidateNames,
+        loaded.map((entry) => entry.candidate.skill.name),
+      );
       const summary = formatLoadedSkillsSummary(loaded);
       const blocks = loaded.map(({ candidate, content }) => ({
         type: "text" as const,
@@ -142,11 +180,16 @@ export default function piSkillShiori(pi: ExtensionAPI) {
         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) },
+        details: {
+          query: params.task,
+          matches: candidates.map((c) => `${c.skill.name}${formatReasonBadgeSuffix(c.reason)}`),
+        },
       };
     },
     renderResult(result, { expanded }, theme) {
-      const details = result.details as { query?: string; matches?: string[] } | undefined;
+      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);
@@ -172,6 +215,7 @@ export default function piSkillShiori(pi: ExtensionAPI) {
       if (!record) throw new Error(`Skill not found: ${params.skill}`);
       const content = await readFile(record.path, "utf8");
       stats.loadedSkillCount += 1;
+      recommendationFeedback.recordSkillLoaded(record.name);
       const details: ShioriLoadDetails = {
         skill: record.name,
         path: record.path,
@@ -210,6 +254,9 @@ export default function piSkillShiori(pi: ExtensionAPI) {
         `duplicates: ${duplicates.size}`,
         `alwaysVisible: ${current.policy.alwaysVisible.join(", ") || "none"}`,
         ...formatAlwaysVisibleDiagnostics(alwaysVisible),
+        "inventoryRoots:",
+        ...formatInventoryRoots(inventoryRoots, current.skills).map((line) => `  - ${line}`),
+        `autoRefreshOnChange: ${isAutoRefreshEnabled(current.policy) ? "enabled" : "disabled"}`,
         `retrievalBackend: ${current.retrievalBackend}`,
         `suppression: ${stats.suppressionStatus}`,
         `code: ${SHIORI_CODE_MARKER}`,
@@ -281,12 +328,18 @@ export default function piSkillShiori(pi: ExtensionAPI) {
 
       const policy = withRecommendLimits(current);
       const candidates = retrieveCandidatesExpanded(query, current.skills, policy, current);
+      const candidateNames = candidates.map((candidate) => candidate.skill.name);
       const planning = isPlanningIntent(query);
       const reviewOnly = action === RECOMMEND_REVIEW_ONLY;
       const loaded = planning || reviewOnly ? [] : await loadRecommendedSkills(candidates);
+      recommendationFeedback.recordRecommendation(
+        "command",
+        candidateNames,
+        loaded.map((entry) => entry.candidate.skill.name),
+      );
       const summary = planning || reviewOnly
         ? candidates.length > 0
-          ? `Matched ${candidates.length} skill(s): ${candidates.map((c) => c.skill.name).join(", ")}`
+          ? `Matched ${candidates.length} skill(s): ${candidates.map((c) => `${c.skill.name}${formatReasonBadgeSuffix(c.reason)}`).join(", ")}`
           : ""
         : formatLoadedSkillsSummary(loaded);
 
@@ -317,14 +370,16 @@ export default function piSkillShiori(pi: ExtensionAPI) {
       }
 
       const choice = await ctx.ui.select("Follow up on a recommendation:", [
-        ...candidates.map((candidate) => candidate.skill.name),
+        ...candidates.map((candidate) => `${candidate.skill.name}${formatReasonBadgeSuffix(candidate.reason)}`),
         "Done",
       ]);
       if (!choice || choice === "Done") {
         return;
       }
 
-      const selected = candidates.find((candidate) => candidate.skill.name === choice);
+      const selected = candidates.find(
+        (candidate) => choice === `${candidate.skill.name}${formatReasonBadgeSuffix(candidate.reason)}`,
+      );
       if (!selected) {
         return;
       }
@@ -345,9 +400,20 @@ export default function piSkillShiori(pi: ExtensionAPI) {
   });
 
   pi.registerCommand("shiori:stats", {
-    description: "Show Pi Skill Shiori operational counters",
+    description: "Show Pi Skill Shiori operational counters and recommendation feedback",
     handler: async (_args, ctx) => {
-      ctx.ui.notify(JSON.stringify(stats, null, 2), "info");
+      const payload = {
+        ...stats,
+        recommendationFeedback: recommendationFeedback.summarize(),
+      };
+      ctx.ui.notify(
+        [
+          recommendationFeedback.formatSummary(),
+          "",
+          JSON.stringify(payload, null, 2),
+        ].join("\n"),
+        "info",
+      );
     },
   });
 

package/src/inventory.ts

@@ -0,0 +1,58 @@
+import {
+  computeInventoryFingerprint,
+  discoverSkillsFromRoots,
+  findDuplicates,
+  resolveVaultSkillRoots,
+} from "./discovery.js";
+import { buildSkillIndex, type SkillIndex } from "./indexer.js";
+import type { ShioriPolicy } from "./types.js";
+
+export interface SkillInventory {
+  index: SkillIndex;
+  roots: string[];
+  fingerprint: string;
+}
+
+export function isAutoRefreshEnabled(policy: ShioriPolicy): boolean {
+  return policy.inventory?.autoRefreshOnChange !== false;
+}
+
+export async function refreshSkillInventory(
+  cwd: string,
+  policy: ShioriPolicy,
+  previous?: SkillIndex,
+): Promise<SkillInventory> {
+  previous?.close?.();
+  const roots = resolveVaultSkillRoots(cwd, policy);
+  const [skills, fingerprint] = await Promise.all([
+    discoverSkillsFromRoots(roots),
+    computeInventoryFingerprint(roots),
+  ]);
+  const index = await buildSkillIndex(cwd, skills, policy);
+  return { index, roots, fingerprint };
+}
+
+export async function isInventoryStale(
+  cwd: string,
+  policy: ShioriPolicy,
+  fingerprint: string,
+): Promise<boolean> {
+  const roots = resolveVaultSkillRoots(cwd, policy);
+  const current = await computeInventoryFingerprint(roots);
+  return current !== fingerprint;
+}
+
+export function countSkillsByRoot(skills: SkillIndex["skills"], roots: string[]): Map<string, number> {
+  const counts = new Map(roots.map((root) => [root, 0]));
+  for (const skill of skills) {
+    counts.set(skill.source, (counts.get(skill.source) ?? 0) + 1);
+  }
+  return counts;
+}
+
+export function formatInventoryRoots(roots: string[], skills: SkillIndex["skills"]): string[] {
+  const counts = countSkillsByRoot(skills, roots);
+  return roots.map((root) => `${root} (${counts.get(root) ?? 0} skills)`);
+}
+
+export { findDuplicates };

package/src/metrics.ts

@@ -10,5 +10,7 @@ export function createStats(): ShioriStats {
     explicitInvocationCount: 0,
     retrievalBackend: "token-match",
     suppressionStatus: "disabled",
+    inventoryRefreshCount: 0,
+    inventoryAutoRefreshCount: 0,
   };
 }

package/src/policy.ts

@@ -30,6 +30,10 @@ export async function loadPolicy(cwd: string): Promise<ShioriPolicy> {
 }
 
 function normalizePolicy(policy: Partial<ShioriPolicy> | undefined): ShioriPolicy {
+  const extraRoots = (policy?.inventory?.roots ?? [])
+    .map((root) => (typeof root === "string" ? root.trim() : ""))
+    .filter(Boolean);
+
   return {
     zeroCatalog: {
       enabled: policy?.zeroCatalog?.enabled ?? DEFAULT_POLICY.zeroCatalog.enabled,
@@ -42,6 +46,13 @@ function normalizePolicy(policy: Partial<ShioriPolicy> | undefined): ShioriPolic
       minScore: policy?.candidateInjection?.minScore ?? DEFAULT_POLICY.candidateInjection.minScore,
     },
     alwaysVisible: normalizeAlwaysVisible(policy?.alwaysVisible ?? DEFAULT_POLICY.alwaysVisible).allowlist,
+    inventory:
+      extraRoots.length > 0 || policy?.inventory?.autoRefreshOnChange === false
+        ? {
+            roots: extraRoots.length > 0 ? extraRoots : undefined,
+            autoRefreshOnChange: policy?.inventory?.autoRefreshOnChange,
+          }
+        : undefined,
     skills: policy?.skills ?? DEFAULT_POLICY.skills,
   };
 }

package/src/prompt.ts

@@ -1,4 +1,5 @@
 import { normalizeAlwaysVisible } from "./always-visible.js";
+import { formatReasonBadgeSuffix } from "./recommendation-reason.js";
 import type { SkillCandidate, SkillRecord, SuppressionStatus } from "./types.js";
 
 export interface CatalogSuppressionResult {
@@ -39,7 +40,7 @@ export function formatCandidateInjection(candidates: SkillCandidate[]): string {
   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}" })`,
+      `- ${candidate.skill.name}${formatReasonBadgeSuffix(candidate.reason)}: ${desc} Load: shiori_load_skill({ skill: "${candidate.skill.name}" })`,
     );
   }
   return lines.join("\n");
@@ -70,8 +71,8 @@ export function formatRecommendKickoffMessage(
 
   for (const { candidate, content } of loaded) {
     lines.push(
-      `### Skill: ${candidate.skill.name}`,
-      `Score: ${candidate.score.toFixed(2)} | Why: ${candidate.why}`,
+      `### Skill: ${candidate.skill.name}${formatReasonBadgeSuffix(candidate.reason)}`,
+      `Score: ${candidate.score.toFixed(2)}`,
       `Path: ${candidate.skill.path}`,
       "",
       content.trim(),
@@ -87,17 +88,16 @@ export function formatLoadedSkillsSummary(loaded: Array<{ candidate: SkillCandid
   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}`);
+    lines.push(`- ${candidate.skill.name}${formatReasonBadgeSuffix(candidate.reason)} (${candidate.score.toFixed(2)}): ${desc}`);
   }
   return lines.join("\n");
 }
 
 export function formatCandidateDetail(candidate: SkillCandidate): string {
   return [
-    candidate.skill.name,
+    `${candidate.skill.name}${formatReasonBadgeSuffix(candidate.reason)}`,
     `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");

package/src/query.ts

@@ -28,10 +28,19 @@ const TERM_ALIASES: Record<string, string[]> = {
 };
 
 /** Whole-prompt intents → English queries that match planning skills in descriptions. */
-const INTENT_QUERY_PACKS: Array<{ test: RegExp; queries: string[] }> = [
-  {
-    test: /計画|プラン|立てたい|planning/i,
-    queries: [
+const INTENT_QUERY_PACKS: Array<{ test: RegExp; queries: string[] }> = [
+  {
+    test:
+      /\bx\s+(?:api|data|export|follower|monitor|post|search|social|timeline|tweet)\b|\b(?:twitter|tweet|timeline|follower)\b|social(?:\s+media)?/i,
+    queries: [
+      "tweet search social media data",
+      "twitter timeline follower export",
+      "x api tweet monitor",
+    ],
+  },
+  {
+    test: /計画|プラン|立てたい|planning/i,
+    queries: [
       "to-prd PRD plan",
       "to-issues breakdown plan",
       "grill me plan design",

package/src/recommendation-feedback.ts

@@ -0,0 +1,177 @@
+export type RecommendationSource = "auto-inject" | "command" | "tool";
+
+export interface SourceFeedbackCounts {
+  offers: number;
+  candidateSlots: number;
+  loaded: number;
+  zeroHits: number;
+}
+
+export interface SkillFeedbackCounts {
+  offered: number;
+  loaded: number;
+}
+
+export interface RecommendationFeedbackSummary {
+  totalOffers: number;
+  totalCandidateSlots: number;
+  totalLoaded: number;
+  totalAbandoned: number;
+  zeroCandidateQueries: number;
+  followThroughRate: number | null;
+  bySource: Record<RecommendationSource, SourceFeedbackCounts>;
+  topSkills: Array<{ name: string; offered: number; loaded: number }>;
+  retention: {
+    maxSkillEntries: number;
+    skillEntries: number;
+  };
+}
+
+const SOURCES: RecommendationSource[] = ["auto-inject", "command", "tool"];
+const MAX_SKILL_ENTRIES = 50;
+
+function emptySourceCounts(): SourceFeedbackCounts {
+  return { offers: 0, candidateSlots: 0, loaded: 0, zeroHits: 0 };
+}
+
+function emptyBySource(): Record<RecommendationSource, SourceFeedbackCounts> {
+  return {
+    "auto-inject": emptySourceCounts(),
+    command: emptySourceCounts(),
+    tool: emptySourceCounts(),
+  };
+}
+
+export interface RecommendationFeedback {
+  recordRecommendation(source: RecommendationSource, candidates: string[], loaded?: string[]): void;
+  recordZeroCandidates(source: RecommendationSource): void;
+  recordSkillLoaded(skillName: string): void;
+  summarize(): RecommendationFeedbackSummary;
+  formatSummary(): string;
+}
+
+export function createRecommendationFeedback(): RecommendationFeedback {
+  const bySource = emptyBySource();
+  const bySkill = new Map<string, SkillFeedbackCounts>();
+  const recentAutoInjectCandidates = new Set<string>();
+
+  let totalOffers = 0;
+  let totalCandidateSlots = 0;
+  let totalLoaded = 0;
+  let totalAbandoned = 0;
+  let zeroCandidateQueries = 0;
+
+  function bumpSkill(name: string, field: "offered" | "loaded"): void {
+    const current = bySkill.get(name) ?? { offered: 0, loaded: 0 };
+    current[field] += 1;
+    bySkill.set(name, current);
+    while (bySkill.size > MAX_SKILL_ENTRIES) {
+      const oldest = bySkill.keys().next().value;
+      if (oldest === undefined) break;
+      bySkill.delete(oldest);
+    }
+  }
+
+  function recordLoadedSkills(source: RecommendationSource, loaded: string[]): void {
+    for (const name of loaded) {
+      bumpSkill(name, "loaded");
+      bySource[source].loaded += 1;
+      totalLoaded += 1;
+      recentAutoInjectCandidates.delete(name);
+    }
+  }
+
+  return {
+    recordRecommendation(source, candidates, loaded = []) {
+      if (candidates.length === 0) {
+        this.recordZeroCandidates(source);
+        return;
+      }
+
+      totalOffers += 1;
+      totalCandidateSlots += candidates.length;
+      const sourceCounts = bySource[source];
+      sourceCounts.offers += 1;
+      sourceCounts.candidateSlots += candidates.length;
+
+      for (const name of candidates) {
+        bumpSkill(name, "offered");
+        if (source === "auto-inject") {
+          recentAutoInjectCandidates.add(name);
+        }
+      }
+
+      if (loaded.length > 0) {
+        recordLoadedSkills(source, loaded);
+      } else if (source !== "auto-inject") {
+        totalAbandoned += 1;
+      }
+    },
+
+    recordZeroCandidates(source) {
+      zeroCandidateQueries += 1;
+      bySource[source].zeroHits += 1;
+    },
+
+    recordSkillLoaded(skillName) {
+      if (!recentAutoInjectCandidates.has(skillName)) {
+        return;
+      }
+      recordLoadedSkills("auto-inject", [skillName]);
+    },
+
+    summarize() {
+      const followThroughRate =
+        totalCandidateSlots > 0 ? Number((totalLoaded / totalCandidateSlots).toFixed(3)) : null;
+
+      const topSkills = [...bySkill.entries()]
+        .map(([name, counts]) => ({ name, ...counts }))
+        .sort((a, b) => b.offered - a.offered || a.name.localeCompare(b.name))
+        .slice(0, 10);
+
+      return {
+        totalOffers,
+        totalCandidateSlots,
+        totalLoaded,
+        totalAbandoned,
+        zeroCandidateQueries,
+        followThroughRate,
+        bySource,
+        topSkills,
+        retention: {
+          maxSkillEntries: MAX_SKILL_ENTRIES,
+          skillEntries: bySkill.size,
+        },
+      };
+    },
+
+    formatSummary() {
+      const summary = this.summarize();
+      const rate =
+        summary.followThroughRate === null ? "n/a" : `${(summary.followThroughRate * 100).toFixed(1)}%`;
+      const lines = [
+        "Recommendation feedback (session-local, no prompts stored)",
+        `offers: ${summary.totalOffers} | candidate slots: ${summary.totalCandidateSlots} | loaded: ${summary.totalLoaded}`,
+        `abandoned: ${summary.totalAbandoned} | zero-candidate queries: ${summary.zeroCandidateQueries} | follow-through: ${rate}`,
+      ];
+
+      for (const source of SOURCES) {
+        const counts = summary.bySource[source];
+        if (counts.offers === 0 && counts.zeroHits === 0) continue;
+        lines.push(
+          `${source}: offers=${counts.offers}, loaded=${counts.loaded}, zeroHits=${counts.zeroHits}`,
+        );
+      }
+
+      if (summary.topSkills.length > 0) {
+        const skillLine = summary.topSkills
+          .slice(0, 5)
+          .map((skill) => `${skill.name}(${skill.loaded}/${skill.offered})`)
+          .join(", ");
+        lines.push(`top skills: ${skillLine}`);
+      }
+
+      return lines.join("\n");
+    },
+  };
+}

package/src/recommendation-reason.ts

@@ -0,0 +1,43 @@
+import type { RecommendationReasonKind, SkillCandidate } from "./types.js";
+
+/** Score within this margin above minScore is treated as low-confidence. */
+export const LOW_CONFIDENCE_MARGIN = 0.08;
+
+export const RECOMMENDATION_REASON_LABELS: Record<RecommendationReasonKind, string> = {
+  trigger: "trigger",
+  description: "description",
+  "low-confidence": "low match",
+};
+
+export type RecommendationMatchSource = "trigger" | "description";
+
+export function classifyRecommendationReason(
+  source: RecommendationMatchSource,
+  score: number,
+  minScore: number,
+): RecommendationReasonKind {
+  if (source === "trigger") return "trigger";
+  return score < minScore + LOW_CONFIDENCE_MARGIN ? "low-confidence" : "description";
+}
+
+export function formatReasonBadge(reason: RecommendationReasonKind | null | undefined): string {
+  if (!reason) return "";
+  const label = RECOMMENDATION_REASON_LABELS[reason];
+  return label ? `[${label}]` : "";
+}
+
+export function formatReasonBadgeSuffix(reason: RecommendationReasonKind | null | undefined): string {
+  const badge = formatReasonBadge(reason);
+  return badge ? ` ${badge}` : "";
+}
+
+export function attachRecommendationReason(
+  candidate: Omit<SkillCandidate, "reason">,
+  source: RecommendationMatchSource,
+  minScore: number,
+): SkillCandidate {
+  return {
+    ...candidate,
+    reason: classifyRecommendationReason(source, candidate.score, minScore),
+  };
+}

package/src/retrieval.ts

@@ -1,3 +1,4 @@
+import { attachRecommendationReason } from "./recommendation-reason.js";
 import type { ShioriPolicy, SkillCandidate, SkillRecord } from "./types.js";
 
 interface RetrievalIndex {
@@ -51,22 +52,30 @@ function evaluateSkill(
   const includes = skillPolicy?.triggers?.include ?? [];
   const matchedInclude = includes.find((trigger) => includesNormalized(normalizedQuery, trigger));
   if (matchedInclude) {
-    return {
-      skill,
-      score: 0.95,
-      why: `matched trigger "${matchedInclude}"`,
-    };
+    return attachRecommendationReason(
+      {
+        skill,
+        score: 0.95,
+        why: `matched trigger "${matchedInclude}"`,
+      },
+      "trigger",
+      policy.candidateInjection.minScore,
+    );
   }
   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",
-  };
+  return attachRecommendationReason(
+    {
+      skill,
+      score: tokenScore,
+      why: "matched skill description",
+    },
+    "description",
+    policy.candidateInjection.minScore,
+  );
 }
 
 function normalize(input: string): string {

package/src/types.ts

@@ -14,6 +14,12 @@ export interface ShioriPolicy {
     minScore: number;
   };
   alwaysVisible: string[];
+  inventory?: {
+    /** Extra skill roots relative to cwd or absolute paths. */
+    roots?: string[];
+    /** Rebuild the index when skill files change under any root (default: true). */
+    autoRefreshOnChange?: boolean;
+  };
   skills: Record<string, SkillPolicy>;
 }
 
@@ -33,10 +39,13 @@ export interface SkillRecord {
   source: string;
 }
 
+export type RecommendationReasonKind = "trigger" | "description" | "low-confidence";
+
 export interface SkillCandidate {
   skill: SkillRecord;
   score: number;
   why: string;
+  reason: RecommendationReasonKind | null;
 }
 
 export interface ShioriStats {
@@ -49,4 +58,6 @@ export interface ShioriStats {
   retrievalBackend: RetrievalBackend;
   suppressionStatus: SuppressionStatus;
   lastReloadAt?: string;
+  inventoryRefreshCount: number;
+  inventoryAutoRefreshCount: number;
 }