@kmiyh/pi-skills-menu 1.1.0 → 1.2.1

package/README.md

@@ -1,14 +1,25 @@
 # @kmiyh/pi-skills-menu
 
-`@kmiyh/pi-skills-menu` is a Pi Agent extension that moves all skills out of Pi's main menu into a separate menu opened with:
+`@kmiyh/pi-skills-menu` is a Pi extension that moves skill browsing and selection into a dedicated `/skills` menu.
+
+Instead of filling Pi's main menu with many `/skill:<name>` entries, it gives you one focused place to search, preview, insert, create, edit, rename, delete, and enable or disable skills.
+
+## Why use it
+
+- keeps the main menu cleaner when many skills are installed
+- puts project, global, and package-provided skills in one searchable list
+- makes skill selection faster in interactive sessions
+- lets you manage your own skills without leaving the TUI
+
+## Installation
 
 ```bash
-/skills
+pi install npm:@kmiyh/pi-skills-menu
 ```
 
-The idea behind the extension is simple: **keep the main menu from getting cluttered** and make it at least a bit easier to navigate when many skills are installed.
+## What changes after installation
 
-When the extension is installed, it automatically writes the following to `settings.json`:
+When the extension is installed, it automatically writes this to `settings.json`:
 
 ```json
 {
@@ -16,135 +27,148 @@ When the extension is installed, it automatically writes the following to `setti
 }
 ```
 
-This disables the default `/skill:<name>` command registration in the main menu and moves skill usage into one dedicated menu.
-
-## Installation
+That disables the default `/skill:<name>` command registration in the main menu and replaces it with a single `/skills` entry.
 
-It can be installed with:
+When you insert a skill from the menu, the extension adds a marker like this to the editor:
 
-```bash
-pi install npm:@kmiyh/pi-skills-menu
+```text
+[skill] my-skill
 ```
 
-## What the `/skills` menu contains
+Before the message is sent, Pi expands that marker into the actual skill content.
 
-The menu shows **all installed available skills**:
+## What the `/skills` menu shows
+
+The menu includes all available installed skills:
 
-- global skills
 - project skills
-- skills coming from other installed libraries/packages
+- global skills
+- skills provided by installed packages/libraries
 
-The list is split into two sections:
+The list is grouped into:
 
-- **Your Skills** — the user's own skills
-- **Library Skills** — skills coming from other installed libraries
+- **Your Skills** — your own project and global skills
+- **Library Skills** — skills coming from installed packages
 
 ![skills-menu.jpg](src/images/skills-menu.jpg)
 
-## What the menu can do
+## What you can do in `/skills`
 
-### Search
+| Action | Shortcut | Notes |
+| --- | --- | --- |
+| Filter skills by name | type | Search works directly in the list |
+| Open preview | `Tab` | Shows full metadata and content |
+| Insert selected skill | `Enter` | Works only for enabled skills |
+| Enable or disable a skill | `Ctrl+X` | Works for your skills and library skills |
+| Create a new skill | `Enter` on **Create new skill** | Opens the creation flow |
+| Delete your own skill | `Backspace` | Available only for project/global skills you own |
 
-The menu includes a search field for filtering skills by name.
+### Preview a skill
 
-### Skill preview
+Press `Tab` on a selected skill to open preview mode.
 
-Press:
+The preview shows:
 
-- `Tab` — open the selected skill in preview mode
+- the skill name and scope
+- its source path or package
+- whether it is enabled or disabled
+- the full frontmatter
+- the full skill content with scrolling support
 
 ![skill-preview.jpg](src/images/skill-preview.jpg)
 
 ### Insert a skill into the editor
 
-Press:
+Press `Enter` on an enabled skill to insert it into the editor.
 
-- `Enter` — select an enabled skill and insert it into the editor
-
-After that, the skill is inserted into the editor so it will be used by Pi when the message is sent.
+This is useful when you want to explicitly attach one or more skills to the message you are writing, without manually copying skill content.
 
 ### Enable or disable a skill
 
-Press:
+Press `Ctrl+X` to toggle the selected skill.
 
-- `x` — toggle the selected skill between enabled and disabled
+Disabled skills stay visible in the list and are marked with `[disabled]`, so you can still find them and re-enable them later.
 
-This also works for skills that come from installed libraries/packages.
+This also works for skills that come from installed packages.
 
-Disabled skills stay visible in the list and are marked with:
+![skill-disable.jpg](src/images/skill-disable.jpg)
 
-- `[disabled]`
+## Creating a new skill
 
-### Create a new skill
+The first row in the menu is **Create new skill**.
 
