@agimon-ai/po-skill 0.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vuong Ngo
+
+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,40 @@
+# @agimon-ai/po-skill
+
+The session skill catalog for [Po](https://www.npmjs.com/package/@agimon-ai/po).
+
+Pi loads skills from the directories it is given at startup. Po adds two things on top: skills
+that are discovered lazily rather than loaded eagerly, and a registry where other extensions
+publish their own skill directories.
+
+## Deferred discovery
+
+Scanning every skill directory is the slowest thing this package does, so it does not block the
+session. Discovery starts on `session_start` as a numbered generation and is awaited only when
+something needs the result. A reload starts a new generation; a snapshot that arrives from a
+superseded one is discarded rather than shown, which is what keeps a fast reload from printing stale
+diagnostics.
+
+## Contributing skill directories
+
+The package provides the session-owned `doom/skill-sources` Cordis service from
+`@agimon-ai/po-core/skills`. Extensions register their directories inside
+`ctx.inject([DOOM_SKILL_SOURCES_SERVICE], ...)`; the returned handle is disposed automatically when
+either the contributor or provider unloads. Contributions are keyed by source, so a replacement
+generation takes the previous package slot without doubling it.
+
+## Help guidance
+
+While the Help minor mode is active, this package contributes `po-author-skill` for creating
+and distributing skills and `po-use-skill` for browsing, invoking, and diagnosing them. Both
+prompts are published under `src/prompts` and routed through this package's [`llms.txt`](./llms.txt).
+
+## Installation
+
+Po depends on this package and activates it as fixed host core, so a Po install already has
+it. It is not selectable from `.po/modes.yaml`.
+
+## License
+
+MIT
+
+Plugin entries live in `src/extensions`, host events and commands in routed surfaces, and catalog and discovery logic in named `src/services` folders. `src/exports` contains public helpers and types. The server awaits its async declaration factory to discover named skill commands before registration and startup.

package/dist/apiContracts.cjs

@@ -0,0 +1,17 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+//#region src/schemas/apiContracts.ts
+/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */
+const apiContracts = (0, require("@agimon-ai/po-core/apiContracts").defineApiContract)({
+	version: 1,
+	http: [],
+	sockets: [],
+	dynamic: []
+});
+//#endregion
+exports.apiContracts = apiContracts;
+exports.default = apiContracts;
+
+//# sourceMappingURL=apiContracts.cjs.map

package/dist/apiContracts.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiContracts.cjs","names":["defineApiContract"],"sources":["../src/schemas/apiContracts.ts"],"sourcesContent":["import { defineApiContract } from '@agimon-ai/po-core/apiContracts';\n\n/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */\nexport const apiContracts = defineApiContract({ version: 1, http: [], sockets: [], dynamic: [] });\nexport default apiContracts;\n"],"mappings":";;;;;;AAGA,MAAa,gBAAA,4CAAeA,CAAAA,CAAAA,kBAAAA,CAAkB;CAAE,SAAS;CAAG,MAAM,CAAC;CAAG,SAAS,CAAC;CAAG,SAAS,CAAC;AAAE,CAAC"}

package/dist/apiContracts.d.mts

@@ -0,0 +1,53 @@
+//#region src/schemas/apiContracts.d.ts
+/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */
+export declare const apiContracts: {
+  version: 1;
+  protocols?: Record<string, string> | undefined;
+  schemas?: Record<string, boolean | object> | undefined;
+  http: {
+    id: string;
+    scope: "global" | "session" | "workspace";
+    basePath?: string | undefined;
+    path: string;
+    method: "DELETE" | "GET" | "HEAD" | "OPTIONS" | "PATCH" | "POST" | "PUT";
+    description: string;
+    availability?: string | undefined;
+    authentication: "device" | "none" | "owner";
+    parameters?: {
+      name: string;
+      in: "header" | "path" | "query";
+      required: boolean;
+      schema: boolean | object;
+    }[] | undefined;
+    body?: {
+      contentType: string;
+      contentTypes?: string[] | undefined;
+      required: boolean;
+      schema: boolean | object;
+    } | undefined;
+    responses: Record<string, {
+      description: string;
+      contentType?: string | undefined;
+      schema?: boolean | object | undefined;
+      events?: Record<string, boolean | object> | undefined;
+    }>;
+  }[];
+  sockets: {
+    id: string;
+    scope: "global" | "session" | "workspace";
+    description: string;
+    availability?: string | undefined;
+    service: string;
+    member: string;
+    direction: "client-to-server" | "server-to-client";
+    kind: "channel" | "method" | "state";
+    input: boolean | object;
+    output?: boolean | object | undefined;
+    errors?: boolean | object | undefined;
+  }[];
+  dynamic: string[];
+  gaps?: string[] | undefined;
+};
+//#endregion
+export { apiContracts as default };
+//# sourceMappingURL=apiContracts.d.mts.map

package/dist/apiContracts.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiContracts.d.mts","names":[],"sources":["../src/schemas/apiContracts.ts"],"mappings":";;qBAGa"}

package/dist/apiContracts.mjs

@@ -0,0 +1,13 @@
+import { defineApiContract } from "@agimon-ai/po-core/apiContracts";
+//#region src/schemas/apiContracts.ts
+/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */
+const apiContracts = defineApiContract({
+	version: 1,
+	http: [],
+	sockets: [],
+	dynamic: []
+});
+//#endregion
+export { apiContracts, apiContracts as default };
+
+//# sourceMappingURL=apiContracts.mjs.map

package/dist/apiContracts.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiContracts.mjs","names":[],"sources":["../src/schemas/apiContracts.ts"],"sourcesContent":["import { defineApiContract } from '@agimon-ai/po-core/apiContracts';\n\n/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */\nexport const apiContracts = defineApiContract({ version: 1, http: [], sockets: [], dynamic: [] });\nexport default apiContracts;\n"],"mappings":";;;AAGA,MAAa,eAAe,kBAAkB;CAAE,SAAS;CAAG,MAAM,CAAC;CAAG,SAAS,CAAC;CAAG,SAAS,CAAC;AAAE,CAAC"}

package/dist/catalog.cjs

@@ -0,0 +1,186 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_rolldown_runtime = require("./rolldown-runtime-VH7oDXx4.cjs");
+let node_fs = require("node:fs");
+node_fs = require_rolldown_runtime.__toESM(node_fs, 1);
+let node_path = require("node:path");
+node_path = require_rolldown_runtime.__toESM(node_path, 1);
+let _agimon_ai_po_config_domains = require("@agimon-ai/po-config/domains");
+let _agimon_ai_po_domain_plugins = require("@agimon-ai/po-domain/plugins");
+let _earendil_works_pi_coding_agent = require("@earendil-works/pi-coding-agent");
+//#region src/services/skillCatalog/index.ts
+const SKILLS_DIRECTORY = "skills";
+const SHARED_SKILLS_OWNER = ".claude/skills";
+/**
+* The tokenizer, loaded on first use rather than at import.
+*
+* `gpt-tokenizer` carries its whole vocabulary and costs about a tenth of a
+* second to load. This module is reachable from the skills extension, which Pi
+* loads at session start, so a top-level import would charge every session for
+* a surface most of them never open.
+*/
+let tokenizer;
+async function counter() {
+	tokenizer ??= import("gpt-tokenizer");
+	return (await tokenizer).countTokens;
+}
+/**
+* Matches a directory against the active set.
+*
+* A domain that lists a plugin subset puts individual skill directories in the
+* set rather than the plugin's `skills` root, so containment has to be checked
+* both ways: the set may hold an ancestor of the directory, or a descendant of
+* it.
+*/
+function createActiveMatcher(directories) {
+	const active = directories.map((directory) => node_path.default.resolve(directory));
+	return (directory) => {
+		const resolved = node_path.default.resolve(directory);
+		return active.some((entry) => entry === resolved || entry.startsWith(`${resolved}${node_path.default.sep}`) || resolved.startsWith(`${entry}${node_path.default.sep}`));
+	};
+}
+function collect(directory, group, owner, isActive, loaded, diagnostics, discovery = "recursive") {
+	const result = (0, _earendil_works_pi_coding_agent.loadSkillsFromDir)({
+		dir: directory,
+		source: owner
+	});
+	for (const diagnostic of result.diagnostics) diagnostics.push(`${diagnostic.path ?? directory}: ${diagnostic.message}`);
+	const root = node_path.default.resolve(directory);
+	const kept = result.skills.filter((skill) => {
+		const skillDirectory = node_path.default.dirname(skill.filePath);
+		if (discovery === "direct-children" && node_path.default.dirname(skillDirectory) !== root) return false;
+		return isActive(skillDirectory);
+	});
+	loaded.push(...kept);
+	return kept.map((skill) => ({
+		name: skill.name,
+		description: skill.description,
+		filePath: skill.filePath,
+		baseDir: skill.baseDir,
+		group,
+		owner,
+		modelInvocable: !skill.disableModelInvocation
+	})).sort((left, right) => left.name.localeCompare(right.name));
+}
+function sortOwners(owners) {
+	return owners.sort((left, right) => left.owner.localeCompare(right.owner));
+}
+function collectHelpSkills(skills, loaded, diagnostics) {
+	const occupiedNames = new Set(loaded.map((skill) => skill.name));
+	const owners = /* @__PURE__ */ new Map();
+	const candidates = [...skills].sort((left, right) => left.sourceInfo.source.localeCompare(right.sourceInfo.source) || left.name.localeCompare(right.name) || left.filePath.localeCompare(right.filePath));
+	for (const skill of candidates) {
+		if (occupiedNames.has(skill.name)) {
+			diagnostics.push(`Help ${skill.sourceInfo.source} [HELP_SKILL_COLLISION]: '${skill.name}' was ignored because a normal skill wins.`);
+			continue;
+		}
+		occupiedNames.add(skill.name);
+		loaded.push(skill);
+		const owner = skill.sourceInfo.source;
+		const entries = owners.get(owner) ?? [];
+		entries.push({
+			name: skill.name,
+			description: skill.description,
+			filePath: skill.filePath,
+			baseDir: skill.baseDir,
+			group: "help",
+			owner,
+			modelInvocable: !skill.disableModelInvocation
+		});
+		owners.set(owner, entries);
+	}
+	return sortOwners([...owners.entries()].map(([owner, entries]) => ({
+		owner,
+		skills: entries.sort((left, right) => left.name.localeCompare(right.name))
+	})));
+}
+/**
+* Every skill this session actually loaded, grouped by where it comes from,
+* priced in tokens.
+*
+* Discovery runs over `loadSkillsFromDir` from Pi rather than the harness's own
+* walker so the listing matches what Pi would load, including its ignore-file
+* handling; the same skills are then handed to Pi's `formatSkillsForPrompt` so
+* the always-on figure is the real prompt block rather than a reconstruction of
+* it.
+*/
+async function buildSkillCatalog(options) {
+	const { repoRoot } = options;
+	const isActive = createActiveMatcher(options.activeSkillDirectories);
+	const diagnostics = [...options.helpDiagnostics ?? []];
+	const loaded = [];
+	const extensionOwners = [];
+	for (const entry of options.extensionSources) {
+		const skills = entry.directories.flatMap((directory) => collect(directory, "extensions", entry.source, () => true, loaded, diagnostics));
+		if (skills.length > 0) extensionOwners.push({
+			owner: entry.source,
+			skills
+		});
+	}
+	const pluginOwners = [];
+	const domainPlugins = await (0, _agimon_ai_po_domain_plugins.materializePluginEntries)((0, _agimon_ai_po_config_domains.resolvePluginEntries)(repoRoot, (0, _agimon_ai_po_config_domains.listDomainNames)(repoRoot), []));
+	for (const entry of domainPlugins) {
+		const directory = node_path.default.join(entry.directory, SKILLS_DIRECTORY);
+		if (!node_fs.default.existsSync(directory)) continue;
+		const owner = node_path.default.basename(entry.directory);
+		const skills = collect(directory, "plugins", owner, isActive, loaded, diagnostics, entry.skillDiscovery);
+		if (skills.length > 0) pluginOwners.push({
+			owner,
+			skills
+		});
+	}
+	const sharedSkills = collect(node_path.default.join(repoRoot, ".claude", SKILLS_DIRECTORY), "default", SHARED_SKILLS_OWNER, isActive, loaded, diagnostics);
+	const defaultOwners = sharedSkills.length > 0 ? [{
+		owner: SHARED_SKILLS_OWNER,
+		skills: sharedSkills
+	}] : [];
+	const helpOwners = collectHelpSkills(options.helpSkills ?? [], loaded, diagnostics);
+	const groups = [
+		{
+			key: "extensions",
+			label: "extensions",
+			owners: sortOwners(extensionOwners)
+		},
+		{
+			key: "help",
+			label: "Help",
+			owners: helpOwners
+		},
+		{
+			key: "plugins",
+			label: "plugins",
+			owners: sortOwners(pluginOwners)
+		},
+		{
+			key: "default",
+			label: "default",
+			owners: defaultOwners
+		}
+	];
+	const countTokens = await counter();
+	const prompt = (0, _earendil_works_pi_coding_agent.formatSkillsForPrompt)(loaded);
+	const framingTokens = countTokens((0, _earendil_works_pi_coding_agent.formatSkillsForPrompt)([]));
+	const marginal = /* @__PURE__ */ new Map();
+	for (const skill of loaded) marginal.set(skill.name, Math.max(0, countTokens((0, _earendil_works_pi_coding_agent.formatSkillsForPrompt)([skill])) - framingTokens));
+	for (const group of groups) for (const owner of group.owners) for (const skill of owner.skills) {
+		const tokens = marginal.get(skill.name);
+		if (tokens !== void 0) skill.promptTokens = tokens;
+	}
+	let bodyTokens = 0;
+	for (const skill of loaded) try {
+		bodyTokens += countTokens(node_fs.default.readFileSync(skill.filePath, "utf8"));
+	} catch (error) {
+		diagnostics.push(`${skill.filePath}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	return {
+		groups,
+		skillCount: loaded.length,
+		promptTokens: prompt ? countTokens(prompt) : 0,
+		bodyTokens,
+		diagnostics
+	};
+}
+//#endregion
+exports.buildSkillCatalog = buildSkillCatalog;
+exports.counter = counter;
+
+//# sourceMappingURL=catalog.cjs.map

package/dist/catalog.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.cjs","names":["path","loadSkillsFromDir","materializePluginEntries","resolvePluginEntries","listDomainNames","fs","formatSkillsForPrompt"],"sources":["../src/services/skillCatalog/index.ts"],"sourcesContent":["import fs from 'node:fs';\nimport path from 'node:path';\n\nimport { listDomainNames, type PluginSkillDiscovery, resolvePluginEntries } from '@agimon-ai/po-config/domains';\nimport type { SkillSourceContribution } from '@agimon-ai/po-core/skills';\nimport { materializePluginEntries } from '@agimon-ai/po-domain/plugins';\nimport { formatSkillsForPrompt, loadSkillsFromDir, type Skill } from '@earendil-works/pi-coding-agent';\n\nconst SKILLS_DIRECTORY = 'skills';\nconst SHARED_SKILLS_OWNER = '.claude/skills';\n\nexport type SkillGroupKey = 'extensions' | 'help' | 'plugins' | 'default';\n\nexport interface SkillEntry {\n  name: string;\n  description: string;\n  filePath: string;\n  baseDir: string;\n  group: SkillGroupKey;\n  /** Package name for an extension, plugin directory name, or `.claude/skills`. */\n  owner: string;\n  modelInvocable: boolean;\n  /**\n   * What removing this skill would save from the `<available_skills>` block.\n   *\n   * Marginal rather than proportional: the block has fixed framing that no\n   * single skill pays for, so the useful figure is what actually goes away.\n   * Bodies are excluded because they load on demand and are not a resting cost.\n   */\n  promptTokens?: number;\n}\n\nexport interface SkillOwnerNode {\n  owner: string;\n  skills: SkillEntry[];\n}\n\nexport interface SkillGroup {\n  key: SkillGroupKey;\n  label: string;\n  owners: SkillOwnerNode[];\n}\n\nexport interface SkillCatalog {\n  groups: SkillGroup[];\n  skillCount: number;\n  /** Tokens the `<available_skills>` prompt block costs on every request. */\n  promptTokens: number;\n  /** Tokens every loaded SKILL.md costs in full, if all of them were read. */\n  bodyTokens: number;\n  /** Frontmatter and read failures, surfaced instead of thrown. */\n  diagnostics: string[];\n}\n\nexport interface SkillCatalogOptions {\n  repoRoot: string;\n  /** Exact files the current selection resolved to, from `HarnessState.skillDirectories`. */\n  activeSkillDirectories: readonly string[];\n  extensionSources: readonly SkillSourceContribution[];\n  /** Activation-gated wrappers already accepted by the merged active-skill view. */\n  helpSkills?: readonly Skill[];\n  /** Bounded Help activation and collision diagnostics. */\n  helpDiagnostics?: readonly string[];\n}\n\n/**\n * The tokenizer, loaded on first use rather than at import.\n *\n * `gpt-tokenizer` carries its whole vocabulary and costs about a tenth of a\n * second to load. This module is reachable from the skills extension, which Pi\n * loads at session start, so a top-level import would charge every session for\n * a surface most of them never open.\n */\nlet tokenizer: Promise<typeof import('gpt-tokenizer')> | undefined;\n\nexport async function counter(): Promise<(text: string) => number> {\n  tokenizer ??= import('gpt-tokenizer');\n  return (await tokenizer).countTokens;\n}\n\n/**\n * Matches a directory against the active set.\n *\n * A domain that lists a plugin subset puts individual skill directories in the\n * set rather than the plugin's `skills` root, so containment has to be checked\n * both ways: the set may hold an ancestor of the directory, or a descendant of\n * it.\n */\nfunction createActiveMatcher(directories: readonly string[]): (directory: string) => boolean {\n  const active = directories.map((directory) => path.resolve(directory));\n  return (directory) => {\n    const resolved = path.resolve(directory);\n    return active.some(\n      (entry) =>\n        entry === resolved || entry.startsWith(`${resolved}${path.sep}`) || resolved.startsWith(`${entry}${path.sep}`),\n    );\n  };\n}\n\nfunction collect(\n  directory: string,\n  group: SkillGroupKey,\n  owner: string,\n  isActive: (directory: string) => boolean,\n  loaded: Skill[],\n  diagnostics: string[],\n  discovery: PluginSkillDiscovery = 'recursive',\n): SkillEntry[] {\n  const result = loadSkillsFromDir({ dir: directory, source: owner });\n  for (const diagnostic of result.diagnostics) {\n    diagnostics.push(`${diagnostic.path ?? directory}: ${diagnostic.message}`);\n  }\n  // Checked per skill, not per root: a subset domain selects some of a plugin's\n  // skills and leaves the rest on disk, unloaded and therefore not listed.\n  const root = path.resolve(directory);\n  const kept = result.skills.filter((skill) => {\n    const skillDirectory = path.dirname(skill.filePath);\n    if (discovery === 'direct-children' && path.dirname(skillDirectory) !== root) return false;\n    return isActive(skillDirectory);\n  });\n  // Kept in their loaded form as well, because the prompt-block cost is measured\n  // by handing them back to Pi's own formatter.\n  loaded.push(...kept);\n  return kept\n    .map((skill) => ({\n      name: skill.name,\n      description: skill.description,\n      filePath: skill.filePath,\n      baseDir: skill.baseDir,\n      group,\n      owner,\n      modelInvocable: !skill.disableModelInvocation,\n    }))\n    .sort((left, right) => left.name.localeCompare(right.name));\n}\n\nfunction sortOwners(owners: SkillOwnerNode[]): SkillOwnerNode[] {\n  return owners.sort((left, right) => left.owner.localeCompare(right.owner));\n}\n\nfunction collectHelpSkills(skills: readonly Skill[], loaded: Skill[], diagnostics: string[]): SkillOwnerNode[] {\n  const occupiedNames = new Set(loaded.map((skill) => skill.name));\n  const owners = new Map<string, SkillEntry[]>();\n  const candidates = [...skills].sort(\n    (left, right) =>\n      left.sourceInfo.source.localeCompare(right.sourceInfo.source) ||\n      left.name.localeCompare(right.name) ||\n      left.filePath.localeCompare(right.filePath),\n  );\n  for (const skill of candidates) {\n    if (occupiedNames.has(skill.name)) {\n      diagnostics.push(\n        `Help ${skill.sourceInfo.source} [HELP_SKILL_COLLISION]: '${skill.name}' was ignored because a normal skill wins.`,\n      );\n      continue;\n    }\n    occupiedNames.add(skill.name);\n    loaded.push(skill);\n    const owner = skill.sourceInfo.source;\n    const entries = owners.get(owner) ?? [];\n    entries.push({\n      name: skill.name,\n      description: skill.description,\n      filePath: skill.filePath,\n      baseDir: skill.baseDir,\n      group: 'help',\n      owner,\n      modelInvocable: !skill.disableModelInvocation,\n    });\n    owners.set(owner, entries);\n  }\n  return sortOwners(\n    [...owners.entries()].map(([owner, entries]) => ({\n      owner,\n      skills: entries.sort((left, right) => left.name.localeCompare(right.name)),\n    })),\n  );\n}\n\n/**\n * Every skill this session actually loaded, grouped by where it comes from,\n * priced in tokens.\n *\n * Discovery runs over `loadSkillsFromDir` from Pi rather than the harness's own\n * walker so the listing matches what Pi would load, including its ignore-file\n * handling; the same skills are then handed to Pi's `formatSkillsForPrompt` so\n * the always-on figure is the real prompt block rather than a reconstruction of\n * it.\n */\nexport async function buildSkillCatalog(options: SkillCatalogOptions): Promise<SkillCatalog> {\n  const { repoRoot } = options;\n  const isActive = createActiveMatcher(options.activeSkillDirectories);\n  const diagnostics: string[] = [...(options.helpDiagnostics ?? [])];\n  const loaded: Skill[] = [];\n\n  const extensionOwners: SkillOwnerNode[] = [];\n  for (const entry of options.extensionSources) {\n    const skills = entry.directories.flatMap((directory) =>\n      collect(directory, 'extensions', entry.source, () => true, loaded, diagnostics),\n    );\n    if (skills.length > 0) extensionOwners.push({ owner: entry.source, skills });\n  }\n\n  const pluginOwners: SkillOwnerNode[] = [];\n  const domainPlugins = await materializePluginEntries(resolvePluginEntries(repoRoot, listDomainNames(repoRoot), []));\n  for (const entry of domainPlugins) {\n    const directory = path.join(entry.directory, SKILLS_DIRECTORY);\n    if (!fs.existsSync(directory)) continue;\n    const owner = path.basename(entry.directory);\n    const skills = collect(directory, 'plugins', owner, isActive, loaded, diagnostics, entry.skillDiscovery);\n    if (skills.length > 0) pluginOwners.push({ owner, skills });\n  }\n\n  const sharedDirectory = path.join(repoRoot, '.claude', SKILLS_DIRECTORY);\n  const sharedSkills = collect(sharedDirectory, 'default', SHARED_SKILLS_OWNER, isActive, loaded, diagnostics);\n  const defaultOwners = sharedSkills.length > 0 ? [{ owner: SHARED_SKILLS_OWNER, skills: sharedSkills }] : [];\n  const helpOwners = collectHelpSkills(options.helpSkills ?? [], loaded, diagnostics);\n\n  const groups: SkillGroup[] = [\n    { key: 'extensions', label: 'extensions', owners: sortOwners(extensionOwners) },\n    { key: 'help', label: 'Help', owners: helpOwners },\n    { key: 'plugins', label: 'plugins', owners: sortOwners(pluginOwners) },\n    { key: 'default', label: 'default', owners: defaultOwners },\n  ];\n\n  const countTokens = await counter();\n  const prompt = formatSkillsForPrompt(loaded);\n  const framingTokens = countTokens(formatSkillsForPrompt([]));\n  const marginal = new Map<string, number>();\n  for (const skill of loaded) {\n    marginal.set(skill.name, Math.max(0, countTokens(formatSkillsForPrompt([skill])) - framingTokens));\n  }\n  for (const group of groups) {\n    for (const owner of group.owners) {\n      for (const skill of owner.skills) {\n        const tokens = marginal.get(skill.name);\n        if (tokens !== undefined) skill.promptTokens = tokens;\n      }\n    }\n  }\n  let bodyTokens = 0;\n  for (const skill of loaded) {\n    try {\n      bodyTokens += countTokens(fs.readFileSync(skill.filePath, 'utf8'));\n    } catch (error) {\n      diagnostics.push(`${skill.filePath}: ${error instanceof Error ? error.message : String(error)}`);\n    }\n  }\n\n  return {\n    groups,\n    skillCount: loaded.length,\n    promptTokens: prompt ? countTokens(prompt) : 0,\n    bodyTokens,\n    diagnostics,\n  };\n}\n\n/** The skills a name resolves to, used to decide what `enter` can invoke. */\nexport function findSkill(catalog: SkillCatalog, name: string): SkillEntry | undefined {\n  for (const group of catalog.groups) {\n    for (const owner of group.owners) {\n      const match = owner.skills.find((skill) => skill.name === name);\n      if (match) return match;\n    }\n  }\n  return undefined;\n}\n"],"mappings":"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"}

package/dist/catalog.d.mts

@@ -0,0 +1,66 @@
+import { Skill } from "@earendil-works/pi-coding-agent";
+import { SkillSourceContribution } from "@agimon-ai/po-core/skills";
+//#region src/services/skillCatalog/index.d.ts
+type SkillGroupKey = 'extensions' | 'help' | 'plugins' | 'default';
+interface SkillEntry {
+  name: string;
+  description: string;
+  filePath: string;
+  baseDir: string;
+  group: SkillGroupKey;
+  /** Package name for an extension, plugin directory name, or `.claude/skills`. */
+  owner: string;
+  modelInvocable: boolean;
+  /**
+   * What removing this skill would save from the `<available_skills>` block.
+   *
+   * Marginal rather than proportional: the block has fixed framing that no
+   * single skill pays for, so the useful figure is what actually goes away.
+   * Bodies are excluded because they load on demand and are not a resting cost.
+   */
+  promptTokens?: number;
+}
+interface SkillOwnerNode {
+  owner: string;
+  skills: SkillEntry[];
+}
+interface SkillGroup {
+  key: SkillGroupKey;
+  label: string;
+  owners: SkillOwnerNode[];
+}
+interface SkillCatalog {
+  groups: SkillGroup[];
+  skillCount: number;
+  /** Tokens the `<available_skills>` prompt block costs on every request. */
+  promptTokens: number;
+  /** Tokens every loaded SKILL.md costs in full, if all of them were read. */
+  bodyTokens: number;
+  /** Frontmatter and read failures, surfaced instead of thrown. */
+  diagnostics: string[];
+}
+interface SkillCatalogOptions {
+  repoRoot: string;
+  /** Exact files the current selection resolved to, from `HarnessState.skillDirectories`. */
+  activeSkillDirectories: readonly string[];
+  extensionSources: readonly SkillSourceContribution[];
+  /** Activation-gated wrappers already accepted by the merged active-skill view. */
+  helpSkills?: readonly Skill[];
+  /** Bounded Help activation and collision diagnostics. */
+  helpDiagnostics?: readonly string[];
+}
+export declare function counter(): Promise<(text: string) => number>;
+/**
+ * Every skill this session actually loaded, grouped by where it comes from,
+ * priced in tokens.
+ *
+ * Discovery runs over `loadSkillsFromDir` from Pi rather than the harness's own
+ * walker so the listing matches what Pi would load, including its ignore-file
+ * handling; the same skills are then handed to Pi's `formatSkillsForPrompt` so
+ * the always-on figure is the real prompt block rather than a reconstruction of
+ * it.
+ */
+export declare function buildSkillCatalog(options: SkillCatalogOptions): Promise<SkillCatalog>;
+//#endregion
+export type { SkillCatalog, SkillCatalogOptions, SkillEntry, SkillGroup, SkillOwnerNode };
+//# sourceMappingURL=catalog.d.mts.map

package/dist/catalog.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.mts","names":[],"sources":["../src/services/skillCatalog/index.ts"],"mappings":";;;KAWY;UAEK;EACf;EACA;EACA;EACA;EACA,OAAO;;EAEP;EACA;;;;;;;;EAQA;;UAGe;EACf;EACA,QAAQ;;UAGO;EACf,KAAK;EACL;EACA,QAAQ;;UAGO;EACf,QAAQ;EACR;;EAEA;;EAEA;;EAEA;;UAGe;EACf;;EAEA;EACA,2BAA2B;;EAE3B,sBAAsB;;EAEtB;;wBAaoB,WAAW,SAAS;;;;;;;;;;;wBAkHpB,kBAAkB,SAAS,sBAAsB,QAAQ"}

package/dist/catalog.mjs

@@ -0,0 +1,181 @@
+import fs from "node:fs";
+import path from "node:path";
+import { listDomainNames, resolvePluginEntries } from "@agimon-ai/po-config/domains";
+import { materializePluginEntries } from "@agimon-ai/po-domain/plugins";
+import { formatSkillsForPrompt, loadSkillsFromDir } from "@earendil-works/pi-coding-agent";
+//#region src/services/skillCatalog/index.ts
+const SKILLS_DIRECTORY = "skills";
+const SHARED_SKILLS_OWNER = ".claude/skills";
+/**
+* The tokenizer, loaded on first use rather than at import.
+*
+* `gpt-tokenizer` carries its whole vocabulary and costs about a tenth of a
+* second to load. This module is reachable from the skills extension, which Pi
+* loads at session start, so a top-level import would charge every session for
+* a surface most of them never open.
+*/
+let tokenizer;
+async function counter() {
+	tokenizer ??= import("gpt-tokenizer");
+	return (await tokenizer).countTokens;
+}
+/**
+* Matches a directory against the active set.
+*
+* A domain that lists a plugin subset puts individual skill directories in the
+* set rather than the plugin's `skills` root, so containment has to be checked
+* both ways: the set may hold an ancestor of the directory, or a descendant of
+* it.
+*/
+function createActiveMatcher(directories) {
+	const active = directories.map((directory) => path.resolve(directory));
+	return (directory) => {
+		const resolved = path.resolve(directory);
+		return active.some((entry) => entry === resolved || entry.startsWith(`${resolved}${path.sep}`) || resolved.startsWith(`${entry}${path.sep}`));
+	};
+}
+function collect(directory, group, owner, isActive, loaded, diagnostics, discovery = "recursive") {
+	const result = loadSkillsFromDir({
+		dir: directory,
+		source: owner
+	});
+	for (const diagnostic of result.diagnostics) diagnostics.push(`${diagnostic.path ?? directory}: ${diagnostic.message}`);
+	const root = path.resolve(directory);
+	const kept = result.skills.filter((skill) => {
+		const skillDirectory = path.dirname(skill.filePath);
+		if (discovery === "direct-children" && path.dirname(skillDirectory) !== root) return false;
+		return isActive(skillDirectory);
+	});
+	loaded.push(...kept);
+	return kept.map((skill) => ({
+		name: skill.name,
+		description: skill.description,
+		filePath: skill.filePath,
+		baseDir: skill.baseDir,
+		group,
+		owner,
+		modelInvocable: !skill.disableModelInvocation
+	})).sort((left, right) => left.name.localeCompare(right.name));
+}
+function sortOwners(owners) {
+	return owners.sort((left, right) => left.owner.localeCompare(right.owner));
+}
+function collectHelpSkills(skills, loaded, diagnostics) {
+	const occupiedNames = new Set(loaded.map((skill) => skill.name));
+	const owners = /* @__PURE__ */ new Map();
+	const candidates = [...skills].sort((left, right) => left.sourceInfo.source.localeCompare(right.sourceInfo.source) || left.name.localeCompare(right.name) || left.filePath.localeCompare(right.filePath));
+	for (const skill of candidates) {
+		if (occupiedNames.has(skill.name)) {
+			diagnostics.push(`Help ${skill.sourceInfo.source} [HELP_SKILL_COLLISION]: '${skill.name}' was ignored because a normal skill wins.`);
+			continue;
+		}
+		occupiedNames.add(skill.name);
+		loaded.push(skill);
+		const owner = skill.sourceInfo.source;
+		const entries = owners.get(owner) ?? [];
+		entries.push({
+			name: skill.name,
+			description: skill.description,
+			filePath: skill.filePath,
+			baseDir: skill.baseDir,
+			group: "help",
+			owner,
+			modelInvocable: !skill.disableModelInvocation
+		});
+		owners.set(owner, entries);
+	}
+	return sortOwners([...owners.entries()].map(([owner, entries]) => ({
+		owner,
+		skills: entries.sort((left, right) => left.name.localeCompare(right.name))
+	})));
+}
+/**
+* Every skill this session actually loaded, grouped by where it comes from,
+* priced in tokens.
+*
+* Discovery runs over `loadSkillsFromDir` from Pi rather than the harness's own
+* walker so the listing matches what Pi would load, including its ignore-file
+* handling; the same skills are then handed to Pi's `formatSkillsForPrompt` so
+* the always-on figure is the real prompt block rather than a reconstruction of
+* it.
+*/
+async function buildSkillCatalog(options) {
+	const { repoRoot } = options;
+	const isActive = createActiveMatcher(options.activeSkillDirectories);
+	const diagnostics = [...options.helpDiagnostics ?? []];
+	const loaded = [];
+	const extensionOwners = [];
+	for (const entry of options.extensionSources) {
+		const skills = entry.directories.flatMap((directory) => collect(directory, "extensions", entry.source, () => true, loaded, diagnostics));
+		if (skills.length > 0) extensionOwners.push({
+			owner: entry.source,
+			skills
+		});
+	}
+	const pluginOwners = [];
+	const domainPlugins = await materializePluginEntries(resolvePluginEntries(repoRoot, listDomainNames(repoRoot), []));
+	for (const entry of domainPlugins) {
+		const directory = path.join(entry.directory, SKILLS_DIRECTORY);
+		if (!fs.existsSync(directory)) continue;
+		const owner = path.basename(entry.directory);
+		const skills = collect(directory, "plugins", owner, isActive, loaded, diagnostics, entry.skillDiscovery);
+		if (skills.length > 0) pluginOwners.push({
+			owner,
+			skills
+		});
+	}
+	const sharedSkills = collect(path.join(repoRoot, ".claude", SKILLS_DIRECTORY), "default", SHARED_SKILLS_OWNER, isActive, loaded, diagnostics);
+	const defaultOwners = sharedSkills.length > 0 ? [{
+		owner: SHARED_SKILLS_OWNER,
+		skills: sharedSkills
+	}] : [];
+	const helpOwners = collectHelpSkills(options.helpSkills ?? [], loaded, diagnostics);
+	const groups = [
+		{
+			key: "extensions",
+			label: "extensions",
+			owners: sortOwners(extensionOwners)
+		},
+		{
+			key: "help",
+			label: "Help",
+			owners: helpOwners
+		},
+		{
+			key: "plugins",
+			label: "plugins",
+			owners: sortOwners(pluginOwners)
+		},
+		{
+			key: "default",
+			label: "default",
+			owners: defaultOwners
+		}
+	];
+	const countTokens = await counter();
+	const prompt = formatSkillsForPrompt(loaded);
+	const framingTokens = countTokens(formatSkillsForPrompt([]));
+	const marginal = /* @__PURE__ */ new Map();
+	for (const skill of loaded) marginal.set(skill.name, Math.max(0, countTokens(formatSkillsForPrompt([skill])) - framingTokens));
+	for (const group of groups) for (const owner of group.owners) for (const skill of owner.skills) {
+		const tokens = marginal.get(skill.name);
+		if (tokens !== void 0) skill.promptTokens = tokens;
+	}
+	let bodyTokens = 0;
+	for (const skill of loaded) try {
+		bodyTokens += countTokens(fs.readFileSync(skill.filePath, "utf8"));
+	} catch (error) {
+		diagnostics.push(`${skill.filePath}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	return {
+		groups,
+		skillCount: loaded.length,
+		promptTokens: prompt ? countTokens(prompt) : 0,
+		bodyTokens,
+		diagnostics
+	};
+}
+//#endregion
+export { buildSkillCatalog, counter };
+
+//# sourceMappingURL=catalog.mjs.map