pi-nested-skills 0.1.0

package/README.md

@@ -0,0 +1,73 @@
+# pi-nested-skills
+
+A Pi extension that discovers skills recursively and provides convenient aliases for nested skill directories.
+
+[中文文档](./README.zh-CN.md)
+
+## Features
+
+- Recursively discovers `SKILL.md` files below one or more configurable skill roots.
+- Supports package-style aliases such as `/development:code-reviewer` and `/design:icons.favicon`.
+- Keeps Pi's native skill loader responsible for frontmatter validation and skill-body expansion; this package does not duplicate `read` compatibility or skill expansion.
+- Extends the native slash-command completion list and preserves built-in Pi command suggestions.
+- Provides `/skills` to list discovered aliases.
+- Provides `/config:nested-skills` to edit the skill roots through the normal TUI input; use `reset` for the default `skills` root.
+- Contributes discovered skill files through Pi's `resources_discover` event.
+- Uses `pi-extensions-i18n` for all user-visible messages.
+
+## Install
+
+```bash
+pi install npm:pi-nested-skills
+```
+
+Then run `/reload` in Pi.
+
+## Configure skill roots
+
+Start from [`config.example.json`](./config.example.json) and write it to:
+
+```text
+<pi-agent-dir>/extensions/pi-nested-skills/config.json
+```
+
+`<pi-agent-dir>` is Pi's configured agent directory, normally `~/.pi/agent`. The `PI_CODING_AGENT_DIR` override is respected by Pi and by this extension.
+
+```json
+{
+  "skillRoots": [
+    "~/shared-skills",
+    "skills"
+  ]
+}
+```
+
+A relative root is resolved relative to the Pi agent directory. Each direct child of a root is treated as a skill package, and every visible descendant containing `SKILL.md` is discovered. A root containing `SKILL.md` itself is also accepted as one package.
+
+Use `/config:nested-skills` to change the roots in the normal TUI input. Enter comma-separated paths, or use `reset` for the default root. Run `/reload` after saving.
+
+## Aliases and native expansion
+
+For a skill at `development/code-reviewer/SKILL.md`, the extension offers:
+
+```text
+/development:code-reviewer [arguments]
+/skill:development.code-reviewer [arguments]
+```
+
+The input hook converts the alias to Pi's native `/skill:<frontmatter-name>` form. Pi then reads the skill body and resolves relative references using its normal skill mechanism. If a frontmatter name is shared by multiple discovered skills, the name-only native form is not guessed; use an unambiguous package/path alias.
+
+Use `/skills` to inspect the complete list. Type `/` to search the merged native and nested-skill completion candidates.
+
+## Portability and privacy
+
+The package does not access credentials, make network requests, start processes, or assume a particular home directory. It follows Pi's agent-directory setting and accepts explicit roots for project or team layouts.
+
+## Requirements
+
+- Node.js 22 or newer.
+- Pi `>=0.80.0 <0.81.0`.
+
+## License
+
+MIT — see the repository license.

package/README.zh-CN.md

@@ -0,0 +1,73 @@
+# pi-nested-skills
+
+Pi 的嵌套技能扩展：递归发现多级 `SKILL.md`，并为嵌套技能提供快捷别名、列表和补全。
+
+[English](./README.md)
+
+## 功能
+
+- 递归扫描一个或多个可配置技能根目录下的 `SKILL.md`。
+- 支持 `/development:code-reviewer`、`/design:icons.favicon` 等技能包别名。
+- 保留 Pi 原生技能加载器负责 frontmatter 校验和正文展开；不重复实现 `read` 兼容层或技能展开。
+- 将嵌套技能补全合并到 Pi 原生斜杠命令补全中，不影响内置命令。
+- 提供 `/skills` 列出发现到的全部别名。
+- 提供 `/config:nested-skills` 通过常规 TUI 输入配置技能根目录；输入 `reset` 恢复默认的 `skills` 根目录。
+- 通过 Pi 的 `resources_discover` 事件注册发现到的技能文件。
+- 所有用户可见文案都通过 `pi-extensions-i18n` 提供中英文版本。
+
+## 安装
+
+```bash
+pi install npm:pi-nested-skills
+```
+
+然后在 Pi 中执行 `/reload`。
+
+## 配置技能根目录
+
+复制 [`config.example.json`](./config.example.json)，写入：
+
+```text
+<Pi agent 目录>/extensions/pi-nested-skills/config.json
+```
+
+`<Pi agent 目录>` 是 Pi 配置的 agent 目录，通常为 `~/.pi/agent`。扩展遵循 Pi 的 `PI_CODING_AGENT_DIR` 设置。
+
+```json
+{
+  "skillRoots": [
+    "~/shared-skills",
+    "skills"
+  ]
+}
+```
+
+相对路径以 Pi agent 目录为基准。根目录的每个直接子目录视为一个技能包，扩展会递归发现其中所有可见目录下的 `SKILL.md`。如果根目录本身包含 `SKILL.md`，也会把它作为一个技能包处理。
+
+使用 `/config:nested-skills` 在 TUI 输入框中修改配置，多个目录用逗号分隔；输入 `reset` 恢复默认目录。保存后执行 `/reload`。
+
+## 别名与原生展开
+
+对于 `development/code-reviewer/SKILL.md`，扩展提供：
+
+```text
+/development:code-reviewer [参数]
+/skill:development.code-reviewer [参数]
+```
+
+输入事件会把别名转换为 Pi 原生的 `/skill:<frontmatter-name>` 形式，再由 Pi 读取技能正文，并按原生机制解析相对引用。如果多个技能共用同一个 frontmatter name，扩展不会猜测无路径的名称；请使用明确的技能包/路径别名。
+
+使用 `/skills` 查看完整列表。输入 `/` 可在同一个列表中搜索 Pi 内置命令和嵌套技能。
+
+## 可移植性与隐私
+
+本包不读取凭据、不发起网络请求、不启动进程，也不假设固定的用户目录。它遵循 Pi 的 agent 目录配置，并支持显式指定项目或团队技能目录。
+
+## 要求
+
+- Node.js 22 或更高版本。
+- Pi `>=0.80.0 <0.81.0`。
+
+## 许可证
+
+MIT — 详见仓库许可证。

