@chankov/agent-skills 0.1.0 → 0.3.0

package/.versions/0.2.0/.pi/extensions/chrome-devtools-mcp/README.md

@@ -0,0 +1,39 @@
+# chrome-devtools-mcp
+
+A pi extension that bridges the [`chrome-devtools-mcp`](https://www.npmjs.com/package/chrome-devtools-mcp) server into pi as native tools.
+
+Built on top of `../mcp-bridge/` — this file is a thin wrapper that supplies Chrome-specific config.
+
+## What you get
+
+After installing, pi exposes the full Chrome DevTools MCP toolset under the `chrome_devtools__` prefix (e.g. `chrome_devtools__navigate`, `chrome_devtools__click`, etc.). A status command `/chrome_devtools-status` reports whether the bridge connected.
+
+This unlocks the workflow described in `skills/browser-testing-with-devtools/` for pi users.
+
+## Install
+
+Symlink both extensions from this repo into your project's `.pi/extensions/`:
+
+```bash
+mkdir -p .pi/extensions
+ln -s /path/to/agent-skills/.pi/extensions/mcp-bridge          .pi/extensions/mcp-bridge
+ln -s /path/to/agent-skills/.pi/extensions/chrome-devtools-mcp .pi/extensions/chrome-devtools-mcp
+```
+
+`mcp-bridge` is a sibling library; `chrome-devtools-mcp` imports it via the relative path. Runtime dependencies are hoisted to `.pi/extensions/package.json` — run `npm ci` there once after cloning `agent-skills` (see [docs/pi-setup.md](../../../docs/pi-setup.md#optional-pi-extensions)).
+
+## Verify
+
+Run `pi` from the project, then:
+
+```
+/chrome_devtools-status
+```
+
+Expect: `Chrome DevTools MCP connected. Registered N tool(s).`
+
+Type `chrome_devtools__` in tool autocomplete to see the wrapped tools.
+
+## Note
+
+This extension exists because pi does not yet have first-class MCP infrastructure. Once pi supports MCP servers natively, this wrapper will be retired in favor of the native mechanism.

package/.versions/0.2.0/.pi/extensions/chrome-devtools-mcp/index.ts

@@ -0,0 +1,61 @@
+import process from "node:process";
+import { createMcpBridgeExtension } from "../mcp-bridge/index.js";
+
+const GUI_ENV_KEYS = [
+	"DISPLAY",
+	"XAUTHORITY",
+	"WAYLAND_DISPLAY",
+	"XDG_RUNTIME_DIR",
+	"XDG_SESSION_TYPE",
+	"XDG_CURRENT_DESKTOP",
+	"DBUS_SESSION_BUS_ADDRESS",
+] as const;
+
+const NODE_WEBSTORAGE_DISABLE_OPTION = "--no-experimental-webstorage";
+
+function appendNodeOption(current: string | undefined, option: string): string {
+	const parts = current?.trim() ? current.trim().split(/\s+/) : [];
+	if (!parts.includes(option)) parts.push(option);
+	return parts.join(" ");
+}
+
+function supportsNoExperimentalWebStorage(): boolean {
+	const major = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
+	return major >= 25;
+}
+
+function buildChromeDevToolsEnv(): Record<string, string> {
+	const env: Record<string, string> = {};
+
+	for (const key of GUI_ENV_KEYS) {
+		const value = process.env[key];
+		if (value) env[key] = value;
+	}
+
+	// Avoid unsolicited update-check output in the MCP child process.
+	env.CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS = "1";
+
+	// Node 25 exposes experimental Web Storage. A bundled chrome-devtools-mcp
+	// dependency probes localStorage at startup, which emits a
+	// `--localstorage-file` warning unless Web Storage is disabled for this child.
+	if (supportsNoExperimentalWebStorage()) {
+		env.NODE_OPTIONS = appendNodeOption(process.env.NODE_OPTIONS, NODE_WEBSTORAGE_DISABLE_OPTION);
+	}
+
+	return env;
+}
+
+export default createMcpBridgeExtension({
+	prefix: "chrome_devtools__",
+	command: "npx",
+	args: [
+		"-y",
+		"chrome-devtools-mcp@latest",
+		"--isolated",
+		"--no-usage-statistics",
+		"--no-performance-crux",
+	],
+	env: buildChromeDevToolsEnv(),
+	stderr: "pipe",
+	labelPrefix: "Chrome DevTools",
+});

package/.versions/0.2.0/.pi/extensions/chrome-devtools-mcp/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "agent-skills-pi-chrome-devtools-mcp",
+  "private": true,
+  "type": "module",
+  "main": "index.ts"
+}

package/.versions/0.2.0/.pi/extensions/compact-and-continue/README.md

@@ -0,0 +1,42 @@
+# compact-and-continue
+
+A pi extension that registers a single tool, `request_compaction`, for queueing pi context compaction at a safe checkpoint and (optionally) resuming work from a self-contained continuation prompt afterward.
+
+## What it does
+
+`request_compaction` does **not** compact immediately. It queues the request, lets the current agent turn finish, then runs compaction on `agent_end`. If a `continuationPrompt` is provided, the extension re-injects it as a new user message after compaction finishes — pi picks up exactly where the summarized plan says to continue.
+
+This keeps the user in control: compaction never interrupts a tool call mid-flight, and resumption is explicit (you decide what survives the compaction by what you put in `continuationPrompt`).
+
+## Tool: `request_compaction`
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `customInstructions` | string | no | Instructions for the compaction summary. Defaults to: *"Preserve task goal, completed work, changed/read files, decisions, blockers, and next steps."* |
+| `reason` | string | no | Short explanation recorded in tool details. |
+| `continuationPrompt` | string | no | Self-contained summary of the remaining plan. If provided, pi auto-resumes from this message after compaction. **Do not copy the original prompt verbatim** — restate the next concrete actions. |
+
+The tool does not ask for confirmation. Workflows that need confirmation (e.g. `/build`) must ask the user **before** calling it.
+
+## When to use
+
+Use only when explicitly requested by the user, a skill, or a prompt template. Do not call it pre-emptively or on a hunch that context is "getting long" — pi has its own autocompaction for that.
+
+The canonical usage point in this repo is `/build`: at slice-approval time, the user can pick "Compact & continue" to compact between slices and resume from a summarized remaining plan. See `.pi/prompts/build.md` and `skills/incremental-implementation/SKILL.md`.
+
+## Install
+
+Symlink alongside the other extensions (see [docs/pi-setup.md](../../../docs/pi-setup.md#optional-pi-extensions)):
+
+```bash
+ln -s /path/to/agent-skills/.pi/extensions/compact-and-continue .pi/extensions/compact-and-continue
+```
+
+The only runtime dep (`typebox`) is already hoisted at `.pi/extensions/package.json` for the other extensions, so no extra `npm ci` is needed if you've already installed.
+
+## Behavior notes
+
+- Multiple queued requests in the same turn are coalesced into one compaction with all reasons concatenated.
+- Only the latest `continuationPrompt` (last queued) is honored.
+- If compaction fails, the error is surfaced via `ctx.ui.notify` and the queue is drained — pi does not auto-retry.
+- The tool returns `terminate: true`, ending the current turn so `agent_end` can fire and the queued compaction can run.

package/.versions/0.2.0/.pi/extensions/compact-and-continue/index.ts

@@ -0,0 +1,120 @@
+import type { CompactionResult, ExtensionAPI, ExtensionContext } from '@mariozechner/pi-coding-agent';
+import { Type } from 'typebox';
+
+const DEFAULT_COMPACTION_INSTRUCTIONS = 'Preserve task goal, completed work, changed/read files, decisions, blockers, and next steps.';
+
+const RequestCompactionParams = Type.Object({
+	customInstructions: Type.Optional(Type.String({
+		description: 'Instructions for the compaction summary. Include what must be preserved for continuing safely.',
+	})),
+	reason: Type.Optional(Type.String({
+		description: 'Short explanation recorded in tool details for why immediate compaction was requested.',
+	})),
+	continuationPrompt: Type.Optional(Type.String({
+		description: 'Self-contained summary of the remaining plan to execute after compaction. Do not copy the original prompt verbatim. Include the next concrete actions. If the original plan explicitly requires later compaction checkpoints, include them; otherwise do not repeat the same compaction request.',
+	})),
+});
+
+function compact(ctx: ExtensionContext, customInstructions: string): Promise<CompactionResult> {
+	return new Promise((resolve, reject) => {
+		ctx.compact({
+			customInstructions,
+			onComplete: resolve,
+			onError: reject,
+		});
+	});
+}
+
+export default function compactAndContinueExtension(pi: ExtensionAPI) {
+	type PendingCompaction = {
+		customInstructions: string;
+		reason: string;
+		continuationPrompt?: string;
+	};
+
+	const pendingCompactions: PendingCompaction[] = [];
+	let compactionRunning = false;
+
+	async function runQueuedCompactions(ctx: ExtensionContext): Promise<void> {
+		if (compactionRunning || pendingCompactions.length === 0) {
+			return;
+		}
+
+		compactionRunning = true;
+		const pending = pendingCompactions.splice(0);
+		const customInstructions = pending
+			.map((item, index) => [
+				`Queued compaction request ${index + 1}/${pending.length}.`,
+				`Reason: ${item.reason}`,
+				item.customInstructions,
+			].join(' '))
+			.join('\n\n');
+		const continuationRequest = [...pending].reverse().find(item => item.continuationPrompt !== undefined);
+
+		try {
+			ctx.ui.notify('Compacting queued context request.', 'info');
+			await compact(ctx, customInstructions);
+			ctx.ui.notify('Queued compaction finished.', 'info');
+
+			if (continuationRequest?.continuationPrompt) {
+				ctx.ui.notify('Continuing summarized plan after compaction.', 'info');
+				setTimeout(() => pi.sendUserMessage(continuationRequest.continuationPrompt!), 0);
+			}
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			ctx.ui.notify(`Queued compaction failed: ${message}`, 'error');
+		} finally {
+			compactionRunning = false;
+			if (pendingCompactions.length > 0) {
+				setTimeout(() => void runQueuedCompactions(ctx), 0);
+			}
+		}
+	}
+
+	pi.on('agent_end', async (_event, ctx) => {
+		if (pendingCompactions.length > 0 && !compactionRunning) {
+			setTimeout(() => void runQueuedCompactions(ctx), 0);
+		}
+	});
+
+	pi.registerTool({
+		name: 'request_compaction',
+		label: 'Request Compaction',
+		description: 'Queue pi context compaction to run as soon as the current agent turn finishes. Use only when the user, a skill, or a prompt explicitly asks for compaction. If more work should continue after compaction, provide continuationPrompt as a concise summary of the remaining plan rather than the original prompt verbatim. This tool does not ask for confirmation; workflows that need confirmation must ask the user before calling it.',
+		promptSnippet: 'request_compaction(customInstructions?, reason?, continuationPrompt?) - queue context compaction after the current turn, then optionally continue from a summarized remaining plan.',
+		promptGuidelines: [
+			'Use request_compaction only when compaction was explicitly requested by the user, skill, or prompt.',
+			'If user confirmation is required, ask the user before calling request_compaction; this tool does not ask for confirmation.',
+			'Use request_compaction when the user asks to compact now or before continuing to later steps in the same task.',
+			'Provide customInstructions that preserve goals, decisions, files read/modified, blockers, and next steps.',
+			'When work should continue after compaction, provide continuationPrompt as a concise, self-contained summary of the remaining plan; do not copy the original prompt verbatim.',
+			'If the original plan explicitly requires later compaction checkpoints, include those checkpoints in continuationPrompt so request_compaction can be called again later; otherwise do not repeat the same compaction request.',
+		],
+		parameters: RequestCompactionParams,
+		executionMode: 'sequential',
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const customInstructions = params.customInstructions?.trim() || DEFAULT_COMPACTION_INSTRUCTIONS;
+			const reason = params.reason?.trim() || 'The current instructions requested immediate context compaction.';
+			const continuationPrompt = params.continuationPrompt?.trim() || undefined;
+
+			pendingCompactions.push({ customInstructions, reason, continuationPrompt });
+			ctx.ui.notify(
+				continuationPrompt
+					? 'Compaction queued after the current turn. The summarized remaining plan will continue after compaction.'
+					: 'Compaction queued after the current turn.',
+				'info',
+			);
+
+			return {
+				content: [{
+					type: 'text',
+					text: continuationPrompt
+						? 'Compaction queued. It will run after this agent turn finishes, then the summarized remaining plan will continue.'
+						: 'Compaction queued. It will run after this agent turn finishes.',
+				}],
+				details: { queued: true, continueAfterCompaction: continuationPrompt !== undefined, customInstructions, reason, continuationPrompt },
+				terminate: true,
+			};
+		},
+	});
+}

package/.versions/0.2.0/.pi/extensions/compact-and-continue/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "agent-skills-pi-compact-and-continue",
+  "private": true,
+  "type": "module",
+  "main": "index.ts"
+}

package/.versions/0.2.0/.pi/extensions/mcp-bridge/README.md

@@ -0,0 +1,46 @@
+# mcp-bridge
+
+A reusable factory for turning any stdio MCP server into a pi extension.
+
+This is a **library**, not a standalone pi extension. It is consumed by other extensions in `.pi/extensions/` (for example, `chrome-devtools-mcp/`). pi will not load it directly.
+
+## What it does
+
+Given a config describing how to spawn an MCP server, the factory returns a pi extension that:
+
+1. Spawns the MCP server over stdio (`StdioClientTransport`).
+2. Lists the server's tools via `listTools`.
+3. Registers each tool with pi under a configurable prefix.
+4. Forwards calls and normalizes MCP content (`text`, `image`, `resource`) back to pi.
+5. Registers a status command and cleans up on `session_shutdown`.
+
+## Usage
+
+```ts
+import { createMcpBridgeExtension } from "../mcp-bridge/index.js";
+
+export default createMcpBridgeExtension({
+  prefix: "my_server__",
+  command: "npx",
+  args: ["-y", "some-mcp-server@latest"],
+});
+```
+
+## Config
+
+| Field | Required | Default | Description |
+|---|---|---|---|
+| `prefix` | yes | — | Prefix prepended to every registered pi tool name (e.g. `chrome_devtools__`). |
+| `command` | yes | — | Executable used to spawn the MCP server (e.g. `npx`, `node`, an absolute path). |
+| `args` | yes | — | Arguments passed to `command`. |
+| `clientName` | no | `pi-<prefix>` | Identifier sent to the MCP server during connection. |
+| `labelPrefix` | no | humanized `prefix` | Shown in pi tool labels and status messages. |
+| `statusCommandName` | no | `<prefix>-status` | Slash command that reports bridge status. |
+
+## Why this exists
+
+pi does not yet have first-class MCP support. This bridge is a **stopgap**: it lets pi consume MCP servers today. When pi gains native MCP support, individual wrapper extensions can be retired or replaced; this library will then be deprecated.
+
+## Dependencies
+
+Runtime dependencies (`@modelcontextprotocol/sdk`, `typebox`) are declared once at `.pi/extensions/package.json` and installed via `npm ci` in the cloned `agent-skills` repo. Wrapper extensions resolve them from the hoisted `node_modules/` — no per-wrapper install required. `@mariozechner/pi-coding-agent` is supplied by the pi runtime that loads the extension.

package/.versions/0.2.0/.pi/extensions/mcp-bridge/index.ts

@@ -0,0 +1,206 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "typebox";
+
+export interface McpBridgeConfig {
+	prefix: string;
+	command: string;
+	args: string[];
+	env?: Record<string, string>;
+	stderr?: "inherit" | "pipe" | "overlapped";
+	clientName?: string;
+	labelPrefix?: string;
+	statusCommandName?: string;
+}
+
+type JsonObject = Record<string, unknown>;
+
+type McpTool = {
+	name: string;
+	description?: string;
+	inputSchema?: JsonObject;
+};
+
+type McpClient = {
+	listTools(): Promise<{ tools?: McpTool[] }>;
+	callTool(input: { name: string; arguments: JsonObject }): Promise<{ isError?: boolean; content?: unknown }>;
+	close(): Promise<void>;
+};
+
+type McpTransport = {
+	close?: () => Promise<void> | void;
+};
+
+function humanizePrefix(prefix: string): string {
+	return prefix
+		.replace(/__+$/, "")
+		.replace(/[_-]+/g, " ")
+		.replace(/\b\w/g, (c) => c.toUpperCase())
+		.trim();
+}
+
+function toPiToolName(prefix: string, mcpToolName: string): string {
+	const safeName = mcpToolName.replace(/[^A-Za-z0-9_-]/g, "_");
+	return `${prefix}${safeName}`;
+}
+
+function normalizeInputSchema(tool: McpTool) {
+	const schema = tool.inputSchema as JsonObject | undefined;
+	if (!schema || typeof schema !== "object") {
+		return Type.Object({});
+	}
+
+	return {
+		type: "object",
+		properties: {},
+		additionalProperties: true,
+		...schema,
+	} as ReturnType<typeof Type.Object>;
+}
+
+function stringifyMcpContent(content: unknown): string {
+	if (!Array.isArray(content)) {
+		return JSON.stringify(content, null, 2);
+	}
+
+	return content
+		.map((part) => {
+			if (!part || typeof part !== "object") return String(part);
+			const item = part as JsonObject;
+
+			if (item.type === "text" && typeof item.text === "string") {
+				return item.text;
+			}
+
+			if (item.type === "image") {
+				const mimeType = typeof item.mimeType === "string" ? item.mimeType : "image/*";
+				return `[Image returned by MCP bridge: ${mimeType}]`;
+			}
+
+			if (item.type === "resource") {
+				return `[Resource returned by MCP bridge]\n${JSON.stringify(item.resource ?? item, null, 2)}`;
+			}
+
+			return JSON.stringify(item, null, 2);
+		})
+		.join("\n\n");
+}
+
+function errorWithStderr(error: unknown, stderr: string): Error {
+	const message = error instanceof Error ? error.message : String(error);
+	const stderrExcerpt = stderr.trim().slice(-2_000);
+	return new Error(stderrExcerpt ? `${message}\n${stderrExcerpt}` : message);
+}
+
+// pi auto-discovers `.pi/extensions/*/index.ts` files. This module is primarily
+// a library consumed by wrapper extensions (for example, `chrome-devtools-mcp`),
+// but when the directory itself is symlinked as recommended it is also loaded as
+// a project extension. Export a harmless default factory so that direct loading
+// succeeds without registering tools; wrappers should import `createMcpBridgeExtension`.
+export default function mcpBridgeLibraryExtension(_pi: ExtensionAPI) {
+	// Intentionally empty.
+}
+
+export function createMcpBridgeExtension(config: McpBridgeConfig) {
+	const {
+		prefix,
+		command,
+		args,
+		env,
+		stderr = "inherit",
+		clientName = `pi-${prefix.replace(/__+$/, "")}`,
+		labelPrefix = humanizePrefix(prefix),
+		statusCommandName = `${prefix.replace(/__+$/, "")}-status`,
+	} = config;
+
+	async function connect(): Promise<{ client: McpClient; transport: McpTransport }> {
+		const [{ Client }, { StdioClientTransport }] = await Promise.all([
+			import("@modelcontextprotocol/sdk/client/index.js"),
+			import("@modelcontextprotocol/sdk/client/stdio.js"),
+		]);
+		const client = new Client({ name: clientName, version: "1.0.0" });
+		const transport = new StdioClientTransport({ command, args, env, stderr });
+		let stderrOutput = "";
+		transport.stderr?.on("data", (chunk: Buffer) => {
+			stderrOutput += chunk.toString();
+		});
+
+		try {
+			await client.connect(transport);
+			return { client, transport };
+		} catch (error) {
+			await transport.close().catch(() => undefined);
+			throw errorWithStderr(error, stderrOutput);
+		}
+	}
+
+	return async function mcpBridgeExtension(pi: ExtensionAPI) {
+		let client: McpClient | undefined;
+		let transport: McpTransport | undefined;
+		let tools: McpTool[] = [];
+
+		try {
+			const connection = await connect();
+			client = connection.client;
+			transport = connection.transport;
+			tools = (await client.listTools()).tools ?? [];
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			pi.registerCommand(statusCommandName, {
+				description: `Show ${labelPrefix} MCP bridge status`,
+				handler: async (_args, ctx) => {
+					ctx.ui.notify(`${labelPrefix} MCP failed to start: ${message}`, "error");
+				},
+			});
+			return;
+		}
+
+		for (const tool of tools) {
+			const piToolName = toPiToolName(prefix, tool.name);
+
+			pi.registerTool({
+				name: piToolName,
+				label: `${labelPrefix}: ${tool.name}`,
+				description: `${tool.description ?? `${labelPrefix} MCP tool`}\n\nWrapped MCP tool: ${tool.name}`,
+				promptSnippet: `${piToolName}: use ${labelPrefix} MCP tool '${tool.name}'.`,
+				parameters: normalizeInputSchema(tool),
+				executionMode: "sequential",
+				execute: async (_toolCallId, params, signal) => {
+					if (!client) {
+						throw new Error(`${labelPrefix} MCP client is not connected`);
+					}
+					if (signal?.aborted) {
+						throw new Error(`${labelPrefix} MCP tool call was aborted before it started`);
+					}
+
+					const result = await client.callTool({
+						name: tool.name,
+						arguments: params as JsonObject,
+					});
+
+					if (result.isError) {
+						throw new Error(stringifyMcpContent(result.content));
+					}
+
+					return {
+						content: [{ type: "text", text: stringifyMcpContent(result.content) }],
+						details: { mcpToolName: tool.name, rawResult: result },
+					};
+				},
+			});
+		}
+
+		pi.registerCommand(statusCommandName, {
+			description: `Show ${labelPrefix} MCP bridge status`,
+			handler: async (_args, ctx) => {
+				ctx.ui.notify(`${labelPrefix} MCP connected. Registered ${tools.length} tool(s).`, "success");
+			},
+		});
+
+		pi.on("session_shutdown", async () => {
+			await client?.close().catch(() => undefined);
+			await transport?.close?.().catch(() => undefined);
+			client = undefined;
+			transport = undefined;
+		});
+	};
+}

package/.versions/0.2.0/.pi/extensions/mcp-bridge/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "agent-skills-pi-mcp-bridge",
+  "private": true,
+  "type": "module",
+  "main": "index.ts"
+}