-The list also contains a dedicated entry for creating a new skill.
+Creation is split into three short steps:
 
-Skill creation is done in three steps:
+1. **Name** — the skill folder/name slug
+2. **Description** — one clear sentence describing what the skill does and when Pi should use it
+3. **Visibility** — whether the skill should be saved globally or only for the current project
 
-1. **skill name**
+### 1. Name
 
 ![skill-create-name.jpg](src/images/skill-create-name.jpg)
 
-2. **skill description**
+### 2. Description
 
 ![skill-create-description.jpg](src/images/skill-create-description.jpg)
 
-3. **skill visibility**
-   - **Global** — save the skill in your user-level Pi skills directory
-   - **Project** — save the skill in the current project's `.pi/skills` directory
+### 3. Visibility
+
+![skill-create-visibility.jpg](src/images/skill-create-visibility.jpg)
 
-After that, the extension generates a `SKILL.md`.
+After that, the extension generates `SKILL.md` for you.
 
 Generation uses:
 
-- the **currently selected model in the TUI**
-- the **currently selected thinking level** in the TUI
+- the model currently selected in the TUI
+- the current thinking level selected in the TUI
 
-So skill generation always follows the exact model configuration already active in the current Pi session.
+So the draft follows the model configuration already active in your Pi session.
 
-![skill-create-generating.jpg](src/images/skill-create-generating.jpg)
+![skill-create-generate.jpg](src/images/skill-create-generate.jpg)
 
-## Skill preview
+## Editing, renaming, and deleting your own skills
 
-The preview opened with `Tab` contains:
+Your own project and global skills can be managed directly from preview mode.
 
-- the full skill text
-- scrolling support for reading the content
+Library skills can be previewed, inserted, and enabled/disabled, but they cannot be edited, renamed, or deleted from this menu.
 
-From preview mode, you can also use quick actions:
+### Edit skill content
 
-- `r` — edit the skill name
+In preview mode, press `e` to edit the skill content and metadata body.
+
+Use `Ctrl+S` to save.
 
 ![skill-edit.jpg](src/images/skill-edit.jpg)
 
-- `e` — edit the skill content itself
+### Rename a skill
 
-![skill-rename.jpg](src/images/skill-rename.jpg)
+In preview mode, press `r` to rename the skill.
 
-## Where new skills are saved
+This updates both the directory name and the `name` field in frontmatter.
 
-New skills are saved into Pi's standard skill directories depending on the selected scope.
+![skill-rename.jpg](src/images/skill-rename.jpg)
 
-### Project scope
+### Delete a skill
 
-If project scope is selected, the skill is saved here:
+In browse mode or preview mode, press `Backspace` to delete your own skill.
 
-```text
-.pi/skills/<skill-name>/SKILL.md
-```
+A confirmation dialog is shown before removal.
 
-Example:
+![skill-delete.jpg](src/images/skill-delete.jpg)
 
-```text
-.pi/skills/react-review/SKILL.md
-```
+## Where new skills are saved
+
+New skills are stored in Pi's standard skill directories depending on the selected visibility.
 
-### Global scope
+| Visibility | Path |
+| --- | --- |
+| Project | `.pi/skills/<skill-name>/SKILL.md` |
+| Global | `~/.pi/agent/skills/<skill-name>/SKILL.md` |
 
-If global scope is selected, the skill is saved here:
+Example project skill:
 
 ```text
-~/.pi/agent/skills/<skill-name>/SKILL.md
+.pi/skills/react-review/SKILL.md
 ```
 
 ## Local development
