pi-skillful 0.2.4 → 0.3.0

package/CHANGELOG.md

@@ -6,6 +6,12 @@ This project follows the spirit of [Keep a Changelog](https://keepachangelog.com
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-05-09
+
+### Added
+
+- Added session-scoped skill toggle slots with configurable modifier-number shortcuts and prompt-editor top-border status.
+
 ## [0.2.4] - 2026-05-09
 
 ### Changed

package/README.md

@@ -6,10 +6,11 @@
 
 `pi-skillful` is a [Pi](https://github.com/badlogic/pi-mono) package that improves skill workflows.
 
-It currently provides two extensions:
+It currently provides three extensions:
 
 - **Inline skill invocation**: invoke one or more skills anywhere in a prompt with `/skill:name`.
 - **Skill prompt visibility**: choose which skills are hidden from the model's automatic skill-discovery prompt, while keeping them explicitly invokable and visibly marked in Pi's startup skill list.
+- **Session skill toggles**: assign up to nine skills to number slots and toggle model visibility while writing a prompt.
 
 > [!WARNING]
 > Pi packages can execute arbitrary code through extensions. Review package source before installing any third-party Pi package.
@@ -65,6 +66,30 @@ Pi's startup `[Skills]` list also highlights hidden skills in the error color (r
 
 When the project settings file contains only `skillful` settings and the project `hiddenSkills` list becomes empty, `.pi/settings.json` is deleted instead of leaving an empty settings file behind.
 
+### Session skill toggles
+
+Assign skills to up to nine prompt-editor slots with JSON settings:
+
+```json
+{
+  "skillful": {
+    "hiddenSkills": ["pdf", "xlsx"],
+    "toggleSlots": {
+      "1": "typescript",
+      "2": "code-review",
+      "3": "git"
+    },
+    "toggleModifier": "alt"
+  }
+}
+```
+
+Configured slots appear on the prompt editor's top border as `N skill-name`. Long names are truncated per slot when needed so all configured slot numbers remain visible. Active slots use the theme accent color; inactive slots use the muted color. Press `alt+1` through `alt+9` by default to toggle a slot for the current session only.
+
+`toggleModifier` defaults to `"alt"`. Supported values are `"alt"`, `"ctrl"`, `"ctrl+shift"`, `"alt+shift"`, `"ctrl+alt"`, and `"ctrl+alt+shift"`. Change it if your terminal reserves `alt+number` shortcuts.
+
+On session start, non-hidden skills are active and hidden skills are inactive. Starting, resuming, or forking a session resets toggle state from settings. Inline `/skill:name` invocation remains explicit and works even when that skill is inactive.
+
 ## Installation
 
 Install from GitHub:

package/extensions/index.ts

@@ -1,8 +1,10 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import inlineSkillInvocation from "../src/extensions/inline-skill-invocation.js";
 import skillVisibility from "../src/extensions/skill-visibility.js";
+import sessionSkillToggles from "../src/extensions/session-skill-toggles.js";
 
 export default function piSkillful(pi: ExtensionAPI) {
   inlineSkillInvocation(pi);
   skillVisibility(pi);
+  sessionSkillToggles(pi);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-skillful",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "Pi package with skill invocation and visibility improvements.",
   "type": "module",
   "license": "MIT",

package/src/config.ts

@@ -3,17 +3,40 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
 export type SkillfulScope = "global" | "project";
+export type SkillToggleSlot = "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
+export const SUPPORTED_TOGGLE_MODIFIERS = [
+  "alt",
+  "ctrl",
+  "ctrl+shift",
+  "alt+shift",
+  "ctrl+alt",
+  "ctrl+alt+shift",
+] as const;
+export type SkillToggleModifier = (typeof SUPPORTED_TOGGLE_MODIFIERS)[number];
+
+export interface SkillToggleConfig {
+  toggleSlots: Partial<Record<SkillToggleSlot, string>>;
+  toggleModifier: SkillToggleModifier;
+}
 
-export interface SkillfulSettings {
+export interface SkillfulSettings extends SkillToggleConfig {
   hiddenSkills: string[];
 }
 
+export interface EffectiveSkillfulSettings extends SkillfulSettings {
+  hiddenSkillSet: Set<string>;
+}
+
 interface PiSettingsDocument {
   skillful?: Partial<SkillfulSettings>;
   [key: string]: unknown;
 }
 
 export const SKILLFUL_SETTINGS_KEY = "skillful";
+export const SKILL_TOGGLE_SLOTS: SkillToggleSlot[] = ["1", "2", "3", "4", "5", "6", "7", "8", "9"];
+export const DEFAULT_TOGGLE_MODIFIER: SkillToggleModifier = "alt";
+
+const SUPPORTED_TOGGLE_MODIFIERS_SET: ReadonlySet<string> = new Set(SUPPORTED_TOGGLE_MODIFIERS);
 
 export function globalSettingsPath(): string {
   return join(homedir(), ".pi", "agent", "settings.json");
@@ -42,6 +65,33 @@ export function normalizeSkillNames(names: Iterable<string>): string[] {
   );
 }
 
+export function normalizeToggleSlots(value: unknown): Partial<Record<SkillToggleSlot, string>> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+
+  const result: Partial<Record<SkillToggleSlot, string>> = {};
+  const seenSkillNames = new Set<string>();
+  const source = value as Record<string, unknown>;
+
+  for (const slot of SKILL_TOGGLE_SLOTS) {
+    const rawName = source[slot];
+    if (typeof rawName !== "string") continue;
+
+    const name = normalizeSkillName(rawName);
+    if (!name || seenSkillNames.has(name)) continue;
+
+    result[slot] = name;
+    seenSkillNames.add(name);
+  }
+
+  return result;
+}
+
+export function normalizeToggleModifier(value: unknown): SkillToggleModifier {
+  if (typeof value !== "string") return DEFAULT_TOGGLE_MODIFIER;
+  const normalized = value.trim().toLowerCase();
+  return SUPPORTED_TOGGLE_MODIFIERS_SET.has(normalized) ? (normalized as SkillToggleModifier) : DEFAULT_TOGGLE_MODIFIER;
+}
+
 async function readSettingsDocument(path: string): Promise<PiSettingsDocument> {
   try {
     const raw = await readFile(path, "utf-8");
@@ -58,12 +108,16 @@ async function readSettingsDocument(path: string): Promise<PiSettingsDocument> {
 export async function readSkillfulSettings(path: string): Promise<SkillfulSettings> {
   const settings = await readSettingsDocument(path);
   const skillful = settings[SKILLFUL_SETTINGS_KEY];
-  const hiddenSkills =
-    skillful && typeof skillful === "object" && Array.isArray(skillful.hiddenSkills)
-      ? skillful.hiddenSkills.filter((name): name is string => typeof name === "string")
-      : [];
-
-  return { hiddenSkills: normalizeSkillNames(hiddenSkills) };
+  const skillfulObject = skillful && typeof skillful === "object" && !Array.isArray(skillful) ? skillful : {};
+  const hiddenSkills = Array.isArray(skillfulObject.hiddenSkills)
+    ? skillfulObject.hiddenSkills.filter((name): name is string => typeof name === "string")
+    : [];
+
+  return {
+    hiddenSkills: normalizeSkillNames(hiddenSkills),
+    toggleSlots: normalizeToggleSlots(skillfulObject.toggleSlots),
+    toggleModifier: normalizeToggleModifier(skillfulObject.toggleModifier),
+  };
 }
 
 export async function readScopedSkillfulSettings(cwd: string): Promise<Record<SkillfulScope, SkillfulSettings>> {
@@ -79,6 +133,19 @@ export async function readEffectiveHiddenSkills(cwd: string): Promise<Set<string
   return new Set([...scoped.global.hiddenSkills, ...scoped.project.hiddenSkills]);
 }
 
+export async function readEffectiveSkillfulSettings(cwd: string): Promise<EffectiveSkillfulSettings> {
+  const scoped = await readScopedSkillfulSettings(cwd);
+  const hiddenSkills = normalizeSkillNames([...scoped.global.hiddenSkills, ...scoped.project.hiddenSkills]);
+  const toggleSlots = normalizeToggleSlots({ ...scoped.global.toggleSlots, ...scoped.project.toggleSlots });
+  return {
+    hiddenSkills,
+    hiddenSkillSet: new Set(hiddenSkills),
+    toggleSlots,
+    toggleModifier:
+      scoped.project.toggleModifier !== DEFAULT_TOGGLE_MODIFIER ? scoped.project.toggleModifier : scoped.global.toggleModifier,
+  };
+}
+
 export async function writeHiddenSkills(
   scope: SkillfulScope,
   cwd: string,
@@ -88,25 +155,32 @@ export async function writeHiddenSkills(
   const document = await readSettingsDocument(path);
   const updated = normalizeSkillNames(hiddenSkills);
 
-  if (updated.length === 0) {
-    delete document[SKILLFUL_SETTINGS_KEY];
-  } else {
-    document[SKILLFUL_SETTINGS_KEY] = {
-      ...(document[SKILLFUL_SETTINGS_KEY] && typeof document[SKILLFUL_SETTINGS_KEY] === "object"
-        ? document[SKILLFUL_SETTINGS_KEY]
-        : {}),
-      hiddenSkills: updated,
-    };
-  }
+  const existingSkillful =
+    document[SKILLFUL_SETTINGS_KEY] && typeof document[SKILLFUL_SETTINGS_KEY] === "object" && !Array.isArray(document[SKILLFUL_SETTINGS_KEY])
+      ? (document[SKILLFUL_SETTINGS_KEY] as Record<string, unknown>)
+      : {};
+  const nextSkillful = { ...existingSkillful };
+
+  if (updated.length === 0) delete nextSkillful.hiddenSkills;
+  else nextSkillful.hiddenSkills = updated;
+
+  if (Object.keys(nextSkillful).length === 0) delete document[SKILLFUL_SETTINGS_KEY];
+  else document[SKILLFUL_SETTINGS_KEY] = nextSkillful as Partial<SkillfulSettings>;
+
+  const result: SkillfulSettings = {
+    hiddenSkills: updated,
+    toggleSlots: normalizeToggleSlots(nextSkillful.toggleSlots),
+    toggleModifier: normalizeToggleModifier(nextSkillful.toggleModifier),
+  };
 
   if (scope === "project" && Object.keys(document).length === 0) {
     await unlinkIfExists(path);
-    return { hiddenSkills: updated };
+    return result;
   }
 
   await mkdir(dirname(path), { recursive: true });
   await writeFile(path, `${JSON.stringify(document, null, 2)}\n`, "utf-8");
-  return { hiddenSkills: updated };
+  return result;
 }
 
 export async function updateHiddenSkills(

package/src/extensions/session-skill-toggles.ts

@@ -0,0 +1,294 @@
+import { CustomEditor, type ExtensionAPI, type KeybindingsManager, type Skill, type Theme } from "@earendil-works/pi-coding-agent";
+import type { AutocompleteProvider, Component, EditorComponent, EditorTheme, TUI } from "@earendil-works/pi-tui";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import {
+  DEFAULT_TOGGLE_MODIFIER,
+  normalizeSkillName,
+  readEffectiveSkillfulSettings,
+  SKILL_TOGGLE_SLOTS,
+  SUPPORTED_TOGGLE_MODIFIERS,
+  type SkillToggleModifier,
+  type SkillToggleSlot,
+} from "../config.js";
+import { replaceSkillsSection } from "../skill-prompt.js";
+import { listLoadedSkills } from "../skills.js";
+
+const WIDGET_KEY = "pi-skillful-session-toggles";
+const BORDER_PREFIX = "─── ";
+const BORDER_SUFFIX = " ";
+const BORDER_PREFIX_WIDTH = visibleWidth(BORDER_PREFIX);
+const BORDER_SUFFIX_WIDTH = visibleWidth(BORDER_SUFFIX);
+const MAX_SLOT_NAME_WIDTH = 16;
+
+interface ToggleSlotState {
+  slot: SkillToggleSlot;
+  skillName: string;
+}
+
+interface SessionToggleState {
+  cwd: string;
+  modifier: SkillToggleModifier;
+  hiddenSkills: Set<string>;
+  slots: ToggleSlotState[];
+  activeBySkill: Map<string, boolean>;
+  installedEditor: boolean;
+  installedWidget: boolean;
+  previousEditorFactory: SkillfulEditorFactory | undefined;
+  activeTui: TUI | undefined;
+  theme: Theme | undefined;
+}
+
+let state: SessionToggleState = createEmptyState();
+
+export default function sessionSkillToggles(pi: ExtensionAPI) {
+  for (const modifier of SUPPORTED_TOGGLE_MODIFIERS) {
+    for (const slot of SKILL_TOGGLE_SLOTS) {
+      pi.registerShortcut(`${modifier}+${slot}`, {
+        description: `Toggle pi-skillful slot ${slot}`,
+        handler: (ctx) => {
+          if (state.modifier !== modifier) return;
+          toggleSlot(slot, ctx.ui.notify.bind(ctx.ui));
+        },
+      });
+    }
+  }
+
+  pi.on("session_start", async (_event, ctx) => {
+    const settings = await readEffectiveSkillfulSettings(ctx.cwd);
+    const loadedSkillNames = new Set(listLoadedSkills(pi.getCommands()).map((s) => s.name));
+    const slots = SKILL_TOGGLE_SLOTS.flatMap((slot): ToggleSlotState[] => {
+      const skillName = settings.toggleSlots[slot];
+      if (!skillName || !loadedSkillNames.has(skillName)) return [];
+      return [{ slot, skillName }];
+    });
+
+    state = {
+      cwd: ctx.cwd,
+      modifier: settings.toggleModifier,
+      hiddenSkills: settings.hiddenSkillSet,
+      slots,
+      activeBySkill: new Map(slots.map(({ skillName }) => [skillName, !settings.hiddenSkillSet.has(skillName)])),
+      installedEditor: false,
+      installedWidget: false,
+      previousEditorFactory: undefined,
+      activeTui: undefined,
+      theme: ctx.ui.theme,
+    };
+
+    if (ctx.hasUI && slots.length > 0) installEditor(ctx.ui);
+    refreshUi();
+  });
+
+  pi.on("before_agent_start", (event) => {
+    if (state.slots.length === 0 || !event.systemPromptOptions.skills?.length) return;
+
+    const updatedSkills: Skill[] = event.systemPromptOptions.skills.map((skill) => ({
+      ...skill,
+      disableModelInvocation: !isSkillActive(normalizeSkillName(skill.name)),
+    }));
+
+    const systemPrompt = replaceSkillsSection(event.systemPrompt, updatedSkills);
+    if (!systemPrompt) return;
+    return { systemPrompt };
+  });
+
+  pi.on("session_shutdown", (_event, ctx) => {
+    if (state.installedEditor) ctx.ui.setEditorComponent(state.previousEditorFactory);
+    if (state.installedWidget) ctx.ui.setWidget(WIDGET_KEY, undefined);
+    state = createEmptyState();
+  });
+}
+
+function createEmptyState(): SessionToggleState {
+  return {
+    cwd: "",
+    modifier: DEFAULT_TOGGLE_MODIFIER,
+    hiddenSkills: new Set<string>(),
+    slots: [],
+    activeBySkill: new Map<string, boolean>(),
+    installedEditor: false,
+    installedWidget: false,
+    previousEditorFactory: undefined,
+    activeTui: undefined,
+    theme: undefined,
+  };
+}
+
+function isSkillActive(skillName: string): boolean {
+  return state.activeBySkill.get(skillName) ?? !state.hiddenSkills.has(skillName);
+}
+
+function toggleSlot(slot: SkillToggleSlot, notify: (message: string, type?: "info" | "warning" | "error") => void): void {
+  const entry = state.slots.find((candidate) => candidate.slot === slot);
+  if (!entry) {
+    notify(`No pi-skillful skill assigned to slot ${slot}.`, "info");
+    return;
+  }
+
+  const next = !isSkillActive(entry.skillName);
+  state.activeBySkill.set(entry.skillName, next);
+  notify(`${entry.skillName} ${next ? "active" : "inactive"} for this session.`, "info");
+  refreshUi();
+}
+
+type SkillfulEditorFactory = (tui: TUI, theme: EditorTheme, keybindings: KeybindingsManager) => EditorComponent;
+
+type SkillfulUi = {
+  getEditorComponent: () => SkillfulEditorFactory | undefined;
+  setEditorComponent: (factory: SkillfulEditorFactory | undefined) => void;
+  setWidget: (
+    key: string,
+    content: ((tui: TUI, theme: Theme) => Component & { dispose?(): void }) | undefined,
+    options?: { placement?: "aboveEditor" | "belowEditor" },
+  ) => void;
+};
+
+function installEditor(ui: SkillfulUi): void {
+  state.previousEditorFactory = ui.getEditorComponent();
+
+  try {
+    const previous = state.previousEditorFactory;
+    ui.setEditorComponent((tui, theme, keybindings) => {
+      state.activeTui = tui;
+      if (previous) return new SkillToggleEditorWrapper(previous(tui, theme, keybindings));
+      return new SkillToggleEditor(tui, theme, keybindings);
+    });
+    state.installedEditor = true;
+  } catch {
+    ui.setWidget(WIDGET_KEY, (tui) => {
+      state.activeTui = tui;
+      return new SkillToggleWidget();
+    });
+    state.installedWidget = true;
+  }
+}
+
+function refreshUi(): void {
+  state.activeTui?.requestRender();
+}
+
+class SkillToggleEditor extends CustomEditor {
+  render(width: number): string[] {
+    const lines = super.render(width);
+    if (lines.length === 0) return lines;
+    lines[0] = renderToggleBorder(width, (text) => this.borderColor(text));
+    return lines;
+  }
+}
+
+class SkillToggleEditorWrapper implements EditorComponent {
+  borderColor?: (str: string) => string;
+
+  constructor(private readonly inner: EditorComponent) {
+    this.borderColor = inner.borderColor?.bind(inner);
+  }
+
+  get onSubmit(): ((text: string) => void) | undefined {
+    return this.inner.onSubmit;
+  }
+
+  set onSubmit(handler: ((text: string) => void) | undefined) {
+    this.inner.onSubmit = handler;
+  }
+
+  get onChange(): ((text: string) => void) | undefined {
+    return this.inner.onChange;
+  }
+
+  set onChange(handler: ((text: string) => void) | undefined) {
+    this.inner.onChange = handler;
+  }
+
+  render(width: number): string[] {
+    const lines = this.inner.render(width);
+    if (lines.length === 0) return lines;
+    lines[0] = renderToggleBorder(width, this.borderColor ?? ((text) => text));
+    return lines;
+  }
+
+  invalidate(): void {
+    this.inner.invalidate();
+  }
+
+  getText(): string {
+    return this.inner.getText();
+  }
+
+  setText(text: string): void {
+    this.inner.setText(text);
+  }
+
+  handleInput(data: string): void {
+    this.inner.handleInput(data);
+  }
+
+  addToHistory(text: string): void {
+    this.inner.addToHistory?.(text);
+  }
+
+  insertTextAtCursor(text: string): void {
+    this.inner.insertTextAtCursor?.(text);
+  }
+
+  getExpandedText(): string {
+    return this.inner.getExpandedText?.() ?? this.inner.getText();
+  }
+
+  setAutocompleteProvider(provider: AutocompleteProvider): void {
+    this.inner.setAutocompleteProvider?.(provider);
+  }
+
+  setPaddingX(padding: number): void {
+    this.inner.setPaddingX?.(padding);
+  }
+
+  setAutocompleteMaxVisible(maxVisible: number): void {
+    this.inner.setAutocompleteMaxVisible?.(maxVisible);
+  }
+
+  dispose(): void {
+    (this.inner as EditorComponent & { dispose?(): void }).dispose?.();
+  }
+}
+
+class SkillToggleWidget implements Component {
+  render(width: number): string[] {
+    return [renderToggleBorder(width, (text) => text)];
+  }
+
+  invalidate(): void {}
+}
+
+function renderToggleBorder(width: number, borderColor: (text: string) => string): string {
+  if (width <= 0) return "";
+  if (state.slots.length === 0) return borderColor("─".repeat(width));
+
+  const available = Math.max(0, width - BORDER_PREFIX_WIDTH - BORDER_SUFFIX_WIDTH);
+  const fittedContent = truncateToWidth(renderToggleSegments(available), available, "");
+  const used = BORDER_PREFIX_WIDTH + visibleWidth(fittedContent) + BORDER_SUFFIX_WIDTH;
+  const fill = borderColor("─".repeat(Math.max(0, width - used)));
+  return `${borderColor(BORDER_PREFIX)}${fittedContent}${BORDER_SUFFIX}${fill}`;
+}
+
+function renderToggleSegments(availableWidth: number): string {
+  const separatorWidth = Math.max(0, state.slots.length - 1) * 2;
+  const slotLabelWidth = state.slots.length * 2;
+  const fullNameWidth = state.slots.reduce((total, slot) => total + visibleWidth(slot.skillName), 0);
+  const truncate = separatorWidth + slotLabelWidth + fullNameWidth > availableWidth;
+  const maxNameWidth = Math.max(
+    1,
+    Math.min(MAX_SLOT_NAME_WIDTH, Math.floor((availableWidth - separatorWidth - slotLabelWidth) / Math.max(1, state.slots.length))),
+  );
+
+  return state.slots
+    .map(({ slot, skillName }) => {
+      const name = truncate ? truncateToWidth(skillName, maxNameWidth, "…") : skillName;
+      const text = `${slot} ${name}`;
+      return stateThemeFg(isSkillActive(skillName) ? "accent" : "muted", text);
+    })
+    .join("  ");
+}
+
+function stateThemeFg(color: "accent" | "muted", text: string): string {
+  return state.theme?.fg(color, text) ?? text;
+}

package/src/extensions/skill-visibility.ts

@@ -1,6 +1,5 @@
 import {
   DynamicBorder,
-  formatSkillsForPrompt,
   getSettingsListTheme,
   InteractiveMode,
   type ExtensionAPI,
@@ -16,8 +15,8 @@ import {
   type SkillfulScope,
   writeHiddenSkills,
 } from "../config.js";
-
-const SKILLS_SECTION_PATTERN = /\n\nThe following skills provide specialized instructions for specific tasks\.[\s\S]*?<\/available_skills>/;
+import { replaceSkillsSection } from "../skill-prompt.js";
+import { listLoadedSkills, type LoadedSkillInfo } from "../skills.js";
 const SCOPES: SkillfulScope[] = ["global", "project"];
 const STORE_KEY = Symbol.for("pi-skillful.skillVisibilityStore");
 const STARTUP_PATCH_KEY = Symbol.for("pi-skillful.startupPatchV2");
@@ -50,10 +49,7 @@ const store = (((globalThis as Record<PropertyKey, unknown>)[STORE_KEY] as Skill
   theme: null,
 }) as SkillVisibilityStore;
 
-interface SkillListItem {
-  name: string;
-  description: string;
-}
+type SkillListItem = LoadedSkillInfo;
 
 export default function skillVisibility(pi: ExtensionAPI) {
   installStartupSkillListPatch();
@@ -70,10 +66,9 @@ export default function skillVisibility(pi: ExtensionAPI) {
     const filteredSkills: Skill[] = event.systemPromptOptions.skills.map((skill) =>
       hidden.has(skill.name) ? { ...skill, disableModelInvocation: true } : skill,
     );
-    const replacement = formatSkillsForPrompt(filteredSkills);
-
-    if (!SKILLS_SECTION_PATTERN.test(event.systemPrompt)) return;
-    return { systemPrompt: event.systemPrompt.replace(SKILLS_SECTION_PATTERN, replacement) };
+    const systemPrompt = replaceSkillsSection(event.systemPrompt, filteredSkills);
+    if (!systemPrompt) return;
+    return { systemPrompt };
   });
 
   pi.registerCommand("skillful", {
@@ -118,8 +113,7 @@ async function pruneStaleHiddenSkills(pi: ExtensionAPI, cwd: string): Promise<vo
       const current = scoped[scope].hiddenSkills;
       const pruned = current.filter((name) => installedNames.has(name));
       if (pruned.length < current.length) {
-        await writeHiddenSkills(scope, cwd, pruned);
-        scoped[scope] = { hiddenSkills: pruned };
+        scoped[scope] = await writeHiddenSkills(scope, cwd, pruned);
       }
     }),
   );
@@ -201,18 +195,7 @@ function buildColorizedSkillList(names: string[], hidden: Set<string>, theme: Th
 }
 
 function getSkillItems(pi: ExtensionAPI): SkillListItem[] {
-  const byName = new Map<string, SkillListItem>();
-  for (const command of pi.getCommands()) {
-    if (command.source !== "skill") continue;
-    const name = normalizeSkillName(command.name);
-    if (!name) continue;
-    byName.set(name, {
-      name,
-      description: command.description ?? "",
-    });
-  }
-
-  return Array.from(byName.values()).sort((a, b) => a.name.localeCompare(b.name));
+  return listLoadedSkills(pi.getCommands());
 }
 
 class SkillfulVisibilityMenu implements Component {

package/src/skill-prompt.ts

@@ -0,0 +1,8 @@
+import { formatSkillsForPrompt, type Skill } from "@earendil-works/pi-coding-agent";
+
+export const SKILLS_SECTION_PATTERN = /\n\nThe following skills provide specialized instructions for specific tasks\.[\s\S]*?<\/available_skills>/;
+
+export function replaceSkillsSection(systemPrompt: string, skills: Skill[]): string | undefined {
+  const next = systemPrompt.replace(SKILLS_SECTION_PATTERN, formatSkillsForPrompt(skills));
+  return next === systemPrompt ? undefined : next;
+}

package/src/skills.ts

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
 import { dirname } from "node:path";
+import { normalizeSkillName } from "./config.js";
 
 export interface SkillCommandInfo {
   name: string;
@@ -7,6 +8,28 @@ export interface SkillCommandInfo {
   baseDir: string;
 }
 
+export interface LoadedSkillInfo {
+  name: string;
+  description: string;
+}
+
+interface CommandLike {
+  name: string;
+  source: string;
+  description?: string;
+}
+
+export function listLoadedSkills(commands: Iterable<CommandLike>): LoadedSkillInfo[] {
+  const byName = new Map<string, LoadedSkillInfo>();
+  for (const command of commands) {
+    if (command.source !== "skill") continue;
+    const name = normalizeSkillName(command.name);
+    if (!name) continue;
+    byName.set(name, { name, description: command.description ?? "" });
+  }
+  return Array.from(byName.values()).sort((a, b) => a.name.localeCompare(b.name));
+}
+
 export function stripFrontmatter(markdown: string): string {
   const normalized = markdown.replace(/^\uFEFF/, "");
   const match = normalized.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/);