@adeildo/pi-skills 0.0.0 → 5.5.0

package/LICENSE

@@ -0,0 +1,28 @@
+MIT License
+
+Copyright (c) 2026 adeildo
+
+Parts of this package are ported from rpiv-ask-user-question
+(https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-ask-user-question):
+the tool's schema, the validation and line-ending cleanup, the preview layout and box,
+and the RPC dialog walker. Those parts are also:
+
+Copyright (c) 2026 juicesharp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,43 @@
-# @adeildo/pi-skills
+<h1 align="center">@adeildo/pi-skills</h1>
 
-Placeholder. The real package starts at 5.4.0: https://github.com/felipeadeildo/pi-harness/tree/main/packages/skills
+<p align="center">
+  <a href="https://www.npmjs.com/package/@adeildo/pi-skills"><img src="https://img.shields.io/npm/v/@adeildo/pi-skills" alt="npm"></a>
+  <a href="https://pi.dev"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Ffelipeadeildo%2Fpi-harness%2Fmain%2Fpackage.json&query=%24.devDependencies%5B%22%40earendil-works%2Fpi-coding-agent%22%5D&label=pi%20SDK&color=6E56CF" alt="pi SDK"></a>
+</p>
+
+<p align="center">
+  <strong>Call your skills from anywhere in a message, several at once.</strong><br>
+  The model reads each one in full. The chat shows a small chip where you typed it.
+</p>
+
+<p align="center"><code>pi install npm:@adeildo/pi-skills</code></p>
+
+## What changes
+
+This piece brings no skills of its own. It changes how you call the ones pi already loaded, from your skill folders or from packages.
+
+Pi expands `/skill:name` only at the start of a message, and only one. With this piece, any `/skill:name` in the text counts:
+
+```text
+use /skill:simplify, then go over the docs with /skill:unslop
+```
+
+Before the message, the model gets one block per skill, the same `<skill>` block pi writes for `/skill:name`. Your text reaches it as you typed it. In the chat, each reference shows as `[skill] name` on a violet background, the way pi labels a folded skill. The blocks stay folded until `Ctrl+O`, which expands tool output, shows them in full.
+
+A reference counts when it names a skill pi loaded and follows a space, the start of a line or an opening bracket. Inside backticks it stays text.
+
+## Typing a reference
+
+A `/` past the start of the message opens a list of the skills alone, narrowed as you type, the way pi's palette does at the start. Picking one writes `/skill:name` and a space. The list opens on `/` in the editor of [`@adeildo/pi-look`](../look), which also colors each reference while you type. In any other editor, `Tab` after the `/` opens it.
+
+At the start of the message, `/` still opens pi's own palette, with the commands and the skills.
+
+## Notes
+
+- A message that starts with `/skill:` goes out with a space before it, so pi does not expand that skill a second time. The chat does not draw the space.
+- While the model works, the skills queue with the message, as a steer or a follow-up.
+- If a skill file cannot be read, the message goes without that skill and a warning says why.
+
+## License
+
+MIT

package/package.json

@@ -1,12 +1,50 @@
 {
 	"name": "@adeildo/pi-skills",
-	"version": "0.0.0",
-	"description": "Placeholder that reserves the name for trusted publishing. Install 5.4.0 or later.",
+	"version": "5.5.0",
+	"description": "Call the skills you already have from anywhere in a message, several at once. The model reads each one in full, and the chat shows a small chip where you typed it.",
+	"keywords": [
+		"pi",
+		"pi-coding-agent",
+		"pi-extension",
+		"pi-package",
+		"skills"
+	],
+	"homepage": "https://github.com/felipeadeildo/pi-harness/tree/main/packages/skills#readme",
+	"bugs": "https://github.com/felipeadeildo/pi-harness/issues",
 	"license": "MIT",
+	"author": {
+		"name": "adeildo",
+		"email": "contato@felipeadeildo.com",
+		"url": "https://github.com/felipeadeildo"
+	},
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/felipeadeildo/pi-harness.git",
 		"directory": "packages/skills"
 	},
-	"publishConfig": { "access": "public" }
+	"files": [
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"type": "module",
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@adeildo/pi-kit": "5.5.0"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*"
+	},
+	"pi": {
+		"extensions": [
+			"./src/index.ts"
+		]
+	}
 }

package/src/complete.ts

