xcode-skills 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 darsha80
+
+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,173 @@
+# xcode-skills
+
+Manage Agent Skills for Xcode's Coding Assistant integrations.
+
+Xcode reads skills from fixed Codex and Claude locations. Skills installed for other tools, global agent environments, or project-local folders are not automatically available to Xcode. `xcode-skills` installs and manages existing Agent Skills for Xcode only.
+
+## Scope
+
+`xcode-skills` manages:
+
+- Codex: `~/Library/Developer/Xcode/CodingAssistant/codex`
+- Claude: `~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig`
+
+It does not manage global Codex skills, Claude Code skills, project-local skills, or arbitrary skill folders.
+
+Xcode must activate an integration first. This tool will not create missing integration roots, but it can create skill-management subdirectories inside an activated root.
+
+## Install
+
+From this repo:
+
+```sh
+npm install
+npm run build
+npm link
+```
+
+After npm publication, install with:
+
+```sh
+npm install -g xcode-skills
+```
+
+## Commands
+
+```sh
+xcode-skills install <skill-spec>
+xcode-skills uninstall <skill-name>
+xcode-skills enable <skill-name>
+xcode-skills disable <skill-name>
+xcode-skills list
+xcode-skills manage
+```
+
+Write commands accept:
+
+```sh
+--target codex|claude|both
+--yes
+--dry-run
+--verbose
+```
+
+If `--target` is omitted for a write command, `xcode-skills` prompts for Codex, Claude, or both.
+
+`list` is read-only, does not prompt by default, and supports:
+
+```sh
+--target codex|claude|both
+--json
+```
+
+## Examples
+
+Install a skill for Codex:
+
+```sh
+xcode-skills install mattpocock/skills/skills/engineering/diagnose --target codex
+```
+
+Install for both integrations:
+
+```sh
+xcode-skills install mattpocock/skills/skills/engineering/diagnose --target both
+```
+
+List installed skills:
+
+```sh
+xcode-skills list
+```
+
+Machine-readable list output:
+
+```sh
+xcode-skills list --json
+```
+
+Disable and re-enable a skill:
+
+```sh
+xcode-skills disable diagnose --target codex
+xcode-skills enable diagnose --target codex
+```
+
+Uninstall a skill:
+
+```sh
+xcode-skills uninstall diagnose --target both
+```
+
+Preview a write operation:
+
+```sh
+xcode-skills uninstall diagnose --target codex --dry-run
+```
+
+## Manage TUI
+
+`xcode-skills manage` opens a keyboard-only management view.
+
+Controls:
+
+- `Tab`: switch Codex/Claude tab
+- `Up` / `Down` or `k` / `j`: move selection
+- `Space` / `Enter`: toggle enabled/disabled for the selected skill
+- `q`: quit
+
+The TUI shows inactive integrations, conflicts, and suspicious folders. It does not install or uninstall skills.
+
+## State Model
+
+Enabled skills live at:
+
+```text
+<integration-root>/skills/<skill-name>/
+```
+
+Disabled skills are preserved offline at:
+
+```text
+<integration-root>/.xcode-skills/disabled/<skill-name>/
+```
+
+States:
+
+- `enabled`: active Skill Folder exists
+- `disabled`: disabled Skill Folder exists
+- `conflict`: active and disabled copies both exist
+- `suspicious`: a discovered folder lacks `SKILL.md`
+- `not-installed`: neither active nor disabled copy exists
+
+`disable` is reversible offline. `uninstall` removes both enabled and disabled copies for the selected target integration.
+
+## Resolver
+
+`xcode-skills` depends on the `skills` npm package and invokes its packaged CLI as the Skill Source Resolver. It resolves a Skill Spec once in a temporary workspace, uses copy mode, then copies the resolved Skill Folder into the selected Xcode integration locations.
+
+The temporary workspace is deleted after the operation, including failure and dry-run cases.
+
+## Safety
+
+`xcode-skills` only touches paths for the selected skill:
+
+```text
+skills/<skill-name>/
+.xcode-skills/disabled/<skill-name>/
+```
+
+It preserves unrelated Skill Folders, Xcode files, and user files.
+
+The tool requires confirmation before overwriting or deleting no-lock/manual folders. Use `--yes` to bypass confirmation in automation.
+
+## Development
+
+```sh
+npm install
+npm test
+npm run typecheck
+npm run build
+```
+
+The test suite uses fake integration roots and does not touch real Xcode directories.

