@howaboua/pi-better-skills-tool 0.0.10 → 0.0.11
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 +7 -0
- package/package.json +3 -3
- package/src/catalog.ts +52 -16
- package/src/skill-package.ts +47 -53
- package/src/tool.ts +5 -3
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,12 @@
|
|
|
1
1
|
# @howaboua/pi-better-skills-tool
|
|
2
2
|
|
|
3
|
+
## 0.0.11
|
|
4
|
+
|
|
5
|
+
- - Skills help and catalog results now explain reference-only reads and batching skill bodies with references.
|
|
6
|
+
- Invalid Code and Notebook calls now show no-argument discovery syntax.
|
|
7
|
+
- GPT-mode catalog help uses denser guidance.
|
|
8
|
+
- Skill results include structured read receipts for usage tracking, distinguishing references and continuation pages.
|
|
9
|
+
|
|
3
10
|
## 0.0.10
|
|
4
11
|
|
|
5
12
|
- Use consistent skill discovery across native, Code and Notebook modes, with compact help in PCC GPT prompt mode.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@howaboua/pi-better-skills-tool",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.11",
|
|
4
4
|
"description": "Progressive skill discovery for Pi, Code Mode and Notebook Mode.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -39,7 +39,7 @@
|
|
|
39
39
|
"pack:dry": "npm pack --dry-run"
|
|
40
40
|
},
|
|
41
41
|
"peerDependencies": {
|
|
42
|
-
"@howaboua/pi-codex-conversion": ">=4.0.
|
|
42
|
+
"@howaboua/pi-codex-conversion": ">=4.0.3",
|
|
43
43
|
"@earendil-works/pi-coding-agent": ">=1.0.0",
|
|
44
44
|
"@earendil-works/pi-tui": ">=1.0.0",
|
|
45
45
|
"typebox": "*"
|
|
@@ -50,7 +50,7 @@
|
|
|
50
50
|
}
|
|
51
51
|
},
|
|
52
52
|
"devDependencies": {
|
|
53
|
-
"@howaboua/pi-codex-conversion": "4.0.
|
|
53
|
+
"@howaboua/pi-codex-conversion": "4.0.3",
|
|
54
54
|
"@biomejs/biome": "^2.5.15",
|
|
55
55
|
"@earendil-works/pi-coding-agent": "1.3.0",
|
|
56
56
|
"@earendil-works/pi-tui": "1.3.0",
|
package/src/catalog.ts
CHANGED
|
@@ -6,7 +6,7 @@ import {
|
|
|
6
6
|
discoverVisibleSkills,
|
|
7
7
|
type LoadedSkill,
|
|
8
8
|
} from "./discovery.js";
|
|
9
|
-
import { readSkillPackage } from "./skill-package.js";
|
|
9
|
+
import { readSkillPackage, type SkillReadOutput } from "./skill-package.js";
|
|
10
10
|
|
|
11
11
|
export type { LoadedSkill } from "./discovery.js";
|
|
12
12
|
export { defaultSessionSkillsDir, defaultSkillsDir } from "./discovery.js";
|
|
@@ -14,6 +14,10 @@ export { defaultSessionSkillsDir, defaultSkillsDir } from "./discovery.js";
|
|
|
14
14
|
const MAX_OUTPUT_BYTES = 48 * 1024;
|
|
15
15
|
// Leave room for an exact continuation command inside the output budget.
|
|
16
16
|
const MAX_COMMAND_BYTES = 4 * 1024;
|
|
17
|
+
const READ_HELP =
|
|
18
|
+
"Reference-only selectors omit the initial skill body. To read a body plus references, use separate commands: read skill; read other/references/topic";
|
|
19
|
+
const GPT_READ_HELP =
|
|
20
|
+
"Reference-only selectors→no initial skill body; body+refs→separate commands: read skill; read other/references/topic";
|
|
17
21
|
|
|
18
22
|
type SkillRequest =
|
|
19
23
|
| { action: "help" }
|
|
@@ -133,7 +137,8 @@ function formatSkillList(
|
|
|
133
137
|
return lines.join("\n");
|
|
134
138
|
}
|
|
135
139
|
|
|
136
|
-
function boundedOutput(
|
|
140
|
+
function boundedOutput(result: SkillReadOutput, request: SkillsRequest) {
|
|
141
|
+
const { output, reads } = result;
|
|
137
142
|
const bytes = Buffer.from(output);
|
|
138
143
|
const { offset } = request;
|
|
139
144
|
if (offset > bytes.length || (offset > 0 && offset === bytes.length))
|
|
@@ -142,14 +147,31 @@ function boundedOutput(output: string, request: SkillsRequest): string {
|
|
|
142
147
|
);
|
|
143
148
|
if (offset < bytes.length && ((bytes[offset] ?? 0) & 0xc0) === 0x80)
|
|
144
149
|
throw new Error(`--offset ${offset} splits a UTF-8 character`);
|
|
150
|
+
const page = (output: string, end: number) => ({
|
|
151
|
+
output,
|
|
152
|
+
skillReads: {
|
|
153
|
+
version: 1 as const,
|
|
154
|
+
// Only exposed body bytes count, not labels, path inventories or footers.
|
|
155
|
+
reads: reads
|
|
156
|
+
.filter(
|
|
157
|
+
(span) =>
|
|
158
|
+
span.start < span.end && span.start < end && span.end > offset,
|
|
159
|
+
)
|
|
160
|
+
.map(({ read }) => read),
|
|
161
|
+
continuation: offset > 0,
|
|
162
|
+
},
|
|
163
|
+
});
|
|
145
164
|
if (bytes.length - offset <= MAX_OUTPUT_BYTES)
|
|
146
|
-
return
|
|
165
|
+
return page(
|
|
166
|
+
offset === 0 ? output : bytes.subarray(offset).toString("utf8"),
|
|
167
|
+
bytes.length,
|
|
168
|
+
);
|
|
147
169
|
const command = formatCommand(request.commands);
|
|
148
170
|
const footer = (end: number) =>
|
|
149
171
|
`\n\n---\nIncomplete: bytes ${offset}-${end} of ${bytes.length}. Continue with command:\n${command} --offset ${end}`;
|
|
150
172
|
let end = offset + MAX_OUTPUT_BYTES - Buffer.byteLength(footer(bytes.length));
|
|
151
173
|
while (((bytes[end] ?? 0) & 0xc0) === 0x80) end--;
|
|
152
|
-
return bytes.subarray(offset, end).toString("utf8") + footer(end);
|
|
174
|
+
return page(bytes.subarray(offset, end).toString("utf8") + footer(end), end);
|
|
153
175
|
}
|
|
154
176
|
|
|
155
177
|
export function runSkills(
|
|
@@ -160,19 +182,33 @@ export function runSkills(
|
|
|
160
182
|
: undefined,
|
|
161
183
|
loadedSkills: readonly LoadedSkill[] = [],
|
|
162
184
|
gpt = false,
|
|
163
|
-
)
|
|
185
|
+
) {
|
|
164
186
|
const request = parseRequest(input);
|
|
165
187
|
const skills = discoverVisibleSkills(globalRoot, sessionRoot, loadedSkills);
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
188
|
+
const result: SkillReadOutput = { output: "", reads: [] };
|
|
189
|
+
for (const [index, command] of request.commands.entries()) {
|
|
190
|
+
if (index) result.output += "\n\n";
|
|
191
|
+
if (command.action === "read") {
|
|
192
|
+
const selected = readSkillPackage(
|
|
193
|
+
skills,
|
|
194
|
+
command.name,
|
|
195
|
+
command.selectors,
|
|
196
|
+
);
|
|
197
|
+
const start = Buffer.byteLength(result.output);
|
|
198
|
+
result.output += selected.output;
|
|
199
|
+
result.reads.push(
|
|
200
|
+
...selected.reads.map((span) => ({
|
|
201
|
+
read: span.read,
|
|
202
|
+
start: start + span.start,
|
|
203
|
+
end: start + span.end,
|
|
204
|
+
})),
|
|
205
|
+
);
|
|
206
|
+
} else {
|
|
207
|
+
result.output +=
|
|
169
208
|
command.action === "help"
|
|
170
|
-
? `${gpt ? 'list [category...] | read <skill> [skill-or-reference...] | help; separator ;\nJS: tools.skills("read <skill>")' : 'Commands: list [category...] | read <skill> [skill-or-reference...] | help. Join commands with ;\nJS: tools.skills("read <skill>")'}\n\n${formatSkillList(skills)}`
|
|
171
|
-
: command.
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
.join("\n\n"),
|
|
176
|
-
request,
|
|
177
|
-
);
|
|
209
|
+
? `${gpt ? 'list [category...] | read <skill> [skill-or-reference...] | help; separator ;\nJS: tools.skills("read <skill>")' : 'Commands: list [category...] | read <skill> [skill-or-reference...] | help. Join commands with ;\nJS: tools.skills("read <skill>")'}\n${gpt ? GPT_READ_HELP : READ_HELP}\n\n${formatSkillList(skills)}`
|
|
210
|
+
: `${gpt ? GPT_READ_HELP : READ_HELP}\n\n${formatSkillList(skills, command.categories)}`;
|
|
211
|
+
}
|
|
212
|
+
}
|
|
213
|
+
return boundedOutput(result, request);
|
|
178
214
|
}
|
package/src/skill-package.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { Buffer } from "node:buffer";
|
|
1
2
|
import { readFileSync, realpathSync, statSync } from "node:fs";
|
|
2
3
|
import { isAbsolute, join, relative, resolve, sep } from "node:path";
|
|
3
4
|
import {
|
|
@@ -135,10 +136,6 @@ function formatSkillPaths(skill: CatalogSkill): string {
|
|
|
135
136
|
return `---\nSkill paths (${paths.length}):\n${paths.map((path) => `- ${path}`).join("\n")}`;
|
|
136
137
|
}
|
|
137
138
|
|
|
138
|
-
function formatSkill(skill: CatalogSkill): string {
|
|
139
|
-
return `${skill.body}\n\n${formatSkillPaths(skill)}`;
|
|
140
|
-
}
|
|
141
|
-
|
|
142
139
|
function referenceFiles(skill: CatalogSkill): string[] {
|
|
143
140
|
const root = resolve(skill.directory, "references");
|
|
144
141
|
return packageFiles(skill).filter(
|
|
@@ -279,51 +276,59 @@ function deduplicateSelections(selections: ReadSelection[]): ReadSelection[] {
|
|
|
279
276
|
});
|
|
280
277
|
}
|
|
281
278
|
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
}));
|
|
288
|
-
const content =
|
|
289
|
-
withContent.length === 1
|
|
290
|
-
? (withContent[0]?.content ?? "")
|
|
291
|
-
: withContent
|
|
292
|
-
.map(({ skill, reference, content: body }) => {
|
|
293
|
-
const label = oneSkill
|
|
294
|
-
? reference
|
|
295
|
-
: `${skill.name}/references/${reference}`;
|
|
296
|
-
return `--- ${label} ---\n${body}`;
|
|
297
|
-
})
|
|
298
|
-
.join("\n\n");
|
|
299
|
-
return `${content}\n\n---\nSources:\n${withContent.map(({ path }) => `- ${path}`).join("\n")}`;
|
|
279
|
+
interface SkillRead {
|
|
280
|
+
name: string;
|
|
281
|
+
skillPath: string;
|
|
282
|
+
path: string;
|
|
283
|
+
kind: "skill" | "reference";
|
|
300
284
|
}
|
|
301
285
|
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
.
|
|
311
|
-
const
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
286
|
+
export interface SkillReadOutput {
|
|
287
|
+
output: string;
|
|
288
|
+
reads: { read: SkillRead; start: number; end: number }[];
|
|
289
|
+
}
|
|
290
|
+
|
|
291
|
+
function formatSelections(selections: ReadSelection[]): SkillReadOutput {
|
|
292
|
+
const referencesOnly = selections.every(({ kind }) => kind === "reference");
|
|
293
|
+
const oneSkill =
|
|
294
|
+
new Set(selections.map(({ skill }) => skill.name)).size === 1;
|
|
295
|
+
const result: SkillReadOutput = { output: "", reads: [] };
|
|
296
|
+
const sources: string[] = [];
|
|
297
|
+
for (const selection of selections) {
|
|
298
|
+
if (result.reads.length) result.output += "\n\n";
|
|
299
|
+
const { skill, kind } = selection;
|
|
300
|
+
const path = kind === "skill" ? skill.path : selection.path;
|
|
301
|
+
const body =
|
|
302
|
+
kind === "skill" ? skill.body : readFileSync(path, "utf8").trim();
|
|
303
|
+
if (selections.length > 1) {
|
|
304
|
+
const label =
|
|
305
|
+
kind === "skill"
|
|
306
|
+
? skill.name
|
|
307
|
+
: referencesOnly && oneSkill
|
|
308
|
+
? selection.reference
|
|
309
|
+
: `${skill.name}/references/${selection.reference}`;
|
|
310
|
+
result.output += `--- ${label} ---\n`;
|
|
311
|
+
}
|
|
312
|
+
const start = Buffer.byteLength(result.output);
|
|
313
|
+
result.output += body;
|
|
314
|
+
result.reads.push({
|
|
315
|
+
read: { name: skill.name, skillPath: skill.path, path, kind },
|
|
316
|
+
start,
|
|
317
|
+
end: Buffer.byteLength(result.output),
|
|
318
|
+
});
|
|
319
|
+
if (kind === "skill") result.output += `\n\n${formatSkillPaths(skill)}`;
|
|
320
|
+
else sources.push(`- ${path}`);
|
|
321
|
+
}
|
|
322
|
+
if (sources.length)
|
|
323
|
+
result.output += `\n\n---\nSources:\n${sources.join("\n")}`;
|
|
324
|
+
return result;
|
|
320
325
|
}
|
|
321
326
|
|
|
322
327
|
export function readSkillPackage(
|
|
323
328
|
skills: CatalogSkill[],
|
|
324
329
|
name: string,
|
|
325
330
|
selectors: string[],
|
|
326
|
-
):
|
|
331
|
+
): SkillReadOutput {
|
|
327
332
|
const catalog: ReferenceCatalog = new Map();
|
|
328
333
|
const primary = resolvePrimarySelection(skills, name, catalog);
|
|
329
334
|
let selectedSkill = primary.skill;
|
|
@@ -346,16 +351,5 @@ export function readSkillPackage(
|
|
|
346
351
|
? additional
|
|
347
352
|
: [primary, ...additional],
|
|
348
353
|
);
|
|
349
|
-
|
|
350
|
-
const selection = selections[0] as ReadSelection;
|
|
351
|
-
return selection.kind === "skill"
|
|
352
|
-
? formatSkill(selection.skill)
|
|
353
|
-
: formatReferences([selection]);
|
|
354
|
-
}
|
|
355
|
-
return selections.every(
|
|
356
|
-
(selection): selection is ReferenceSelection =>
|
|
357
|
-
selection.kind === "reference",
|
|
358
|
-
)
|
|
359
|
-
? formatReferences(selections)
|
|
360
|
-
: formatMixedSelections(selections);
|
|
354
|
+
return formatSelections(selections);
|
|
361
355
|
}
|
package/src/tool.ts
CHANGED
|
@@ -26,7 +26,9 @@ export interface SkillsToolOptions {
|
|
|
26
26
|
export function prepareSkillsCodeModeInput(input: unknown): SkillsParameters {
|
|
27
27
|
if (input === undefined) return {};
|
|
28
28
|
if (typeof input !== "string")
|
|
29
|
-
throw new Error(
|
|
29
|
+
throw new Error(
|
|
30
|
+
'Expected a string command or no arguments: tools.skills() for discovery, tools.skills("read <skill>") to read',
|
|
31
|
+
);
|
|
30
32
|
return { command: input };
|
|
31
33
|
}
|
|
32
34
|
|
|
@@ -40,7 +42,7 @@ export function createSkillsTool(options: SkillsToolOptions = {}) {
|
|
|
40
42
|
],
|
|
41
43
|
parameters: SkillsParameters,
|
|
42
44
|
async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
|
|
43
|
-
const output = runSkills(
|
|
45
|
+
const { output, skillReads } = runSkills(
|
|
44
46
|
params.command ?? "",
|
|
45
47
|
options.globalRoot ?? defaultSkillsDir(),
|
|
46
48
|
defaultSessionSkillsDir(ctx.cwd),
|
|
@@ -49,7 +51,7 @@ export function createSkillsTool(options: SkillsToolOptions = {}) {
|
|
|
49
51
|
);
|
|
50
52
|
return {
|
|
51
53
|
content: [{ type: "text", text: output }],
|
|
52
|
-
details: {},
|
|
54
|
+
details: { skillReads },
|
|
53
55
|
};
|
|
54
56
|
},
|
|
55
57
|
});
|