@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 +11 -0
- package/README.md +7 -2
- package/index.ts +1 -1
- package/package.json +7 -7
- package/src/catalog.ts +60 -12
- package/src/skill-package.ts +16 -3
- package/src/tool.ts +2 -1
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.
|
|
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.
|
|
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") //
|
|
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.
|
|
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.
|
|
44
|
-
"@earendil-works/pi-coding-agent": ">=0.
|
|
45
|
-
"@earendil-works/pi-tui": ">=0.
|
|
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.
|
|
54
|
+
"@howaboua/pi-codex-conversion": "3.0.43",
|
|
55
55
|
"@biomejs/biome": "^2.5.10",
|
|
56
|
-
"@earendil-works/pi-coding-agent": "0.
|
|
57
|
-
"@earendil-works/pi-tui": "0.
|
|
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
|
-
|
|
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:
|
|
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
|
|
101
|
-
const bytes = Buffer.
|
|
102
|
-
|
|
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
|
-
|
|
139
|
+
`--offset ${offset} is outside output (${bytes.length} bytes)`,
|
|
105
140
|
);
|
|
106
|
-
|
|
107
|
-
|
|
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
|
|
121
|
-
request.
|
|
122
|
-
|
|
123
|
-
|
|
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
|
}
|
package/src/skill-package.ts
CHANGED
|
@@ -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
|
-
|
|
327
|
-
|
|
328
|
-
|
|
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:
|
|
14
|
+
description:
|
|
15
|
+
"list [category...] | read <skill> [skill-or-reference...]; separate commands with ;",
|
|
15
16
|
}),
|
|
16
17
|
},
|
|
17
18
|
{ additionalProperties: false },
|