package/dist/cli.js

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+import { pathToFileURL } from "node:url";
+import { createInterface } from "node:readline/promises";
+import { installSkill } from "./install.js";
+import { resolveIntegrationRoots } from "./integrations.js";
+import { formatListHuman, formatListJson, listSkillInstallations } from "./list.js";
+import { buildManageView, formatManageView, runManageSession } from "./manage.js";
+import { disableSkill, enableSkill } from "./lifecycle.js";
+import { resolveSkillArtifactWithCli } from "./resolver.js";
+import { selectTargetIntegrations } from "./targets.js";
+import { uninstallSkill } from "./uninstall.js";
+export async function runCli(argv, dependencies = {}) {
+    try {
+        const parsed = parseArgs(argv);
+        const integrations = await (dependencies.resolveIntegrationRoots ?? resolveIntegrationRoots)();
+        const verboseLines = [];
+        if (parsed.command === "list") {
+            const entries = await listSkillInstallations(integrations, { target: parsed.target });
+            return ok(parsed.json ? formatListJson(entries) : formatListHuman(entries));
+        }
+        if (parsed.command === "manage") {
+            const readKey = dependencies.readManageKey ??
+                (process.stdin.isTTY ? readManageKeyFromStdin : undefined);
+            if (readKey !== undefined) {
+                const interactiveTty = dependencies.readManageKey === undefined && process.stdin.isTTY;
+                const output = await runManageSession(integrations, {
+                    readKey,
+                    render: interactiveTty
+                        ? (screen) => {
+                            process.stdout.write(`\x1Bc${screen}\n`);
+                        }
+                        : undefined,
+                });
+                return ok(interactiveTty ? "" : output);
+            }
+            return ok(formatManageView(await buildManageView(integrations)));
+        }
+        const skillArg = parsed.args[0];
+        if (skillArg === undefined) {
+            return fail(`Missing required argument for ${parsed.command}`);
+        }
+        if (["install", "uninstall", "enable", "disable"].includes(parsed.command) &&
+            parsed.args.length !== 1) {
+            return fail(`${parsed.command} accepts exactly one skill argument`);
+        }
+        const selectedIntegrations = await selectTargetIntegrations({
+            integrations,
+            target: parsed.target,
+            promptForTarget: dependencies.promptForTarget ?? promptForTargetFromStdin,
+        });
+        if (parsed.command === "install") {
+            const resolver = dependencies.resolver ??
+                dependencies.createResolver?.((line) => verboseLines.push(line)) ??
+                ((skillSpec) => resolveSkillArtifactWithCli(skillSpec, {
+                    onVerbose: parsed.verbose ? (line) => verboseLines.push(line) : undefined,
+                }));
+            const results = await installSkill({
+                skillSpec: skillArg,
+                integrations: selectedIntegrations,
+                resolver,
+                dryRun: parsed.dryRun,
+                yes: parsed.yes,
+                confirmOverwrite: parsed.yes || parsed.dryRun
+                    ? undefined
+                    : (path) => confirmWithDependencies(dependencies, `overwrite manual Skill Folder?\n  ${path}`),
+            });
+            return ok(withVerbose(formatInstallResults(results), parsed.verbose ? verboseLines : []));
+        }
+        if (parsed.command === "enable" || parsed.command === "disable") {
+            const results = await Promise.all(selectedIntegrations.map((integration) => parsed.command === "enable"
+                ? enableSkill(integration, skillArg, { dryRun: parsed.dryRun })
+                : disableSkill(integration, skillArg, { dryRun: parsed.dryRun })));
+            return ok(formatLifecycleResults(results));
+        }
+        if (parsed.command === "uninstall") {
+            let results = await Promise.all(selectedIntegrations.map((integration) => uninstallSkill(integration, skillArg, {
+                dryRun: parsed.dryRun,
+                yes: parsed.yes,
+            })));
+            if (!parsed.dryRun && !parsed.yes && results.some((result) => result.status === "needs-confirmation")) {
+                const confirmed = await confirmWithDependencies(dependencies, [
+                    "delete these Skill Installation paths?",
+                    ...results.flatMap((result) => result.removedPaths.map((path) => `  ${path}`)),
+                ].join("\n"));
+                if (confirmed) {
+                    results = await Promise.all(selectedIntegrations.map((integration) => uninstallSkill(integration, skillArg, {
+                        yes: true,
+                    })));
+                }
+            }
+            return ok(formatUninstallResults(results));
+        }
+        return fail(`Unknown command: ${parsed.command}`);
+    }
+    catch (error) {
+        return fail(error instanceof Error ? error.message : String(error));
+    }
+}
+function parseArgs(argv) {
+    const [command = "help", ...rest] = argv;
+    const args = [];
+    let target;
+    let yes = false;
+    let dryRun = false;
+    let verbose = false;
+    let json = false;
+    for (let index = 0; index < rest.length; index += 1) {
+        const token = rest[index];
+        if (token === "--target") {
+            const value = rest[index + 1];
+            if (value !== "codex" && value !== "claude" && value !== "both") {
+                throw new Error(`Invalid target: ${value ?? ""}`);
+            }
+            target = value;
+            index += 1;
+            continue;
+        }
+        if (token === "--yes" || token === "-y") {
+            yes = true;
+            continue;
+        }
+        if (token === "--dry-run") {
+            dryRun = true;
+            continue;
+        }
+        if (token === "--verbose") {
+            verbose = true;
+            continue;
+        }
+        if (token === "--json") {
+            json = true;
+            continue;
+        }
+        args.push(token);
+    }
+    return { command, args, target, yes, dryRun, verbose, json };
+}
+function ok(stdout) {
+    return { exitCode: 0, stdout, stderr: "" };
+}
+function fail(stderr) {
+    return { exitCode: 1, stdout: "", stderr };
+}
+function formatInstallResults(results) {
+    return results
+        .map((result) => `${displayIntegration(result.integrationId)}: ${result.status} ${result.skillIdentity}`)
+        .join("\n");
+}
+function formatLifecycleResults(results) {
+    return results
+        .map((result) => `${displayIntegration(result.integrationId)}: ${result.status} ${result.skillIdentity}`)
+        .join("\n");
+}
+function formatUninstallResults(results) {
+    return results
+        .map((result) => {
+        const header = `${displayIntegration(result.integrationId)}: ${result.status} ${result.skillIdentity}`;
+        if (!["needs-confirmation", "would-need-confirmation", "would-uninstall"].includes(result.status) ||
+            result.removedPaths.length === 0) {
+            return header;
+        }
+        return [header, ...result.removedPaths.map((path) => `  ${path}`)].join("\n");
+    })
+        .join("\n");
+}
+function withVerbose(stdout, verboseLines) {
+    if (verboseLines.length === 0) {
+        return stdout;
+    }
+    return [stdout, "", "Verbose", ...verboseLines].join("\n");
+}
+function displayIntegration(id) {
+    return id === "codex" ? "Codex" : "Claude";
+}
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    const result = await runCli(process.argv.slice(2));
+    if (result.stdout.length > 0) {
+        process.stdout.write(`${result.stdout}\n`);
+    }
+    if (result.stderr.length > 0) {
+        process.stderr.write(`${result.stderr}\n`);
+    }
+    process.exitCode = result.exitCode;
+}
+async function promptForTargetFromStdin() {
+    const readline = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        const answer = (await readline.question("Target Agent Integration (codex/claude/both): "))
+            .trim()
+            .toLowerCase();
+        if (answer === "codex" || answer === "claude" || answer === "both") {
+            return answer;
+        }
+        throw new Error(`Invalid target: ${answer}`);
+    }
+    finally {
+        readline.close();
+    }
+}
+async function confirmWithDependencies(dependencies, message) {
+    if (dependencies.confirm !== undefined) {
+        return dependencies.confirm(message);
+    }
+    return confirmFromStdin(message);
+}
+async function confirmFromStdin(message) {
+    const readline = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        const answer = (await readline.question(`${message}\nContinue? (y/N): `))
+            .trim()
+            .toLowerCase();
+        return answer === "y" || answer === "yes";
+    }
+    finally {
+        readline.close();
+    }
+}
+async function readManageKeyFromStdin() {
+    const stdin = process.stdin;
+    if (stdin.setRawMode !== undefined) {
+        stdin.setRawMode(true);
+    }
+    stdin.resume();
+    stdin.setEncoding("utf8");
+    return new Promise((resolve) => {
+        const onData = (chunk) => {
+            stdin.off("data", onData);
+            if (stdin.setRawMode !== undefined) {
+                stdin.setRawMode(false);
+            }
+            stdin.pause();
+            resolve(chunk === "\u0003" ? "q" : chunk);
+        };
+        stdin.on("data", onData);
+    });
+}