@@ -0,0 +1,63 @@
+// Pi's palette opens on `/` only at the start of a message. This one lists only the skills, anywhere
+// else in the text: the look's editor opens it on `/`, and Tab opens it in any editor.
+import { SKILL_REF, skillQueryAt } from "@adeildo/pi-kit";
+import {
+	type AutocompleteItem,
+	type AutocompleteProvider,
+	fuzzyFilter,
+} from "@earendil-works/pi-tui";
+
+import type { Skill } from "./skills.ts";
+
+export function completeSkills(
+	current: AutocompleteProvider,
+	skills: () => readonly Skill[],
+): AutocompleteProvider {
+	return {
+		triggerCharacters: current.triggerCharacters,
+
+		async getSuggestions(lines, cursorLine, cursorCol, options) {
+			const typing = skillQueryAt(lines, cursorLine, cursorCol);
+			if (typing !== undefined) {
+				const items = matching(skills(), typing.query);
+				if (items.length > 0) return { items, prefix: typing.typed };
+			}
+			return current.getSuggestions(lines, cursorLine, cursorCol, options);
+		},
+
+		applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
+			if (!item.value.startsWith(SKILL_REF) || !prefix.startsWith("/"))
+				return current.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
+
+			const line = lines[cursorLine] ?? "";
+			const start = cursorCol - prefix.length;
+			const rest = line.slice(cursorCol);
+			const after = rest.startsWith(" ") ? rest : ` ${rest}`;
+			return {
+				lines: lines.with(cursorLine, line.slice(0, start) + item.value + after),
+				cursorLine,
+				cursorCol: start + item.value.length + 1,
+			};
+		},
+
+		shouldTriggerFileCompletion(lines, cursorLine, cursorCol) {
+			if (skillQueryAt(lines, cursorLine, cursorCol) !== undefined) return true;
+			return current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ?? true;
+		},
+	};
+}
+
+/** As pi's palette matches: by the bare name first, then by `skill:name`. */
+function matching(skills: readonly Skill[], query: string): AutocompleteItem[] {
+	const byName = fuzzyFilter([...skills], query, (skill) => skill.name);
+	const byRef = fuzzyFilter(
+		skills.filter((skill) => !byName.includes(skill)),
+		query,
+		(skill) => `skill:${skill.name}`,
+	);
+	return [...byName, ...byRef].map((skill) => ({
+		value: `${SKILL_REF}${skill.name}`,
+		label: `skill:${skill.name}`,
+		description: skill.description,
+	}));
+}

package/src/index.ts

@@ -0,0 +1,106 @@
+import {
+	addSkillNames,
+	createApp,
+	defineFeature,
+	drawSkillRefs,
+	type FeatureScope,
+	referencedSkills,
+	SKILL_NAMES,
+	SKILL_REF,
+} from "@adeildo/pi-kit";
+import type { TextContent } from "@earendil-works/pi-ai";
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+	InputEvent,
+	InputEventResult,
+} from "@earendil-works/pi-coding-agent";
+
+import { completeSkills } from "./complete.ts";
+import { chip, renderSkills } from "./render.ts";
+import { loadedSkills, type Skill, skillBlock } from "./skills.ts";
+
+export { loadedSkills, skillBlock, type Skill } from "./skills.ts";
+
+/** The message that carries the skills a message named, right before it. */
+export const SKILLS_MESSAGE = "pi-skills";
+
+export const skills = defineFeature({
+	id: "skills",
+	description: "Call the skills you already have from anywhere in a message, several at once",
+	setup(scope) {
+		let session: ExtensionContext | undefined;
+
+		scope.onSessionStart((ctx) => {
+			session = ctx;
+			if (ctx.mode === "tui")
+				ctx.ui.addAutocompleteProvider((current) =>
+					completeSkills(current, () => loadedSkills(scope)),
+				);
+		});
+		scope.onShutdown(() => {
+			session = undefined;
+		});
+
+		scope.events.on(SKILL_NAMES, (data: unknown) => addSkillNames(data, namesOf(scope)));
+
+		scope.on("input", (event, ctx) => expand(scope, ctx, event));
+
+		scope.registerMessageRenderer(SKILLS_MESSAGE, (message, options) =>
+			renderSkills(message, options.expanded),
+		);
+
+		scope.registerMarkdownTransformer((markdown, context) => {
+			const theme = session?.mode === "tui" ? session.ui.theme : undefined;
+			if (context.messageType !== "user" || theme === undefined) return markdown;
+			const typed = markdown.startsWith(` ${SKILL_REF}`) ? markdown.slice(1) : markdown;
+			return drawSkillRefs(typed, namesOf(scope), (name) => chip(theme, name));
+		});
+	},
+});
+
+/**
+ * The skills the message names go first, in one message the model reads and the chat folds. The
+ * text stays as you typed it, but for a space before a leading `/skill:`, which keeps pi from
+ * expanding that one again. Markdown does not draw the space.
+ */
+function expand(
+	scope: FeatureScope,
+	ctx: ExtensionContext,
+	event: InputEvent,
+): InputEventResult | undefined {
+	const loaded = loadedSkills(scope);
+	const named = referencedSkills(
+		event.text,
+		loaded.map((skill) => skill.name),
+	);
+	const blocks = named.flatMap((name) => blockOf(ctx, loaded, name));
+	if (blocks.length === 0) return undefined;
+
+	scope.sendMessage(
+		{ customType: SKILLS_MESSAGE, content: blocks, display: true, details: { skills: named } },
+		event.streamingBehavior && { deliverAs: event.streamingBehavior },
+	);
+	if (!event.text.startsWith(SKILL_REF)) return undefined;
+	return { action: "transform", text: ` ${event.text}` };
+}
+
+function blockOf(ctx: ExtensionContext, loaded: readonly Skill[], name: string): TextContent[] {
+	const skill = loaded.find((entry) => entry.name === name);
+	if (skill === undefined) return [];
+	try {
+		return [{ type: "text", text: skillBlock(skill) }];
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		ctx.ui.notify(`pi-skills: could not read ${name}: ${reason}`, "warning");
+		return [];
+	}
+}
+
+function namesOf(pi: Pick<ExtensionAPI, "getCommands">): string[] {
+	return loadedSkills(pi).map((skill) => skill.name);
+}
+
+export default function piSkills(pi: ExtensionAPI): void {
+	createApp(pi, { name: "pi-skills" }).use(skills).build();
+}

