pi-skillful 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project follows the spirit of [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and uses semantic versioning for releases.
+
+## [Unreleased]
+
+### Added
+
+- Inline `/skill:name` expansion anywhere in a prompt.
+- `/skillful` menu for global/project skill prompt visibility.
+- `skillful.hiddenSkills` settings support.
+- Startup skill-list annotations for visible vs hidden skills.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,35 @@
+# Code of Conduct
+
+This project follows the Contributor Covenant Code of Conduct, version 2.1.
+
+## Our pledge
+
+We pledge to make participation in this project a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+## Our standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- demonstrating empathy and kindness toward other people;
+- being respectful of differing opinions, viewpoints, and experiences;
+- giving and gracefully accepting constructive feedback;
+- accepting responsibility and apologizing to those affected by mistakes;
+- focusing on what is best for the overall community.
+
+Examples of unacceptable behavior include:
+
+- sexualized language or imagery, and sexual attention or advances;
+- trolling, insulting or derogatory comments, and personal or political attacks;
+- public or private harassment;
+- publishing others' private information without explicit permission;
+- other conduct that could reasonably be considered inappropriate in a professional setting.
+
+## Enforcement
+
+Project maintainers are responsible for clarifying and enforcing standards of acceptable behavior and may remove, edit, or reject comments, commits, code, issues, and other contributions that are not aligned with this Code of Conduct.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainer through GitHub. All reports will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.

package/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing
+
+Thanks for your interest in contributing to `pi-skillful`.
+
+## Development setup
+
+```bash
+bun install
+bun run check
+```
+
+The package is source-distributed: Pi loads the TypeScript extension files directly. There is no build step for runtime use.
+
+## Local testing
+
+Install this checkout into a temporary Pi project:
+
+```bash
+mkdir -p <test-project>
+cd <test-project>
+pi install -l /path/to/pi-skillful
+pi
+```
+
+Then run `/skillful` inside Pi.
+
+For a one-off run without changing settings:
+
+```bash
+pi -e /path/to/pi-skillful/extensions/pi-skillful
+```
+
+## Pull request checklist
+
+Before opening a pull request:
+
+- Run `bun run check`.
+- Run `bun run pack:dry-run` and confirm the package contents are intentional.
+- Update `README.md` if user-facing behavior changes.
+- Update `CHANGELOG.md` for notable changes.
+- Keep examples and paths generic; do not commit machine-specific paths or credentials.
+
+## Coding guidelines
+
+- Keep extensions small and focused.
+- Prefer Pi's documented extension APIs and TUI primitives over private internals.
+- Preserve explicit skill invocation even when a skill is hidden from model auto-discovery.
+- Be careful when writing project settings. If `.pi/settings.json` would become empty after removing `skillful`, delete it instead.
+
+## Code of conduct
+
+This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jose Mocito
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# pi-skillful
+
+`pi-skillful` is a [Pi](https://github.com/badlogic/pi-mono) package that improves skill workflows.
+
+It currently provides two 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.
+
+> [!WARNING]
+> Pi packages can execute arbitrary code through extensions. Review package source before installing any third-party Pi package.
+
+## Features
+
+### Inline skill invocation
+
+Vanilla Pi expands `/skill:name` only when it appears at the beginning of the prompt. `pi-skillful` expands known skill markers anywhere in the prompt, including multiple skills:
+
+```text
+Use /skill:code-security and /skill:semgrep to review this change.
+```
+
+The extension replaces each known marker with that skill's `SKILL.md` content before Pi's built-in skill/template expansion runs.
+
+### Skill prompt visibility
+
+Hide skills from the `<available_skills>` section of the system prompt without editing each skill's `disable-model-invocation` frontmatter.
+
+Hidden skills:
+
+- are not advertised to the model for automatic skill selection;
+- remain loaded by Pi;
+- remain available for explicit invocation with `/skill:name`, including inline invocation.
+
+Configuration is stored under the `skillful` key in Pi settings:
+
+```json
+{
+  "skillful": {
+    "hiddenSkills": ["pdf", "xlsx"]
+  }
+}
+```
+
+Supported scopes:
+
+- Global: `~/.pi/agent/settings.json`
+- Project: `.pi/settings.json`
+
+Effective hidden skills are the union of global and project `hiddenSkills`.
+
+Open the menu with:
+
+```text
+/skillful
+```
+
+The menu lists all loaded skills alphabetically. Toggle a skill off to save it in the active scope's `hiddenSkills` list. Use the Global/Project tabs to choose which settings file to edit.
+
+Pi's startup `[Skills]` list is also annotated: visible skills are marked with a green dot, and hidden skills are marked with a dim red dot.
+
+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.
+
+## Installation
+
+Install from GitHub:
+
+```bash
+pi install git:github.com/jvm/pi-skillful
+```
+
+Install project-locally with Pi's `-l` flag:
+
+```bash
+pi install -l git:github.com/jvm/pi-skillful
+```
+
+During local development from this repository:
+
+```bash
+pi install /path/to/pi-skillful
+```
+
+For a one-off test run without installing:
+
+```bash
+pi -e /path/to/pi-skillful/extensions/pi-skillful
+```
+
+## Usage
+
+1. Start Pi in a project with this package installed.
+2. Run `/skillful`.
+3. Select the Global or Project tab.
+4. Toggle skills on/off.
+5. Send a prompt normally, or explicitly invoke hidden skills with `/skill:name` anywhere in the prompt.
+
+Example:
+
+```text
+Please analyze this using /skill:code-security, then summarize the risk.
+```
+
+## Development
+
+This package is source-distributed. Pi loads the TypeScript extensions directly via its extension loader.
+
+Requirements:
+
+- Node.js >= 20.6.0
+- Bun for local development commands
+
+Common commands:
+
+```bash
+bun install
+bun run check
+bun run pack:dry-run
+```
+
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for development workflow and pull request guidelines.
+
+## Security
+
+Please report security issues privately. See [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/SECURITY.md

@@ -0,0 +1,22 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are provided for the latest released version of `pi-skillful`.
+
+## Reporting a vulnerability
+
+Please do not open a public issue for suspected security vulnerabilities.
+
+Report privately by contacting the repository maintainer through GitHub. Include:
+
+- a description of the issue;
+- steps to reproduce;
+- affected versions or commits, if known;
+- any suggested mitigation.
+
+The maintainer will acknowledge reports as soon as practical and coordinate disclosure once a fix or mitigation is available.
+
+## Security model
+
+`pi-skillful` is a Pi package. Pi extensions execute with the same permissions as the local user running Pi. Users should review installed Pi packages and only install packages from sources they trust.

package/extensions/pi-skillful/index.ts

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

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "pi-skillful",
+  "version": "0.1.0",
+  "description": "Pi package with skill invocation and visibility improvements.",
+  "type": "module",
+  "license": "MIT",
+  "author": "jvm",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jvm/pi-skillful.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jvm/pi-skillful/issues"
+  },
+  "homepage": "https://github.com/jvm/pi-skillful#readme",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "skills"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/pi-skillful"
+    ]
+  },
+  "files": [
+    "extensions",
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    "CODE_OF_CONDUCT.md"
+  ],
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@mariozechner/pi-coding-agent": "^0.73.0",
+    "@mariozechner/pi-tui": "^0.73.0",
+    "@types/node": "^25.6.0",
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "pack:dry-run": "npm pack --dry-run"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.6.0"
+  }
+}