package/dist/filesystem-state.js

@@ -0,0 +1,99 @@
+import { readFile, readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+export async function scanIntegrationSkills(integration) {
+    if (!integration.activated) {
+        return [];
+    }
+    const activeEntries = await readSkillDirectories(integration.activeSkillsPath);
+    const disabledEntries = await readSkillDirectories(integration.disabledSkillsPath);
+    const skillIdentities = [...new Set([...activeEntries, ...disabledEntries])].sort();
+    return Promise.all(skillIdentities.map(async (skillIdentity) => {
+        const active = activeEntries.includes(skillIdentity);
+        const disabled = disabledEntries.includes(skillIdentity);
+        const activePath = active ? join(integration.activeSkillsPath, skillIdentity) : null;
+        const disabledPath = disabled
+            ? join(integration.disabledSkillsPath, skillIdentity)
+            : null;
+        const hasSkillFile = await hasRootSkillFile(activePath ?? disabledPath);
+        const state = !hasSkillFile
+            ? "suspicious"
+            : active && disabled
+                ? "conflict"
+                : active
+                    ? "enabled"
+                    : "disabled";
+        return {
+            skillIdentity,
+            integrationId: integration.id,
+            state,
+            provenance: await readProvenance(skillIdentity, activePath ?? disabledPath),
+            paths: {
+                active: activePath,
+                disabled: disabledPath,
+            },
+        };
+    }));
+}
+async function readSkillDirectories(path) {
+    let entries;
+    try {
+        entries = await readdir(path);
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT") {
+            return [];
+        }
+        throw error;
+    }
+    const directories = await Promise.all(entries.map(async (entry) => {
+        const entryPath = join(path, entry);
+        const entryStat = await stat(entryPath);
+        return entryStat.isDirectory() ? entry : null;
+    }));
+    return directories.filter((entry) => entry !== null).sort();
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}
+async function hasRootSkillFile(skillPath) {
+    if (skillPath === null) {
+        return false;
+    }
+    try {
+        const skillFile = await stat(join(skillPath, "SKILL.md"));
+        return skillFile.isFile();
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+}
+async function readProvenance(skillIdentity, skillPath) {
+    const unknown = {
+        source: null,
+        sourceType: null,
+        computedHash: null,
+    };
+    if (skillPath === null) {
+        return unknown;
+    }
+    let rawLockFile;
+    try {
+        rawLockFile = await readFile(join(skillPath, "skills-lock.json"), "utf8");
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT") {
+            return unknown;
+        }
+        throw error;
+    }
+    const parsed = JSON.parse(rawLockFile);
+    const entry = parsed.skills?.[skillIdentity];
+    return {
+        source: typeof entry?.source === "string" ? entry.source : null,
+        sourceType: typeof entry?.sourceType === "string" ? entry.sourceType : null,
+        computedHash: typeof entry?.computedHash === "string" ? entry.computedHash : null,
+    };
+}