@@ -167,31 +191,29 @@ Run the extension directly from a local checkout:
 pi -e ./src/index.ts
 ```
 
-## How to help improve the extension
+## Contributing
 
-If you want to help improve the extension, you can:
+Contributions are welcome, especially around:
 
-- report bugs and UX issues
-- suggest improvements to the `/skills` menu
-- improve skill generation quality
-- improve search and list navigation
-- improve editing and preview flows
-- suggest improvements to project structure and Pi package support
-- etc
+- menu UX and navigation
+- skill search and filtering
+- preview and editing flows
+- skill generation quality
+- Pi package compatibility
 
-A typical contribution workflow:
+Typical workflow:
 
 1. fork the repository
-2. create a separate branch
+2. create a branch
 3. make your changes
-4. verify everything with:
+4. verify with:
 
 ```bash
 npm install
 npm run typecheck
 ```
 
-5. test locally
+5. test locally:
 
 ```bash
 pi -e ./src/index.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kmiyh/pi-skills-menu",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Pi extension that moves skills into a dedicated /skills menu with browsing, preview, editing, and AI-assisted creation.",
   "type": "module",
   "keywords": [

package/src/create-skill.ts

@@ -546,6 +546,7 @@ export type SkillCreationThinkingLevel = ThinkingLevel | "off";
 
 export interface SkillGenerationOptions {
 	thinkingLevel?: SkillCreationThinkingLevel;
+	signal?: AbortSignal;
 }
 
 class SingleLineText implements Component {
@@ -863,11 +864,21 @@ function getGenerationStatusLabel(
 		: `Generating skill draft using ${modelLabel}...`;
 }
 
+function isAbortError(error: unknown): boolean {
+	if (!error || typeof error !== "object") return false;
+	const name = "name" in error ? String((error as { name?: unknown }).name) : "";
+	const message = "message" in error ? String((error as { message?: unknown }).message) : "";
+	return name === "AbortError" || message.toLowerCase().includes("aborted");
+}
+
 async function generateSkillDraft(
 	ctx: ExtensionContext,
 	answers: SkillCreationAnswers,
 	options?: SkillGenerationOptions,
 ): Promise<string> {
+	if (options?.signal?.aborted) {
+		throw new Error("Generation aborted");
+	}
 	if (!ctx.model) {
 		return buildFallbackSkill(answers);
 	}
@@ -910,9 +921,13 @@ async function generateSkillDraft(
 	const response = await completeSimple(
 		ctx.model,
 		{ systemPrompt: GENERATE_SKILL_SYSTEM_PROMPT, messages: [userMessage] },
-		{ apiKey: auth.apiKey, headers: auth.headers, ...(reasoning ? { reasoning } : {}) },
+		{ apiKey: auth.apiKey, headers: auth.headers, ...(reasoning ? { reasoning } : {}), ...(options?.signal ? { signal: options.signal } : {}) },
 	);
 
+	if (options?.signal?.aborted) {
+		throw new Error("Generation aborted");
+	}
+
 	const generated = response.content
 		.filter((c): c is { type: "text"; text: string } => c.type === "text")
 		.map((c) => c.text)
@@ -942,12 +957,45 @@ async function runDraftGeneration(
 
 		generateSkillDraft(ctx, answers, options)
 			.then(done)
-			.catch(() => done(buildFallbackSkill(answers)));
+			.catch((error) => done(isAbortError(error) ? null : buildFallbackSkill(answers)));
 
 		return loader;
 	});
 }
 
+async function saveCreatedSkill(
+	ctx: ExtensionContext,
+	answers: SkillCreationAnswers,
+	draft: string,
+): Promise<SkillEntry | null> {
+	let parsedSkill: ParsedSkillDraft;
+	try {
+		parsedSkill = parseSkillDraft(draft, answers.name);
+	} catch (error) {
+		ctx.ui.notify(error instanceof Error ? error.message : "Invalid generated SKILL.md", "error");
+		return null;
+	}
+
+	const targetDir = getTargetDir(ctx, answers.location, answers.name);
+	const targetPath = join(targetDir, "SKILL.md");
+	await mkdir(targetDir, { recursive: true });
+	await writeFile(targetPath, parsedSkill.raw, "utf8");
+
+	ctx.ui.notify(`Created skill: ${targetPath}`, "info");
+	return {
+		name: parsedSkill.name,
+		description: parsedSkill.description,
+		path: targetPath,
+		content: parsedSkill.content,
+		frontmatter: parsedSkill.frontmatter,
+		scope: answers.location === "global" ? "user" : "project",
+		origin: "top-level",
+		source: "auto",
+		baseDir: targetDir,
+		enabled: true,
+	};
+}
+
 async function collectAnswers(ctx: ExtensionContext): Promise<SkillCreationAnswers | null> {
 	const answers = await ctx.ui.custom<SkillCreationAnswers | null>((tui, _theme, _kb, done) => {
 		const component = new SkillCreationWizard(ctx.ui.theme, done);
@@ -992,30 +1040,36 @@ export async function createSkillFromAnswers(
 		return null;
 	}
 
-	let parsedSkill: ParsedSkillDraft;
+	return await saveCreatedSkill(ctx, answers, draft);
+}
+
+export async function createSkillFromAnswersWithoutUI(
+	ctx: ExtensionContext,
+	answers: SkillCreationAnswers,
+	options?: SkillGenerationOptions,
+): Promise<SkillEntry | null> {
+	const targetDir = getTargetDir(ctx, answers.location, answers.name);
+	const targetPath = join(targetDir, "SKILL.md");
+	if (existsSync(targetPath)) {
+		ctx.ui.notify(`Skill already exists: ${targetPath}`, "error");
+		return null;
+	}
+
+	let draft: string;
 	try {
-		parsedSkill = parseSkillDraft(draft, answers.name);
+		draft = await generateSkillDraft(ctx, answers, options);
 	} catch (error) {
-		ctx.ui.notify(error instanceof Error ? error.message : "Invalid generated SKILL.md", "error");
-		return null;
+		if (isAbortError(error) || options?.signal?.aborted) {
+			return null;
+		}
+		draft = buildFallbackSkill(answers);
 	}
 
-	await mkdir(targetDir, { recursive: true });
-	await writeFile(targetPath, parsedSkill.raw, "utf8");
+	if (options?.signal?.aborted) {
+		return null;
+	}
 
-	ctx.ui.notify(`Created skill: ${targetPath}`, "info");
-	return {
-		name: parsedSkill.name,
-		description: parsedSkill.description,
-		path: targetPath,
-		content: parsedSkill.content,
-		frontmatter: parsedSkill.frontmatter,
-		scope: answers.location === "global" ? "user" : "project",
-		origin: "top-level",
-		source: "auto",
-		baseDir: targetDir,
-		enabled: true,
-	};
+	return await saveCreatedSkill(ctx, answers, draft);
 }
 
 export async function createNewSkill(

package/src/index.ts

@@ -1,5 +1,5 @@
 import type { ExtensionAPI, ExtensionContext, InputEventResult } from "@mariozechner/pi-coding-agent";
-import { createSkillFromAnswers } from "./create-skill.js";
+import { createSkillFromAnswersWithoutUI } from "./create-skill.js";
 import { deleteSkill } from "./delete-skill.js";
 import { detectExtensionInstallScope } from "./extension-scope.js";
 import { expandSkillMarkers, hasSkillMarker, insertSkillMarker, removeIncompleteSkillMarkerLines } from "./markers.js";
@@ -7,8 +7,7 @@ import { loadSkillRegistry } from "./skill-registry.js";
 import { ensureSkillCommandsHidden } from "./settings-toggle.js";
 import { setSkillEnabled } from "./skill-enabled-toggle.js";
 import type { ExtensionInstallScope, SkillRegistry } from "./types.js";
-import { showSkillPreview } from "./ui/skill-preview.js";
-import { showSkillsSelector } from "./ui/skills-selector.js";
+import { showSkillsManager } from "./ui/skills-manager.js";
 
 const EMPTY_REGISTRY: SkillRegistry = {
 	skills: [],
@@ -107,81 +106,42 @@ export default function skillsMenuExtension(pi: ExtensionAPI) {
 				return;
 			}
 
-			let selectorIndex = 0;
-			let selectorQuery = "";
-			while (true) {
-				try {
-					await refreshRegistry(ctx.cwd);
-				} catch (error) {
-					console.error("skills-menu: failed to refresh skills registry", error);
-					ctx.ui.notify("Failed to load skills list", "error");
-					return;
-				}
-
-				const selection = await showSkillsSelector(ctx, registry, selectorIndex, selectorQuery);
-				if (!selection) {
-					return;
-				}
-				selectorIndex = selection.selectedIndex;
-				selectorQuery = selection.query;
-
-				if (selection.type === "create") {
-					const createdSkill = await createSkillFromAnswers(ctx, selection.answers, {
-						thinkingLevel: pi.getThinkingLevel(),
-					});
-					if (!createdSkill) {
-						continue;
-					}
-					await refreshRegistry(ctx.cwd);
-					const createdSkillIndex = registry.allSkills.findIndex((skill) => skill.path === createdSkill.path);
-					selectorIndex = createdSkillIndex >= 0 ? createdSkillIndex + 1 : 0;
-					selectorQuery = "";
-					continue;
-				}
-
-				if (selection.type === "toggle") {
+			try {
+				await refreshRegistry(ctx.cwd);
+			} catch (error) {
+				console.error("skills-menu: failed to refresh skills registry", error);
+				ctx.ui.notify("Failed to load skills list", "error");
+				return;
+			}
+
+			const selection = await showSkillsManager(ctx, registry, {
+				onCreate: async (answers, signal) => await createSkillFromAnswersWithoutUI(ctx, answers, {
+					thinkingLevel: pi.getThinkingLevel(),
+					signal,
+				}),
+				onDelete: async (skill) => {
 					try {
-						await setSkillEnabled(ctx.cwd, selection.skill, !selection.skill.enabled);
-						await refreshRegistry(ctx.cwd);
-						ctx.ui.notify(
-							selection.skill.enabled
-								? `Disabled ${selection.skill.name}. Run /reload to fully apply the change.`
-								: `Enabled ${selection.skill.name}. Run /reload to fully apply the change.`,
-							"info",
-						);
+						return await deleteSkill(ctx, skill);
 					} catch (error) {
-						console.error("skills-menu: failed to toggle skill", error);
-						ctx.ui.notify(error instanceof Error ? error.message : "Failed to update skill visibility", "error");
-					}
-					continue;
-				}
-
-				if (selection.type === "preview") {
-					await showSkillPreview(ctx, selection.skill);
-					continue;
-				}
-
-				if (selection.type === "delete") {
-					const confirmed = await ctx.ui.confirm(
-						"Delete skill",
-						`Delete ${selection.skill.name}? This removes the skill from disk and cannot be undone.`,
-					);
-					if (!confirmed) {
-						continue;
+						console.error("skills-menu: failed to delete skill", error);
+						ctx.ui.notify("Failed to delete skill", "error");
+						return false;
 					}
+				},
+				onToggle: async (skill, enabled) => {
 					try {
-						await deleteSkill(ctx, selection.skill);
-						selectorIndex = Math.max(0, selectorIndex - 1);
+						await setSkillEnabled(ctx.cwd, skill, enabled);
 					} catch (error) {
-						console.error("skills-menu: failed to delete skill", error);
-						ctx.ui.notify("Failed to delete skill", "error");
+						console.error("skills-menu: failed to toggle skill", error);
+						throw error instanceof Error ? error : new Error("Failed to update skill visibility");
 					}
-					continue;
-				}
-
-				insertSkillMarker(ctx, selection.skill);
+				},
+				onRefresh: async () => await refreshRegistry(ctx.cwd),
+			});
+			if (!selection) {
 				return;
 			}
+			insertSkillMarker(ctx, selection);
 		},
 	});
 
@@ -207,7 +167,7 @@ export default function skillsMenuExtension(pi: ExtensionAPI) {
 			return { action: "continue" };
 		}
 
-		if (!currentCwd || currentCwd !== ctx.cwd || registry.skills.length === 0) {
+		if (!currentCwd || currentCwd !== ctx.cwd || registry.allSkills.length === 0) {
 			try {
 				await refreshRegistry(ctx.cwd);
 			} catch (error) {

package/src/skill-registry.ts

@@ -3,10 +3,6 @@ import { parseSkillFile } from "./skill-parser.js";
 import type { SkillEntry, SkillRegistry } from "./types.js";
 
 function compareSkills(a: SkillEntry, b: SkillEntry): number {
-	if (a.enabled !== b.enabled) {
-		return a.enabled ? -1 : 1;
-	}
-
 	const scopeRank = (scope: SkillEntry["scope"]) => {
 		switch (scope) {
 			case "project":

package/src/ui/skill-preview.ts

@@ -37,7 +37,7 @@ function getSkillLocation(skill: SkillEntry): string {
 }
 
 function getSkillLocationLabel(skill: SkillEntry): string {
-	return skill.origin === "package" ? "package" : "path";
+	return skill.origin === "package" ? "package • " : "";
 }
 
 function formatScalar(value: unknown): string {
@@ -271,7 +271,7 @@ class ScrollableSkillPreview implements Component {
 	private buildContentLines(innerWidth: number): string[] {
 		const content = new Container();
 		content.addChild(new Text(this.theme.fg("accent", this.theme.bold(this.skill.name)), 0, 0));
-		content.addChild(new Text(this.theme.fg("muted", `${getSkillLocationLabel(this.skill)} • ${getSkillLocation(this.skill)}`), 0, 0));
+		content.addChild(new Text(this.theme.fg("muted", `${getSkillLocationLabel(this.skill)}${getSkillLocation(this.skill)}`), 0, 0));
 		content.addChild(new Spacer(1));
 		content.addChild(new Text(this.theme.fg("muted", this.theme.bold("Metadata")), 0, 0));
 		content.addChild(new Text(this.theme.fg("dim", buildFrontmatterBlock(this.skill)), 0, 0));
@@ -292,7 +292,7 @@ class ScrollableSkillPreview implements Component {
 			: "";
 		const editInfo = this.editable ? " • e edit • r rename" : "";
 		return truncateToWidth(
-			this.theme.fg("dim", `↑/↓ scroll • pgup/pgdn jump • home/end${editInfo} • esc back${scrollInfo}`),
+			this.theme.fg("dim", `↑/↓ scroll${editInfo} • esc back${scrollInfo}`),
 			innerWidth,
 			this.theme.fg("dim", "..."),
 		);