@penpair/core 0.3.0 → 0.3.3

package/dist/cli-main.js

@@ -28,6 +28,7 @@ import { archiveOperation, runOnPage, runOperation } from "./operation.js";
 import { formatDeepReport, runDeepCheck } from "./deep-check.js";
 import { probe } from "./probe.js";
 import { installSkills, listBundledSkills } from "./skills.js";
+import { checkSkills } from "./skill-check.js";
 import { checkProjectSnippets, loadProjectSnippets } from "./project-snippets.js";
 import { builtInRegistry, coerceParams, RegistryError } from "./registry.js";
 import { runSnippet } from "./snippet.js";
@@ -39,6 +40,7 @@ import { init } from "./instance/init.js";
 import { ConnectError, connectProject, keyFileCheck } from "./instance/connect.js";
 import { hostedOrigin, setup } from "./instance/setup.js";
 import { askHidden, askLine, openInBrowser } from "./instance/tty.js";
+import { validateSkillAgent } from "./skill-hosts.js";
 import { loadAdapters, readRawConfig, reservedCommands, } from "./adapters.js";
 import { requireLocalProfile } from "./local-profile.js";
 import { assertEndpointIsInstance, doctorExternal, LifecycleError, } from "./instance/connection.js";
@@ -109,6 +111,7 @@ Compare:
 @@INSTANCE@@Skills (the rules an AI agent follows, shipped with penpair):
   penpair skills                                       list them
   penpair skills install [--to <folder>] [--only <name>] [--force] [--agents AGENTS.md] [--dry-run]