package/dist/fs-utils.js

@@ -0,0 +1,43 @@
+import { cp, lstat, mkdir, readdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+export async function pathExists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+}
+export async function removePath(path) {
+    await rm(path, { recursive: true, force: true });
+}
+export async function copyDirectoryReplacing(source, destination) {
+    await assertNoSymlinks(source);
+    await removePath(destination);
+    await mkdir(destination, { recursive: true });
+    await rm(destination, { recursive: true, force: true });
+    await cp(source, destination, {
+        recursive: true,
+        preserveTimestamps: true,
+        errorOnExist: false,
+        force: true,
+    });
+}
+async function assertNoSymlinks(path) {
+    const entry = await lstat(path);
+    if (entry.isSymbolicLink()) {
+        throw new Error(`Resolved Skill Artifact contains symlink: ${path}`);
+    }
+    if (!entry.isDirectory()) {
+        return;
+    }
+    const children = await readdir(path);
+    await Promise.all(children.map((child) => assertNoSymlinks(join(path, child))));
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}

package/dist/install.js

@@ -0,0 +1,93 @@
+import { mkdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { copyDirectoryReplacing, pathExists, removePath } from "./fs-utils.js";
+export async function installSkill(options) {
+    const artifact = await options.resolver(options.skillSpec);
+    try {
+        await validateArtifact(artifact);
+        const results = [];
+        for (const integration of options.integrations) {
+            if (!integration.activated) {
+                results.push({
+                    integrationId: integration.id,
+                    skillIdentity: artifact.skillIdentity,
+                    status: "not-activated",
+                });
+                continue;
+            }
+            const activePath = join(integration.activeSkillsPath, artifact.skillIdentity);
+            const disabledPath = join(integration.disabledSkillsPath, artifact.skillIdentity);
+            const needsConfirmation = options.yes !== true &&
+                (await pathExists(activePath)) &&
+                !(await pathExists(join(activePath, "skills-lock.json")));
+            if (needsConfirmation && options.dryRun === true) {
+                results.push({
+                    integrationId: integration.id,
+                    skillIdentity: artifact.skillIdentity,
+                    status: "would-need-confirmation",
+                });
+                continue;
+            }
+            if (needsConfirmation && options.confirmOverwrite !== undefined) {
+                const confirmed = await options.confirmOverwrite(activePath);
+                if (!confirmed) {
+                    results.push({
+                        integrationId: integration.id,
+                        skillIdentity: artifact.skillIdentity,
+                        status: "needs-confirmation",
+                    });
+                    continue;
+                }
+            }
+            else if (needsConfirmation) {
+                results.push({
+                    integrationId: integration.id,
+                    skillIdentity: artifact.skillIdentity,
+                    status: "needs-confirmation",
+                });
+                continue;
+            }
+            if (options.dryRun === true) {
+                results.push({
+                    integrationId: integration.id,
+                    skillIdentity: artifact.skillIdentity,
+                    status: "would-install",
+                });
+                continue;
+            }
+            await mkdir(integration.activeSkillsPath, { recursive: true });
+            await copyDirectoryReplacing(artifact.artifactPath, activePath);
+            await removePath(disabledPath);
+            results.push({
+                integrationId: integration.id,
+                skillIdentity: artifact.skillIdentity,
+                status: "installed",
+            });
+        }
+        return results;
+    }
+    finally {
+        await artifact.cleanup?.();
+    }
+}
+async function validateArtifact(artifact) {
+    const artifactStat = await stat(artifact.artifactPath);
+    if (!artifactStat.isDirectory()) {
+        throw new Error(`Resolved Skill Artifact is not a directory: ${artifact.artifactPath}`);
+    }
+    try {
+        const skillFile = await stat(join(artifact.artifactPath, "SKILL.md"));
+        if (!skillFile.isFile()) {
+            throw new Error(`Resolved Skill Artifact is missing root SKILL.md: ${artifact.artifactPath}`);
+        }
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT") {
+            throw new Error(`Resolved Skill Artifact is missing root SKILL.md: ${artifact.artifactPath}`);
+        }
+        throw error;
+    }
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}