package/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: configure-pi-nested-skills
+description: "配置与排查 pi-nested-skills 的技能根目录、递归发现、别名调用和补全。Use when configuring nested skill roots, aliases, discovery, or completion."
+---
+
+# 配置 pi-nested-skills
+
+## 诊断
+
+读取实际 Pi agent 目录下的：
+
+```text
+extensions/pi-nested-skills/config.json
+```
+
+默认路径是 `~/.pi/agent/extensions/pi-nested-skills/config.json`；设置 `PI_CODING_AGENT_DIR` 时跟随 Pi 的 agent 目录。配置字段只有 `skillRoots`，可以是一个路径字符串或路径字符串数组。
+
+技能根目录下的一级目录视为技能包；扩展会递归查找其中的 `SKILL.md`。如果根目录本身直接包含 `SKILL.md`，则把这个目录作为一个技能包处理。
+
+## 修改
+
+优先复制包内 [`config.example.json`](./config.example.json)，再修改 `skillRoots`。路径可以是绝对路径、`~/` 路径，或相对于 Pi agent 目录的路径。
+
+也可以使用 `/config:nested-skills` 修改配置；命令会在 TUI 输入框中接收逗号分隔的目录，输入 `reset` 恢复默认值。保存后执行 `/reload`。
+
+别名形式为 `/技能包:子目录.子目录`，例如 `/development:code-reviewer` 或 `/design:icons.favicon`。也支持 `/skill:技能包.子目录`；扩展会把它转换为 Pi 原生 `/skill:<name>`，由 Pi 负责技能正文展开。
+
+## 验证
+
+- 执行 `/skills` 查看递归发现的别名。
+- 在输入框输入 `/`，确认补全同时保留 Pi 内置命令和嵌套技能。
+- 手动调用一个嵌套别名并带参数，确认参数仍传给原生技能展开。
+- 配置空目录、缺失目录或无 description 的 `SKILL.md` 时，确认 Pi/扩展明确报告诊断；不要把无法加载的技能静默显示为可用。
+- 不要复制 Pi 原生 `read` 路径处理或技能正文展开逻辑。

package/config.example.json

@@ -0,0 +1,5 @@
+{
+  "skillRoots": [
+    "skills"
+  ]
+}

package/index.ts

@@ -0,0 +1,2 @@
+export { default } from "./src/index.ts";
+export * from "./src/index.ts";

package/locales/index.json