package/src/config.ts

@@ -0,0 +1,129 @@
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export type SkillfulScope = "global" | "project";
+
+export interface SkillfulSettings {
+  hiddenSkills: string[];
+}
+
+interface PiSettingsDocument {
+  skillful?: Partial<SkillfulSettings>;
+  [key: string]: unknown;
+}
+
+export const SKILLFUL_SETTINGS_KEY = "skillful";
+
+export function globalSettingsPath(): string {
+  return join(homedir(), ".pi", "agent", "settings.json");
+}
+
+export function projectSettingsPath(cwd: string): string {
+  return join(cwd, ".pi", "settings.json");
+}
+
+export function settingsPath(scope: SkillfulScope, cwd: string): string {
+  return scope === "global" ? globalSettingsPath() : projectSettingsPath(cwd);
+}
+
+export function normalizeSkillName(name: string): string {
+  return name.trim().replace(/^skill:/, "");
+}
+
+export function normalizeSkillNames(names: Iterable<string>): string[] {
+  return Array.from(
+    new Set(
+      Array.from(names)
+        .map(normalizeSkillName)
+        .filter((name) => name.length > 0)
+        .sort(),
+    ),
+  );
+}
+
+async function readSettingsDocument(path: string): Promise<PiSettingsDocument> {
+  try {
+    const raw = await readFile(path, "utf-8");
+    const parsed = JSON.parse(raw) as unknown;
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? (parsed as PiSettingsDocument) : {};
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      return {};
+    }
+    throw error;
+  }
+}
+
+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) };
+}
+
+export async function readScopedSkillfulSettings(cwd: string): Promise<Record<SkillfulScope, SkillfulSettings>> {
+  const [global, project] = await Promise.all([
+    readSkillfulSettings(globalSettingsPath()),
+    readSkillfulSettings(projectSettingsPath(cwd)),
+  ]);
+  return { global, project };
+}
+
+export async function readEffectiveHiddenSkills(cwd: string): Promise<Set<string>> {
+  const scoped = await readScopedSkillfulSettings(cwd);
+  return new Set([...scoped.global.hiddenSkills, ...scoped.project.hiddenSkills]);
+}
+
+export async function writeHiddenSkills(
+  scope: SkillfulScope,
+  cwd: string,
+  hiddenSkills: Iterable<string>,
+): Promise<SkillfulSettings> {
+  const path = settingsPath(scope, cwd);
+  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,
+    };
+  }
+
+  if (scope === "project" && Object.keys(document).length === 0) {
+    await unlinkIfExists(path);
+    return { hiddenSkills: updated };
+  }
+
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(document, null, 2)}\n`, "utf-8");
+  return { hiddenSkills: updated };
+}
+
+export async function updateHiddenSkills(
+  scope: SkillfulScope,
+  cwd: string,
+  updater: (current: string[]) => string[],
+): Promise<SkillfulSettings> {
+  const path = settingsPath(scope, cwd);
+  const current = await readSkillfulSettings(path);
+  return writeHiddenSkills(scope, cwd, updater(current.hiddenSkills));
+}
+
+async function unlinkIfExists(path: string): Promise<void> {
+  try {
+    await unlink(path);
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") return;
+    throw error;
+  }
+}

package/src/extensions/inline-skill-invocation.ts

@@ -0,0 +1,72 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { readSkillBlock, sourceInfoToSkill, type SkillCommandInfo } from "../skills.js";
+
+const SKILL_INVOCATION_PATTERN = /(^|[^\w/-])\/skill:([a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?)(?=$|[^a-z0-9-])/g;
+
+export default function inlineSkillInvocation(pi: ExtensionAPI) {
+  pi.on("input", async (event, ctx) => {
+    if (event.source === "extension" || !event.text.includes("/skill:")) {
+      return { action: "continue" };
+    }
+
+    const skillsByName = getSkillsByName(pi);
+    const invocations = findInvocations(event.text);
+    if (invocations.length === 0) return { action: "continue" };
+
+    const unknown = invocations.filter((invocation) => !skillsByName.has(invocation.name));
+    if (unknown.length > 0) {
+      ctx.ui.notify(
+        `Unknown skill invocation(s): ${Array.from(new Set(unknown.map((invocation) => invocation.name))).join(", ")}`,
+        "warning",
+      );
+    }
+
+    const blocks = new Map<string, string>();
+    for (const invocation of invocations) {
+      const skill = skillsByName.get(invocation.name);
+      if (!skill || blocks.has(invocation.name)) continue;
+
+      try {
+        blocks.set(invocation.name, await readSkillBlock(skill));
+      } catch (error) {
+        ctx.ui.notify(
+          `Failed to read skill ${invocation.name}: ${error instanceof Error ? error.message : String(error)}`,
+          "warning",
+        );
+      }
+    }
+
+    if (blocks.size === 0) return { action: "continue" };
+
+    const expanded = event.text.replace(SKILL_INVOCATION_PATTERN, (fullMatch: string, prefix: string, name: string) => {
+      const block = blocks.get(name);
+      return block ? `${prefix}\n\n${block}\n\n` : fullMatch;
+    });
+
+    return { action: "transform", text: normalizeBlankLines(expanded), images: event.images };
+  });
+
+}
+
+function getSkillsByName(pi: ExtensionAPI): Map<string, SkillCommandInfo> {
+  const result = new Map<string, SkillCommandInfo>();
+  for (const command of pi.getCommands()) {
+    if (command.source !== "skill") continue;
+    const skill = sourceInfoToSkill(command);
+    if (skill) result.set(skill.name, skill);
+  }
+  return result;
+}
+
+function findInvocations(text: string): Array<{ name: string }> {
+  const result: Array<{ name: string }> = [];
+  const pattern = new RegExp(SKILL_INVOCATION_PATTERN.source, "g");
+  for (const match of text.matchAll(pattern)) {
+    result.push({ name: match[2] });
+  }
+  return result;
+}
+
+function normalizeBlankLines(text: string): string {
+  return text.replace(/\n{4,}/g, "\n\n\n").trim();
+}

package/src/extensions/skill-visibility.ts

@@ -0,0 +1,296 @@
+import {
+  DynamicBorder,
+  formatSkillsForPrompt,
+  getSettingsListTheme,
+  InteractiveMode,
+  type ExtensionAPI,
+  type Skill,
+  type Theme,
+} from "@mariozechner/pi-coding-agent";
+import { type Component, Key, matchesKey, type SettingItem, SettingsList, truncateToWidth, type TUI } from "@mariozechner/pi-tui";
+import {
+  normalizeSkillName,
+  normalizeSkillNames,
+  readEffectiveHiddenSkills,
+  readScopedSkillfulSettings,
+  type SkillfulScope,
+  writeHiddenSkills,
+} from "../config.js";
+
+const SKILLS_SECTION_PATTERN = /\n\nThe following skills provide specialized instructions for specific tasks\.[\s\S]*?<\/available_skills>/;
+const SCOPES: SkillfulScope[] = ["global", "project"];
+const STORE_KEY = Symbol.for("pi-skillful.skillVisibilityStore");
+const STARTUP_SKILL_LIST_PATCH_KEY = Symbol.for("pi-skillful.startupSkillListPatchInstalled");
+
+interface SkillVisibilityStore {
+  hiddenSkillsByCwd: Map<string, Set<string>>;
+  lastHiddenSkills: Set<string>;
+}
+
+const skillVisibilityStore = (((globalThis as Record<PropertyKey, unknown>)[STORE_KEY] as SkillVisibilityStore | undefined) ??= {
+  hiddenSkillsByCwd: new Map<string, Set<string>>(),
+  lastHiddenSkills: new Set<string>(),
+}) as SkillVisibilityStore;
+
+interface SkillListItem {
+  name: string;
+  description: string;
+}
+
+export default function skillVisibility(pi: ExtensionAPI) {
+  installStartupSkillListPatch();
+
+  pi.on("session_start", async (_event, ctx) => {
+    await refreshHiddenSkillCache(ctx.cwd);
+  });
+
+  pi.on("before_agent_start", async (event, ctx) => {
+    const hidden = await refreshHiddenSkillCache(ctx.cwd);
+    if (hidden.size === 0 || !event.systemPromptOptions.skills?.length) return;
+
+    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) };
+  });
+
+  pi.registerCommand("skillful", {
+    description: "Open the pi-skillful skill visibility menu.",
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) {
+        ctx.ui.notify("/skillful requires interactive UI", "warning");
+        return;
+      }
+
+      const skills = getSkillItems(pi);
+      if (skills.length === 0) {
+        ctx.ui.notify("No skills are currently loaded.", "info");
+        return;
+      }
+
+      const scoped = await readScopedSkillfulSettings(ctx.cwd);
+      await ctx.ui.custom<void>((tui, theme, _keybindings, done) =>
+        new SkillfulVisibilityMenu({
+          cwd: ctx.cwd,
+          skills,
+          hiddenByScope: {
+            global: new Set(scoped.global.hiddenSkills),
+            project: new Set(scoped.project.hiddenSkills),
+          },
+          theme,
+          tui,
+          notify: (message, type) => ctx.ui.notify(message, type),
+          done,
+        }),
+      );
+    },
+  });
+}
+
+async function refreshHiddenSkillCache(cwd: string): Promise<Set<string>> {
+  const hidden = await readEffectiveHiddenSkills(cwd);
+  skillVisibilityStore.hiddenSkillsByCwd.set(cwd, hidden);
+  skillVisibilityStore.lastHiddenSkills = hidden;
+  return hidden;
+}
+
+function installStartupSkillListPatch(): void {
+  type StartupResourceLoader = {
+    getSkills: () => { skills: Skill[]; diagnostics: unknown[] };
+  };
+  type InteractiveModeWithStartupResources = {
+    showLoadedResources?: (options?: unknown) => void;
+    session?: { resourceLoader?: StartupResourceLoader };
+    sessionManager?: { getCwd?: () => string };
+  };
+
+  const prototype = (InteractiveMode as unknown as { prototype: InteractiveModeWithStartupResources }).prototype;
+  const patchState = prototype as InteractiveModeWithStartupResources & Record<PropertyKey, unknown>;
+  if (patchState[STARTUP_SKILL_LIST_PATCH_KEY]) return;
+
+  const original = prototype.showLoadedResources;
+  if (typeof original !== "function") return;
+
+  prototype.showLoadedResources = function showLoadedResourcesWithSkillfulVisibility(
+    this: InteractiveModeWithStartupResources,
+    options?: unknown,
+  ): void {
+    const loader = this.session?.resourceLoader;
+    const originalGetSkills = loader?.getSkills;
+    if (!loader || typeof originalGetSkills !== "function") {
+      original.call(this, options);
+      return;
+    }
+
+    const cwd = this.sessionManager?.getCwd?.();
+    const hidden = (cwd ? skillVisibilityStore.hiddenSkillsByCwd.get(cwd) : undefined) ?? skillVisibilityStore.lastHiddenSkills;
+
+    loader.getSkills = () => {
+      const result = originalGetSkills.call(loader);
+      return {
+        ...result,
+        skills: result.skills.map((skill) => ({
+          ...skill,
+          name: formatStartupSkillName(skill.name, hidden.has(skill.name)),
+        })),
+      };
+    };
+
+    try {
+      original.call(this, options);
+    } finally {
+      loader.getSkills = originalGetSkills;
+    }
+  };
+
+  patchState[STARTUP_SKILL_LIST_PATCH_KEY] = true;
+}
+
+function formatStartupSkillName(name: string, hidden: boolean): string {
+  return hidden ? `${name} \x1b[31;2m●\x1b[22;39m` : `${name} \x1b[32m●\x1b[39m`;
+}
+
+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));
+}
+
+class SkillfulVisibilityMenu implements Component {
+  private readonly cwd: string;
+  private readonly skills: SkillListItem[];
+  private readonly hiddenByScope: Record<SkillfulScope, Set<string>>;
+  private readonly theme: Theme;
+  private readonly tui: TUI;
+  private readonly notify: (message: string, type?: "info" | "warning" | "error") => void;
+  private readonly done: () => void;
+  private readonly topBorder: DynamicBorder;
+  private readonly bottomBorder: DynamicBorder;
+  private scope: SkillfulScope = "project";
+  private settingsList: SettingsList;
+  private saveQueue: Promise<void> = Promise.resolve();
+
+  constructor(options: {
+    cwd: string;
+    skills: SkillListItem[];
+    hiddenByScope: Record<SkillfulScope, Set<string>>;
+    theme: Theme;
+    tui: TUI;
+    notify: (message: string, type?: "info" | "warning" | "error") => void;
+    done: () => void;
+  }) {
+    this.cwd = options.cwd;
+    this.skills = options.skills;
+    this.hiddenByScope = options.hiddenByScope;
+    this.theme = options.theme;
+    this.tui = options.tui;
+    this.notify = options.notify;
+    this.done = options.done;
+    this.topBorder = new DynamicBorder((text: string) => this.theme.fg("accent", text));
+    this.bottomBorder = new DynamicBorder((text: string) => this.theme.fg("accent", text));
+    this.settingsList = this.createSettingsList();
+  }
+
+  render(width: number): string[] {
+    return [
+      ...this.topBorder.render(width),
+      truncateToWidth(`  ${this.theme.bold(this.theme.fg("accent", "pi-skillful"))}  ${this.renderTabs()}`, width),
+      truncateToWidth(this.theme.fg("dim", "  Toggle skills shown in the model-invocation system prompt"), width),
+      "",
+      ...this.settingsList.render(width),
+      "",
+      truncateToWidth(this.theme.fg("dim", "  Tab/←/→ switch global/project · Enter/Space toggle · Esc close"), width),
+      ...this.bottomBorder.render(width),
+    ];
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, Key.tab) || matchesKey(data, Key.right)) {
+      this.switchScope(1);
+      return;
+    }
+    if (matchesKey(data, Key.shift(Key.tab)) || matchesKey(data, Key.left)) {
+      this.switchScope(-1);
+      return;
+    }
+
+    this.settingsList.handleInput(data);
+    this.tui.requestRender();
+  }
+
+  invalidate(): void {
+    this.topBorder.invalidate();
+    this.bottomBorder.invalidate();
+    this.settingsList.invalidate();
+  }
+
+  private renderTabs(): string {
+    return SCOPES
+      .map((scope) => {
+        const label = scope === "global" ? "Global" : "Project";
+        return scope === this.scope
+          ? this.theme.bg("selectedBg", this.theme.fg("accent", ` ${label} `))
+          : this.theme.fg("muted", ` ${label} `);
+      })
+      .join(" ");
+  }
+
+  private switchScope(direction: 1 | -1): void {
+    const current = SCOPES.indexOf(this.scope);
+    this.scope = SCOPES[(current + direction + SCOPES.length) % SCOPES.length];
+    this.settingsList = this.createSettingsList();
+    this.tui.requestRender();
+  }
+
+  private createSettingsList(): SettingsList {
+    const items: SettingItem[] = this.skills.map((skill) => {
+      const hidden = this.hiddenByScope[this.scope].has(skill.name);
+      return {
+        id: skill.name,
+        label: skill.name,
+        description: skill.description || "No skill description provided.",
+        currentValue: hidden ? "off" : "on",
+        values: ["on", "off"],
+      };
+    });
+
+    return new SettingsList(
+      items,
+      12,
+      getSettingsListTheme(),
+      (skillName, newValue) => {
+        const hidden = this.hiddenByScope[this.scope];
+        if (newValue === "off") hidden.add(skillName);
+        else hidden.delete(skillName);
+        this.persistScope(this.scope);
+      },
+      this.done,
+      { enableSearch: true },
+    );
+  }
+
+  private persistScope(scope: SkillfulScope): void {
+    const snapshot = normalizeSkillNames(this.hiddenByScope[scope]);
+    this.saveQueue = this.saveQueue
+      .catch(() => undefined)
+      .then(async () => {
+        await writeHiddenSkills(scope, this.cwd, snapshot);
+        await refreshHiddenSkillCache(this.cwd);
+      })
+      .catch((error) => {
+        this.notify(`Failed to save ${scope} skill visibility: ${error instanceof Error ? error.message : String(error)}`, "error");
+      });
+  }
+}

package/src/skills.ts

@@ -0,0 +1,38 @@
+import { readFile } from "node:fs/promises";
+import { dirname } from "node:path";
+
+export interface SkillCommandInfo {
+  name: string;
+  path: string;
+  baseDir: string;
+}
+
+export function stripFrontmatter(markdown: string): string {
+  const normalized = markdown.replace(/^\uFEFF/, "");
+  const match = normalized.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/);
+  return match ? normalized.slice(match[0].length) : normalized;
+}
+
+export async function readSkillBlock(skill: SkillCommandInfo): Promise<string> {
+  const content = await readFile(skill.path, "utf-8");
+  const body = stripFrontmatter(content).trim();
+  return `<skill name="${escapeAttribute(skill.name)}" location="${escapeAttribute(skill.path)}">\nReferences are relative to ${skill.baseDir}.\n\n${body}\n</skill>`;
+}
+
+export function sourceInfoToSkill(command: {
+  name: string;
+  sourceInfo: { path: string; baseDir?: string };
+}): SkillCommandInfo | null {
+  if (!command.name.startsWith("skill:")) return null;
+  const name = command.name.slice("skill:".length);
+  if (!name) return null;
+  return {
+    name,
+    path: command.sourceInfo.path,
+    baseDir: command.sourceInfo.baseDir ?? dirname(command.sourceInfo.path),
+  };
+}
+
+function escapeAttribute(value: string): string {
+  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+}