+  penpair skills check [--agent codex|claude|copilot] [--only <name>] [--agents <file>] [--json]
   (built-in help lists configured extensions without importing their trusted code)
   (config-free inspection requires --standalone; writes require a project)
   penpair --version`;
@@ -337,6 +340,9 @@ async function main(argv, cli) {
             agents: {
                 type: "string",
             },
+            agent: {
+                type: "string",
+            },
             "dry-run": {
                 type: "boolean",
             },
@@ -541,6 +547,7 @@ async function main(argv, cli) {
             "kit",
         ],
         skills: [
+            "agent",
             "to",
             "only",
             "force",
@@ -801,14 +808,21 @@ async function main(argv, cli) {
     if (command === "skills" &&
         rest[0] !== "install" &&
         [
-            values.agents,
             values["dry-run"],
             values.to,
-            values.only,
             values.force,
         ].some((value) => value !== undefined)) {
         throw new Error("Installation flags require skills install");
     }
+    if (values.agent !== undefined && (command !== "skills" || rest[0] !== "check")) {
+        throw new CommandArgumentError("--agent requires skills check");
+    }
+    if (command === "skills" &&
+        rest[0] !== "install" &&
+        rest[0] !== "check" &&
+        (values.agents !== undefined || values.only !== undefined)) {
+        throw new CommandArgumentError("--agents and --only require skills install or skills check");
+    }
     if ((values.resume || values.checkpoint || values["force-lock"] || values.trace) &&
         (!values.apply ||
             !([
@@ -1165,6 +1179,25 @@ async function main(argv, cli) {
         return 0;
     }
     if (command === "skills") {
+        if (rest.length > 1 ||
+            (rest[0] !== undefined &&
+                ![
+                    "install",
+                    "check",
+                ].includes(rest[0]))) {
+            throw new CommandArgumentError("Usage: skills [install | check]; see penpair --help");
+        }
+        if (rest[0] === "check") {
+            const report = await checkSkills({
+                root,
+                agent: validateSkillAgent(values.agent),
+                agents: values.agents,
+                only: values.only,
+            });
+            output.result(report);
+            output.log(JSON.stringify(report, null, 2));
+            return report.ready ? 0 : 3;
+        }
         if (rest[0] === "install") {
             const report = await installSkills({
                 root,
@@ -1206,7 +1239,7 @@ async function main(argv, cli) {
                 output.log("\nChoose --agents <path> to integrate these rows:\n" + report.agentsRows.join("\n"));
             }
             for (const old of report.legacy) {
-                output.log(`\nnote ${old.folder} is the old name of ${old.renamedTo}. ${old.carriedFacts ? "Your project-facts.md was copied to the new folder. " : ""}Delete the old folder and its links (.agents/skills/${path.posix.basename(old.folder)}, .claude/skills/${path.posix.basename(old.folder)}) and update its row in your AGENTS.md.`);
+                output.log(`\nnote ${old.folder} is replaced by ${old.renamedTo}. ${old.carriedFacts ? "Your project-facts.md was copied to the new folder. " : ""}Review and migrate custom guidance before removing the old folder, its discovery links and stale instruction rows. No legacy files were deleted.`);
             }
             output.log("\nThen fill in references/project-facts.md in penpair-design: it is yours and is never replaced.");
             return report.instructions?.status === "choice-required" ? 3 : 0;

package/dist/skill-check-entry.d.ts

@@ -0,0 +1,19 @@
+import { type SkillInstructionCheck } from "./skill-check-instructions.js";
+import { type SkillAgent } from "./skill-hosts.js";
+export interface SkillDiagnostic {
+    name: string;
+    path: string;
+    implicitInvocation: boolean | null;
+    entrypoint: "current" | "modified" | "unavailable";
+    problems: string[];
+    warnings: string[];
+}
+interface EntryOptions {
+    root: string;
+    agent: SkillAgent;
+    name: string;
+    bundledDirectory: string;
+    instructions: SkillInstructionCheck;
+}
+export declare function checkSkillEntry(options: EntryOptions): Promise<SkillDiagnostic>;
+export {};

package/dist/skill-check-entry.js

@@ -0,0 +1,107 @@
+import { lstat, readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import { parseSkillMetadata, parseSkillYaml } from "./skill-metadata.js";
+import { readSkillFile } from "./skill-file.js";
+import { resolveSkillLink } from "./skill-check-instructions.js";
+import { skillHosts } from "./skill-hosts.js";
+async function invocationAllowed(root, skillPath) {
+    const relative = path.posix.join(path.posix.dirname(skillPath), "agents/openai.yaml");
+    const present = await lstat(path.join(root, relative)).catch((error) => {
+        if (error.code !== "ENOENT") {
+            throw error;
+        }
+        return undefined;
+    });
+    if (!present) {
+        return true;
+    }
+    const metadata = parseSkillYaml(await readSkillFile(root, relative));
+    if (metadata.policy === undefined) {
+        return true;
+    }
+    if (!metadata.policy || typeof metadata.policy !== "object" || Array.isArray(metadata.policy)) {
+        throw new Error("Invalid invocation policy");
+    }
+    const allowed = metadata.policy.allow_implicit_invocation;
+    if (allowed !== undefined && typeof allowed !== "boolean") {
+        throw new Error("Invocation policy must use a boolean");
+    }
+    return allowed !== false;
+}
+export async function checkSkillEntry(options) {
+    const { root, agent, name, bundledDirectory, instructions } = options;
+    const skillPath = path.posix.join(skillHosts[agent].folder, name, "SKILL.md");
+    const report = {
+        name,
+        path: skillPath,
+        implicitInvocation: null,
+        entrypoint: "unavailable",
+        problems: [],
+        warnings: [],
+    };
+    try {
+        const source = await readSkillFile(root, skillPath);
+        parseSkillMetadata(source, name);
+        const bundled = await readFile(path.join(bundledDirectory, name, "SKILL.md"), "utf8");
+        report.entrypoint = source === bundled ? "current" : "modified";
+        if (report.entrypoint === "modified") {
+            report.warnings.push("The discoverable entrypoint differs from the bundled skill; review intentional customization before refresh.");
+        }
+        const localLinks = [
+            ...source.matchAll(/\[[^\]]+\]\(([^)]+)\)/g),
+        ]
+            .map((match) => match[1])
+            .filter((target) => target && !target.startsWith("#") && !/^[a-z][a-z0-9+.-]*:/i.test(target));
+        if (localLinks.length > 100) {
+            throw new Error("Too many local resource links");
+        }
+        for (const target of localLinks) {
+            await resolveSkillLink(root, skillPath, target);
+        }
+        if (agent === "codex") {
+            report.implicitInvocation = await invocationAllowed(root, skillPath);
+        }
+        else if (agent === "claude") {
+            const frontmatter = /^\uFEFF?---\r?\n([\s\S]*?)\r?\n---/.exec(source);
+            const disabled = parseSkillYaml(frontmatter[1])["disable-model-invocation"];
+            if (disabled !== undefined && typeof disabled !== "boolean") {
+                throw new Error("Invalid Claude invocation policy");
+            }
+            report.implicitInvocation = disabled !== true;
+        }
+        if (report.implicitInvocation === false) {
+            report.problems.push("Implicit invocation is disabled by this host's skill policy; explicit invocation remains available.");
+        }
+        for (const folder of [
+            ".skills",
+            ".claude/skills",
+            ".agents/skills",
+            ".github/skills",
+        ]) {
+            const otherPath = path.posix.join(folder, name, "SKILL.md");
+            const other = await readSkillFile(root, otherPath).catch(() => undefined);
+            if (other !== undefined && other !== source) {
+                report.problems.push("Discoverable skill copies differ; review the conflicting copies before refreshing.");
+            }
+            else if (other !== undefined &&
+                (await realpath(path.join(root, otherPath))) !==
+                    (await realpath(path.join(root, skillPath)))) {
+                report.problems.push("Independent skill copies require consolidation even when their contents match; preserve customizations before removing duplicates.");
+            }
+        }
+        const routes = instructions.links[name] ?? [];
+        if (!routes.length) {
+            report.problems.push("No generated task route links this skill from the selected instruction file.");
+        }
+        const resolvedSkill = await realpath(path.join(root, skillPath));
+        for (const target of routes) {
+            if ((await resolveSkillLink(root, instructions.path, target)) !== resolvedSkill) {
+                report.problems.push("An instruction route points to a different skill copy.");
+            }
+        }
+    }
+    catch {
+        report.problems.push("Skill discovery, frontmatter, local resources or UI policy is missing, invalid or resolves outside the project; inspect the local files and preview a skill refresh.");
+    }
+    return report;
+}

package/dist/skill-check-instructions.d.ts

@@ -0,0 +1,7 @@
+export interface SkillInstructionCheck {
+    path: string;
+    problems: string[];
+    links: Record<string, string[]>;
+}
+export declare function resolveSkillLink(root: string, from: string, target: string): Promise<string>;
+export declare function checkSkillInstructions(root: string, instructionFile: string): Promise<SkillInstructionCheck>;

package/dist/skill-check-instructions.js

@@ -0,0 +1,39 @@
+import path from "node:path";
+import { readSkillFile } from "./skill-file.js";
+import { skillInstructionMarkers } from "./skill-instructions.js";
+import { resolveProjectInput } from "./project-input.js";
+export async function resolveSkillLink(root, from, target) {
+    const decoded = decodeURIComponent(target.split("#")[0]);
+    if (!decoded || path.isAbsolute(decoded) || /^[a-z][a-z0-9+.-]*:/i.test(decoded)) {
+        throw new Error("Skill resource link must resolve inside the project");
+    }
+    const relative = path.relative(root, path.resolve(root, path.dirname(from), decoded));
+    return resolveProjectInput(root, relative);
+}
+export async function checkSkillInstructions(root, instructionFile) {
+    const report = {
+        path: instructionFile,
+        problems: [],
+        links: {},
+    };
+    try {
+        const resolved = await resolveProjectInput(root, instructionFile);
+        report.path = path.relative(root, resolved).split(path.sep).join("/");
+        const source = await readSkillFile(root, report.path);
+        const { start, end } = skillInstructionMarkers;
+        if (source.split(start).length !== 2 ||
+            source.split(end).length !== 2 ||
+            source.indexOf(start) > source.indexOf(end)) {
+            throw new Error("Missing or malformed installer-owned skill routing block");
+        }
+        const block = source.slice(source.indexOf(start) + start.length, source.indexOf(end));
+        const routing = block.split("| Skill | Purpose |")[0];
+        for (const match of routing.matchAll(/\[([a-z0-9-]+)\]\(([^)]+)\)/g)) {
+            (report.links[match[1]] ??= []).push(match[2]);
+        }
+    }
+    catch {
+        report.problems.push("Project instructions are missing, unreadable or lack a valid owned routing block; preview skills install --agents with this destination.");
+    }
+    return report;
+}

package/dist/skill-check.d.ts

@@ -0,0 +1,18 @@
+import { type SkillDiagnostic } from "./skill-check-entry.js";
+import { type SkillInstructionCheck } from "./skill-check-instructions.js";
+import { type SkillAgent } from "./skill-hosts.js";
+export interface SkillCheckOptions {
+    root: string;
+    agent?: SkillAgent;
+    agents?: string;
+    only?: string[];
+}
+export interface SkillCheckReport {
+    agent: SkillAgent;
+    ready: boolean;
+    legacy: string[];
+    instructions: Pick<SkillInstructionCheck, "path" | "problems">;
+    skills: SkillDiagnostic[];
+    limitations: string[];
+}
+export declare function checkSkills(options: SkillCheckOptions): Promise<SkillCheckReport>;

package/dist/skill-check.js

@@ -0,0 +1,58 @@
+import { lstat, realpath } from "node:fs/promises";
+import path from "node:path";
+import { bundledSkillsDirectory, listBundledSkills } from "./skills.js";
+import { checkSkillEntry } from "./skill-check-entry.js";
+import { checkSkillInstructions } from "./skill-check-instructions.js";
+import { skillHosts, validateSkillAgent } from "./skill-hosts.js";
+export async function checkSkills(options) {
+    const agent = validateSkillAgent(options.agent);
+    const root = await realpath(options.root);
+    const bundledDirectory = bundledSkillsDirectory();
+    const names = await listBundledSkills(bundledDirectory);
+    const selected = options.only ?? names;
+    if (!selected.length || selected.some((name) => !names.includes(name))) {
+        throw new Error("Select one or more bundled skill names; use penpair skills to list them");
+    }
+    const instructions = await checkSkillInstructions(root, options.agents ?? skillHosts[agent].instructions);
+    const skills = await Promise.all([
+        ...new Set(selected),
+    ].map((name) => checkSkillEntry({
+        root,
+        agent,
+        name,
+        bundledDirectory,
+        instructions,
+    })));
+    const legacy = [];
+    if (selected.includes("penpair-setup")) {
+        for (const folder of [
+            ".skills",
+            ".agents/skills",
+            ".claude/skills",
+            ".github/skills",
+        ]) {
+            const relative = path.posix.join(folder, "penpair-setup-guide");
+            if (await lstat(path.join(root, relative)).catch(() => undefined)) {
+                legacy.push(relative);
+            }
+        }
+    }
+    return {
+        agent,
+        ready: !legacy.length &&
+            !instructions.problems.length &&
+            skills.every((skill) => !skill.problems.length),
+        legacy,
+        instructions: {
+            path: instructions.path,
+            problems: instructions.problems,
+        },
+        skills,
+        limitations: [
+            "Offline project-file checks only; no connection, adapter/provider execution, credential reads or writes.",
+            "Does not inspect global host settings, session skill catalogs, context budgets or UI selection badges.",
+            "Checks the selected instruction file, not whether the running host loaded it; Copilot invocation policy is not evaluated.",
+            "A valid install and allowed invocation policy do not prove model selection, correct workflow application, visual quality or owner approval.",
+        ],
+    };
+}

package/dist/skill-file.d.ts

@@ -0,0 +1,2 @@
+/** Read only bounded regular files inside the explicitly selected project. */
+export declare function readSkillFile(root: string, relative: string): Promise<string>;

package/dist/skill-file.js

@@ -0,0 +1,31 @@
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import { resolveProjectInput } from "./project-input.js";
+import { maxSkillBytes } from "./skill-metadata.js";
+/** Read only bounded regular files inside the explicitly selected project. */
+export async function readSkillFile(root, relative) {
+    const resolved = await resolveProjectInput(root, relative);
+    const handle = await open(resolved, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+    try {
+        const info = await handle.stat();
+        if (!info.isFile() || info.size > maxSkillBytes) {
+            throw new Error("Skill input must be a regular file within the 128 KB limit");
+        }
+        const buffer = Buffer.alloc(maxSkillBytes + 1);
+        let length = 0;
+        while (length < buffer.length) {
+            const { bytesRead } = await handle.read(buffer, length, buffer.length - length, length);
+            if (!bytesRead) {
+                break;
+            }
+            length += bytesRead;
+        }
+        if (length > maxSkillBytes) {
+            throw new Error("Skill input exceeds the 128 KB limit");
+        }
+        return buffer.subarray(0, length).toString("utf8");
+    }
+    finally {
+        await handle.close();
+    }
+}

package/dist/skill-hosts.d.ts

@@ -0,0 +1,16 @@
+export declare const skillHosts: {
+    readonly codex: {
+        readonly folder: ".agents/skills";
+        readonly instructions: "AGENTS.md";
+    };
+    readonly claude: {
+        readonly folder: ".claude/skills";
+        readonly instructions: "CLAUDE.md";
+    };
+    readonly copilot: {
+        readonly folder: ".agents/skills";
+        readonly instructions: "AGENTS.md";
+    };
+};
+export type SkillAgent = keyof typeof skillHosts;
+export declare function validateSkillAgent(value?: string): SkillAgent;

package/dist/skill-hosts.js

@@ -0,0 +1,20 @@
+export const skillHosts = {
+    codex: {
+        folder: ".agents/skills",
+        instructions: "AGENTS.md",
+    },
+    claude: {
+        folder: ".claude/skills",
+        instructions: "CLAUDE.md",
+    },
+    copilot: {
+        folder: ".agents/skills",
+        instructions: "AGENTS.md",
+    },
+};
+export function validateSkillAgent(value = "codex") {
+    if (value === "codex" || value === "claude" || value === "copilot") {
+        return value;
+    }
+    throw new Error("Skill agent must be codex, claude or copilot");
+}

package/dist/skill-instructions.d.ts

@@ -1,3 +1,7 @@
+export declare const skillInstructionMarkers: {
+    start: string;
+    end: string;
+};
 export interface InstructionReport {
     path: string | null;
     status: "not-selected" | "choice-required" | "unchanged" | "preview" | "written";

package/dist/skill-instructions.js

@@ -2,8 +2,13 @@ import { lstat, readFile, realpath } from "node:fs/promises";
 import path from "node:path";
 import { resolveProjectOutput } from "./project-input.js";
 import { atomicWriteFile } from "./atomic-output.js";
+import { renderSkillRouting } from "./skill-routing.js";
 const start = "<!-- penpair:skills:start -->";
 const end = "<!-- penpair:skills:end -->";
+export const skillInstructionMarkers = {
+    start,
+    end,
+};
 async function exists(file) {
     try {
         await lstat(file);
@@ -70,6 +75,7 @@ export async function planSkillInstructions(root, rows, destination) {
     }));
     const block = [
         start,
+        ...renderSkillRouting(relativeRows),
         "| Skill | Purpose |",
         "| --- | --- |",
         ...relativeRows,

package/dist/skill-metadata.d.ts

@@ -0,0 +1,8 @@
+export interface SkillMetadata {
+    name: string;
+    description: string;
+}
+export declare const maxSkillBytes: number;
+/** Parse data only; aliases and unknown tags cannot expand a local skill file. */
+export declare function parseSkillYaml(source: string): Record<string, unknown>;
+export declare function parseSkillMetadata(source: string, expectedName?: string): SkillMetadata;

package/dist/skill-metadata.js

@@ -0,0 +1,52 @@
+import { parseDocument } from "yaml";
+export const maxSkillBytes = 128 * 1024;
+/** Parse data only; aliases and unknown tags cannot expand a local skill file. */
+export function parseSkillYaml(source) {
+    if (Buffer.byteLength(source) > maxSkillBytes) {
+        throw new Error("Skill metadata exceeds the 128 KB limit");
+    }
+    const document = parseDocument(source, {
+        uniqueKeys: true,
+    });
+    if (document.errors.length || document.warnings.length) {
+        throw new Error("Invalid skill YAML metadata");
+    }
+    let value;
+    try {
+        value = document.toJS({
+            maxAliasCount: 0,
+        });
+    }
+    catch {
+        throw new Error("Skill YAML aliases are not supported");
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Skill YAML metadata must be an object");
+    }
+    return value;
+}
+export function parseSkillMetadata(source, expectedName) {
+    if (Buffer.byteLength(source) > maxSkillBytes) {
+        throw new Error("SKILL.md exceeds the 128 KB limit");
+    }
+    const frontmatter = /^\uFEFF?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(source);
+    if (!frontmatter) {
+        throw new Error("SKILL.md requires YAML frontmatter with name and description");
+    }
+    const metadata = parseSkillYaml(frontmatter[1]);
+    if (typeof metadata.name !== "string" ||
+        !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(metadata.name) ||
+        metadata.name.length > 64 ||
+        (expectedName !== undefined && metadata.name !== expectedName)) {
+        throw new Error("Skill name must match its kebab-case folder (at most 64 characters)");
+    }
+    if (typeof metadata.description !== "string" ||
+        !metadata.description.trim() ||
+        metadata.description.length > 1024) {
+        throw new Error("Skill description must be nonempty text (at most 1024 characters)");
+    }
+    return {
+        name: metadata.name,
+        description: metadata.description.trim().replace(/\s+/g, " "),
+    };
+}

package/dist/skill-routing.d.ts

@@ -0,0 +1,2 @@
+/** Instruction links have already been made relative to their destination. */
+export declare function renderSkillRouting(rows: string[]): string[];

package/dist/skill-routing.js

@@ -0,0 +1,36 @@
+const tasksBySkill = {
+    "penpair-setup": "Install Penpair or repair a Penpot connection",
+    "penpair-design": "Inspect, edit, audit or export a Penpot file",
+    "penpair-recipes": "Build a Penpot screen or derive a state variant from an approved frame",
+    "design-judgment": "Choose or critique hierarchy, density and screen states",
+    "penpair-handoff": "Implement a frontend from an approved Penpot design",
+    "penpair-verify": "Compare a frontend with its approved design or recheck visual fixes",
+};
+/** Instruction links have already been made relative to their destination. */
+export function renderSkillRouting(rows) {
+    const routes = [];
+    for (const row of rows) {
+        const match = /^\| \[([a-z0-9-]+)\]\(([^)]+)\) \|/.exec(row);
+        if (!match) {
+            continue;
+        }
+        const name = match[1];
+        const task = tasksBySkill[name];
+        if (task) {
+            routes.push(`| ${task} | [${name}](${match[2]}) |`);
+        }
+    }
+    if (!routes.length) {
+        return [];
+    }
+    return [
+        "Before working on a matching task, read the linked SKILL.md and follow its relevant workflow before running design or implementation tools.",
+        "Briefly name the selected skill and its purpose when starting or changing workflow; report actual evidence separately from the intention to use a skill.",
+        "Use the smallest applicable set of skills; follow a linked companion only when the task reaches that stage. Skill selection does not authorize additional writes or replace owner approval.",
+        "",
+        "| Task | Read first |",
+        "| --- | --- |",
+        ...routes,
+        "",
+    ];
+}

package/dist/skills.d.ts

@@ -18,7 +18,7 @@ export interface InstallOptions {
     only?: string[];
     /** Replace files that differ from the shipped ones (never the project-owned ones). */
     force?: boolean;
-    /** Make the skills discoverable for Codex and Claude Code with relative links (default true). */
+    /** Make one shared copy discoverable for Codex, Claude Code and Copilot (default true). */
     links?: boolean;
     /** For tests. */
     source?: string;

package/dist/skills.js

@@ -4,6 +4,7 @@ import { planSkillInstructions, applySkillInstructions, } from "./skill-instruct
 import { lstat, mkdir, readdir, readFile, symlink } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { parseSkillMetadata } from "./skill-metadata.js";
 /** The skills shipped inside the package (`skills/` next to `dist/`). */
 export const bundledSkillsDirectory = () => path.join(path.dirname(fileURLToPath(import.meta.url)), "../skills");
 /** Files a project fills in. They are written once and never replaced, not even with --force. */
@@ -61,8 +62,7 @@ async function exists(file) {
 /** The skill's name and the first sentence of its description, from the frontmatter, for a row in a project's agent guide. */
 export async function describeSkill(skillDirectory) {
     const text = (await readIfExists(path.join(skillDirectory, "SKILL.md"))) ?? "";
-    const name = /^name:\s*(.+)$/m.exec(text)?.[1]?.trim() ?? path.basename(skillDirectory);
-    const description = /^description:\s*(.+)$/m.exec(text)?.[1]?.trim() ?? "";
+    const { name, description } = parseSkillMetadata(text, path.basename(skillDirectory));
     return {
         name,
         summary: description.split(/(?<=\.)\s/)[0] ?? description,
@@ -71,22 +71,30 @@ export async function describeSkill(skillDirectory) {
 /** Skills that changed name. Installing the new one leaves the old folder behind, which `installSkills` then reports. */
 export const renamedSkills = {
     "penpot-design": "penpair-design",
+    "penpair-setup-guide": "penpair-setup",
 };
 /** Where the penpair skills already live in a project as real folders (not links), so a later install goes to the same place. */
 export async function existingSkillsFolder(root) {
-    for (const folder of [
+    const folders = [
         ".skills",
         ".claude/skills",
         ".agents/skills",
-    ]) {
-        for (const name of [
+        ".github/skills",
+    ];
+    // Prefer an existing canonical pack over a legacy bootstrap in another host.
+    for (const names of [
+        [
             "penpair-design",
             "penpair-setup",
-            ...Object.keys(renamedSkills),
-        ]) {
-            const found = await lstat(path.join(root, folder, name)).catch(() => undefined);
-            if (found?.isDirectory()) {
-                return folder;
+        ],
+        Object.keys(renamedSkills),
+    ]) {
+        for (const folder of folders) {
+            for (const name of names) {
+                const found = await lstat(path.join(root, folder, name)).catch(() => undefined);
+                if (found?.isDirectory()) {
+                    return folder;
+                }
             }
         }
     }
@@ -197,6 +205,26 @@ export async function installSkills(options) {
             carriedFacts: carriedFacts && !options.dryRun,
         });
     }
+    // A standalone bootstrap guide may have been installed in a host's own folder.
+    // Report those copies for review; never delete a user's customized skill.
+    if (chosen.includes("penpair-setup")) {
+        for (const folder of [
+            ".skills",
+            ".agents/skills",
+            ".claude/skills",
+            ".github/skills",
+        ]) {
+            const legacyFolder = path.posix.join(folder, "penpair-setup-guide");
+            if (!report.legacy.some((entry) => entry.folder === legacyFolder) &&
+                (await exists(path.join(options.root, legacyFolder)))) {
+                report.legacy.push({
+                    folder: legacyFolder,
+                    renamedTo: "penpair-setup",
+                    carriedFacts: false,
+                });
+            }
+        }
+    }
     if (options.dryRun) {
         report.wouldInstall = [
             ...writes.values(),