@@ -0,0 +1,54 @@
+{
+  "commandDescription": {
+    "zh-CN": "列出所有可用的嵌套技能及其命令",
+    "en-US": "List all available nested skills and their commands"
+  },
+  "title": {
+    "zh-CN": "## 可用嵌套技能命令\n",
+    "en-US": "## Available nested skill commands\n"
+  },
+  "footer": {
+    "zh-CN": "在聊天中输入上述命令即可手动调用对应技能。",
+    "en-US": "Enter one of the commands above in chat to invoke the corresponding skill."
+  },
+  "noSkills": {
+    "zh-CN": "技能根目录中没有发现可用技能：{roots}",
+    "en-US": "No usable skills were found in the configured roots: {roots}"
+  },
+  "noRoots": {
+    "zh-CN": "未配置根目录",
+    "en-US": "no configured roots"
+  },
+  "configWarning": {
+    "zh-CN": "嵌套技能配置警告：{reason}",
+    "en-US": "Nested skills configuration warning: {reason}"
+  },
+  "scanWarning": {
+    "zh-CN": "扫描技能目录失败：{path}（{reason}）",
+    "en-US": "Failed to scan skill path: {path} ({reason})"
+  },
+  "configCommandDescription": {
+    "zh-CN": "配置嵌套技能根目录",
+    "en-US": "Configure nested skill roots"
+  },
+  "configCommandInput": {
+    "zh-CN": "输入技能根目录（多个目录用逗号分隔）",
+    "en-US": "Enter skill roots (separate multiple roots with commas)"
+  },
+  "configCommandUsage": {
+    "zh-CN": "用法：/config:nested-skills（打开配置输入）或 /config:nested-skills reset（恢复默认值）",
+    "en-US": "Usage: /config:nested-skills (open settings) or /config:nested-skills reset (restore defaults)"
+  },
+  "configCommandInteractiveOnly": {
+    "zh-CN": "嵌套技能配置需要在 TUI 中修改；请在交互式 Pi 会话中执行命令。",
+    "en-US": "Nested skill configuration requires the TUI; run this command in an interactive Pi session."
+  },
+  "configCommandSaved": {
+    "zh-CN": "嵌套技能配置已保存：{path}。请执行 /reload 使配置生效。",
+    "en-US": "Nested skill configuration saved to {path}. Run /reload to apply it."
+  },
+  "configCommandInvalid": {
+    "zh-CN": "嵌套技能配置无效：{error}",
+    "en-US": "Invalid nested skill configuration: {error}"
+  }
+}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "pi-nested-skills",
+  "version": "0.1.0",
+  "description": "Pi extension for recursive nested-skill discovery and aliases",
+  "type": "module",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "locales",
+    "config.example.json",
+    "README.md",
+    "README.zh-CN.md",
+    "SKILL.md",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "test": "tsx --test tests/*.test.ts",
+    "typecheck": "tsc --noEmit --pretty false",
+    "build": "npm run typecheck",
+    "check": "npm run typecheck && npm test && npm pack --dry-run --json > /dev/null"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts",
+      "../pi-extensions-i18n/index.ts"
+    ],
+    "skills": [
+      "./SKILL.md"
+    ]
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "author": "maplezzk",
+  "homepage": "https://github.com/maplezzk/pi-extensions/tree/main/packages/pi-nested-skills",
+  "bugs": "https://github.com/maplezzk/pi-extensions/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maplezzk/pi-extensions.git",
+    "directory": "packages/pi-nested-skills"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "coding-agent",
+    "skills",
+    "nested-skills",
+    "autocomplete"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.80.0 <0.81.0",
+    "@earendil-works/pi-tui": ">=0.80.0 <0.81.0"
+  },
+  "dependencies": {
+    "pi-extensions-i18n": "^0.4.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.80.10",
+    "@earendil-works/pi-tui": "0.80.10",
+    "@types/node": "24.12.4",
+    "tsx": "4.23.1",
+    "typescript": "5.9.3"
+  }
+}

package/src/config.ts

