@howaboua/pi-better-skills-tool 0.0.3 → 0.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,13 @@
1
1
  # @howaboua/pi-better-skills-tool
2
2
 
3
+ ## 0.0.5
4
+
5
+ - Skills tool usage now advertises category-filtered listing in Code and Notebook modes.
6
+
7
+ ## 0.0.4
8
+
9
+ - The skills tool now reads mixed skills and unique cross-skill references in one call. Ambiguous reference names report their qualified choices.
10
+
3
11
  ## 0.0.3
4
12
 
5
13
  - Removed redundant tool guidance from Ask, Shepherdr, Skills and Browser. Code and Notebook Mode now show one callable contract per tool, with detailed Browser and agent rules in help.
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @howaboua/pi-better-skills-tool
2
2
 
3
- Progressive skill discovery for Pi, Code Mode and Notebook Mode. The `skills` tool lists the active catalog by category, reads one skill, or reads selected references without loading an entire package into context.
3
+ Progressive skill discovery for Pi, Code Mode and Notebook Mode. The `skills` tool lists the active catalog by category, reads one or more skills, or reads selected references without loading an entire package into context.
4
4
 
5
5
  ## Install
6
6
 
@@ -42,10 +42,13 @@ Normal Pi uses one structured `command` parameter. Code Mode and Notebook Mode u
42
42
  await tools.skills("list")
43
43
  await tools.skills("list code session")
44
44
  await tools.skills("read code-review")
45
+ await tools.skills("read communication codebase-hygiene")
45
46
  await tools.skills("read codebase-hygiene testing js-ts")
