@howaboua/pi-better-skills-tool 0.0.4 → 0.0.6

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,16 @@
1
1
  # @howaboua/pi-better-skills-tool
2
2
 
3
+ ## 0.0.6
4
+
5
+ - Requires Pi 1.0.0 or later.
6
+
7
+ - Skill reads now resolve shorthand references within the selected skill and accept semicolon-separated read/list groups.
8
+ - Large results now return bounded pages with explicit continuation commands instead of failing.
9
+
10
+ ## 0.0.5
11
+
12
+ - Skills tool usage now advertises category-filtered listing in Code and Notebook modes.
13
+
3
14
  ## 0.0.4
4
15
 
5
16
  - The skills tool now reads mixed skills and unique cross-skill references in one call. Ambiguous reference names report their qualified choices.
package/README.md CHANGED
@@ -8,7 +8,7 @@ Progressive skill discovery for Pi, Code Mode and Notebook Mode. The `skills` to
8
8
  pi install npm:@howaboua/pi-better-skills-tool
9
9
  ```
10
10
 
11
- Requires Pi 0.84.3 or newer. Install `@howaboua/pi-codex-conversion` 3.0.25 or newer too for Code Mode and Notebook Mode. The extension remains a normal Pi tool when Codex conversion is absent.
11
+ Requires Pi 1.0.0 or newer. Install `@howaboua/pi-codex-conversion` 3.0.25 or newer too for Code Mode and Notebook Mode. The extension remains a normal Pi tool when Codex conversion is absent.
12
12
 
13
13
  ## Start Pi without native skills
14
14
 
@@ -44,11 +44,16 @@ await tools.skills("list code session")
44
44
  await tools.skills("read code-review")
45
45
  await tools.skills("read communication codebase-hygiene")
46
46
  await tools.skills("read codebase-hygiene testing js-ts")
47
+ await tools.skills("read communication conversation writing; read codebase-hygiene testing")
47
48
  ```
48
49
 
49
50
  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
 
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.
52
+ After the initial skill, an exact skill name adds that full skill package. Reference shorthand resolves within the most recently selected skill first, then across the visible catalog. A unique reference can come from another skill. An ambiguous global reference requires a skill-qualified name 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.
53
+
54
+ Separate independent `read` or `list` commands with `;`. Each group resolves references in its own skill scope. Invalid groups fail the whole call.
55
+
56
+ Results stay within 48 KiB of UTF-8 text. Larger results include an `Incomplete` marker and an exact continuation command ending in `--offset <byte>`. Run that command to retrieve the next part. Continuations are stateless and re-read the catalog, so restart the original command if skill files change between calls. Normalized commands, excluding the offset suffix, are limited to 4 KiB to keep continuation instructions within the result budget.
52
57
 
53
58
  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.
54
59
 
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> [skill-or-reference...]"',
48
+ 'await tools.skills("list") // list [category...] | read <skill> [skill-or-reference...]; join commands with ;',
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.4",
3
+ "version": "0.0.6",
4
4
  "description": "Progressive skill discovery for Pi, Code Mode and Notebook Mode.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -40,9 +40,9 @@
40
40
  "pack:dry": "npm pack --dry-run"
41
41
  },
42
42
  "peerDependencies": {
43
- "@howaboua/pi-codex-conversion": ">=3.0.34",
44
- "@earendil-works/pi-coding-agent": ">=0.84.3",
45
- "@earendil-works/pi-tui": ">=0.84.3",
43
+ "@howaboua/pi-codex-conversion": ">=3.0.43",
44
+ "@earendil-works/pi-coding-agent": ">=1.0.0",
45
+ "@earendil-works/pi-tui": ">=1.0.0",
46
46
  "typebox": "*"
47
47
  },
48
48
  "peerDependenciesMeta": {
@@ -51,10 +51,10 @@
51
51
  }
52
52
  },