@@ -0,0 +1,143 @@
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+
+export const CONFIG_FILE_NAME = "config.json";
+export const CONFIG_DIRECTORY_NAME = "pi-nested-skills";
+
+export interface NestedSkillsConfig {
+  /** 包含技能包目录的根目录列表。 */
+  skillRoots: string[];
+}
+
+export type ConfigSource = "file" | "default";
+
+export interface LoadedNestedSkillsConfig {
+  config: NestedSkillsConfig;
+  source: ConfigSource;
+  /** 配置文件存在但无法使用时的明确诊断。 */
+  warnings: string[];
+  /** 是否由用户显式提供过根目录配置。 */
+  explicit: boolean;
+}
+
+interface ConfigObject {
+  skillRoots?: unknown;
+  /** 早期试用版本使用的单数名称，读取时保留兼容性。 */
+  skillsDir?: unknown;
+}
+
+/** 返回实际 Pi agent 目录下的扩展配置文件路径。 */
+export function configPath(agentDir = getAgentDir()): string {
+  return join(agentDir, "extensions", CONFIG_DIRECTORY_NAME, CONFIG_FILE_NAME);
+}
+
+/** 默认使用 Pi 的标准全局技能目录；需要兼容其他技能树时可通过配置覆盖。 */
+export function defaultSkillRoots(agentDir = getAgentDir()): string[] {
+  return [join(agentDir, "skills")];
+}
+
+function expandHomePath(value: string, homeDirectory = homedir()): string {
+  if (value === "~") return homeDirectory;
+  if (value.startsWith("~/") || value.startsWith("~\\")) {
+    return join(homeDirectory, value.slice(2));
+  }
+  return value;
+}
+
+/** 将配置中的绝对、~/ 和相对 Pi agent 目录路径统一为绝对路径。 */
+export function resolveSkillRoot(
+  value: string,
+  agentDir: string,
+  homeDirectory = homedir(),
+): string {
+  const expanded = expandHomePath(value.trim(), homeDirectory);
+  return isAbsolute(expanded) ? expanded : resolve(agentDir, expanded);
+}
+
+function normalizeRootValues(value: unknown): string[] | undefined {
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    return trimmed ? [trimmed] : [];
+  }
+  if (!Array.isArray(value)) return undefined;
+
+  const roots: string[] = [];
+  for (const item of value) {
+    if (typeof item !== "string" || item.trim() === "") return undefined;
+    roots.push(item.trim());
+  }
+  return roots;
+}
+
+/** 校验 TUI 配置输入，并保留早期配置文件的 skillsDir 兼容字段。 */
+export function parseConfig(value: unknown): NestedSkillsConfig {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("configuration must be an object");
+  }
+  const raw = value as ConfigObject;
+  const configured = raw.skillRoots === undefined ? raw.skillsDir : raw.skillRoots;
+  const roots = normalizeRootValues(configured);
+  if (roots === undefined) {
+    throw new Error('configuration field "skillRoots" must be a string or an array of strings');
+  }
+  return { skillRoots: roots };
+}
+
+/** 读取配置文件并返回规范化前的根目录值或明确诊断。 */
+function readConfigFile(path: string): { value?: string[]; warning?: string } {
+  if (!existsSync(path)) return {};
+
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as ConfigObject;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return { warning: `Invalid configuration object in ${path}.` };
+    }
+
+    const configured = parsed.skillRoots === undefined ? parsed.skillsDir : parsed.skillRoots;
+    if (configured === undefined) return {};
+    const roots = normalizeRootValues(configured);
+    if (roots === undefined) {
+      return { warning: `Configuration field "skillRoots" must be a string or an array of strings in ${path}.` };
+    }
+    return { value: roots };
+  } catch (error) {
+    return {
+      warning: `Failed to read ${path}: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}
+
+/** 将技能根目录配置写入 Pi agent 配置目录。 */
+export function saveConfig(config: NestedSkillsConfig, agentDir = getAgentDir()): string {
+  const path = configPath(agentDir);
+  mkdirSync(join(agentDir, "extensions", CONFIG_DIRECTORY_NAME), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+  return path;
+}
+
+/** 读取技能根目录配置：配置文件 > Pi 标准默认目录。 */
+export function loadConfig(agentDir = getAgentDir()): LoadedNestedSkillsConfig {
+  const path = configPath(agentDir);
+  const fileResult = readConfigFile(path);
+  const warnings = fileResult.warning ? [fileResult.warning] : [];
+
+  if (fileResult.value !== undefined) {
+    return {
+      config: {
+        skillRoots: fileResult.value.map((value) => resolveSkillRoot(value, agentDir)),
+      },
+      source: "file",
+      warnings,
+      explicit: true,
+    };
+  }
+
+  return {
+    config: { skillRoots: defaultSkillRoots(agentDir) },
+    source: "default",
+    warnings,
+    explicit: false,
+  };
+}

package/src/index.ts

@@ -0,0 +1,319 @@
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { fuzzyFilter } from "@earendil-works/pi-tui";
+import type { AutocompleteItem, AutocompleteProvider } from "@earendil-works/pi-tui";
+import { createTranslator, loadCatalog } from "pi-extensions-i18n";
+import { loadConfig, parseConfig, saveConfig, type LoadedNestedSkillsConfig } from "./config.ts";
+import { scanSkillRoots, type NestedSkill, type SkillScanResult } from "./skills.ts";
+
+const messages = loadCatalog(new URL("../locales/index.json", import.meta.url));
+const i18n = createTranslator(messages);
+
+const COMMAND_NAME = "skills";
+const COMMAND_ALIASES = [COMMAND_NAME] as const;
+const CONFIG_COMMAND_ALIASES = ["config:nested-skills", "nested-skills-config", "pi-nested-skills-config"] as const;
+const CONFIG_RESET_COMMAND = "reset";
+const DEFAULT_CONFIG_ROOT = "skills";
+const ROOT_INPUT_SEPARATOR = ",";
+const ROOT_DISPLAY_SEPARATOR = ", ";
+const NOTICE_WARNING = "warning" as const;
+const NOTICE_INFO = "info" as const;
+const NOTICE_ERROR = "error" as const;
+const SKILL_COMMAND_PREFIX = "skill:";
+const INPUT_SOURCES = new Set(["interactive", "rpc"]);
+
+type SkillCommandContext = ExtensionCommandContext;
+
+interface SkillCandidate {
+  alias: string;
+  skill: NestedSkill;
+}
+
+interface SkillIndex {
+  readonly skills: NestedSkill[];
+  readonly skillPaths: string[];
+  readonly warnings: SkillScanResult["warnings"];
+  readonly aliases: Map<string, NestedSkill>;
+  readonly names: Map<string, NestedSkill | null>;
+}
+
+/** 将扫描结果转换为稳定的别名索引，并标记 frontmatter name 冲突。 */
+function buildSkillIndex(scan: SkillScanResult): SkillIndex {
+  const aliases = new Map<string, NestedSkill>();
+  const names = new Map<string, NestedSkill | null>();
+
+  for (const skill of scan.skills) {
+    const alias = skillAlias(skill);
+    if (!aliases.has(alias)) aliases.set(alias, skill);
+
+    const existing = names.get(skill.skillName);
+    if (existing === undefined) names.set(skill.skillName, skill);
+    else if (existing !== skill) names.set(skill.skillName, null);
+  }
+
+  return {
+    skills: scan.skills,
+    skillPaths: scan.skillPaths,
+    warnings: scan.warnings,
+    aliases,
+    names,
+  };
+}
+
+/** 返回用户输入和补全展示使用的别名，不改变 frontmatter 中的原生技能名称。 */
+export function skillAlias(skill: Pick<NestedSkill, "packName" | "skillDir">): string {
+  return skill.skillDir ? `${skill.packName}:${skill.skillDir}` : skill.packName;
+}
+
+/** 将 /skill:pack.path、/pack:path 等形式解析为一个已扫描技能。 */
+export function resolveSkillAlias(raw: string, index: Pick<SkillIndex, "aliases" | "names">): NestedSkill | undefined {
+  const candidates = new Set<string>();
+  const addCandidate = (candidate: string): void => {
+    const normalized = candidate.trim();
+    if (normalized) candidates.add(normalized);
+  };
+
+  addCandidate(raw);
+  if (raw.startsWith(SKILL_COMMAND_PREFIX)) {
+    const body = raw.slice(SKILL_COMMAND_PREFIX.length);
+    addCandidate(body);
+
+    // /skill:pack.path.to.skill 使用第一个点分隔技能包和嵌套路径。
+    const firstDot = body.indexOf(".");
+    if (firstDot > 0) addCandidate(`${body.slice(0, firstDot)}:${body.slice(firstDot + 1)}`);
+  } else {
+    // 也接受不带 skill: 前缀的点号路径，方便旧别名和手工输入互通。
+    const firstDot = raw.indexOf(".");
+    if (firstDot > 0) addCandidate(`${raw.slice(0, firstDot)}:${raw.slice(firstDot + 1)}`);
+  }
+
+  for (const candidate of candidates) {
+    const direct = index.aliases.get(candidate);
+    if (direct) return direct;
+  }
+
+  // /skill:<frontmatter name> 交给索引映射；冲突名称不猜测，避免调用错误技能。
+  if (!raw.startsWith(SKILL_COMMAND_PREFIX)) return undefined;
+  const named = index.names.get(raw.slice(SKILL_COMMAND_PREFIX.length));
+  return named ?? undefined;
+}
+
+/** 将原生 /skill:<name> 调用交给 Pi 自己展开，避免复制技能正文展开逻辑。 */
+export function transformSkillInput(
+  text: string,
+  index: Pick<SkillIndex, "aliases" | "names">,
+): string | undefined {
+  const match = text.match(/^\/([^\s]+)(?:\s+([\s\S]*))?$/);
+  if (!match) return undefined;
+
+  const skill = resolveSkillAlias(match[1], index);
+  if (!skill || index.names.get(skill.skillName) !== skill) return undefined;
+
+  const args = match[2]?.trim();
+  return `/skill:${skill.skillName}${args ? ` ${args}` : ""}`;
+}
+
+function skillCandidates(index: SkillIndex): SkillCandidate[] {
+  return [...index.aliases.entries()].map(([alias, skill]) => ({ alias, skill }));
+}
+
+function nativeSkillValue(alias: string): string {
+  const separator = alias.indexOf(":");
+  return separator === -1
+    ? `${SKILL_COMMAND_PREFIX}${alias}`
+    : `${SKILL_COMMAND_PREFIX}${alias.slice(0, separator)}.${alias.slice(separator + 1)}`;
+}
+
+function createAutocompleteProvider(
+  current: AutocompleteProvider,
+  index: SkillIndex,
+): AutocompleteProvider {
+  return {
+    async getSuggestions(lines, cursorLine, cursorCol, options) {
+      const base = await current.getSuggestions(lines, cursorLine, cursorCol, options);
+      const beforeCursor = (lines[cursorLine] ?? "").slice(0, cursorCol);
+      const match = beforeCursor.match(/^\/([^\s]*)$/);
+      if (!match) return base;
+
+      const query = match[1].startsWith(SKILL_COMMAND_PREFIX)
+        ? match[1].slice(SKILL_COMMAND_PREFIX.length)
+        : match[1];
+      const items = fuzzyFilter(
+        skillCandidates(index),
+        query,
+        ({ alias, skill }) => `${alias} ${skill.skillName} ${skill.description}`,
+      ).map(({ alias, skill }): AutocompleteItem => ({
+        value: nativeSkillValue(alias),
+        label: alias,
+        description: skill.description || skill.skillName,
+      }));
+
+      if (items.length === 0) return base;
+      const existingValues = new Set((base?.items ?? []).map((item) => item.value));
+      const merged = [
+        ...(base?.items ?? []),
+        ...items.filter((item) => !existingValues.has(item.value)),
+      ];
+      return { prefix: beforeCursor, items: merged };
+    },
+
+    applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
+      return current.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
+    },
+
+    shouldTriggerFileCompletion(lines, cursorLine, cursorCol) {
+      return current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ?? true;
+    },
+  };
+}
+
+function commandItems(index: SkillIndex): AutocompleteItem[] {
+  return skillCandidates(index).map(({ alias, skill }) => ({
+    value: alias,
+    label: alias,
+    description: skill.description || skill.skillName,
+  }));
+}
+
+function formatSkillsMessage(index: SkillIndex): string {
+  const lines = [i18n.t("title")];
+  const grouped = new Map<string, NestedSkill[]>();
+  for (const skill of index.skills) {
+    const skills = grouped.get(skill.packName) ?? [];
+    skills.push(skill);
+    grouped.set(skill.packName, skills);
+  }
+
+  for (const [pack, skills] of grouped) {
+    lines.push(`### ${pack}\n`);
+    for (const skill of skills) {
+      const description = skill.description ? ` - ${skill.description}` : "";
+      const alias = skillAlias(skill);
+      const indent = "  ".repeat(Math.max(skill.depth - 1, 0));
+      lines.push(`${indent}- \`/${alias}\` ${description}`);
+    }
+    lines.push("");
+  }
+
+  lines.push("---", i18n.t("footer"));
+  return lines.join("\n");
+}
+
+/** 注册配置命令，通过 TUI 输入逗号分隔的技能根目录。 */
+function registerConfigCommand(pi: ExtensionAPI): void {
+  const command = {
+    description: i18n.t("configCommandDescription"),
+    getArgumentCompletions: () => [{ value: CONFIG_RESET_COMMAND, label: CONFIG_RESET_COMMAND }],
+    handler: async (args: string, ctx: ExtensionCommandContext): Promise<void> => {
+      const argument = args.trim();
+      if (argument && argument !== CONFIG_RESET_COMMAND) {
+        ctx.ui.notify(i18n.t("configCommandUsage"), NOTICE_WARNING);
+        return;
+      }
+      if (argument === CONFIG_RESET_COMMAND) {
+        try {
+          const path = saveConfig(parseConfig({ skillRoots: [DEFAULT_CONFIG_ROOT] }));
+          ctx.ui.notify(i18n.t("configCommandSaved", { path }), NOTICE_INFO);
+        } catch (error) {
+          ctx.ui.notify(i18n.t("configCommandInvalid", {
+            error: error instanceof Error ? error.message : String(error),
+          }), NOTICE_ERROR);
+        }
+        return;
+      }
+      if (!ctx.hasUI) {
+        ctx.ui.notify(i18n.t("configCommandInteractiveOnly"), NOTICE_WARNING);
+        return;
+      }
+
+      const current = loadConfig().config;
+      const input = await ctx.ui.input(
+        i18n.t("configCommandInput"),
+        current.skillRoots.join(ROOT_DISPLAY_SEPARATOR),
+      );
+      if (input === undefined) return;
+      try {
+        const roots = input.split(ROOT_INPUT_SEPARATOR).map((root) => root.trim()).filter(Boolean);
+        const path = saveConfig(parseConfig({ skillRoots: roots }));
+        ctx.ui.notify(i18n.t("configCommandSaved", { path }), NOTICE_INFO);
+      } catch (error) {
+        ctx.ui.notify(i18n.t("configCommandInvalid", {
+          error: error instanceof Error ? error.message : String(error),
+        }), NOTICE_ERROR);
+      }
+    },
+  };
+  for (const name of CONFIG_COMMAND_ALIASES) pi.registerCommand(name, command);
+}
+
+function registerSkillsCommand(pi: ExtensionAPI, index: SkillIndex): void {
+  const command = {
+    description: i18n.t("commandDescription"),
+    getArgumentCompletions: (): AutocompleteItem[] => commandItems(index),
+    handler: async (_args: string, _ctx: SkillCommandContext) => {
+      await pi.sendUserMessage(formatSkillsMessage(index), { deliverAs: "followUp" });
+    },
+  };
+
+  for (const name of COMMAND_ALIASES) pi.registerCommand(name, command);
+}
+
+function notifyDiagnostics(ctx: ExtensionContext, loaded: LoadedNestedSkillsConfig, index: SkillIndex): void {
+  if (!ctx.hasUI) return;
+  for (const warning of loaded.warnings) {
+    ctx.ui.notify(i18n.t("configWarning", { reason: warning }), NOTICE_WARNING);
+  }
+  for (const warning of index.warnings) {
+    ctx.ui.notify(
+      i18n.t("scanWarning", { path: warning.path, reason: warning.reason }),
+      NOTICE_WARNING,
+    );
+  }
+  if (loaded.explicit && index.skills.length === 0) {
+    ctx.ui.notify(
+      i18n.t("noSkills", { roots: loaded.config.skillRoots.join(", ") || i18n.t("noRoots") }),
+      NOTICE_WARNING,
+    );
+  }
+}
+
+/** 注册递归技能别名，同时把实际技能正文交给 Pi 原生技能加载和展开流程。 */
+export default function nestedSkillsExtension(pi: ExtensionAPI): void {
+  const loaded = loadConfig();
+  const scan = scanSkillRoots(loaded.config.skillRoots);
+  const index = buildSkillIndex(scan);
+
+  pi.on("resources_discover", () => ({
+    // 每个 SKILL.md 单独交给原生 loader，绕过“父目录含 SKILL.md 后停止递归”的规则，
+    // 同时保留 Pi 原生的 frontmatter 校验、正文展开和资源来源信息。
+    skillPaths: index.skillPaths,
+  }));
+
+  pi.on("input", (event) => {
+    if (!INPUT_SOURCES.has(event.source)) return { action: "continue" as const };
+    const transformed = transformSkillInput(event.text, index);
+    if (!transformed) return { action: "continue" as const };
+    return {
+      action: "transform" as const,
+      text: transformed,
+      images: event.images,
+    };
+  });
+
+  pi.on("session_start", (_event, ctx) => {
+    notifyDiagnostics(ctx, loaded, index);
+    if (index.aliases.size === 0) return;
+    ctx.ui.addAutocompleteProvider((current) => createAutocompleteProvider(current, index));
+  });
+
+  registerConfigCommand(pi);
+  registerSkillsCommand(pi, index);
+}
+
+export { buildSkillIndex, createAutocompleteProvider, formatSkillsMessage };
+export type { SkillIndex };
+export * from "./config.ts";
+export * from "./skills.ts";