46
47
  ```
47
48
 
48
- Pi's loaded skill catalog is authoritative during normal use. When Pi has no loaded skills, including `--no-skills` sessions, the tool falls back to the standard global `skills/` directory under Pi's agent directory and `$PWD/.pi/skills/`. A same-named session skill overrides the global skill. Skill reads include absolute package paths for later reference, script, or asset access. Reference reads return only the requested Markdown and its source paths, without repeating the package inventory.
49
+ Pi's loaded skill catalog is authoritative during normal use. When Pi has no loaded skills, including `--no-skills` sessions, the tool falls back to the standard global `skills/` directory under Pi's agent directory and `$PWD/.pi/skills/`. A same-named session skill overrides the global skill. Skill reads include absolute package paths for later reference, script, or asset access.
50
+
51
+ After the initial skill, an exact skill name adds that full skill package. Other names resolve against references in every visible skill. A unique reference can come from another skill. If multiple skills contain the name, the tool asks for a skill-qualified reference such as `communication/references/conversation` or an absolute source path. A read with only references still returns only the requested Markdown and source paths, without repeating the initial package inventory.
49
52
 
50
53
  Remove or disable any legacy `codex-conversion-custom-tools/skills.toml` after installing this extension. Keeping both definitions gives Code Mode two tools named `skills`, which it rejects.
51
54
 
package/index.ts CHANGED
@@ -45,7 +45,7 @@ async function registerSkillsInCodeMode(
45
45
  kind: "freeform",
46
46
  prepareInput: prepareSkillsCodeModeInput,
47
47
  usage:
48
- 'await tools.skills("list") // or "read <skill> [reference-name...]"',
48
+ 'await tools.skills("list") // or "list <category>...", "read <skill> [skill-or-reference...]"',
49
49
  }),
50
50
  ]);
51
51
  } catch (error) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@howaboua/pi-better-skills-tool",
3
- "version": "0.0.3",
3
+ "version": "0.0.5",
4
4
  "description": "Progressive skill discovery for Pi, Code Mode and Notebook Mode.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -40,7 +40,7 @@
40
40
  "pack:dry": "npm pack --dry-run"
41
41
  },
42
42
  "peerDependencies": {
43
- "@howaboua/pi-codex-conversion": ">=3.0.33",
43
+ "@howaboua/pi-codex-conversion": ">=3.0.40",
44
44
  "@earendil-works/pi-coding-agent": ">=0.84.3",
45
45
  "@earendil-works/pi-tui": ">=0.84.3",
46
46
  "typebox": "*"
@@ -51,10 +51,10 @@
51
51
  }
52
52
  },
53
53
  "devDependencies": {
54
- "@howaboua/pi-codex-conversion": "3.0.33",
54
+ "@howaboua/pi-codex-conversion": "3.0.40",
55
55
  "@biomejs/biome": "^2.5.10",
56
- "@earendil-works/pi-coding-agent": "0.85.1",
57
- "@earendil-works/pi-tui": "0.85.1",
56
+ "@earendil-works/pi-coding-agent": "0.99.1",
57
+ "@earendil-works/pi-tui": "0.99.1",
58
58
  "@types/node": "^26.2.0",
59
59
  "tsx": "^4.23.12",
60
60
  "typebox": "1.3.18",
package/src/catalog.ts CHANGED
@@ -19,7 +19,7 @@ const MAX_OUTPUT_BYTES = 48 * 1024;
19
19
 
20
20
  type SkillRequest =
21
21
  | { action: "list"; categories: string[] }
22
- | { action: "read"; name: string; references: string[] };
22
+ | { action: "read"; name: string; selectors: string[] };
23
23
 
24
24
  export function parseRequest(input: unknown): SkillRequest {
25
25
  if (typeof input !== "string")
@@ -33,16 +33,16 @@ export function parseRequest(input: unknown): SkillRequest {
33
33
  return {
34
34
  action,
35
35
  name: arguments_[0] ?? "",
36
- references: [...new Set(arguments_.slice(1))],
36
+ selectors: [...new Set(arguments_.slice(1))],
37
37
  };
38
38
  }
39
39
  if (action === "read") {
40
40
  throw new Error(
41
- 'read expects one skill name and optional reference names: "read <exact-skill-name> [reference...]"',
41
+ 'read expects one skill name and optional skill or reference names: "read <exact-skill-name> [skill-or-reference...]"',
42
42
  );
43
43
  }
44
44
  throw new Error(
45
- 'Expected "list", "list <category>...", or "read <exact-skill-name> [reference...]"',
45
+ 'Expected "list", "list <category>...", or "read <exact-skill-name> [skill-or-reference...]"',
46
46
  );
47
47
  }
48
48
 
@@ -120,6 +120,6 @@ export function runSkills(
120
120
  return enforceOutputLimit(
121
121
  request.action === "list"
122
122
  ? formatSkillList(skills, request.categories)
123
- : readSkillPackage(skills, request.name, request.references),
123
+ : readSkillPackage(skills, request.name, request.selectors),
124
124
  );
125
125
  }
@@ -55,57 +55,30 @@ function findSkillByName(
55
55
  );
56
56
  }
57
57
 
58
- function resolveSkillRead(
59
- skills: CatalogSkill[],
60
- name: string,
61
- references: string[],
62
- ): { skill: CatalogSkill; references: string[] } | undefined {
63
- const direct = findSkillByName(skills, name);
64
- if (direct) return { skill: direct, references };
65
- const normalized = normalizedPath(name);
66
- for (const skill of skills) {
67
- if (normalized.toLowerCase() === `${skill.name}/skill.md`) {
68
- return { skill, references };
69
- }
70
- const prefix = `${skill.name}/references/`;
71
- if (normalized.toLowerCase().startsWith(prefix)) {
72
- const reference = normalized.slice(prefix.length);
73
- if (reference) {
74
- return {
75
- skill,
76
- references: [...new Set([reference, ...references])],
77
- };
78
- }
79
- }
80
- }
81
- if (!isAbsolute(name)) return undefined;
82
- const requestedPath = resolve(name);
83
- for (const skill of skills) {
84
- if (requestedPath === resolve(skill.path)) {
85
- return { skill, references };
86
- }
87
- const reference = referenceFiles(skill).find(
88
- (path) => resolve(path) === requestedPath,
89
- );
90
- if (reference) {
91
- return {
92
- skill,
93
- references: [...new Set([reference, ...references])],
94
- };
95
- }
96
- }
97
- return undefined;
98
- }
99
-
100
- function isOwnSkillDocument(reference: string, skill: CatalogSkill): boolean {
101
- const normalized = normalizedPath(reference).toLowerCase();
58
+ function isOwnSkillDocument(name: string, skill: CatalogSkill): boolean {
59
+ const normalized = normalizedPath(name).toLowerCase();
102
60
  return (
103
61
  normalized === "skill.md" ||
104
62
  normalized === `${skill.name}/skill.md` ||
105
- (isAbsolute(reference) && resolve(reference) === resolve(skill.path))
63
+ (isAbsolute(name) && resolve(name) === resolve(skill.path))
106
64
  );
107
65
  }
108
66
 
67
+ interface SkillSelection {
68
+ kind: "skill";
69
+ skill: CatalogSkill;
70
+ }
71
+
72
+ interface ReferenceSelection {
73
+ kind: "reference";
74
+ skill: CatalogSkill;
75
+ reference: string;
76
+ path: string;
77
+ }
78
+
79
+ type ReadSelection = SkillSelection | ReferenceSelection;
80
+ type ReferenceCatalog = Map<CatalogSkill, Map<string, string>>;
81
+
109
82
  function packageFiles(skill: CatalogSkill): string[] {
110
83
  const root = realpathSync(skill.directory);
111
84
  const paths: string[] = [];
@@ -176,11 +149,12 @@ function referenceFiles(skill: CatalogSkill): string[] {
176
149
  );
177
150
  }
178
151
 
179
- function readReferences(
152
+ function referencesForSkill(
180
153
  skill: CatalogSkill,
181
- references: string[],
182
- skills: CatalogSkill[],
183
- ): string {
154
+ catalog: ReferenceCatalog,
155
+ ): Map<string, string> {
156
+ const existing = catalog.get(skill);
157
+ if (existing) return existing;
184
158
  const root = resolve(skill.directory, "references");
185
159
  const available = new Map(
186
160
  referenceFiles(skill).map((path) => [
@@ -188,72 +162,187 @@ function readReferences(
188
162
  path,
189
163
  ]),
190
164
  );
191
- const selected: Array<{ reference: string; path: string; content: string }> =
192
- [];
193
- const seen = new Set<string>();
194
- for (const requestedReference of references) {
195
- const absoluteReference = isAbsolute(requestedReference)
196
- ? [...available].find(
197
- ([, path]) => resolve(path) === resolve(requestedReference),
198
- )?.[0]
199
- : undefined;
200
- const reference =
201
- absoluteReference ??
202
- referenceCandidates(requestedReference, skill).find((candidate) =>
203
- available.has(candidate),
204
- );
205
- const path = reference ? available.get(reference) : undefined;
206
- if (!reference || !path) {
207
- const separate = resolveSkillRead(skills, requestedReference, []);
208
- if (separate && separate.skill !== skill) {
209
- const command = [
210
- "read",
211
- separate.skill.name,
212
- ...separate.references,
213
- ].join(" ");
214
- throw new Error(
215
- `"${requestedReference}" is a separate skill, not a reference of "${skill.name}". Read it separately with "${command}"`,
216
- );
217
- }
218
- const choices = [...available.keys()].join(", ") || "none";
219
- throw new Error(
220
- `Unknown reference "${requestedReference}" for skill "${skill.name}". Available: ${choices}`,
165
+ catalog.set(skill, available);
166
+ return available;
167
+ }
168
+
169
+ function findReference(
170
+ skill: CatalogSkill,
171
+ name: string,
172
+ catalog: ReferenceCatalog,
173
+ ): ReferenceSelection | undefined {
174
+ const available = referencesForSkill(skill, catalog);
175
+ const absoluteReference = isAbsolute(name)
176
+ ? [...available].find(([, path]) => resolve(path) === resolve(name))?.[0]
177
+ : undefined;
178
+ const reference =
179
+ absoluteReference ??
180
+ referenceCandidates(name, skill).find((candidate) =>
181
+ available.has(candidate),
182
+ );
183
+ const path = reference ? available.get(reference) : undefined;
184
+ return reference && path
185
+ ? { kind: "reference", skill, reference, path }
186
+ : undefined;
187
+ }
188
+
189
+ function unknownReferenceForSkill(name: string, skill: CatalogSkill): never {
190
+ throw new Error(
191
+ `Unknown reference "${name}" for skill "${skill.name}". Use "read ${skill.name}" to inspect its reference paths`,
192
+ );
193
+ }
194
+
195
+ function resolveExplicitSelection(
196
+ skills: CatalogSkill[],
197
+ name: string,
198
+ catalog: ReferenceCatalog,
199
+ ): ReadSelection | undefined {
200
+ const normalized = normalizedPath(name);
201
+ for (const skill of skills) {
202
+ if (normalized.toLowerCase() === `${skill.name}/skill.md`) {
203
+ return { kind: "skill", skill };
204
+ }
205
+ const prefix = `${skill.name}/references/`;
206
+ if (normalized.toLowerCase().startsWith(prefix)) {
207
+ const requestedReference = normalized.slice(prefix.length);
208
+ return (
209
+ findReference(skill, requestedReference, catalog) ??
210
+ unknownReferenceForSkill(requestedReference, skill)
221
211
  );
222
212
  }
223
- if (seen.has(reference)) continue;
224
- seen.add(reference);
225
- selected.push({
226
- reference,
227
- path,
228
- content: readFileSync(path, "utf8").trim(),
229
- });
230
213
  }
214
+ if (!isAbsolute(name)) return undefined;
215
+ const requestedPath = resolve(name);
216
+ for (const skill of skills) {
217
+ if (requestedPath === resolve(skill.path)) return { kind: "skill", skill };
218
+ const reference = findReference(skill, requestedPath, catalog);
219
+ if (reference) return reference;
220
+ }
221
+ return undefined;
222
+ }
223
+
224
+ function resolvePrimarySelection(
225
+ skills: CatalogSkill[],
226
+ name: string,
227
+ catalog: ReferenceCatalog,
228
+ ): ReadSelection {
229
+ const direct = findSkillByName(skills, name);
230
+ if (direct) return { kind: "skill", skill: direct };
231
+ const explicit = resolveExplicitSelection(skills, name, catalog);
232
+ if (explicit) return explicit;
233
+ throw new Error(
234
+ `Unknown skill "${name}". Available: ${skills.map((skill) => skill.name).join(", ") || "none"}`,
235
+ );
236
+ }
237
+
238
+ function resolveAdditionalSelection(
239
+ skills: CatalogSkill[],
240
+ name: string,
241
+ catalog: ReferenceCatalog,
242
+ ): ReadSelection {
243
+ const exactSkill = skills.find((skill) => skill.name === name);
244
+ if (exactSkill) return { kind: "skill", skill: exactSkill };
245
+ const explicit = resolveExplicitSelection(skills, name, catalog);
246
+ if (explicit) return explicit;
247
+ const references = skills.flatMap((skill) => {
248
+ const reference = findReference(skill, name, catalog);
249
+ return reference ? [reference] : [];
250
+ });
251
+ if (references.length === 1) return references[0] as ReferenceSelection;
252
+ if (references.length > 1) {
253
+ throw new Error(
254
+ `Ambiguous reference "${name}". Use one of: ${references
255
+ .map(
256
+ (reference) =>
257
+ `${reference.skill.name}/references/${reference.reference}`,
258
+ )
259
+ .join(", ")}`,
260
+ );
261
+ }
262
+ throw new Error(
263
+ `Unknown skill or reference "${name}". Use "list" for skill names or "read <skill>" to inspect reference paths`,
264
+ );
265
+ }
266
+
267
+ function deduplicateSelections(selections: ReadSelection[]): ReadSelection[] {
268
+ const seen = new Set<string>();
269
+ return selections.filter((selection) => {
270
+ const path = resolve(
271
+ selection.kind === "skill" ? selection.skill.path : selection.path,
272
+ );
273
+ if (seen.has(path)) return false;
274
+ seen.add(path);
275
+ return true;
276
+ });
277
+ }
278
+
279
+ function formatReferences(selected: ReferenceSelection[]): string {
280
+ const oneSkill = new Set(selected.map(({ skill }) => skill.name)).size === 1;
281
+ const withContent = selected.map((selection) => ({
282
+ ...selection,
283
+ content: readFileSync(selection.path, "utf8").trim(),
284
+ }));
231
285
  const content =
232
- selected.length === 1
233
- ? (selected[0]?.content ?? "")
234
- : selected
235
- .map(
236
- ({ reference, content: body }) => `--- ${reference} ---\n${body}`,
237
- )
286
+ withContent.length === 1
287
+ ? (withContent[0]?.content ?? "")
288
+ : withContent
289
+ .map(({ skill, reference, content: body }) => {
290
+ const label = oneSkill
291
+ ? reference
292
+ : `${skill.name}/references/${reference}`;
293
+ return `--- ${label} ---\n${body}`;
294
+ })
238
295
  .join("\n\n");
239
- return `${content}\n\n---\nSources:\n${selected.map(({ path }) => `- ${path}`).join("\n")}`;
296
+ return `${content}\n\n---\nSources:\n${withContent.map(({ path }) => `- ${path}`).join("\n")}`;
297
+ }
298
+
299
+ function formatMixedSelections(selections: ReadSelection[]): string {
300
+ const content = selections
301
+ .map((selection) => {
302
+ if (selection.kind === "skill") {
303
+ return `--- ${selection.skill.name} ---\n${formatSkill(selection.skill)}`;
304
+ }
305
+ return `--- ${selection.skill.name}/references/${selection.reference} ---\n${readFileSync(selection.path, "utf8").trim()}`;
306
+ })
307
+ .join("\n\n");
308
+ const sources = selections
309
+ .filter(
310
+ (selection): selection is ReferenceSelection =>
311
+ selection.kind === "reference",
312
+ )
313
+ .map(({ path }) => `- ${path}`);
314
+ return sources.length
315
+ ? `${content}\n\n---\nSources:\n${sources.join("\n")}`
316
+ : content;
240
317
  }
241
318
 
242
319
  export function readSkillPackage(
243
320
  skills: CatalogSkill[],
244
321
  name: string,
245
- references: string[],
322
+ selectors: string[],
246
323
  ): string {
247
- const target = resolveSkillRead(skills, name, references);
248
- if (!target) {
249
- throw new Error(
250
- `Unknown skill "${name}". Available: ${skills.map((skill) => skill.name).join(", ") || "none"}`,
251
- );
252
- }
253
- const selectedReferences = target.references.filter(
254
- (reference) => !isOwnSkillDocument(reference, target.skill),
324
+ const catalog: ReferenceCatalog = new Map();
325
+ const primary = resolvePrimarySelection(skills, name, catalog);
326
+ const additional = selectors
327
+ .filter((reference) => !isOwnSkillDocument(reference, primary.skill))
328
+ .map((reference) => resolveAdditionalSelection(skills, reference, catalog));
329
+ const selections = deduplicateSelections(
330
+ primary.kind === "skill" &&
331
+ additional.length > 0 &&
332
+ additional.every((selection) => selection.kind === "reference")
333
+ ? additional
334
+ : [primary, ...additional],
255
335
  );
256
- return selectedReferences.length
257
- ? readReferences(target.skill, selectedReferences, skills)
258
- : formatSkill(target.skill);
336
+ if (selections.length === 1) {
337
+ const selection = selections[0] as ReadSelection;
338
+ return selection.kind === "skill"
339
+ ? formatSkill(selection.skill)
340
+ : formatReferences([selection]);
341
+ }
342
+ return selections.every(
343
+ (selection): selection is ReferenceSelection =>
344
+ selection.kind === "reference",
345
+ )
346
+ ? formatReferences(selections)
347
+ : formatMixedSelections(selections);
259
348
  }
package/src/tool.ts CHANGED
@@ -11,7 +11,7 @@ import {
11
11
  const SkillsParameters = Type.Object(
12
12
  {
13
13
  command: Type.String({
14
- description: "list [category...] | read <skill> [reference...]",
14
+ description: "list [category...] | read <skill> [skill-or-reference...]",
15
15
  }),
16
16
  },
17
17
  { additionalProperties: false },