package/dist/integrations.js

@@ -0,0 +1,34 @@
+import { access } from "node:fs/promises";
+import { constants } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+const integrationOrder = ["codex", "claude"];
+function defaultRootFor(id, homeDir) {
+    const codingAssistantRoot = join(homeDir, "Library", "Developer", "Xcode", "CodingAssistant");
+    if (id === "codex") {
+        return join(codingAssistantRoot, "codex");
+    }
+    return join(codingAssistantRoot, "ClaudeAgentConfig");
+}
+async function pathExists(path) {
+    try {
+        await access(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function resolveIntegrationRoots(options = {}) {
+    const home = options.homeDir ?? homedir();
+    return Promise.all(integrationOrder.map(async (id) => {
+        const rootPath = options.roots?.[id] ?? defaultRootFor(id, home);
+        return {
+            id,
+            rootPath,
+            activated: await pathExists(rootPath),
+            activeSkillsPath: join(rootPath, "skills"),
+            disabledSkillsPath: join(rootPath, ".xcode-skills", "disabled"),
+        };
+    }));
+}

package/dist/lifecycle.js

@@ -0,0 +1,127 @@
+import { mkdir, rename, stat } from "node:fs/promises";
+import { join } from "node:path";
+export async function disableSkill(integration, skillIdentity, options = {}) {
+    if (!integration.activated) {
+        return {
+            integrationId: integration.id,
+            skillIdentity,
+            status: "not-activated",
+        };
+    }
+    const activePath = join(integration.activeSkillsPath, skillIdentity);
+    const disabledPath = join(integration.disabledSkillsPath, skillIdentity);
+    const activeExists = await pathExists(activePath);
+    const disabledExists = await pathExists(disabledPath);
+    if (activeExists && disabledExists) {
+        return {
+            integrationId: integration.id,
+            skillIdentity,
+            status: "conflict",
+        };
+    }
+    if (!activeExists && disabledExists) {
+        return {
+            integrationId: integration.id,
+            skillIdentity,
+            status: "already-disabled",
+        };
+    }
+    if (!activeExists) {
+        return {
+            integrationId: integration.id,
+            skillIdentity,
+            status: "not-installed",
+        };
+    }
+    if (!(await pathExists(join(activePath, "SKILL.md")))) {
+        return {
+            integrationId: integration.id,
+            skillIdentity,
+            status: "suspicious",
+        };
+    }
+    if (options.dryRun === true) {
+        return {
+            integrationId: integration.id,
+            skillIdentity,
+            status: "would-disable",
+        };
+    }
+    await mkdir(integration.disabledSkillsPath, { recursive: true });
+    await rename(activePath, disabledPath);
+    return {
+        integrationId: integration.id,
+        skillIdentity,
+        status: "disabled",
+    };
+}
+export async function enableSkill(integration, skillIdentity, options = {}) {
+    if (!integration.activated) {
+        return {
+            integrationId: integration.id,
+            skillIdentity,
+            status: "not-activated",
+        };
+    }
+    const activePath = join(integration.activeSkillsPath, skillIdentity);
+    const disabledPath = join(integration.disabledSkillsPath, skillIdentity);
+    const activeExists = await pathExists(activePath);
+    const disabledExists = await pathExists(disabledPath);
+    if (activeExists && disabledExists) {
+        return {
+            integrationId: integration.id,
+            skillIdentity,
+            status: "conflict",
+        };
+    }
+    if (activeExists) {
+        return {
+            integrationId: integration.id,
+            skillIdentity,
+            status: "already-enabled",
+        };
+    }
+    if (!disabledExists) {
+        return {
+            integrationId: integration.id,
+            skillIdentity,
+            status: "not-installed",
+        };
+    }
+    if (!(await pathExists(join(disabledPath, "SKILL.md")))) {
+        return {
+            integrationId: integration.id,
+            skillIdentity,
+            status: "suspicious",
+        };
+    }
+    if (options.dryRun === true) {
+        return {
+            integrationId: integration.id,
+            skillIdentity,
+            status: "would-enable",
+        };
+    }
+    await mkdir(integration.activeSkillsPath, { recursive: true });
+    await rename(disabledPath, activePath);
+    return {
+        integrationId: integration.id,
+        skillIdentity,
+        status: "enabled",
+    };
+}
+async function pathExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}

package/dist/list.js

@@ -0,0 +1,43 @@
+import { scanIntegrationSkills } from "./filesystem-state.js";
+export async function listSkillInstallations(integrations, options = {}) {
+    const filteredIntegrations = integrations.filter((integration) => {
+        if (options.target === undefined || options.target === "both") {
+            return true;
+        }
+        return integration.id === options.target;
+    });
+    const activatedIntegrations = filteredIntegrations.filter((integration) => integration.activated);
+    const entries = await Promise.all(activatedIntegrations.map((integration) => scanIntegrationSkills(integration)));
+    return entries.flat().sort((left, right) => {
+        const integrationCompare = left.integrationId.localeCompare(right.integrationId);
+        return integrationCompare === 0
+            ? left.skillIdentity.localeCompare(right.skillIdentity)
+            : integrationCompare;
+    });
+}
+export function formatListJson(entries) {
+    return JSON.stringify(entries, null, 2);
+}
+export function formatListHuman(entries) {
+    if (entries.length === 0) {
+        return "No Xcode Skill Installations found.";
+    }
+    const grouped = new Map();
+    for (const entry of entries) {
+        grouped.set(entry.integrationId, [...(grouped.get(entry.integrationId) ?? []), entry]);
+    }
+    const sections = [...grouped.entries()].map(([integrationId, integrationEntries]) => {
+        const title = integrationId === "codex" ? "Codex" : "Claude";
+        const rows = integrationEntries.map((entry) => {
+            const source = entry.provenance.source === null
+                ? "unknown"
+                : `${entry.provenance.sourceType ?? "source"}:${entry.provenance.source}`;
+            const hash = entry.provenance.computedHash === null
+                ? ""
+                : `  ${entry.provenance.computedHash.slice(0, 8)}`;
+            return `  ${entry.skillIdentity}  ${entry.state}  ${source}${hash}`;
+        });
+        return [title, ...rows].join("\n");
+    });
+    return sections.join("\n\n");
+}

package/dist/manage.js

@@ -0,0 +1,95 @@
+import { scanIntegrationSkills } from "./filesystem-state.js";
+import { disableSkill, enableSkill } from "./lifecycle.js";
+export async function buildManageView(integrations) {
+    return Promise.all(integrations.map(async (integration) => ({
+        integrationId: integration.id,
+        activated: integration.activated,
+        skills: integration.activated ? await scanIntegrationSkills(integration) : [],
+    })));
+}
+export function formatManageView(tabs, options = {}) {
+    return tabs
+        .map((tab, tabIndex) => {
+        const title = tab.integrationId === "codex" ? "Codex" : "Claude";
+        const formattedTitle = options.activeTabIndex === tabIndex ? `[${title}]` : title;
+        if (!tab.activated) {
+            return `${formattedTitle}\n  not activated in Xcode`;
+        }
+        if (tab.skills.length === 0) {
+            return `${formattedTitle}\n  no skills`;
+        }
+        const selectedSkillIndex = options.selectedSkillIndexes?.[tabIndex] ?? -1;
+        return [
+            formattedTitle,
+            ...tab.skills.map((skill, skillIndex) => {
+                const marker = selectedSkillIndex === skillIndex ? ">" : " ";
+                return `${marker} ${skill.skillIdentity}  ${skill.state}`;
+            }),
+        ].join("\n");
+    })
+        .join("\n\n");
+}
+export async function runManageSession(integrations, options) {
+    let activeTabIndex = 0;
+    const selectedSkillIndexes = integrations.map(() => 0);
+    let latestView = await buildManageView(integrations);
+    options.render?.(formatManageView(latestView, { activeTabIndex, selectedSkillIndexes }));
+    while (true) {
+        const key = await options.readKey();
+        if (key === "q") {
+            return formatManageView(latestView);
+        }
+        if (key === "Tab" || key === "\t") {
+            activeTabIndex = (activeTabIndex + 1) % Math.max(latestView.length, 1);
+            options.render?.(formatManageView(latestView, { activeTabIndex, selectedSkillIndexes }));
+            continue;
+        }
+        if (key === "ArrowDown" || key === "\u001B[B" || key === "j") {
+            const skillCount = latestView[activeTabIndex]?.skills.length ?? 0;
+            if (skillCount > 0) {
+                selectedSkillIndexes[activeTabIndex] =
+                    ((selectedSkillIndexes[activeTabIndex] ?? 0) + 1) % skillCount;
+                options.render?.(formatManageView(latestView, { activeTabIndex, selectedSkillIndexes }));
+            }
+            continue;
+        }
+        if (key === "ArrowUp" || key === "\u001B[A" || key === "k") {
+            const skillCount = latestView[activeTabIndex]?.skills.length ?? 0;
+            if (skillCount > 0) {
+                selectedSkillIndexes[activeTabIndex] =
+                    ((selectedSkillIndexes[activeTabIndex] ?? 0) - 1 + skillCount) % skillCount;
+                options.render?.(formatManageView(latestView, { activeTabIndex, selectedSkillIndexes }));
+            }
+            continue;
+        }
+        if (key === " " || key === "Enter" || key === "\r") {
+            const tab = latestView[activeTabIndex];
+            const selectedSkillIndex = selectedSkillIndexes[activeTabIndex] ?? 0;
+            const selectedSkill = tab?.skills[selectedSkillIndex];
+            const integration = integrations[activeTabIndex];
+            if (tab?.activated === true &&
+                integration !== undefined &&
+                selectedSkill !== undefined &&
+                (selectedSkill.state === "enabled" || selectedSkill.state === "disabled")) {
+                await toggleManagedSkill(integration, selectedSkill.skillIdentity);
+                latestView = await buildManageView(integrations);
+                selectedSkillIndexes[activeTabIndex] = Math.min(selectedSkillIndex, Math.max((latestView[activeTabIndex]?.skills.length ?? 1) - 1, 0));
+                options.render?.(formatManageView(latestView, { activeTabIndex, selectedSkillIndexes }));
+            }
+        }
+    }
+}
+export async function toggleManagedSkill(integration, skillIdentity) {
+    const [current] = (await scanIntegrationSkills(integration)).filter((skill) => skill.skillIdentity === skillIdentity);
+    if (current?.state === "enabled") {
+        return disableSkill(integration, skillIdentity);
+    }
+    if (current?.state === "disabled") {
+        return enableSkill(integration, skillIdentity);
+    }
+    return {
+        integrationId: integration.id,
+        skillIdentity,
+        status: current?.state ?? "not-installed",
+    };
+}

package/dist/resolver.js

@@ -0,0 +1,90 @@
+import { cp, mkdtemp, readdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+export async function resolveSkillArtifactWithCli(skillSpec, options = {}) {
+    const workspace = await mkdtemp(join(options.tempRoot ?? tmpdir(), "xcode-skills-"));
+    const removeWorkspace = options.removeWorkspace ??
+        ((path) => rm(path, { recursive: true, force: true }));
+    const runCommand = options.runCommand ?? spawnCommand;
+    const skillsCliPath = options.skillsCliPath ?? defaultSkillsCliPath();
+    try {
+        const invocation = {
+            executable: process.execPath,
+            args: [skillsCliPath, "add", skillSpec, "--copy", "--yes"],
+            cwd: workspace,
+        };
+        options.onVerbose?.(`workspace: ${workspace}`);
+        options.onVerbose?.(`command: ${invocation.executable} ${invocation.args.join(" ")}`);
+        const result = await runCommand(invocation);
+        if (result.stdout.length > 0) {
+            options.onVerbose?.(`stdout: ${result.stdout.trim()}`);
+        }
+        if (result.stderr.length > 0) {
+            options.onVerbose?.(`stderr: ${result.stderr.trim()}`);
+        }
+        if (result.exitCode !== 0) {
+            throw new Error(result.stderr || result.stdout || `skills add failed with exit code ${result.exitCode}`);
+        }
+        const skillRoot = join(workspace, ".agents", "skills");
+        const skillIdentities = (await readdir(skillRoot, { withFileTypes: true }))
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort();
+        if (skillIdentities.length !== 1) {
+            throw new Error(`Expected one resolved Skill Folder, found ${skillIdentities.length}`);
+        }
+        const skillIdentity = skillIdentities[0];
+        const artifactPath = join(skillRoot, skillIdentity);
+        await copyLockFileIfPresent(workspace, artifactPath);
+        return {
+            skillIdentity,
+            artifactPath,
+            cleanup: () => removeWorkspace(workspace),
+        };
+    }
+    catch (error) {
+        await removeWorkspace(workspace);
+        throw error;
+    }
+}
+async function copyLockFileIfPresent(workspace, artifactPath) {
+    try {
+        await cp(join(workspace, "skills-lock.json"), join(artifactPath, "skills-lock.json"));
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT") {
+            return;
+        }
+        throw error;
+    }
+}
+function defaultSkillsCliPath() {
+    return join(dirname(fileURLToPath(import.meta.url)), "..", "node_modules", "skills", "bin", "cli.mjs");
+}
+function spawnCommand(command) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command.executable, command.args, {
+            cwd: command.cwd,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        child.on("error", reject);
+        child.on("close", (exitCode) => {
+            resolve({ exitCode: exitCode ?? 1, stdout, stderr });
+        });
+    });
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}

