@michaeltroya/pouch 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mt
+
+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

@@ -0,0 +1,237 @@
+# Pouch
+
+Create one agent skill and share it across Codex, Cursor, and Claude.
+
+Pouch is a small CLI for keeping agent skills in one canonical place. Instead of copying the same `SKILL.md` into every agent's folder, Pouch creates the real skill once and links each agent to it.
+
+```txt
+.agents/skills/review-helper/SKILL.md
+.codex/skills/review-helper  -> ../../.agents/skills/review-helper
+.cursor/skills/review-helper -> ../../.agents/skills/review-helper
+.claude/skills/review-helper -> ../../.agents/skills/review-helper
+```
+
+## Why Pouch?
+
+Agent skills are useful, but they tend to drift when each tool keeps its own copy.
+
+Pouch gives you one source of truth:
+
+- Create a skill once.
+- Use it from multiple agents.
+- Keep project-local skills inside the repo.
+- Keep personal/global skills in your home directory.
+- Avoid overwriting existing skills by accident.
+
+Pouch is CLI-only. It does not expose a JavaScript API.
+
+## Quick Start
+
+Requires Node.js 22.13 or newer.
+
+Run without installing:
+
+```sh
+pnpm dlx @michaeltroya/pouch create
+```
+
+With npm:
+
+```sh
+npx @michaeltroya/pouch create
+```
+
+With Yarn:
+
+```sh
+yarn dlx @michaeltroya/pouch create
+```
+
+Or install globally:
+
+```sh
+npm install --global @michaeltroya/pouch
+pouch create
+```
+
+For local development in this repo:
+
+```sh
+pnpm install
+pnpm build
+```
+
+During local development, run the CLI directly from TypeScript:
+
+```sh
+pnpm dev -- create
+```
+
+After building, the package exposes a `pouch` binary:
+
+```sh
+pouch create
+```
+
+## Usage
+
+Create a shared skill:
+
+```sh
+pouch create
+```
+
+Pouch will ask:
+
+1. Skill name
+2. Skill description
+3. Where the canonical skill should live
+4. Which agents should use it
+
+You can choose a project-local skill:
+
+```txt
+./.agents/skills/<skill-name>
+```
+
+Or a global skill:
+
+```txt
+~/.agents/skills/<skill-name>
+```
+
+Example output:
+
+```txt
+review-helper
+Canonical: /path/to/project/.agents/skills/review-helper
+Codex: /path/to/project/.codex/skills/review-helper (created)
+Cursor: /path/to/project/.cursor/skills/review-helper (created)
+Claude: /path/to/project/.claude/skills/review-helper (created)
+```
+
+## What Pouch Creates
+
+Creating a project-local skill named `Review Helper` produces:
+
+```txt
+.agents/
+  skills/
+    review-helper/
+      SKILL.md
+.codex/
+  skills/
+    review-helper -> ../../.agents/skills/review-helper
+.cursor/
+  skills/
+    review-helper -> ../../.agents/skills/review-helper
+.claude/
+  skills/
+    review-helper -> ../../.agents/skills/review-helper
+```
+
+The generated `SKILL.md` starts like this:
+
+```md
+---
+name: review-helper
+description: 'Helps agents review code consistently.'
+---
+
+# Review Helper
+
+Helps agents review code consistently.
+```
+
+## Supported Agents
+
+| Agent  | Project-local skill directory | Global skill directory |
+| ------ | ----------------------------- | ---------------------- |
+| Codex  | `./.codex/skills`             | `~/.codex/skills`      |
+| Cursor | `./.cursor/skills`            | `~/.cursor/skills`     |
+| Claude | `./.claude/skills`            | `~/.claude/skills`     |
+
+## Safety
+
+Pouch is conservative with your files:
+
+- It will not overwrite an existing canonical `SKILL.md`.
+- It will not replace an existing non-symlink in an agent skill directory.
+- It will not repoint an existing symlink that targets a different skill.
+- If symlink creation fails partway through, it rolls back the skill and links it created during that run.
+
+For project-local skills, Pouch creates relative symlinks so the links keep working if the project folder is moved.
+
+On Windows, symlink creation may require Developer Mode or an elevated shell.
+
+## Local Development
+
+This repo uses pnpm.
+
+Install dependencies:
+
+```sh
+pnpm install
+```
+
+Run the CLI from TypeScript:
+
+```sh
+pnpm dev -- create
+```
+
+Build the package:
+
+```sh
+pnpm build
+```
+
+Run checks and formatting:
+
+```sh
+pnpm check
+pnpm lint
+pnpm format
+```
+
+Tests are available through:
+
+```sh
+pnpm test
+```
+
+## Project Structure
+
+```txt
+src/
+  index.ts              CLI entrypoint
+  commands/
+    create.ts           Prompt flow for `pouch create`
+  lib/
+    agents.ts           Supported agents and skill directory resolution
+    fs.ts               Shared filesystem helpers
+    paths.ts            Canonical skill paths and location schema
+    skill.ts            Skill creation, symlink planning, and rollback
+```
+
+## Contributing
+
+Issues and pull requests are welcome.
+
+Before opening a PR, please run:
+
+```sh
+pnpm check
+pnpm lint
+pnpm format
+```
+
+If your change touches behavior, also run:
+
+```sh
+pnpm test
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/index.mjs

@@ -0,0 +1,284 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { intro, isCancel, multiselect, note, outro, select, spinner, text } from "@clack/prompts";
+import { z } from "zod";
+import path from "node:path";
+import os from "node:os";
+import fs from "fs-extra";
+//#region src/lib/paths.ts
+const canonicalSkillLocationSchema = z.enum(["home", "project"]);
+function getLocationRoot(location) {
+	if (location === "project") return process.cwd();
+	return os.homedir();
+}
+function getCanonicalSkillsDirectory(location) {
+	return path.join(getLocationRoot(location), ".agents", "skills");
+}
+function getCanonicalSkillPath(location, skillName) {
+	return path.join(getCanonicalSkillsDirectory(location), skillName);
+}
+function toComparablePath(value) {
+	const resolved = path.resolve(value);
+	if (resolved.startsWith("/private/var/")) return resolved.replace("/private/var/", "/var/");
+	return resolved;
+}
+//#endregion
+//#region src/lib/agents.ts
+const agentIdSchema = z.enum([
+	"codex",
+	"cursor",
+	"claude"
+]);
+const supportedAgents = [
+	{
+		id: "codex",
+		label: "Codex",
+		directoryName: ".codex"
+	},
+	{
+		id: "cursor",
+		label: "Cursor",
+		directoryName: ".cursor"
+	},
+	{
+		id: "claude",
+		label: "Claude",
+		directoryName: ".claude"
+	}
+];
+function getAgentsById(agentIds, location) {
+	const selected = new Set(agentIds);
+	return supportedAgents.filter((agent) => selected.has(agent.id)).map((agent) => ({
+		id: agent.id,
+		label: agent.label,
+		skillDirectory: getAgentSkillDirectory(agent.directoryName, location)
+	}));
+}
+function getAgentSkillDirectory(directoryName, location) {
+	return path.join(getLocationRoot(location), directoryName, "skills");
+}
+//#endregion
+//#region src/lib/fs.ts
+function isNodeError(error) {
+	return error instanceof Error && "code" in error;
+}
+async function lstatOrNull(filePath) {
+	return fs.lstat(filePath).catch((error) => {
+		if (isNodeError(error) && error.code === "ENOENT") return null;
+		throw error;
+	});
+}
+//#endregion
+//#region src/lib/skill.ts
+const skillInputSchema = z.object({
+	name: z.string().trim().min(1, "Skill name is required"),
+	description: z.string().trim().min(1, "Skill description is required")
+});
+function toSkillSlug(value) {
+	return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+async function createSkill(input) {
+	const parsed = skillInputSchema.parse(input);
+	const skillName = toSkillSlug(parsed.name);
+	if (!skillName) throw new Error("Skill name must include at least one letter or number.");
+	const agents = dedupeAgents(input.agents);
+	const canonicalPath = getCanonicalSkillPath(input.location, skillName);
+	const skillFilePath = path.join(canonicalPath, "SKILL.md");
+	const canonicalExisted = await fs.pathExists(canonicalPath);
+	await ensureCanonicalSkillCanBeCreated(canonicalPath);
+	const linkPlans = await planSkillSymlinks(agents, canonicalPath, skillName);
+	await fs.ensureDir(canonicalPath);
+	await writeSkillFile(skillFilePath, parsed.name, parsed.description);
+	const links = [];
+	const createdLinkPaths = [];
+	try {
+		for (const linkPlan of linkPlans) {
+			const result = await applySkillSymlink(linkPlan, canonicalPath);
+			if (result.status === "created") createdLinkPaths.push(result.linkPath);
+			links.push(result);
+		}
+	} catch (error) {
+		await rollbackCreatedPaths({
+			canonicalExisted,
+			canonicalPath,
+			createdLinkPaths,
+			skillFilePath
+		});
+		throw error;
+	}
+	return {
+		skillName,
+		canonicalPath,
+		skillFilePath,
+		links
+	};
+}
+function dedupeAgents(agents) {
+	const seen = /* @__PURE__ */ new Set();
+	return agents.filter((agent) => {
+		if (seen.has(agent.id)) return false;
+		seen.add(agent.id);
+		return true;
+	});
+}
+async function writeSkillFile(skillFilePath, name, description) {
+	await fs.writeFile(skillFilePath, renderSkillMarkdown(name, description), { flag: "wx" }).catch((error) => {
+		if (isNodeError(error) && error.code === "EEXIST") throw new Error(`A canonical skill already exists at ${skillFilePath}`);
+		throw error;
+	});
+}
+async function ensureCanonicalSkillCanBeCreated(canonicalPath) {
+	await ensureDirectoryPathCanBeCreated(path.dirname(canonicalPath));
+	const existingCanonicalPath = await lstatOrNull(canonicalPath);
+	if (existingCanonicalPath && !existingCanonicalPath.isDirectory()) throw new Error(`Cannot create skill because ${canonicalPath} already exists.`);
+	if (existingCanonicalPath) {
+		const contents = await fs.readdir(canonicalPath);
+		if (contents.length > 0 && !contents.includes("SKILL.md")) throw new Error(`Cannot create skill because ${canonicalPath} already exists and is not empty.`);
+	}
+}
+function renderSkillMarkdown(name, description) {
+	return `---
+name: ${toSkillSlug(name)}
+description: ${JSON.stringify(description.trim())}
+---
+
+# ${name.trim()}
+
+${description.trim()}
+`;
+}
+async function planSkillSymlinks(agents, canonicalPath, skillName) {
+	return Promise.all(agents.map(async (agent) => {
+		const linkPath = path.join(agent.skillDirectory, skillName);
+		await ensureDirectoryPathCanBeCreated(path.dirname(linkPath));
+		const existing = await lstatOrNull(linkPath);
+		if (!existing) return {
+			agent,
+			linkPath,
+			action: "link"
+		};
+		if (!existing.isSymbolicLink()) throw new Error(`Cannot link skill because ${linkPath} already exists and is not a symlink.`);
+		const target = await fs.readlink(linkPath);
+		const resolvedTarget = path.resolve(path.dirname(linkPath), target);
+		if (toComparablePath(resolvedTarget) !== toComparablePath(canonicalPath)) throw new Error(`Cannot link skill because ${linkPath} points to ${resolvedTarget}.`);
+		return {
+			agent,
+			linkPath,
+			action: "skip"
+		};
+	}));
+}
+async function ensureDirectoryPathCanBeCreated(directoryPath) {
+	const existing = await lstatOrNull(directoryPath);
+	if (existing) {
+		if (!existing.isDirectory()) throw new Error(`Cannot create directory because ${directoryPath} already exists and is not a directory.`);
+		return;
+	}
+	const parentPath = path.dirname(directoryPath);
+	if (parentPath === directoryPath) return;
+	await ensureDirectoryPathCanBeCreated(parentPath);
+}
+async function applySkillSymlink(plan, canonicalPath) {
+	if (plan.action === "skip") return {
+		agent: plan.agent,
+		linkPath: plan.linkPath,
+		status: "existing"
+	};
+	await fs.ensureDir(path.dirname(plan.linkPath));
+	const linkTarget = path.relative(path.dirname(plan.linkPath), canonicalPath);
+	await fs.symlink(linkTarget, plan.linkPath, "dir");
+	return {
+		agent: plan.agent,
+		linkPath: plan.linkPath,
+		status: "created"
+	};
+}
+async function rollbackCreatedPaths(options) {
+	await Promise.all(options.createdLinkPaths.map((linkPath) => fs.remove(linkPath)));
+	if (options.canonicalExisted) {
+		await fs.remove(options.skillFilePath);
+		return;
+	}
+	await fs.remove(options.canonicalPath);
+}
+//#endregion
+//#region src/commands/create.ts
+function promptOrExit(value) {
+	if (isCancel(value)) {
+		outro("Cancelled");
+		process.exit(0);
+	}
+	return value;
+}
+function requireNonEmpty(message) {
+	return (value) => {
+		if (!(value ?? "").trim()) return message;
+	};
+}
+function createCommand() {
+	const command = new Command("create");
+	command.description("Create a shared skill and link it into agent skill directories");
+	command.action(async () => {
+		intro("Create a shared agent skill");
+		const name = promptOrExit(await text({
+			message: "Skill name",
+			placeholder: "review-helper",
+			validate: requireNonEmpty("Enter a skill name.")
+		}));
+		const description = promptOrExit(await text({
+			message: "Skill description",
+			placeholder: "Helps agents review code consistently.",
+			validate: requireNonEmpty("Enter a skill description.")
+		}));
+		const location = promptOrExit(await select({
+			message: "Where should the canonical skill live?",
+			options: [{
+				value: "project",
+				label: "Current project",
+				hint: "./.agents/skills/<skill-name>"
+			}, {
+				value: "home",
+				label: "Home directory",
+				hint: "~/.agents/skills/<skill-name>"
+			}]
+		}));
+		const selectedAgentIds = promptOrExit(await multiselect({
+			message: "Which agents should use this skill?",
+			options: supportedAgents.map((agent) => ({
+				value: agent.id,
+				label: agent.label
+			})),
+			required: true
+		}));
+		const canonicalLocation = canonicalSkillLocationSchema.parse(location);
+		const agents = getAgentsById(agentIdSchema.array().parse(selectedAgentIds), canonicalLocation);
+		const activity = spinner();
+		activity.start("Creating canonical skill and symlinks");
+		try {
+			const result = await createSkill({
+				name,
+				description,
+				location: canonicalLocation,
+				agents
+			});
+			activity.stop("Skill created");
+			note([`Canonical: ${result.canonicalPath}`, ...result.links.map((link) => `${link.agent.label}: ${link.linkPath} (${link.status})`)].join("\n"), result.skillName);
+			outro("Done");
+		} catch (error) {
+			activity.stop("Could not create skill");
+			outro(error instanceof Error ? error.message : "Unknown error");
+			process.exit(1);
+		}
+	});
+	return command;
+}
+//#endregion
+//#region src/index.ts
+const program = new Command();
+program.name("pouch").description("Create and link shared agent skills").version("0.1.0");
+program.addCommand(createCommand());
+await program.parseAsync();
+//#endregion
+export {};
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/lib/paths.ts","../src/lib/agents.ts","../src/lib/fs.ts","../src/lib/skill.ts","../src/commands/create.ts","../src/index.ts"],"sourcesContent":["import os from 'node:os'\nimport path from 'node:path'\nimport { z } from 'zod'\n\nexport const canonicalSkillLocationSchema = z.enum(['home', 'project'])\n\nexport type CanonicalSkillLocation = z.infer<typeof canonicalSkillLocationSchema>\n\nexport function resolveHomePath(value: string): string {\n  if (value === '~') {\n    return os.homedir()\n  }\n\n  if (value.startsWith('~/')) {\n    return path.join(os.homedir(), value.slice(2))\n  }\n\n  return value\n}\n\nexport function getLocationRoot(location: CanonicalSkillLocation): string {\n  if (location === 'project') {\n    return process.cwd()\n  }\n\n  return os.homedir()\n}\n\nexport function getCanonicalSkillsDirectory(location: CanonicalSkillLocation): string {\n  return path.join(getLocationRoot(location), '.agents', 'skills')\n}\n\nexport function getCanonicalSkillPath(location: CanonicalSkillLocation, skillName: string): string {\n  return path.join(getCanonicalSkillsDirectory(location), skillName)\n}\n\nexport function toComparablePath(value: string): string {\n  const resolved = path.resolve(value)\n\n  if (resolved.startsWith('/private/var/')) {\n    return resolved.replace('/private/var/', '/var/')\n  }\n\n  return resolved\n}\n","import { z } from 'zod'\nimport path from 'node:path'\nimport { getLocationRoot } from '@/lib/paths.js'\nimport type { CanonicalSkillLocation } from '@/lib/paths.js'\n\nexport const agentIdSchema = z.enum(['codex', 'cursor', 'claude'])\n\nexport type AgentId = z.infer<typeof agentIdSchema>\n\nexport type AgentDefinition = {\n  id: AgentId\n  label: string\n  skillDirectory: string\n}\n\ntype SupportedAgent = {\n  id: AgentId\n  label: string\n  directoryName: string\n}\n\nexport const supportedAgents = [\n  {\n    id: 'codex',\n    label: 'Codex',\n    directoryName: '.codex',\n  },\n  {\n    id: 'cursor',\n    label: 'Cursor',\n    directoryName: '.cursor',\n  },\n  {\n    id: 'claude',\n    label: 'Claude',\n    directoryName: '.claude',\n  },\n] satisfies SupportedAgent[]\n\nexport function getAgentsById(\n  agentIds: AgentId[],\n  location: CanonicalSkillLocation,\n): AgentDefinition[] {\n  const selected = new Set(agentIds)\n  return supportedAgents\n    .filter((agent) => selected.has(agent.id))\n    .map((agent) => ({\n      id: agent.id,\n      label: agent.label,\n      skillDirectory: getAgentSkillDirectory(agent.directoryName, location),\n    }))\n}\n\nfunction getAgentSkillDirectory(directoryName: string, location: CanonicalSkillLocation): string {\n  return path.join(getLocationRoot(location), directoryName, 'skills')\n}\n","import fs from 'fs-extra'\n\nexport function isNodeError(error: unknown): error is NodeJS.ErrnoException {\n  return error instanceof Error && 'code' in error\n}\n\nexport async function lstatOrNull(filePath: string): Promise<fs.Stats | null> {\n  return fs.lstat(filePath).catch((error: unknown) => {\n    if (isNodeError(error) && error.code === 'ENOENT') {\n      return null\n    }\n\n    throw error\n  })\n}\n","import path from 'node:path'\nimport fs from 'fs-extra'\nimport { z } from 'zod'\nimport type { AgentDefinition } from '@/lib/agents.js'\nimport { isNodeError, lstatOrNull } from '@/lib/fs.js'\nimport {\n  getCanonicalSkillPath,\n  toComparablePath,\n  type CanonicalSkillLocation,\n} from '@/lib/paths.js'\n\nconst skillInputSchema = z.object({\n  name: z.string().trim().min(1, 'Skill name is required'),\n  description: z.string().trim().min(1, 'Skill description is required'),\n})\n\nexport type CreateSkillInput = z.input<typeof skillInputSchema> & {\n  agents: AgentDefinition[]\n  location: CanonicalSkillLocation\n}\n\nexport type SkillLinkPlan =\n  | { action: 'link'; agent: AgentDefinition; linkPath: string }\n  | { action: 'skip'; agent: AgentDefinition; linkPath: string }\n\nexport type SkillLinkResult = {\n  agent: AgentDefinition\n  linkPath: string\n  status: 'created' | 'existing'\n}\n\nexport type CreateSkillResult = {\n  skillName: string\n  canonicalPath: string\n  skillFilePath: string\n  links: SkillLinkResult[]\n}\n\nexport function toSkillSlug(value: string): string {\n  return value\n    .trim()\n    .toLowerCase()\n    .replace(/[^a-z0-9]+/g, '-')\n    .replace(/^-+|-+$/g, '')\n}\n\nexport async function createSkill(input: CreateSkillInput): Promise<CreateSkillResult> {\n  const parsed = skillInputSchema.parse(input)\n  const skillName = toSkillSlug(parsed.name)\n\n  if (!skillName) {\n    throw new Error('Skill name must include at least one letter or number.')\n  }\n\n  const agents = dedupeAgents(input.agents)\n  const canonicalPath = getCanonicalSkillPath(input.location, skillName)\n  const skillFilePath = path.join(canonicalPath, 'SKILL.md')\n  const canonicalExisted = await fs.pathExists(canonicalPath)\n\n  await ensureCanonicalSkillCanBeCreated(canonicalPath)\n  const linkPlans = await planSkillSymlinks(agents, canonicalPath, skillName)\n\n  await fs.ensureDir(canonicalPath)\n  await writeSkillFile(skillFilePath, parsed.name, parsed.description)\n\n  const links: SkillLinkResult[] = []\n  const createdLinkPaths: string[] = []\n\n  try {\n    for (const linkPlan of linkPlans) {\n      const result = await applySkillSymlink(linkPlan, canonicalPath)\n\n      if (result.status === 'created') {\n        createdLinkPaths.push(result.linkPath)\n      }\n\n      links.push(result)\n    }\n  } catch (error) {\n    await rollbackCreatedPaths({\n      canonicalExisted,\n      canonicalPath,\n      createdLinkPaths,\n      skillFilePath,\n    })\n\n    throw error\n  }\n\n  return {\n    skillName,\n    canonicalPath,\n    skillFilePath,\n    links,\n  }\n}\n\nfunction dedupeAgents(agents: AgentDefinition[]): AgentDefinition[] {\n  const seen = new Set<AgentDefinition['id']>()\n\n  return agents.filter((agent) => {\n    if (seen.has(agent.id)) {\n      return false\n    }\n\n    seen.add(agent.id)\n    return true\n  })\n}\n\nasync function writeSkillFile(\n  skillFilePath: string,\n  name: string,\n  description: string,\n): Promise<void> {\n  await fs\n    .writeFile(skillFilePath, renderSkillMarkdown(name, description), {\n      flag: 'wx',\n    })\n    .catch((error: unknown) => {\n      if (isNodeError(error) && error.code === 'EEXIST') {\n        throw new Error(`A canonical skill already exists at ${skillFilePath}`)\n      }\n\n      throw error\n    })\n}\n\nasync function ensureCanonicalSkillCanBeCreated(canonicalPath: string): Promise<void> {\n  await ensureDirectoryPathCanBeCreated(path.dirname(canonicalPath))\n\n  const existingCanonicalPath = await lstatOrNull(canonicalPath)\n\n  if (existingCanonicalPath && !existingCanonicalPath.isDirectory()) {\n    throw new Error(`Cannot create skill because ${canonicalPath} already exists.`)\n  }\n\n  if (existingCanonicalPath) {\n    const contents = await fs.readdir(canonicalPath)\n\n    if (contents.length > 0 && !contents.includes('SKILL.md')) {\n      throw new Error(\n        `Cannot create skill because ${canonicalPath} already exists and is not empty.`,\n      )\n    }\n  }\n}\n\nfunction renderSkillMarkdown(name: string, description: string): string {\n  return `---\nname: ${toSkillSlug(name)}\ndescription: ${JSON.stringify(description.trim())}\n---\n\n# ${name.trim()}\n\n${description.trim()}\n`\n}\n\nasync function planSkillSymlinks(\n  agents: AgentDefinition[],\n  canonicalPath: string,\n  skillName: string,\n): Promise<SkillLinkPlan[]> {\n  return Promise.all(\n    agents.map(async (agent) => {\n      const linkPath = path.join(agent.skillDirectory, skillName)\n      await ensureDirectoryPathCanBeCreated(path.dirname(linkPath))\n\n      const existing = await lstatOrNull(linkPath)\n\n      if (!existing) {\n        return {\n          agent,\n          linkPath,\n          action: 'link' as const,\n        }\n      }\n\n      if (!existing.isSymbolicLink()) {\n        throw new Error(\n          `Cannot link skill because ${linkPath} already exists and is not a symlink.`,\n        )\n      }\n\n      const target = await fs.readlink(linkPath)\n      const resolvedTarget = path.resolve(path.dirname(linkPath), target)\n\n      if (toComparablePath(resolvedTarget) !== toComparablePath(canonicalPath)) {\n        throw new Error(`Cannot link skill because ${linkPath} points to ${resolvedTarget}.`)\n      }\n\n      return {\n        agent,\n        linkPath,\n        action: 'skip' as const,\n      }\n    }),\n  )\n}\n\nasync function ensureDirectoryPathCanBeCreated(directoryPath: string): Promise<void> {\n  const existing = await lstatOrNull(directoryPath)\n\n  if (existing) {\n    if (!existing.isDirectory()) {\n      throw new Error(\n        `Cannot create directory because ${directoryPath} already exists and is not a directory.`,\n      )\n    }\n\n    return\n  }\n\n  const parentPath = path.dirname(directoryPath)\n\n  if (parentPath === directoryPath) {\n    return\n  }\n\n  await ensureDirectoryPathCanBeCreated(parentPath)\n}\n\nasync function applySkillSymlink(\n  plan: SkillLinkPlan,\n  canonicalPath: string,\n): Promise<SkillLinkResult> {\n  if (plan.action === 'skip') {\n    return {\n      agent: plan.agent,\n      linkPath: plan.linkPath,\n      status: 'existing',\n    }\n  }\n\n  await fs.ensureDir(path.dirname(plan.linkPath))\n  const linkTarget = path.relative(path.dirname(plan.linkPath), canonicalPath)\n  await fs.symlink(linkTarget, plan.linkPath, 'dir')\n\n  return {\n    agent: plan.agent,\n    linkPath: plan.linkPath,\n    status: 'created',\n  }\n}\n\nasync function rollbackCreatedPaths(options: {\n  canonicalExisted: boolean\n  canonicalPath: string\n  createdLinkPaths: string[]\n  skillFilePath: string\n}): Promise<void> {\n  await Promise.all(options.createdLinkPaths.map((linkPath) => fs.remove(linkPath)))\n\n  if (options.canonicalExisted) {\n    await fs.remove(options.skillFilePath)\n    return\n  }\n\n  await fs.remove(options.canonicalPath)\n}\n","import { intro, isCancel, multiselect, note, outro, select, spinner, text } from '@clack/prompts'\nimport { Command } from 'commander'\nimport { agentIdSchema, getAgentsById, supportedAgents } from '@/lib/agents.js'\nimport { createSkill } from '@/lib/skill.js'\nimport { canonicalSkillLocationSchema } from '@/lib/paths.js'\n\nfunction promptOrExit<T>(value: T | symbol): T {\n  if (isCancel(value)) {\n    outro('Cancelled')\n    process.exit(0)\n  }\n\n  return value\n}\n\nfunction requireNonEmpty(message: string) {\n  return (value?: string) => {\n    if (!(value ?? '').trim()) {\n      return message\n    }\n    return undefined\n  }\n}\n\nexport function createCommand(): Command {\n  const command = new Command('create')\n\n  command.description('Create a shared skill and link it into agent skill directories')\n\n  command.action(async () => {\n    intro('Create a shared agent skill')\n\n    const name = promptOrExit(\n      await text({\n        message: 'Skill name',\n        placeholder: 'review-helper',\n        validate: requireNonEmpty('Enter a skill name.'),\n      }),\n    )\n\n    const description = promptOrExit(\n      await text({\n        message: 'Skill description',\n        placeholder: 'Helps agents review code consistently.',\n        validate: requireNonEmpty('Enter a skill description.'),\n      }),\n    )\n\n    const location = promptOrExit(\n      await select({\n        message: 'Where should the canonical skill live?',\n        options: [\n          {\n            value: 'project',\n            label: 'Current project',\n            hint: './.agents/skills/<skill-name>',\n          },\n          {\n            value: 'home',\n            label: 'Home directory',\n            hint: '~/.agents/skills/<skill-name>',\n          },\n        ],\n      }),\n    )\n\n    const selectedAgentIds = promptOrExit(\n      await multiselect({\n        message: 'Which agents should use this skill?',\n        options: supportedAgents.map((agent) => ({\n          value: agent.id,\n          label: agent.label,\n        })),\n        required: true,\n      }),\n    )\n\n    const canonicalLocation = canonicalSkillLocationSchema.parse(location)\n    const parsedAgentIds = agentIdSchema.array().parse(selectedAgentIds)\n    const agents = getAgentsById(parsedAgentIds, canonicalLocation)\n    const activity = spinner()\n\n    activity.start('Creating canonical skill and symlinks')\n\n    try {\n      const result = await createSkill({\n        name,\n        description,\n        location: canonicalLocation,\n        agents,\n      })\n\n      activity.stop('Skill created')\n\n      note(\n        [\n          `Canonical: ${result.canonicalPath}`,\n          ...result.links.map((link) => `${link.agent.label}: ${link.linkPath} (${link.status})`),\n        ].join('\\n'),\n        result.skillName,\n      )\n\n      outro('Done')\n    } catch (error) {\n      activity.stop('Could not create skill')\n      outro(error instanceof Error ? error.message : 'Unknown error')\n      process.exit(1)\n    }\n  })\n\n  return command\n}\n","#!/usr/bin/env node\n\nimport { Command } from 'commander'\nimport { createCommand } from '@/commands/create.js'\n\nconst program = new Command()\n\nprogram.name('pouch').description('Create and link shared agent skills').version('0.1.0')\n\nprogram.addCommand(createCommand())\n\nawait program.parseAsync()\n"],"mappings":";;;;;;;;AAIA,MAAa,+BAA+B,EAAE,KAAK,CAAC,QAAQ,SAAS,CAAC;AAgBtE,SAAgB,gBAAgB,UAA0C;CACxE,IAAI,aAAa,WACf,OAAO,QAAQ,IAAI;CAGrB,OAAO,GAAG,QAAQ;AACpB;AAEA,SAAgB,4BAA4B,UAA0C;CACpF,OAAO,KAAK,KAAK,gBAAgB,QAAQ,GAAG,WAAW,QAAQ;AACjE;AAEA,SAAgB,sBAAsB,UAAkC,WAA2B;CACjG,OAAO,KAAK,KAAK,4BAA4B,QAAQ,GAAG,SAAS;AACnE;AAEA,SAAgB,iBAAiB,OAAuB;CACtD,MAAM,WAAW,KAAK,QAAQ,KAAK;CAEnC,IAAI,SAAS,WAAW,eAAe,GACrC,OAAO,SAAS,QAAQ,iBAAiB,OAAO;CAGlD,OAAO;AACT;;;ACvCA,MAAa,gBAAgB,EAAE,KAAK;CAAC;CAAS;CAAU;AAAQ,CAAC;AAgBjE,MAAa,kBAAkB;CAC7B;EACE,IAAI;EACJ,OAAO;EACP,eAAe;CACjB;CACA;EACE,IAAI;EACJ,OAAO;EACP,eAAe;CACjB;CACA;EACE,IAAI;EACJ,OAAO;EACP,eAAe;CACjB;AACF;AAEA,SAAgB,cACd,UACA,UACmB;CACnB,MAAM,WAAW,IAAI,IAAI,QAAQ;CACjC,OAAO,gBACJ,QAAQ,UAAU,SAAS,IAAI,MAAM,EAAE,CAAC,EACxC,KAAK,WAAW;EACf,IAAI,MAAM;EACV,OAAO,MAAM;EACb,gBAAgB,uBAAuB,MAAM,eAAe,QAAQ;CACtE,EAAE;AACN;AAEA,SAAS,uBAAuB,eAAuB,UAA0C;CAC/F,OAAO,KAAK,KAAK,gBAAgB,QAAQ,GAAG,eAAe,QAAQ;AACrE;;;ACrDA,SAAgB,YAAY,OAAgD;CAC1E,OAAO,iBAAiB,SAAS,UAAU;AAC7C;AAEA,eAAsB,YAAY,UAA4C;CAC5E,OAAO,GAAG,MAAM,QAAQ,EAAE,OAAO,UAAmB;EAClD,IAAI,YAAY,KAAK,KAAK,MAAM,SAAS,UACvC,OAAO;EAGT,MAAM;CACR,CAAC;AACH;;;ACHA,MAAM,mBAAmB,EAAE,OAAO;CAChC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,GAAG,wBAAwB;CACvD,aAAa,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,GAAG,+BAA+B;AACvE,CAAC;AAwBD,SAAgB,YAAY,OAAuB;CACjD,OAAO,MACJ,KAAK,EACL,YAAY,EACZ,QAAQ,eAAe,GAAG,EAC1B,QAAQ,YAAY,EAAE;AAC3B;AAEA,eAAsB,YAAY,OAAqD;CACrF,MAAM,SAAS,iBAAiB,MAAM,KAAK;CAC3C,MAAM,YAAY,YAAY,OAAO,IAAI;CAEzC,IAAI,CAAC,WACH,MAAM,IAAI,MAAM,wDAAwD;CAG1E,MAAM,SAAS,aAAa,MAAM,MAAM;CACxC,MAAM,gBAAgB,sBAAsB,MAAM,UAAU,SAAS;CACrE,MAAM,gBAAgB,KAAK,KAAK,eAAe,UAAU;CACzD,MAAM,mBAAmB,MAAM,GAAG,WAAW,aAAa;CAE1D,MAAM,iCAAiC,aAAa;CACpD,MAAM,YAAY,MAAM,kBAAkB,QAAQ,eAAe,SAAS;CAE1E,MAAM,GAAG,UAAU,aAAa;CAChC,MAAM,eAAe,eAAe,OAAO,MAAM,OAAO,WAAW;CAEnE,MAAM,QAA2B,CAAC;CAClC,MAAM,mBAA6B,CAAC;CAEpC,IAAI;EACF,KAAK,MAAM,YAAY,WAAW;GAChC,MAAM,SAAS,MAAM,kBAAkB,UAAU,aAAa;GAE9D,IAAI,OAAO,WAAW,WACpB,iBAAiB,KAAK,OAAO,QAAQ;GAGvC,MAAM,KAAK,MAAM;EACnB;CACF,SAAS,OAAO;EACd,MAAM,qBAAqB;GACzB;GACA;GACA;GACA;EACF,CAAC;EAED,MAAM;CACR;CAEA,OAAO;EACL;EACA;EACA;EACA;CACF;AACF;AAEA,SAAS,aAAa,QAA8C;CAClE,MAAM,uBAAO,IAAI,IAA2B;CAE5C,OAAO,OAAO,QAAQ,UAAU;EAC9B,IAAI,KAAK,IAAI,MAAM,EAAE,GACnB,OAAO;EAGT,KAAK,IAAI,MAAM,EAAE;EACjB,OAAO;CACT,CAAC;AACH;AAEA,eAAe,eACb,eACA,MACA,aACe;CACf,MAAM,GACH,UAAU,eAAe,oBAAoB,MAAM,WAAW,GAAG,EAChE,MAAM,KACR,CAAC,EACA,OAAO,UAAmB;EACzB,IAAI,YAAY,KAAK,KAAK,MAAM,SAAS,UACvC,MAAM,IAAI,MAAM,uCAAuC,eAAe;EAGxE,MAAM;CACR,CAAC;AACL;AAEA,eAAe,iCAAiC,eAAsC;CACpF,MAAM,gCAAgC,KAAK,QAAQ,aAAa,CAAC;CAEjE,MAAM,wBAAwB,MAAM,YAAY,aAAa;CAE7D,IAAI,yBAAyB,CAAC,sBAAsB,YAAY,GAC9D,MAAM,IAAI,MAAM,+BAA+B,cAAc,iBAAiB;CAGhF,IAAI,uBAAuB;EACzB,MAAM,WAAW,MAAM,GAAG,QAAQ,aAAa;EAE/C,IAAI,SAAS,SAAS,KAAK,CAAC,SAAS,SAAS,UAAU,GACtD,MAAM,IAAI,MACR,+BAA+B,cAAc,kCAC/C;CAEJ;AACF;AAEA,SAAS,oBAAoB,MAAc,aAA6B;CACtE,OAAO;QACD,YAAY,IAAI,EAAE;eACX,KAAK,UAAU,YAAY,KAAK,CAAC,EAAE;;;IAG9C,KAAK,KAAK,EAAE;;EAEd,YAAY,KAAK,EAAE;;AAErB;AAEA,eAAe,kBACb,QACA,eACA,WAC0B;CAC1B,OAAO,QAAQ,IACb,OAAO,IAAI,OAAO,UAAU;EAC1B,MAAM,WAAW,KAAK,KAAK,MAAM,gBAAgB,SAAS;EAC1D,MAAM,gCAAgC,KAAK,QAAQ,QAAQ,CAAC;EAE5D,MAAM,WAAW,MAAM,YAAY,QAAQ;EAE3C,IAAI,CAAC,UACH,OAAO;GACL;GACA;GACA,QAAQ;EACV;EAGF,IAAI,CAAC,SAAS,eAAe,GAC3B,MAAM,IAAI,MACR,6BAA6B,SAAS,sCACxC;EAGF,MAAM,SAAS,MAAM,GAAG,SAAS,QAAQ;EACzC,MAAM,iBAAiB,KAAK,QAAQ,KAAK,QAAQ,QAAQ,GAAG,MAAM;EAElE,IAAI,iBAAiB,cAAc,MAAM,iBAAiB,aAAa,GACrE,MAAM,IAAI,MAAM,6BAA6B,SAAS,aAAa,eAAe,EAAE;EAGtF,OAAO;GACL;GACA;GACA,QAAQ;EACV;CACF,CAAC,CACH;AACF;AAEA,eAAe,gCAAgC,eAAsC;CACnF,MAAM,WAAW,MAAM,YAAY,aAAa;CAEhD,IAAI,UAAU;EACZ,IAAI,CAAC,SAAS,YAAY,GACxB,MAAM,IAAI,MACR,mCAAmC,cAAc,wCACnD;EAGF;CACF;CAEA,MAAM,aAAa,KAAK,QAAQ,aAAa;CAE7C,IAAI,eAAe,eACjB;CAGF,MAAM,gCAAgC,UAAU;AAClD;AAEA,eAAe,kBACb,MACA,eAC0B;CAC1B,IAAI,KAAK,WAAW,QAClB,OAAO;EACL,OAAO,KAAK;EACZ,UAAU,KAAK;EACf,QAAQ;CACV;CAGF,MAAM,GAAG,UAAU,KAAK,QAAQ,KAAK,QAAQ,CAAC;CAC9C,MAAM,aAAa,KAAK,SAAS,KAAK,QAAQ,KAAK,QAAQ,GAAG,aAAa;CAC3E,MAAM,GAAG,QAAQ,YAAY,KAAK,UAAU,KAAK;CAEjD,OAAO;EACL,OAAO,KAAK;EACZ,UAAU,KAAK;EACf,QAAQ;CACV;AACF;AAEA,eAAe,qBAAqB,SAKlB;CAChB,MAAM,QAAQ,IAAI,QAAQ,iBAAiB,KAAK,aAAa,GAAG,OAAO,QAAQ,CAAC,CAAC;CAEjF,IAAI,QAAQ,kBAAkB;EAC5B,MAAM,GAAG,OAAO,QAAQ,aAAa;EACrC;CACF;CAEA,MAAM,GAAG,OAAO,QAAQ,aAAa;AACvC;;;AC/PA,SAAS,aAAgB,OAAsB;CAC7C,IAAI,SAAS,KAAK,GAAG;EACnB,MAAM,WAAW;EACjB,QAAQ,KAAK,CAAC;CAChB;CAEA,OAAO;AACT;AAEA,SAAS,gBAAgB,SAAiB;CACxC,QAAQ,UAAmB;EACzB,IAAI,EAAE,SAAS,IAAI,KAAK,GACtB,OAAO;CAGX;AACF;AAEA,SAAgB,gBAAyB;CACvC,MAAM,UAAU,IAAI,QAAQ,QAAQ;CAEpC,QAAQ,YAAY,gEAAgE;CAEpF,QAAQ,OAAO,YAAY;EACzB,MAAM,6BAA6B;EAEnC,MAAM,OAAO,aACX,MAAM,KAAK;GACT,SAAS;GACT,aAAa;GACb,UAAU,gBAAgB,qBAAqB;EACjD,CAAC,CACH;EAEA,MAAM,cAAc,aAClB,MAAM,KAAK;GACT,SAAS;GACT,aAAa;GACb,UAAU,gBAAgB,4BAA4B;EACxD,CAAC,CACH;EAEA,MAAM,WAAW,aACf,MAAM,OAAO;GACX,SAAS;GACT,SAAS,CACP;IACE,OAAO;IACP,OAAO;IACP,MAAM;GACR,GACA;IACE,OAAO;IACP,OAAO;IACP,MAAM;GACR,CACF;EACF,CAAC,CACH;EAEA,MAAM,mBAAmB,aACvB,MAAM,YAAY;GAChB,SAAS;GACT,SAAS,gBAAgB,KAAK,WAAW;IACvC,OAAO,MAAM;IACb,OAAO,MAAM;GACf,EAAE;GACF,UAAU;EACZ,CAAC,CACH;EAEA,MAAM,oBAAoB,6BAA6B,MAAM,QAAQ;EAErE,MAAM,SAAS,cADQ,cAAc,MAAM,EAAE,MAAM,gBACT,GAAG,iBAAiB;EAC9D,MAAM,WAAW,QAAQ;EAEzB,SAAS,MAAM,uCAAuC;EAEtD,IAAI;GACF,MAAM,SAAS,MAAM,YAAY;IAC/B;IACA;IACA,UAAU;IACV;GACF,CAAC;GAED,SAAS,KAAK,eAAe;GAE7B,KACE,CACE,cAAc,OAAO,iBACrB,GAAG,OAAO,MAAM,KAAK,SAAS,GAAG,KAAK,MAAM,MAAM,IAAI,KAAK,SAAS,IAAI,KAAK,OAAO,EAAE,CACxF,EAAE,KAAK,IAAI,GACX,OAAO,SACT;GAEA,MAAM,MAAM;EACd,SAAS,OAAO;GACd,SAAS,KAAK,wBAAwB;GACtC,MAAM,iBAAiB,QAAQ,MAAM,UAAU,eAAe;GAC9D,QAAQ,KAAK,CAAC;EAChB;CACF,CAAC;CAED,OAAO;AACT;;;AC1GA,MAAM,UAAU,IAAI,QAAQ;AAE5B,QAAQ,KAAK,OAAO,EAAE,YAAY,qCAAqC,EAAE,QAAQ,OAAO;AAExF,QAAQ,WAAW,cAAc,CAAC;AAElC,MAAM,QAAQ,WAAW"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@michaeltroya/pouch",
+  "version": "0.1.0",
+  "description": "Create and link shared agent skills",
+  "keywords": [
+    "agents",
+    "ai",
+    "claude",
+    "cli",
+    "codex",
+    "cursor",
+    "skills"
+  ],
+  "homepage": "https://github.com/michaeltroya/pouch#readme",
+  "bugs": {
+    "url": "https://github.com/michaeltroya/pouch/issues"
+  },
+  "license": "MIT",
+  "author": "Michael Troya",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/michaeltroya/pouch.git"
+  },
+  "bin": {
+    "pouch": "./dist/index.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "vp pack",
+    "check": "vp check",
+    "check:fix": "vp check --fix",
+    "format": "vp fmt",
+    "lint": "vp lint",
+    "prepack": "vp pack",
+    "test": "vp test",
+    "prepare": "vp config"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.5.1",
+    "commander": "^15.0.0",
+    "fs-extra": "^11.3.5",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^25.9.3",
+    "oxfmt": "^0.54.0",
+    "oxlint": "^1.69.0",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3",
+    "vite-plus": "catalog:",
+    "vitest": "catalog:"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "packageManager": "pnpm@11.7.0+sha512.19cc852c120c7125760f2443ee6be0ca5b40f9f50598de1a09a1f177503e010e57c23c77646e01e761de59bf874fb22a3398c33ab9691fc13eb946b6f0f4d620"
+}