53
53
  "devDependencies": {
54
- "@howaboua/pi-codex-conversion": "3.0.34",
54
+ "@howaboua/pi-codex-conversion": "3.0.43",
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": "1.0.0",
57
+ "@earendil-works/pi-tui": "1.0.0",
58
58
  "@types/node": "^26.2.0",
59
59
  "tsx": "^4.23.12",
60
60
  "typebox": "1.3.18",
package/src/catalog.ts CHANGED
@@ -16,14 +16,38 @@ export {
16
16
  } from "./discovery.js";
17
17
 
18
18
  const MAX_OUTPUT_BYTES = 48 * 1024;
19
+ // Leave room for an exact continuation command inside the output budget.
20
+ const MAX_COMMAND_BYTES = 4 * 1024;
19
21
 
20
22
  type SkillRequest =
21
23
  | { action: "list"; categories: string[] }
22
24
  | { action: "read"; name: string; selectors: string[] };
23
25
 
24
- export function parseRequest(input: unknown): SkillRequest {
26
+ interface SkillsRequest {
27
+ commands: SkillRequest[];
28
+ offset: number;
29
+ }
30
+
31
+ export function parseRequest(input: unknown): SkillsRequest {
25
32
  if (typeof input !== "string")
26
33
  throw new Error("skills expects a string command");
34
+ const offsetMatch = input.match(/\s+--offset\s+(\d+)\s*$/);
35
+ const offset = offsetMatch ? Number(offsetMatch[1]) : 0;
36
+ if (!Number.isSafeInteger(offset))
37
+ throw new Error("--offset expects a non-negative safe integer byte offset");
38
+ const command = offsetMatch ? input.slice(0, offsetMatch.index) : input;
39
+ if (/(?:^|\s)--offset(?:\s|$)/.test(command))
40
+ throw new Error("Use --offset <byte> once at the end of the command");
41
+ const groups = command.split(";");
42
+ if (groups.length > 1 && groups.some((group) => !group.trim()))
43
+ throw new Error("Empty command group. Separate read/list commands with ;");
44
+ const commands = groups.map(parseCommand);
45
+ if (Buffer.byteLength(formatCommand(commands)) > MAX_COMMAND_BYTES)
46
+ throw new Error(`skills command exceeds ${MAX_COMMAND_BYTES} bytes`);
47
+ return { commands, offset };
48
+ }
49
+
50
+ function parseCommand(input: string): SkillRequest {
27
51
  const parts = input.trim().split(/\s+/).filter(Boolean);
28
52
  const [action, ...arguments_] = parts;
29
53
  if (!action || action === "list") {
@@ -33,7 +57,7 @@ export function parseRequest(input: unknown): SkillRequest {
33
57
  return {
34
58
  action,
35
59
  name: arguments_[0] ?? "",
36
- selectors: [...new Set(arguments_.slice(1))],
60
+ selectors: arguments_.slice(1),
37
61
  };
38
62
  }
39
63
  if (action === "read") {
@@ -46,6 +70,16 @@ export function parseRequest(input: unknown): SkillRequest {
46
70
  );
47
71
  }
48
72
 
73
+ function formatCommand(commands: SkillRequest[]): string {
74
+ return commands
75
+ .map((group) =>
76
+ group.action === "list"
77
+ ? ["list", ...group.categories].join(" ")
78
+ : ["read", group.name, ...group.selectors].join(" "),
79
+ )
80
+ .join("; ");
81
+ }
82
+
49
83
  function formatSkillList(
50
84
  skills: CatalogSkill[],
51
85
  requestedCategories: string[] = [],
@@ -97,14 +131,23 @@ function formatSkillList(
97
131
  return lines.join("\n");
98
132
  }
99
133
 
100
- function enforceOutputLimit(output: string): string {
101
- const bytes = Buffer.byteLength(output);
102
- if (bytes > MAX_OUTPUT_BYTES) {
134
+ function boundedOutput(output: string, request: SkillsRequest): string {
135
+ const bytes = Buffer.from(output);
136
+ const { offset } = request;
137
+ if (offset > bytes.length || (offset > 0 && offset === bytes.length))
103
138
  throw new Error(
104
- `skills output is ${bytes} bytes; maximum is ${MAX_OUTPUT_BYTES} bytes`,
139
+ `--offset ${offset} is outside output (${bytes.length} bytes)`,
105
140
  );
106
- }
107
- return output;
141
+ if (offset < bytes.length && ((bytes[offset] ?? 0) & 0xc0) === 0x80)
142
+ throw new Error(`--offset ${offset} splits a UTF-8 character`);
143
+ if (bytes.length - offset <= MAX_OUTPUT_BYTES)
144
+ return offset === 0 ? output : bytes.subarray(offset).toString("utf8");
145
+ const command = formatCommand(request.commands);
146
+ const footer = (end: number) =>
147
+ `\n\n---\nIncomplete: bytes ${offset}-${end} of ${bytes.length}. Continue with command:\n${command} --offset ${end}`;
148
+ let end = offset + MAX_OUTPUT_BYTES - Buffer.byteLength(footer(bytes.length));
149
+ while (((bytes[end] ?? 0) & 0xc0) === 0x80) end--;
150
+ return bytes.subarray(offset, end).toString("utf8") + footer(end);
108
151
  }
109
152
 
110
153
  export function runSkills(
@@ -117,9 +160,14 @@ export function runSkills(
117
160
  ): string {
118
161
  const request = parseRequest(input);
119
162
  const skills = discoverVisibleSkills(globalRoot, sessionRoot, loadedSkills);
120
- return enforceOutputLimit(
121
- request.action === "list"
122
- ? formatSkillList(skills, request.categories)
123
- : readSkillPackage(skills, request.name, request.selectors),
163
+ return boundedOutput(
164
+ request.commands
165
+ .map((command) =>
166
+ command.action === "list"
167
+ ? formatSkillList(skills, command.categories)
168
+ : readSkillPackage(skills, command.name, command.selectors),
169
+ )
170
+ .join("\n\n"),
171
+ request,
124
172
  );
125
173
  }
@@ -238,12 +238,15 @@ function resolvePrimarySelection(
238
238
  function resolveAdditionalSelection(
239
239
  skills: CatalogSkill[],
240
240
  name: string,
241
+ selectedSkill: CatalogSkill,
241
242
  catalog: ReferenceCatalog,
242
243
  ): ReadSelection {
243
244
  const exactSkill = skills.find((skill) => skill.name === name);
244
245
  if (exactSkill) return { kind: "skill", skill: exactSkill };
245
246
  const explicit = resolveExplicitSelection(skills, name, catalog);
246
247
  if (explicit) return explicit;
248
+ const local = findReference(selectedSkill, name, catalog);
249
+ if (local) return local;
247
250
  const references = skills.flatMap((skill) => {
248
251
  const reference = findReference(skill, name, catalog);
249
252
  return reference ? [reference] : [];
@@ -323,9 +326,19 @@ export function readSkillPackage(
323
326
  ): string {
324
327
  const catalog: ReferenceCatalog = new Map();
325
328
  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
+ let selectedSkill = primary.skill;
330
+ const additional: ReadSelection[] = [];
331
+ for (const selector of selectors) {
332
+ if (isOwnSkillDocument(selector, selectedSkill)) continue;
333
+ const selection = resolveAdditionalSelection(
334
+ skills,
335
+ selector,
336
+ selectedSkill,
337
+ catalog,
338
+ );
339
+ additional.push(selection);
340
+ if (selection.kind === "skill") selectedSkill = selection.skill;
341
+ }
329
342
  const selections = deduplicateSelections(
330
343
  primary.kind === "skill" &&
331
344
  additional.length > 0 &&
package/src/tool.ts CHANGED
@@ -11,7 +11,8 @@ import {
11
11
  const SkillsParameters = Type.Object(
12
12
  {
13
13
  command: Type.String({
14
- description: "list [category...] | read <skill> [skill-or-reference...]",
14
+ description:
15
+ "list [category...] | read <skill> [skill-or-reference...]; separate commands with ;",
15
16
  }),
16
17
  },
17
18
  { additionalProperties: false },