package/dist/targets.js

@@ -0,0 +1,22 @@
+export async function selectTargetIntegrations(_options) {
+    const target = _options.target ??
+        (await (_options.promptForTarget ?? missingPromptForTarget)());
+    if (target === "both") {
+        return orderTargets(_options.integrations);
+    }
+    const integration = _options.integrations.find((item) => item.id === target);
+    if (integration === undefined) {
+        throw new Error(`Unknown Target Agent Integration: ${target}`);
+    }
+    if (!integration.activated) {
+        throw new Error(`${target} Agent Integration is not activated in Xcode`);
+    }
+    return [integration];
+}
+async function missingPromptForTarget() {
+    throw new Error("Target Agent Integration is required");
+}
+function orderTargets(integrations) {
+    const order = { codex: 0, claude: 1 };
+    return [...integrations].sort((left, right) => order[left.id] - order[right.id]);
+}

package/dist/uninstall.js

@@ -0,0 +1,67 @@
+import { join } from "node:path";
+import { pathExists, removePath } from "./fs-utils.js";
+export async function uninstallSkill(integration, skillIdentity, options = {}) {
+    if (!integration.activated) {
+        return {
+            integrationId: integration.id,
+            skillIdentity,
+            status: "not-activated",
+            removedPaths: [],
+        };
+    }
+    const activePath = join(integration.activeSkillsPath, skillIdentity);
+    const disabledPath = join(integration.disabledSkillsPath, skillIdentity);
+    const paths = [
+        ...(await pathExists(activePath) ? [activePath] : []),
+        ...(await pathExists(disabledPath) ? [disabledPath] : []),
+    ];
+    if (paths.length === 0) {
+        return {
+            integrationId: integration.id,
+            skillIdentity,
+            status: "not-installed",
+            removedPaths: [],
+        };
+    }
+    const needsConfirmation = await requiresConfirmation(paths);
+    if (options.dryRun === true && needsConfirmation) {
+        return {
+            integrationId: integration.id,
+            skillIdentity,
+            status: "would-need-confirmation",
+            removedPaths: paths,
+        };
+    }
+    if (options.dryRun === true) {
+        return {
+            integrationId: integration.id,
+            skillIdentity,
+            status: "would-uninstall",
+            removedPaths: paths,
+        };
+    }
+    if (options.yes !== true && needsConfirmation) {
+        return {
+            integrationId: integration.id,
+            skillIdentity,
+            status: "needs-confirmation",
+            removedPaths: paths,
+        };
+    }
+    await Promise.all(paths.map((path) => removePath(path)));
+    return {
+        integrationId: integration.id,
+        skillIdentity,
+        status: "uninstalled",
+        removedPaths: paths,
+    };
+}
+async function requiresConfirmation(paths) {
+    for (const path of paths) {
+        if (!(await pathExists(join(path, "skills-lock.json"))) ||
+            !(await pathExists(join(path, "SKILL.md")))) {
+            return true;
+        }
+    }
+    return false;
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "xcode-skills",
+  "version": "0.1.0",
+  "description": "Manage Agent Skills for Xcode's Codex and Claude Coding Assistant integrations.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "xcode-skills": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm test && npm run typecheck && npm run build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "skills": "^1.5.9"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^4.0.0"
+  }
+}