@howaboua/pi-better-skills-tool 0.0.3 → 0.0.4
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 +4 -0
- package/README.md +5 -2
- package/index.ts +1 -1
- package/package.json +3 -3
- package/src/catalog.ts +5 -5
- package/src/skill-package.ts +194 -105
- package/src/tool.ts +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,9 @@
|
|
|
1
1
|
# @howaboua/pi-better-skills-tool
|
|
2
2
|
|
|
3
|
+
## 0.0.4
|
|
4
|
+
|
|
5
|
+
- The skills tool now reads mixed skills and unique cross-skill references in one call. Ambiguous reference names report their qualified choices.
|
|
6
|
+
|
|
3
7
|
## 0.0.3
|
|
4
8
|
|
|
5
9
|
- 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
|
|
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.
|
|
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
|
|
48
|
+
'await tools.skills("list") // or "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
|
+
"version": "0.0.4",
|
|
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.
|
|
43
|
+
"@howaboua/pi-codex-conversion": ">=3.0.34",
|
|
44
44
|
"@earendil-works/pi-coding-agent": ">=0.84.3",
|
|
45
45
|
"@earendil-works/pi-tui": ">=0.84.3",
|
|
46
46
|
"typebox": "*"
|
|
@@ -51,7 +51,7 @@
|
|
|
51
51
|
}
|
|
52
52
|
},
|
|
53
53
|
"devDependencies": {
|
|
54
|
-
"@howaboua/pi-codex-conversion": "3.0.
|
|
54
|
+
"@howaboua/pi-codex-conversion": "3.0.34",
|
|
55
55
|
"@biomejs/biome": "^2.5.10",
|
|
56
56
|
"@earendil-works/pi-coding-agent": "0.85.1",
|
|
57
57
|
"@earendil-works/pi-tui": "0.85.1",
|
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;
|
|
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
|
-
|
|
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.
|
|
123
|
+
: readSkillPackage(skills, request.name, request.selectors),
|
|
124
124
|
);
|
|
125
125
|
}
|
package/src/skill-package.ts
CHANGED
|
@@ -55,57 +55,30 @@ function findSkillByName(
|
|
|
55
55
|
);
|
|
56
56
|
}
|
|
57
57
|
|
|
58
|
-
function
|
|
59
|
-
|
|
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(
|
|
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
|
|
152
|
+
function referencesForSkill(
|
|
180
153
|
skill: CatalogSkill,
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
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
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
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
|
-
|
|
233
|
-
? (
|
|
234
|
-
:
|
|
235
|
-
.map(
|
|
236
|
-
|
|
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${
|
|
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
|
-
|
|
322
|
+
selectors: string[],
|
|
246
323
|
): string {
|
|
247
|
-
const
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
);
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
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
|
-
|
|
257
|
-
|
|
258
|
-
|
|
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 },
|