package/src/render.ts

@@ -0,0 +1,45 @@
+import {
+	getMarkdownTheme,
+	type MessageRenderer,
+	parseSkillBlock,
+	SkillInvocationMessageComponent,
+	type Theme,
+} from "@earendil-works/pi-coding-agent";
+import { type Component, Container, Spacer } from "@earendil-works/pi-tui";
+
+type SkillsMessage = Parameters<MessageRenderer>[0];
+
+const NBSP = "\u00a0";
+
+/** A skill where you typed it, drawn as pi draws a folded skill: `[skill] name`. */
+export function chip(theme: Theme, name: string): string {
+	const label = theme.fg("customMessageLabel", "\x1b[1m[skill]\x1b[22m");
+	const inside = `${NBSP}${label}${NBSP}${theme.fg("customMessageText", name)}${NBSP}`;
+	// The line keeps its own colors after the chip.
+	return (
+		theme.bg("customMessageBg", inside) +
+		theme.getBgAnsi("userMessageBg") +
+		theme.getFgAnsi("userMessageText")
+	);
+}
+
+/** Nothing until the tool output expands, then each skill in full, as pi shows one. */
+export function renderSkills(message: SkillsMessage, expanded: boolean): Component {
+	const shown = new Container();
+	if (!expanded) return shown;
+
+	for (const text of textsOf(message)) {
+		const block = parseSkillBlock(text);
+		if (block === null) continue;
+		if (shown.children.length > 0) shown.addChild(new Spacer(1));
+		const skill = new SkillInvocationMessageComponent(block, getMarkdownTheme());
+		skill.setExpanded(true);
+		shown.addChild(skill);
+	}
+	return shown;
+}
+
+function textsOf(message: SkillsMessage): string[] {
+	if (typeof message.content === "string") return [message.content];
+	return message.content.flatMap((part) => (part.type === "text" ? [part.text] : []));
+}

package/src/skills.ts

@@ -0,0 +1,30 @@
+import { readFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+import { type ExtensionAPI, stripFrontmatter } from "@earendil-works/pi-coding-agent";
+
+export interface Skill {
+	name: string;
+	description?: string;
+	filePath: string;
+}
+
+const PREFIX = "skill:";
+
+/** The skills pi loaded for this session, which `/skill:` can name. */
+export function loadedSkills(pi: Pick<ExtensionAPI, "getCommands">): Skill[] {
+	return pi
+		.getCommands()
+		.filter((command) => command.source === "skill" && command.name.startsWith(PREFIX))
+		.map((command) => ({
+			name: command.name.slice(PREFIX.length),
+			description: command.description,
+			filePath: command.sourceInfo.path,
+		}));
+}
+
+/** The skill as the model reads it, in the block pi writes for `/skill:name`. */
+export function skillBlock(skill: Skill): string {
+	const body = stripFrontmatter(readFileSync(skill.filePath, "utf8")).trim();
+	return `<skill name="${skill.name}" location="${skill.filePath}">\nReferences are relative to ${dirname(skill.filePath)}.\n\n${body}\n</skill>`;
+}