pi-skillful 0.3.13 → 0.4.0

package/CHANGELOG.md

@@ -1,18 +1,24 @@
 # Changelog
 
-## 0.3.13 - 2026-07-17
+All notable changes to this project will be documented in this file.
 
-## 0.3.12 - 2026-07-12
+This project follows the spirit of [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and uses semantic versioning for releases.
 
-## 0.3.11 - 2026-07-01
+## [Unreleased]
 
-## 0.3.9 - 2026-06-14
+## [0.4.0] - 2026-07-28
 
-All notable changes to this project will be documented in this file.
+### Added
 
-This project follows the spirit of [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and uses semantic versioning for releases.
+- Progressive skill loading: discover `.agents/skills/` directories from all ancestor directories (like `AGENTS.md`), not just within the git repo boundary. Uses the `resources_discover` event to contribute missed paths.
 
-## [Unreleased]
+## [0.3.14] - 2026-07-17
+
+### Fixed
+
+- Restore red/dim coloring for hidden and visible skills in Pi's startup `[Skills]` list while preserving project-trust-aware settings.
+
+## [0.3.13] - 2026-07-17
 
 ### Fixed
 
@@ -20,16 +26,23 @@ This project follows the spirit of [Keep a Changelog](https://keepachangelog.com
 - Let an explicit project `toggleModifier: "alt"` override a non-default global modifier; unsupported explicit values now follow the documented `"alt"` fallback.
 - Consume only configured modifier-slot combinations in the prompt editor instead of registering all 54 possible shortcuts.
 - Propagate focus and custom-editor hooks through the session-toggle editor wrapper for IME and extension compatibility.
-- Remove the private `InteractiveMode.prototype` startup skill-list patch; visibility now uses only documented Pi APIs.
 - Remove the stale package-local `package-lock.json` in favor of the monorepo root lockfile.
-- Preserve configured hidden skills at session start. Skillful no longer treats a temporarily incomplete loaded-skill list as authoritative and removes global or project visibility settings.
 
-## [0.3.10] - 2026-07-01
+## [0.3.12] - 2026-07-13
 
 ### Fixed
 
-- Color hidden skills in the startup `[Skills]` list on `@earendil-works/pi-coding-agent` 0.80+. The 0.80 release moved the loaded-resources container out of `chatContainer`, so the existing prototype patch walked the wrong container and the red/dim colorization no longer applied. The patch now also walks `loadedResourcesContainer`, where 0.80 actually renders the `[Skills]` section.
-- Bumped dev dependency range to `^0.80.0` to match the new floor.
+- Preserve configured hidden skills at session start instead of pruning settings from a temporarily incomplete loaded-skill list.
+
+## [0.3.11] - 2026-07-01
+
+### Fixed
+
+- Color hidden skills in the startup `[Skills]` list on Pi 0.80+, which moved the rendered resources into `loadedResourcesContainer`.
+
+### Changed
+
+- Raise the Pi development dependency floor to `^0.80.0`.
 
 ## [0.3.9] - 2026-06-14
 

package/README.md

@@ -4,10 +4,11 @@
 
 # pi-skillful
 
-`pi-skillful` is a [Pi](https://pi.dev) package that improves skill workflows.
+Make [Pi](https://pi.dev) skills easier to invoke, curate, and control without editing their source files.
 
-It currently provides three extensions:
+`pi-skillful` provides four focused upgrades:
 
+- **Progressive skill loading**: discover `.agents/skills/` from every ancestor directory (like `AGENTS.md`), not just within the git repo boundary.
 - **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.
 - **Session skill toggles**: assign up to nine skills to number slots and toggle model visibility while writing a prompt.
@@ -17,6 +18,14 @@ It currently provides three extensions:
 
 ## Features
 
+### Progressive skill loading
+
+Pi discovers `.agents/skills/` directories in ancestor folders, but stops at the git repo root — skills above the repo boundary are invisible. `pi-skillful` removes that boundary by walking the full ancestor chain to the filesystem root, mirroring how `AGENTS.md` context files work.
+
+No configuration needed. When a git repo is detected, `pi-skillful` automatically contributes `.agents/skills/` directories from parent directories above the repo root (excluding `~/.agents/skills/`, which Pi already loads globally). In projects without a git repo, Pi already walks to the filesystem root and this feature has no effect.
+
+Skill name collisions follow Pi's first-wins rule: skills discovered closer to the working directory take precedence over skills with the same name found higher up.
+
 ### 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:
@@ -33,6 +42,7 @@ Hide skills from the `<available_skills>` section of the system prompt without e
 
 Hidden skills:
 
+- appear in the startup `[Skills]` list in the theme's error color, while visible skills appear dimmed;
 - 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.

package/SECURITY.md

@@ -20,3 +20,11 @@ The maintainer will acknowledge reports as soon as practical and coordinate disc
 ## 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.
+
+### Progressive skill loading and trust boundary
+
+`pi-skillful` extends Pi's skill discovery to ancestor directories above the git repository root, loading `.agents/skills/` from every parent directory up to the filesystem root (excluding `~/.agents/skills/`, which Pi already loads globally).
+
+This means skills placed in a shared or writable ancestor directory — for example, `/home/shared/.agents/skills/` or `/tmp/.agents/skills/` — are automatically available as skill instructions when Pi runs in any nested repository. Review the contents and ownership of `.agents/skills/` directories above your repositories, as they are now part of the effective skill set.
+
+To disable progressive loading without removing the package, uninstall `pi-skillful` or use Pi's built-in `--no-skills` flag to suppress all skill loading for a session.

package/extensions/index.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-skillful",
-  "version": "0.3.13",
+  "version": "0.4.0",
   "description": "Pi package with skill invocation and visibility improvements.",
   "type": "module",
   "exports": {
@@ -45,10 +45,10 @@
     "@earendil-works/pi-tui": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.80.0",
-    "@earendil-works/pi-tui": "^0.80.0",
-    "@types/node": "^26.1.0",
-    "typescript": "^6.0.3"
+    "@earendil-works/pi-coding-agent": "^0.80.10",
+    "@earendil-works/pi-tui": "^0.80.10",
+    "@types/node": "^26.1.1",
+    "typescript": "^7.0.2"
   },
   "scripts": {
     "check": "tsc --noEmit",

package/src/extensions/progressive-skills.ts

@@ -0,0 +1,55 @@
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Walks from cwd up through all ancestor directories (no git boundary)
+ * and discovers `.agents/skills/` directories that Pi's built-in discovery
+ * misses because it stops at the git repo root.
+ *
+ * This mirrors how AGENTS.md context files are loaded from every parent
+ * directory, not just within the repo boundary.
+ */
+export default function progressiveSkills(pi: ExtensionAPI) {
+  pi.on("resources_discover", async (event) => {
+    const gitRoot = findGitRoot(event.cwd);
+
+    // No git repo — Pi already walks to filesystem root, nothing to add.
+    if (!gitRoot) return;
+
+    const resolvedGitRoot = resolve(gitRoot);
+    const homeAgentsSkills = resolve(homedir(), ".agents", "skills");
+    const skillPaths: string[] = [];
+
+    // Walk from git root's parent up to filesystem root.
+    // Order: git-parent first (closer to cwd = higher priority via first-wins).
+    let dir = dirname(resolvedGitRoot);
+    while (true) {
+      const agentsSkills = join(dir, ".agents", "skills");
+      const resolved = resolve(agentsSkills);
+
+      // Skip ~/.agents/skills (handled globally by Pi) and non-existent dirs.
+      if (resolved !== homeAgentsSkills && existsSync(resolved)) {
+        skillPaths.push(resolved);
+      }
+
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+
+    if (skillPaths.length === 0) return;
+    return { skillPaths };
+  });
+}
+
+function findGitRoot(startDir: string): string | undefined {
+  let dir = resolve(startDir);
+  while (true) {
+    if (existsSync(join(dir, ".git"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}

package/src/extensions/skill-visibility.ts

@@ -1,6 +1,14 @@
-import { DynamicBorder, getSettingsListTheme, type ExtensionAPI, type Skill, type Theme } from "@earendil-works/pi-coding-agent";
+import {
+  DynamicBorder,
+  getSettingsListTheme,
+  InteractiveMode,
+  type ExtensionAPI,
+  type Skill,
+  type Theme,
+} from "@earendil-works/pi-coding-agent";
 import { type Component, Key, matchesKey, type SettingItem, SettingsList, truncateToWidth, type TUI } from "@earendil-works/pi-tui";
 import {
+  normalizeSkillName,
   normalizeSkillNames,
   readEffectiveHiddenSkills,
   readScopedSkillfulSettings,
@@ -15,6 +23,34 @@ import { replaceSkillsSection } from "../skill-prompt.js";
 import { isTopLevelSkill, listLoadedSkills, type LoadedSkillInfo } from "../skills.js";
 import { hasActiveSessionSkillToggles, refreshSessionSkillToggles } from "./session-skill-toggles.js";
 const SCOPES: SkillfulScope[] = ["global", "project"];
+const STORE_KEY = Symbol.for("pi-skillful.skillVisibilityStore");
+const STARTUP_PATCH_KEY = Symbol.for("pi-skillful.startupPatchV3");
+
+interface SkillVisibilityStore {
+  hiddenSkillsByCwd: Map<string, Set<string>>;
+  theme: Theme | null;
+}
+
+interface ExpandableTextLike {
+  getCollapsedText: () => string;
+  setText: (text: string) => void;
+}
+
+interface BoxLike {
+  children: unknown[];
+}
+
+interface InteractiveModeLike {
+  loadedResourcesContainer?: BoxLike;
+  showLoadedResources?: (options?: unknown) => void;
+  session?: { resourceLoader?: { getSkills: () => { skills: Skill[]; diagnostics: unknown[] } } };
+  sessionManager?: { getCwd?: () => string };
+}
+
+const store = (((globalThis as Record<PropertyKey, unknown>)[STORE_KEY] as SkillVisibilityStore | undefined) ??= {
+  hiddenSkillsByCwd: new Map<string, Set<string>>(),
+  theme: null,
+}) as SkillVisibilityStore;
 
 type SkillListItem = LoadedSkillInfo;
 type HiddenSkillsByScope = Record<SkillfulScope, Set<string>>;
@@ -44,14 +80,17 @@ interface SettingsListSelectionView {
 }
 
 export default function skillVisibility(pi: ExtensionAPI) {
+  installStartupSkillListPatch();
+
   pi.on("session_start", async (_event, ctx) => {
-    await readEffectiveHiddenSkills(ctx.cwd, ctx.isProjectTrusted());
+    store.theme = ctx.ui.theme;
+    await refreshHiddenSkillCache(ctx.cwd, ctx.isProjectTrusted());
   });
 
   pi.on("before_agent_start", async (event, ctx) => {
     if (hasActiveSessionSkillToggles()) return;
 
-    const hidden = await readEffectiveHiddenSkills(ctx.cwd, ctx.isProjectTrusted());
+    const hidden = await refreshHiddenSkillCache(ctx.cwd, ctx.isProjectTrusted());
     if (hidden.size === 0 || !event.systemPromptOptions.skills?.length) return;
 
     const filteredSkills: Skill[] = event.systemPromptOptions.skills.map((skill) =>
@@ -110,6 +149,76 @@ export default function skillVisibility(pi: ExtensionAPI) {
   });
 }
 
+async function refreshHiddenSkillCache(cwd: string, projectTrusted: boolean): Promise<Set<string>> {
+  const hidden = await readEffectiveHiddenSkills(cwd, projectTrusted);
+  store.hiddenSkillsByCwd.set(cwd, hidden);
+  return hidden;
+}
+
+// Pi has no public hook for styling the built-in startup resource list, so patch the
+// prototype from Pi's own module and keep the workaround isolated here.
+export function installStartupSkillListPatch(
+  realPrototype: InteractiveModeLike = (InteractiveMode as unknown as { prototype: InteractiveModeLike }).prototype,
+): void {
+  if (!realPrototype) return;
+
+  const patchState = realPrototype as Record<PropertyKey, unknown>;
+  if (patchState[STARTUP_PATCH_KEY]) return;
+
+  const original = realPrototype.showLoadedResources;
+  if (typeof original !== "function") return;
+
+  realPrototype.showLoadedResources = function (this: InteractiveModeLike, 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?.();
+    let rawSkillNames: string[] = [];
+    loader.getSkills = () => {
+      const result = originalGetSkills.call(loader);
+      rawSkillNames = result.skills.map((skill) => normalizeSkillName(skill.name));
+      return result;
+    };
+
+    const childrenBefore = this.loadedResourcesContainer?.children.length ?? 0;
+    try {
+      original.call(this, options);
+    } finally {
+      loader.getSkills = originalGetSkills;
+    }
+
+    if (rawSkillNames.length === 0 || !cwd || !this.loadedResourcesContainer) return;
+
+    const hidden = store.hiddenSkillsByCwd.get(cwd) ?? new Set<string>();
+    const children = this.loadedResourcesContainer.children;
+    for (let index = childrenBefore; index < children.length; index++) {
+      const child = children[index] as ExpandableTextLike | undefined;
+      if (!child || typeof child.getCollapsedText !== "function") continue;
+      if (!child.getCollapsedText().includes("[Skills]")) continue;
+
+      const colorized = buildColorizedSkillList(rawSkillNames, hidden, store.theme);
+      child.getCollapsedText = () => colorized;
+      child.setText(colorized);
+      break;
+    }
+  };
+
+  patchState[STARTUP_PATCH_KEY] = true;
+}
+
+export function buildColorizedSkillList(names: string[], hidden: Set<string>, theme: Theme | null): string {
+  const sorted = [...names].sort((a, b) => a.localeCompare(b));
+  if (!theme) return `[Skills]\n  ${sorted.join(", ")}`;
+
+  const header = theme.fg("mdHeading", "[Skills]");
+  const parts = sorted.map((name) => (hidden.has(name) ? theme.fg("error", name) : theme.fg("dim", name)));
+  return `${header}\n  ${parts.join(", ")}`;
+}
+
 function getSkillItems(pi: ExtensionAPI): SkillListItem[] {
   return listLoadedSkills(pi.getCommands()).filter(isTopLevelSkill);
 }
@@ -331,7 +440,7 @@ class SkillfulVisibilityMenu implements Component {
       .then(async () => {
         if (scope === "project") await this.writeProjectOverrideOrInheritance();
         else await writeHiddenSkills(scope, this.cwd, hiddenSnapshot);
-        await readEffectiveHiddenSkills(this.cwd, this.projectTrusted);
+        await refreshHiddenSkillCache(this.cwd, this.projectTrusted);
       })
       .catch((error) => {
         this.notify(`Failed to save ${scope} skill visibility: ${error instanceof Error ? error.message : String(error)}`, "error");