package/src/skills.ts

@@ -0,0 +1,271 @@
+import {
+  existsSync,
+  lstatSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  statSync,
+} from "node:fs";
+import { basename, dirname, join, relative } from "node:path";
+
+const SKILL_FILE_NAME = "SKILL.md";
+const PATH_SEPARATOR = ".";
+
+export interface NestedSkill {
+  /** 根目录下的技能包名称。 */
+  packName: string;
+  /** 技能包内的目录标识，嵌套层级用点号连接。 */
+  skillDir: string;
+  /** SKILL.md frontmatter 中的技能名称。 */
+  skillName: string;
+  /** SKILL.md frontmatter 中的技能说明。 */
+  description: string;
+  /** SKILL.md 的绝对路径。 */
+  skillPath: string;
+  /** 从技能包目录开始计算的层级，顶层为 1。 */
+  depth: number;
+}
+
+export interface SkillScanWarning {
+  path: string;
+  reason: string;
+}
+
+export interface SkillScanResult {
+  /** 交给 Pi 原生 loader 的全部 SKILL.md 文件路径。 */
+  skillPaths: string[];
+  /** 具有有效 description、可用于别名和补全的技能。 */
+  skills: NestedSkill[];
+  warnings: SkillScanWarning[];
+}
+
+export interface SkillFrontmatter {
+  name?: string;
+  description?: string;
+}
+
+/** 跳过隐藏目录、依赖目录和特殊目录，行为与 Pi 技能发现保持一致。 */
+export function isVisibleSkillDirectory(name: string): boolean {
+  return !name.startsWith(".") && name !== "node_modules" && name !== ".DS_Store";
+}
+
+function unquote(value: string): string {
+  const trimmed = value.trim();
+  if (trimmed.length < 2) return trimmed;
+  const first = trimmed[0];
+  const last = trimmed.at(-1);
+  if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+
+/**
+ * 读取技能所需的两个 frontmatter 字段。
+ * 完整的技能解析和正文展开仍由 Pi 原生 loader 负责；这里仅建立别名索引。
+ */
+export function parseSkillFrontmatter(content: string): SkillFrontmatter {
+  const match = content.match(/^\uFEFF?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (!match) return {};
+
+  const result: SkillFrontmatter = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const field = line.match(/^(name|description):\s*(.*)$/);
+    if (!field) continue;
+    const value = unquote(field[2]);
+    if (field[1] === "name") result.name = value;
+    else result.description = value;
+  }
+  return result;
+}
+
+function resolveRealPath(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}
+
+function readSkillFile(
+  skillPath: string,
+  packName: string,
+  packDir: string,
+  segments: string[],
+  warnings: SkillScanWarning[],
+): NestedSkill | undefined {
+  let content: string;
+  try {
+    content = readFileSync(skillPath, "utf8");
+  } catch (error) {
+    warnings.push({
+      path: skillPath,
+      reason: error instanceof Error ? error.message : String(error),
+    });
+    return undefined;
+  }
+
+  const frontmatter = parseSkillFrontmatter(content);
+  const description = frontmatter.description?.trim() ?? "";
+  if (!description) {
+    // 仍把文件交给 Pi 原生 loader，让 Pi 的标准诊断负责报告格式问题。
+    return undefined;
+  }
+
+  const relativeDir = relative(packDir, dirname(skillPath));
+  const relativeSegments = relativeDir
+    ? relativeDir.split(/[\\/]/).filter(Boolean)
+    : segments;
+  const skillDir = relativeSegments.join(PATH_SEPARATOR);
+
+  return {
+    packName,
+    skillDir,
+    skillName: frontmatter.name?.trim() || basename(skillPath.replace(/[\\/]SKILL\.md$/, "")),
+    description,
+    skillPath,
+    depth: Math.max(relativeSegments.length, 1),
+  };
+}
+
+function scanPack(
+  packDir: string,
+  packName: string,
+  packRoot: string,
+  segments: string[],
+  result: SkillScanResult,
+  visitedDirectories: Set<string>,
+  visitedFiles: Set<string>,
+): void {
+  const realDirectory = resolveRealPath(packDir);
+  if (visitedDirectories.has(realDirectory)) return;
+  visitedDirectories.add(realDirectory);
+
+  let entries;
+  try {
+    entries = readdirSync(packDir, { withFileTypes: true }).sort((left, right) =>
+      left.name.localeCompare(right.name),
+    );
+  } catch (error) {
+    result.warnings.push({
+      path: packDir,
+      reason: error instanceof Error ? error.message : String(error),
+    });
+    return;
+  }
+
+  const skillPath = join(packDir, SKILL_FILE_NAME);
+  if (existsSync(skillPath)) {
+    const realSkillPath = resolveRealPath(skillPath);
+    if (!visitedFiles.has(realSkillPath)) {
+      visitedFiles.add(realSkillPath);
+      result.skillPaths.push(skillPath);
+      const skill = readSkillFile(skillPath, packName, packRoot, segments, result.warnings);
+      if (skill) result.skills.push(skill);
+    }
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+    if (!isVisibleSkillDirectory(entry.name)) continue;
+
+    const childPath = join(packDir, entry.name);
+    try {
+      if (!statSync(childPath).isDirectory()) continue;
+    } catch (error) {
+      result.warnings.push({
+        path: childPath,
+        reason: error instanceof Error ? error.message : String(error),
+      });
+      continue;
+    }
+
+    scanPack(
+      childPath,
+      packName,
+      packRoot,
+      [...segments, entry.name],
+      result,
+      visitedDirectories,
+      visitedFiles,
+    );
+  }
+}
+
+function scanRoot(
+  root: string,
+  result: SkillScanResult,
+  visitedDirectories: Set<string>,
+  visitedFiles: Set<string>,
+): void {
+  if (!existsSync(root)) {
+    result.warnings.push({ path: root, reason: "directory does not exist" });
+    return;
+  }
+
+  let rootIsDirectory = false;
+  try {
+    rootIsDirectory = lstatSync(root).isDirectory();
+  } catch (error) {
+    result.warnings.push({
+      path: root,
+      reason: error instanceof Error ? error.message : String(error),
+    });
+    return;
+  }
+  if (!rootIsDirectory) {
+    result.warnings.push({ path: root, reason: "skill root is not a directory" });
+    return;
+  }
+
+  let entries;
+  try {
+    entries = readdirSync(root, { withFileTypes: true }).sort((left, right) =>
+      left.name.localeCompare(right.name),
+    );
+  } catch (error) {
+    result.warnings.push({
+      path: root,
+      reason: error instanceof Error ? error.message : String(error),
+    });
+    return;
+  }
+
+  // 支持把单个技能目录直接作为 root，同时保留“root 下是多个技能包”的约定。
+  if (entries.some((entry) => entry.name === SKILL_FILE_NAME)) {
+    scanPack(root, basename(root), root, [], result, visitedDirectories, visitedFiles);
+    return;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+    if (!isVisibleSkillDirectory(entry.name)) continue;
+    const packPath = join(root, entry.name);
+    try {
+      if (!statSync(packPath).isDirectory()) continue;
+    } catch (error) {
+      result.warnings.push({
+        path: packPath,
+        reason: error instanceof Error ? error.message : String(error),
+      });
+      continue;
+    }
+    scanPack(packPath, entry.name, packPath, [], result, visitedDirectories, visitedFiles);
+  }
+}
+
+/** 递归发现多个技能根目录下的全部嵌套技能。 */
+export function scanSkillRoots(roots: readonly string[]): SkillScanResult {
+  const result: SkillScanResult = {
+    skillPaths: [],
+    skills: [],
+    warnings: [],
+  };
+  const visitedDirectories = new Set<string>();
+  const visitedFiles = new Set<string>();
+
+  for (const root of roots) {
+    scanRoot(root, result, visitedDirectories, visitedFiles);
+  }
+  return result;
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "strict": false,
+    "types": ["node"]
+  },
+  "include": ["index.ts", "src/**/*.ts", "tests/**/*.ts"]
+}