diff --git a/src/main/ipc/localHandlers.ts b/src/main/ipc/localHandlers.ts
index 83ccb29e..491a1131 100644
--- a/src/main/ipc/localHandlers.ts
+++ b/src/main/ipc/localHandlers.ts
@@ -1,5 +1,5 @@
 import { homedir } from "node:os";
-import { dirname } from "node:path";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import { clipboard, dialog, nativeImage, shell, type BrowserWindow } from "electron";
 import type { BrowserPanelManager } from "../browser";
 import { openMicrophoneSettings } from "../browser/permissions";
@@ -52,8 +52,10 @@ import {
   type WindowChromeResult,
 } from "@/shared/ipc";
 import { supportsNativeWindowMaterial, syncNativeThemeForMaterial } from "../window/windowMaterial";
-import type { AgentInstanceConfig } from "@/shared/contracts";
+import type { AgentInstanceConfig, ProjectLocation, RevealSkillPayload } from "@/shared/contracts";
 import type { LightcodePaths } from "@/shared/lightcodePaths";
+import { SKILL_ROOTS } from "@/shared/skills";
+import { getProjectFsPath } from "@/shared/wsl";
 import { UsageLoginManager } from "../usageLogin/UsageLoginManager";
 
 interface CreateLocalIpcHandlersOptions {
@@ -109,6 +111,36 @@ function assertSafeExternalUrl(rawUrl: string): string {
   return parsed.toString();
 }
 
+function assertRevealSkillPath(payload: RevealSkillPayload): string {
+  if (!isAbsolute(payload.absolutePath)) {
+    throw new Error("Skill path must be absolute.");
+  }
+  const absolutePath = resolve(payload.absolutePath);
+  const parentPath = dirname(absolutePath);
+  const allowed = skillScopeDirs(payload.projectLocation);
+  if (
+    !allowed.some(
+      (scopeDir) => sameFsPath(absolutePath, scopeDir) || sameFsPath(parentPath, scopeDir),
+    )
+  ) {
+    throw new Error("Refusing to reveal a path outside a skills directory.");
+  }
+  return absolutePath;
+}
+
+function skillScopeDirs(projectLocation?: ProjectLocation): string[] {
+  const bases = [homedir()];
+  if (projectLocation) bases.push(getProjectFsPath(projectLocation));
+  return bases.flatMap((base) =>
+    SKILL_ROOTS.map((root) => resolve(join(base, ...root.dirName.split("/")))),
+  );
+}
+
+function sameFsPath(left: string, right: string): boolean {
+  if (process.platform === "win32") return left.toLowerCase() === right.toLowerCase();
+  return left === right;
+}
+
 export function createLocalIpcHandlers(
   options: CreateLocalIpcHandlersOptions,
 ): MainLocalIpcHandlerMap {
@@ -189,6 +221,9 @@ export function createLocalIpcHandlers(
     revealProjectEntry: async (payload) => {
       shell.showItemInFolder(resolveProjectFsPath(payload));
     },
+    revealSkill: async (payload) => {
+      shell.showItemInFolder(assertRevealSkillPath(payload));
+    },
     getSharedSettings: () => readSharedSettingsFile(options.requireLightcodePaths().settingsPath),
     setSharedSettings: (settings) => {
       const settingsPath = options.requireLightcodePaths().settingsPath;
diff --git a/src/renderer/components/skills/SkillEditorModal.tsx b/src/renderer/components/skills/SkillEditorModal.tsx
new file mode 100644
index 00000000..788f2a54
--- /dev/null
+++ b/src/renderer/components/skills/SkillEditorModal.tsx
@@ -0,0 +1,239 @@
+import { useEffect, useRef, useState } from "react";
+import { Button, Label, Modal, toast } from "@heroui/react";
+import type { ProjectLocation, SkillSummary } from "@/shared/contracts";
+import { slugifySkillName } from "@/shared/skills";
+import { readBridge } from "@/renderer/bridge";
+import { Input, PixelLoader, TextArea } from "@/renderer/components/common";
+
+export type SkillEditorTarget =
+  | { mode: "create"; scopeDir: string; scopeLabel: string }
+  | { mode: "edit"; skill: SkillSummary };
+
+function errorMessage(error: unknown, fallback: string): string {
+  return error instanceof Error ? error.message : fallback;
+}
+
+export function SkillEditorModal(props: {
+  target: SkillEditorTarget | null;
+  projectLocation?: ProjectLocation;
+  onClose: () => void;
+  onSaved: () => void;
+}) {
+  const { target, projectLocation, onClose, onSaved } = props;
+  return (
+    <Modal.Backdrop isOpen={target !== null} onOpenChange={(next) => !next && onClose()}>
+      <Modal.Container>
+        <Modal.Dialog className="sm:max-w-[680px]">
+          {target ? (
+            <SkillEditorForm
+              target={target}
+              {...(projectLocation ? { projectLocation } : {})}
+              onClose={onClose}
+              onSaved={onSaved}
+            />
+          ) : null}
+        </Modal.Dialog>
+      </Modal.Container>
+    </Modal.Backdrop>
+  );
+}
+
+function SkillEditorForm(props: {
+  target: SkillEditorTarget;
+  projectLocation?: ProjectLocation;
+  onClose: () => void;
+  onSaved: () => void;
+}) {
+  const { target, projectLocation, onClose, onSaved } = props;
+  const isCreate = target.mode === "create";
+  const operationContext = projectLocation ? { projectLocation } : {};
+
+  const [name, setName] = useState(isCreate ? "" : target.skill.name);
+  const [folderName, setFolderName] = useState(isCreate ? "" : target.skill.folderName);
+  const folderTouched = useRef(!isCreate);
+  const [description, setDescription] = useState(isCreate ? "" : target.skill.description);
+  const [content, setContent] = useState("");
+  const [loading, setLoading] = useState(!isCreate);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  // Edit mode: load the raw SKILL.md so the user can edit it directly.
+  useEffect(() => {
+    if (target.mode !== "edit") return;
+    let active = true;
+    setLoading(true);
+    void readBridge()
+      .readSkill({
+        ...(projectLocation ? { projectLocation } : {}),
+        absolutePath: target.skill.absolutePath,
+      })
+      .then((detail) => {
+        if (!active) return;
+        setContent(detail.content);
+        setName(detail.name);
+        setDescription(detail.description);
+        setLoading(false);
+      })
+      .catch((err) => {
+        if (!active) return;
+        setError(errorMessage(err, "Couldn't read the skill."));
+        setLoading(false);
+      });
+    return () => {
+      active = false;
+    };
+  }, [target, projectLocation]);
+
+  function changeName(value: string) {
+    setName(value);
+    if (isCreate && !folderTouched.current) setFolderName(slugifySkillName(value));
+  }
+
+  const invalid = !folderName.trim() || (isCreate && !name.trim());
+
+  async function handleSubmit() {
+    setBusy(true);
+    setError(null);
+    try {
+      if (target.mode === "create") {
+        await readBridge().createSkill({
+          ...operationContext,
+          scopeDir: target.scopeDir,
+          folderName: folderName.trim(),
+          name: name.trim(),
+          description: description.trim(),
+          ...(content.trim() ? { body: content } : {}),
+        });
+        toast.success(`Created skill “${name.trim()}”.`);
+      } else {
+        // Rename the folder first (if changed) so the write targets the new path.
+        let absolutePath = target.skill.absolutePath;
+        if (folderName.trim() && folderName.trim() !== target.skill.folderName) {
+          const renamed = await readBridge().renameSkill({
+            ...operationContext,
+            absolutePath,
+            nextFolderName: folderName.trim(),
+          });
+          absolutePath = renamed.absolutePath;
+        }
+        await readBridge().writeSkill({ ...operationContext, absolutePath, content });
+        // Use the folder name, not the load-time frontmatter name — the user may
+        // have just edited `name:` in the raw content.
+        toast.success(`Saved “${folderName.trim() || target.skill.folderName}”.`);
+      }
+      onSaved();
+      onClose();
+    } catch (err) {
+      setError(errorMessage(err, "Couldn't save the skill."));
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <>
+      <Modal.CloseTrigger />
+      <Modal.Header>
+        <Modal.Heading>
+          {isCreate ? "New skill" : `Edit ${target.mode === "edit" ? target.skill.name : ""}`}
+        </Modal.Heading>
+        <p className="mt-1 text-xs text-muted">
+          {isCreate
+            ? `Creates a SKILL.md folder in ${target.scopeLabel}.`
+            : "Edit the raw SKILL.md. Frontmatter (name/description) lives at the top."}
+        </p>
+      </Modal.Header>
+      <Modal.Body className="flex flex-col gap-3 p-4">
+        {loading ? (
+          <div className="flex items-center justify-center py-10">
+            <PixelLoader size="md" className="text-muted" />
+          </div>
+        ) : isCreate ? (
+          <>
+            <div className="flex gap-3">
+              <div className="flex flex-1 flex-col gap-1.5">
+                <Label className="text-xs font-medium text-muted">Name</Label>
+                <Input
+                  aria-label="Skill name"
+                  placeholder="My skill"
+                  value={name}
+                  onChange={(e) => changeName(e.target.value)}
+                />
+              </div>
+              <div className="flex flex-1 flex-col gap-1.5">
+                <Label className="text-xs font-medium text-muted">Folder</Label>
+                <Input
+                  aria-label="Folder name"
+                  placeholder="my-skill"
+                  value={folderName}
+                  onChange={(e) => {
+                    folderTouched.current = true;
+                    setFolderName(e.target.value);
+                  }}
+                />
+              </div>
+            </div>
+            <div className="flex flex-col gap-1.5">
+              <Label className="text-xs font-medium text-muted">Description</Label>
+              <Input
+                aria-label="Description"
+                placeholder="Use when… (helps the agent decide when to load this skill)"
+                value={description}
+                onChange={(e) => setDescription(e.target.value)}
+              />
+            </div>
+            <div className="flex flex-col gap-1.5">
+              <Label className="text-xs font-medium text-muted">Instructions (markdown)</Label>
+              <TextArea
+                aria-label="Skill body"
+                placeholder={"# My skill\n\nWhat to do, step by step…"}
+                value={content}
+                onChange={(e) => setContent(e.target.value)}
+                className="min-h-[220px] font-mono text-xs"
+              />
+            </div>
+          </>
+        ) : (
+          <>
+            <div className="flex flex-col gap-1.5">
+              <Label className="text-xs font-medium text-muted">Folder</Label>
+              <Input
+                aria-label="Folder name"
+                placeholder="my-skill"
+                value={folderName}
+                onChange={(e) => setFolderName(e.target.value)}
+              />
+              <p className="text-[11px] text-muted/70">
+                Renaming changes the folder on disk. The name/description shown in lists comes from
+                the SKILL.md frontmatter below.
+              </p>
+            </div>
+            <div className="flex flex-col gap-1.5">
+              <Label className="text-xs font-medium text-muted">SKILL.md</Label>
+              <TextArea
+                aria-label="SKILL.md content"
+                value={content}
+                onChange={(e) => setContent(e.target.value)}
+                className="min-h-[320px] font-mono text-xs"
+              />
+            </div>
+          </>
+        )}
+        {error ? <p className="text-xs text-danger">{error}</p> : null}
+      </Modal.Body>
+      <Modal.Footer>
+        <Button slot="close" variant="ghost" className="text-muted">
+          Cancel
+        </Button>
+        <Button
+          variant="tertiary"
+          isDisabled={loading || busy || invalid}
+          isPending={busy}
+          onPress={() => void handleSubmit()}
+        >
+          {isCreate ? "Create skill" : "Save"}
+        </Button>
+      </Modal.Footer>
+    </>
+  );
+}
diff --git a/src/renderer/components/skills/SkillMarketplaceModal.tsx b/src/renderer/components/skills/SkillMarketplaceModal.tsx
new file mode 100644
index 00000000..21f294e1
--- /dev/null
+++ b/src/renderer/components/skills/SkillMarketplaceModal.tsx
@@ -0,0 +1,248 @@
+import { useState } from "react";
+import { Button, Label, Modal, toast } from "@heroui/react";
+import { Check, Download, ExternalLink, GitBranch, Star } from "lucide-react";
+import type { ProjectLocation } from "@/shared/contracts";
+import { SKILL_MARKETPLACE } from "@/shared/skills";
+import { readBridge } from "@/renderer/bridge";
+import { Input, Select } from "@/renderer/components/common";
+
+export interface MarketplaceTargetScope {
+  id: string;
+  label: string;
+  absolutePath: string;
+  /** Folder names already present in this scope (used to avoid name collisions). */
+  installedFolders: string[];
+  /** `metadata.source` ids already installed here (to mark catalog items installed). */
+  installedSources: string[];
+}
+
+/** Append a numeric suffix until the folder name is unique within the scope. */
+function uniqueFolderName(desired: string, taken: ReadonlySet<string>): string {
+  if (!taken.has(desired)) return desired;
+  for (let i = 2; i < 1000; i++) {
+    const candidate = `${desired}-${i}`;
+    if (!taken.has(candidate)) return candidate;
+  }
+  return `${desired}-${Date.now()}`;
+}
+
+function errorMessage(error: unknown, fallback: string): string {
+  return error instanceof Error ? error.message : fallback;
+}
+
+export function SkillMarketplaceModal(props: {
+  open: boolean;
+  onClose: () => void;
+  onInstalled: () => void;
+  projectLocation?: ProjectLocation;
+  targetScopes: MarketplaceTargetScope[];
+}) {
+  const { open, onClose, onInstalled, projectLocation, targetScopes } = props;
+  return (
+    <Modal.Backdrop isOpen={open} onOpenChange={(next) => !next && onClose()}>
+      <Modal.Container>
+        <Modal.Dialog className="sm:max-w-[720px]">
+          {open ? (
+            <MarketplaceContent
+              targetScopes={targetScopes}
+              {...(projectLocation ? { projectLocation } : {})}
+              onClose={onClose}
+              onInstalled={onInstalled}
+            />
+          ) : null}
+        </Modal.Dialog>
+      </Modal.Container>
+    </Modal.Backdrop>
+  );
+}
+
+function MarketplaceContent(props: {
+  targetScopes: MarketplaceTargetScope[];
+  projectLocation?: ProjectLocation;
+  onClose: () => void;
+  onInstalled: () => void;
+}) {
+  const { targetScopes, projectLocation, onInstalled } = props;
+  const operationContext = projectLocation ? { projectLocation } : {};
+  const [targetId, setTargetId] = useState(targetScopes[0]?.id ?? "");
+  const [installing, setInstalling] = useState<string | null>(null);
+  const [gitUrl, setGitUrl] = useState("");
+  const [gitPath, setGitPath] = useState("");
+
+  const target = targetScopes.find((scope) => scope.id === targetId) ?? targetScopes[0] ?? null;
+  const sorted = [...SKILL_MARKETPLACE].sort((a, b) => b.popularity - a.popularity);
+  // "Installed" is decided by provenance (metadata.source), not folder name, so
+  // an unrelated folder that happens to share a name isn't mislabeled.
+  const installedSources = new Set(target?.installedSources ?? []);
+  const installedFolders = new Set(target?.installedFolders ?? []);
+
+  async function installCatalog(catalogId: string, defaultFolder: string) {
+    if (!target) return;
+    setInstalling(catalogId);
+    try {
+      // Pick a non-colliding folder name so re-installing never dead-ends on
+      // an "already exists" error.
+      const folderName = uniqueFolderName(defaultFolder, installedFolders);
+      const result = await readBridge().installMarketplaceSkill({
+        ...operationContext,
+        catalogId,
+        targetScopeDir: target.absolutePath,
+        folderName,
+      });
+      toast.success(`Installed “${result.folderName}” into ${target.label}.`);
+      onInstalled();
+    } catch (err) {
+      toast.danger(errorMessage(err, "Couldn't install the skill."));
+    } finally {
+      setInstalling(null);
+    }
+  }
+
+  async function installGit() {
+    if (!target || !gitUrl.trim()) return;
+    setInstalling("__git__");
+    try {
+      const result = await readBridge().installSkillFromGit({
+        ...operationContext,
+        repoUrl: gitUrl.trim(),
+        ...(gitPath.trim() ? { sourcePath: gitPath.trim() } : {}),
+        targetScopeDir: target.absolutePath,
+      });
+      toast.success(`Installed “${result.folderName}” into ${target.label}.`);
+      setGitUrl("");
+      setGitPath("");
+      onInstalled();
+    } catch (err) {
+      toast.danger(errorMessage(err, "Couldn't install from git."));
+    } finally {
+      setInstalling(null);
+    }
+  }
+
+  return (
+    <>
+      <Modal.CloseTrigger />
+      <Modal.Header>
+        <Modal.Heading>Skill marketplace</Modal.Heading>
+        <p className="mt-1 text-xs text-muted">
+          Install a popular skill, or pull any skill folder from a git repository.
+        </p>
+      </Modal.Header>
+      <Modal.Body className="flex flex-col gap-4 p-4">
+        <div className="flex items-center gap-2">
+          <Label className="text-xs font-medium text-muted">Install into</Label>
+          {targetScopes.length > 0 ? (
+            <Select
+              aria-label="Install destination"
+              className="min-w-[220px]"
+              options={targetScopes.map((scope) => ({ id: scope.id, label: scope.label }))}
+              value={targetId}
+              onChange={setTargetId}
+            />
+          ) : (
+            <span className="text-xs text-danger">No writable scope available.</span>
+          )}
+        </div>
+
+        <div className="-mr-1 flex max-h-[42vh] flex-col gap-2 overflow-y-auto pr-1">
+          {sorted.map((entry) => {
+            const isInstalled = installedSources.has(entry.id);
+            return (
+              <div
+                key={entry.id}
+                className="flex items-start gap-3 rounded-lg border border-default-200 p-3"
+              >
+                <div className="min-w-0 flex-1">
+                  <div className="flex items-center gap-2">
+                    <span className="truncate text-sm font-medium text-foreground">
+                      {entry.name}
+                    </span>
+                    <span className="flex items-center gap-0.5 text-[10px] text-muted/70">
+                      <Star className="size-3" />
+                      {entry.popularity}
+                    </span>
+                    {entry.homepage ? (
+                      <button
+                        type="button"
+                        className="flex items-center gap-0.5 text-[10px] text-accent underline-offset-2 hover:underline"
+                        onClick={() => void readBridge().openExternal(entry.homepage!)}
+                      >
+                        source <ExternalLink className="size-2.5" />
+                      </button>
+                    ) : null}
+                  </div>
+                  <p className="mt-0.5 line-clamp-2 text-xs text-muted">{entry.description}</p>
+                  <div className="mt-1 flex flex-wrap gap-1">
+                    {entry.tags.map((tag) => (
+                      <span
+                        key={tag}
+                        className="rounded bg-content2 px-1.5 py-0.5 text-[10px] text-muted"
+                      >
+                        {tag}
+                      </span>
+                    ))}
+                  </div>
+                </div>
+                {isInstalled ? (
+                  <span className="flex shrink-0 items-center gap-1 text-[11px] font-medium text-success">
+                    <Check className="size-3.5" />
+                    Installed
+                  </span>
+                ) : (
+                  <Button
+                    size="sm"
+                    variant="tertiary"
+                    className="shrink-0 gap-1.5"
+                    isDisabled={!target || installing !== null}
+                    isPending={installing === entry.id}
+                    onPress={() => void installCatalog(entry.id, entry.folderName)}
+                  >
+                    <Download className="size-3.5" />
+                    Install
+                  </Button>
+                )}
+              </div>
+            );
+          })}
+        </div>
+
+        <div className="flex flex-col gap-2 rounded-lg border border-dashed border-default-300 p-3">
+          <div className="flex items-center gap-1.5 text-xs font-medium text-foreground">
+            <GitBranch className="size-3.5" />
+            Install from git
+          </div>
+          <Input
+            aria-label="Repository URL"
+            placeholder="https://github.com/owner/repo"
+            value={gitUrl}
+            onChange={(e) => setGitUrl(e.target.value)}
+          />
+          <Input
+            aria-label="Path within repo (optional)"
+            placeholder="path/to/skill (optional — defaults to repo root)"
+            value={gitPath}
+            onChange={(e) => setGitPath(e.target.value)}
+          />
+          <div className="flex justify-end">
+            <Button
+              size="sm"
+              variant="tertiary"
+              className="gap-1.5"
+              isDisabled={!target || !gitUrl.trim() || installing !== null}
+              isPending={installing === "__git__"}
+              onPress={() => void installGit()}
+            >
+              <Download className="size-3.5" />
+              Clone & install
+            </Button>
+          </div>
+        </div>
+      </Modal.Body>
+      <Modal.Footer>
+        <Button slot="close" variant="ghost" className="text-muted">
+          Done
+        </Button>
+      </Modal.Footer>
+    </>
+  );
+}
diff --git a/src/renderer/components/skills/SkillOptimizerModal.tsx b/src/renderer/components/skills/SkillOptimizerModal.tsx
new file mode 100644
index 00000000..2d81eeb8
--- /dev/null
+++ b/src/renderer/components/skills/SkillOptimizerModal.tsx
@@ -0,0 +1,162 @@
+import { useEffect, useState } from "react";
+import { Button, Modal, toast } from "@heroui/react";
+import { ArrowRight, CheckCircle2, Wand2 } from "lucide-react";
+import type {
+  OptimizeSkillsResult,
+  ProjectLocation,
+  SkillScopeLevel,
+  SkillSyncOp,
+} from "@/shared/contracts";
+import { readBridge } from "@/renderer/bridge";
+import { PixelLoader } from "@/renderer/components/common";
+
+function errorMessage(error: unknown, fallback: string): string {
+  return error instanceof Error ? error.message : fallback;
+}
+
+export function SkillOptimizerModal(props: {
+  open: boolean;
+  level: SkillScopeLevel;
+  projectLocation?: ProjectLocation;
+  scopeLabel: (scopeId: string) => string;
+  onClose: () => void;
+  onApplied: () => void;
+}) {
+  const { open, level, projectLocation, scopeLabel, onClose, onApplied } = props;
+  const [plan, setPlan] = useState<SkillSyncOp[] | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [applying, setApplying] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!open) return;
+    let active = true;
+    setLoading(true);
+    setError(null);
+    setPlan(null);
+    void readBridge()
+      .optimizeSkills({
+        level,
+        apply: false,
+        ...(projectLocation ? { projectLocation } : {}),
+      })
+      .then((result: OptimizeSkillsResult) => {
+        if (active) {
+          setPlan(result.ops);
+          setLoading(false);
+        }
+      })
+      .catch((err) => {
+        if (active) {
+          setError(errorMessage(err, "Couldn't compute the sync plan."));
+          setLoading(false);
+        }
+      });
+    return () => {
+      active = false;
+    };
+  }, [open, level, projectLocation]);
+
+  async function apply() {
+    setApplying(true);
+    setError(null);
+    try {
+      const result = await readBridge().optimizeSkills({
+        level,
+        apply: true,
+        ...(projectLocation ? { projectLocation } : {}),
+      });
+      toast.success(
+        result.ops.length === 0
+          ? "Skills already in sync."
+          : `Synced ${result.ops.length} skill${result.ops.length === 1 ? "" : "s"} across providers.`,
+      );
+      onApplied();
+      onClose();
+    } catch (err) {
+      setError(errorMessage(err, "Couldn't sync skills."));
+    } finally {
+      setApplying(false);
+    }
+  }
+
+  return (
+    <Modal.Backdrop isOpen={open} onOpenChange={(next) => !next && onClose()}>
+      <Modal.Container>
+        <Modal.Dialog className="sm:max-w-[640px]">
+          <Modal.CloseTrigger />
+          <Modal.Header>
+            <Modal.Heading>Sync skills across providers</Modal.Heading>
+            <p className="mt-1 text-xs text-muted">
+              Different agents read different folders — some use <code>.agents/skills</code>, others
+              read their own. This copies each {level} skill into every provider folder that&apos;s
+              missing it, and refreshes copies that have drifted out of date (the newest edit wins),
+              so any agent sees the same skills.
+            </p>
+          </Modal.Header>
+          <Modal.Body className="flex flex-col gap-2 p-4">
+            {loading ? (
+              <div className="flex items-center justify-center py-10">
+                <PixelLoader size="md" className="text-muted" />
+              </div>
+            ) : error ? (
+              <p className="text-xs text-danger">{error}</p>
+            ) : plan && plan.length > 0 ? (
+              <div className="-mr-1 flex max-h-[46vh] flex-col gap-1 overflow-y-auto pr-1">
+                {plan.map((op) => (
+                  <div
+                    key={`${op.fromScopeId}->${op.toScopeId}:${op.folderName}`}
+                    className="flex items-center gap-2 rounded-lg border border-default-200 px-3 py-2 text-xs"
+                  >
+                    <span className="min-w-0 flex-1 truncate font-medium text-foreground">
+                      {op.skillName}
+                    </span>
+                    <span
+                      className={`shrink-0 rounded px-1.5 py-0.5 text-[10px] ${
+                        op.kind === "update"
+                          ? "bg-warning/15 text-warning"
+                          : "bg-content2 text-muted"
+                      }`}
+                    >
+                      {op.kind === "update" ? "update" : "new"}
+                    </span>
+                    <span className="flex shrink-0 items-center gap-1.5 text-muted">
+                      <span className="truncate">{scopeLabel(op.fromScopeId)}</span>
+                      <ArrowRight className="size-3" />
+                      <span className="truncate text-foreground/80">
+                        {scopeLabel(op.toScopeId)}
+                      </span>
+                    </span>
+                  </div>
+                ))}
+              </div>
+            ) : (
+              <div className="flex flex-col items-center gap-2 py-8 text-center">
+                <CheckCircle2 className="size-6 text-success" />
+                <p className="text-sm text-foreground">All providers already see every skill.</p>
+                <p className="text-xs text-muted">Nothing to sync at the {level} level.</p>
+              </div>
+            )}
+          </Modal.Body>
+          <Modal.Footer>
+            <Button slot="close" variant="ghost" className="text-muted">
+              {plan && plan.length > 0 ? "Cancel" : "Close"}
+            </Button>
+            {plan && plan.length > 0 ? (
+              <Button
+                variant="tertiary"
+                className="gap-1.5"
+                isPending={applying}
+                isDisabled={applying}
+                onPress={() => void apply()}
+              >
+                <Wand2 className="size-3.5" />
+                Sync {plan.length} skill{plan.length === 1 ? "" : "s"}
+              </Button>
+            ) : null}
+          </Modal.Footer>
+        </Modal.Dialog>
+      </Modal.Container>
+    </Modal.Backdrop>
+  );
+}
diff --git a/src/renderer/components/skills/SkillsManager.tsx b/src/renderer/components/skills/SkillsManager.tsx
new file mode 100644
index 00000000..041a257d
--- /dev/null
+++ b/src/renderer/components/skills/SkillsManager.tsx
@@ -0,0 +1,506 @@
+import { useState } from "react";
+import { Button, Dropdown, Label, Separator, toast, Tooltip } from "@heroui/react";
+import {
+  AlertTriangle,
+  ChevronDown,
+  FileWarning,
+  FolderOpen,
+  Pencil,
+  Plus,
+  RefreshCw,
+  Sparkles,
+  Store,
+  Trash2,
+  Wand2,
+} from "lucide-react";
+import type {
+  ProjectLocation,
+  SkillScope,
+  SkillScopeLevel,
+  SkillSummary,
+} from "@/shared/contracts";
+import { readBridge } from "@/renderer/bridge";
+import { ConfirmDialog, PixelLoader } from "@/renderer/components/common";
+import { useSkills } from "./useSkills";
+import { SkillEditorModal, type SkillEditorTarget } from "./SkillEditorModal";
+import { SkillMarketplaceModal } from "./SkillMarketplaceModal";
+import { SkillOptimizerModal } from "./SkillOptimizerModal";
+
+const LEVEL_TITLE: Record<SkillScopeLevel, string> = {
+  project: "This project",
+  global: "Global (all projects)",
+};
+
+const LEVEL_SUBTITLE: Record<SkillScopeLevel, string> = {
+  project: "Skills committed alongside the repo — shared with your team.",
+  global: "Skills in your home directory — available in every project.",
+};
+
+function errorMessage(error: unknown, fallback: string): string {
+  return error instanceof Error ? error.message : fallback;
+}
+
+export function SkillsManager(props: { mode: SkillScopeLevel; projectLocation?: ProjectLocation }) {
+  const { projectLocation } = props;
+  // Global settings shows only the global level; project settings shows the
+  // project level first, with the inherited global skills underneath.
+  const visibleLevels: SkillScopeLevel[] =
+    props.mode === "project" ? ["project", "global"] : ["global"];
+
+  const { scan, loading, error, reload } = useSkills(projectLocation);
+  const operationContext = projectLocation ? { projectLocation } : {};
+
+  const [editorTarget, setEditorTarget] = useState<SkillEditorTarget | null>(null);
+  const [marketplaceLevel, setMarketplaceLevel] = useState<SkillScopeLevel | null>(null);
+  const [optimizerLevel, setOptimizerLevel] = useState<SkillScopeLevel | null>(null);
+  const [pendingDelete, setPendingDelete] = useState<SkillSummary | null>(null);
+  const [pendingOverwrite, setPendingOverwrite] = useState<{
+    skill: SkillSummary;
+    toScope: SkillScope;
+    move: boolean;
+  } | null>(null);
+
+  const scopeById = new Map<string, SkillScope>();
+  for (const scope of scan?.scopes ?? []) scopeById.set(scope.id, scope);
+
+  const skillsByScope = new Map<string, SkillSummary[]>();
+  for (const skill of scan?.skills ?? []) {
+    const list = skillsByScope.get(skill.scopeId) ?? [];
+    list.push(skill);
+    skillsByScope.set(skill.scopeId, list);
+  }
+  for (const list of skillsByScope.values()) list.sort((a, b) => a.name.localeCompare(b.name));
+
+  const scopeLabel = (scopeId: string): string => {
+    const scope = scopeById.get(scopeId);
+    if (!scope) return scopeId;
+    return `${scope.rootLabel} · ${scope.level === "global" ? "global" : "project"}`;
+  };
+
+  async function doTransfer(
+    skill: SkillSummary,
+    toScope: SkillScope,
+    move: boolean,
+    overwrite: boolean,
+  ) {
+    await readBridge().transferSkill({
+      ...operationContext,
+      fromPath: skill.absolutePath,
+      toScopeDir: toScope.absolutePath,
+      move,
+      overwrite,
+    });
+    toast.success(`${move ? "Moved" : "Copied"} “${skill.name}” to ${scopeLabel(toScope.id)}.`);
+    await reload();
+  }
+
+  async function runTransfer(skill: SkillSummary, toScope: SkillScope, move: boolean) {
+    try {
+      await doTransfer(skill, toScope, move, false);
+    } catch (err) {
+      // A same-named skill already lives in the destination — offer to overwrite
+      // instead of dead-ending (this is how you propagate an edit to a sibling root).
+      if (/already exists/i.test(errorMessage(err, ""))) {
+        setPendingOverwrite({ skill, toScope, move });
+        return;
+      }
+      toast.danger(errorMessage(err, "Couldn't transfer the skill."));
+    }
+  }
+
+  async function confirmOverwrite() {
+    if (!pendingOverwrite) return;
+    const { skill, toScope, move } = pendingOverwrite;
+    setPendingOverwrite(null);
+    try {
+      await doTransfer(skill, toScope, move, true);
+    } catch (err) {
+      toast.danger(errorMessage(err, "Couldn't transfer the skill."));
+    }
+  }
+
+  async function confirmDelete() {
+    if (!pendingDelete) return;
+    const skill = pendingDelete;
+    setPendingDelete(null);
+    try {
+      await readBridge().deleteSkill({ ...operationContext, absolutePath: skill.absolutePath });
+      toast.success(`Deleted “${skill.name}”.`);
+      await reload();
+    } catch (err) {
+      toast.danger(errorMessage(err, "Couldn't delete the skill."));
+    }
+  }
+
+  return (
+    <div className="mx-auto min-h-full max-w-[920px]">
+      <div className="mb-5 flex items-start justify-between gap-4">
+        <div>
+          <h1 className="flex items-center gap-2 text-lg font-semibold text-foreground">
+            <Sparkles className="size-4 text-accent" />
+            Skills
+          </h1>
+          <p className="mt-1 text-xs text-muted">
+            Manage agent skills across providers and scopes. Each skill is a folder with a{" "}
+            <code>SKILL.md</code>.
+          </p>
+        </div>
+        <Button
+          size="sm"
+          variant="tertiary"
+          className="shrink-0 gap-1.5"
+          isDisabled={loading}
+          onPress={() => void reload()}
+        >
+          <RefreshCw className={`size-3.5 ${loading ? "animate-spin" : ""}`} />
+          Refresh
+        </Button>
+      </div>
+
+      {error ? (
+        <div className="mb-4 flex items-center gap-2 rounded-lg border border-danger/40 bg-danger/10 px-3 py-2 text-xs text-danger">
+          <AlertTriangle className="size-3.5" />
+          {error}
+        </div>
+      ) : null}
+
+      {loading && !scan ? (
+        <div className="flex items-center justify-center py-16">
+          <PixelLoader size="lg" className="text-muted" />
+        </div>
+      ) : (
+        <div className="space-y-7">
+          {visibleLevels.map((level) => {
+            const scopes = (scan?.scopes ?? []).filter((scope) => scope.level === level);
+            if (scopes.length === 0) return null;
+            return (
+              <LevelGroup
+                key={level}
+                level={level}
+                scopes={scopes}
+                skillsByScope={skillsByScope}
+                allScopes={scan?.scopes ?? []}
+                onNewSkill={(scope) =>
+                  setEditorTarget({
+                    mode: "create",
+                    scopeDir: scope.absolutePath,
+                    scopeLabel: scopeLabel(scope.id),
+                  })
+                }
+                onEdit={(skill) => setEditorTarget({ mode: "edit", skill })}
+                onDelete={(skill) => setPendingDelete(skill)}
+                onTransfer={runTransfer}
+                onOpenMarketplace={() => setMarketplaceLevel(level)}
+                onOptimize={() => setOptimizerLevel(level)}
+                onReveal={(path) =>
+                  void readBridge().revealSkill({ ...operationContext, absolutePath: path })
+                }
+              />
+            );
+          })}
+
+          {scan?.unavailable.length ? (
+            <div className="rounded-lg border border-default-200 px-3 py-2 text-xs text-muted">
+              Some scopes couldn&apos;t be scanned:{" "}
+              {scan.unavailable.map((u) => `${scopeLabel(u.scopeId)} (${u.reason})`).join("; ")}
+            </div>
+          ) : null}
+        </div>
+      )}
+
+      <SkillEditorModal
+        target={editorTarget}
+        {...operationContext}
+        onClose={() => setEditorTarget(null)}
+        onSaved={() => void reload()}
+      />
+      <SkillMarketplaceModal
+        open={marketplaceLevel !== null}
+        onClose={() => setMarketplaceLevel(null)}
+        onInstalled={() => void reload()}
+        {...operationContext}
+        targetScopes={(scan?.scopes ?? [])
+          .filter((scope) => scope.level === marketplaceLevel)
+          .map((scope) => ({
+            id: scope.id,
+            label: scopeLabel(scope.id),
+            absolutePath: scope.absolutePath,
+            installedFolders: (skillsByScope.get(scope.id) ?? []).map((s) => s.folderName),
+            installedSources: (skillsByScope.get(scope.id) ?? [])
+              .map((s) => s.source)
+              .filter((s): s is string => Boolean(s)),
+          }))}
+      />
+      <SkillOptimizerModal
+        open={optimizerLevel !== null}
+        level={optimizerLevel ?? "global"}
+        {...(projectLocation ? { projectLocation } : {})}
+        scopeLabel={scopeLabel}
+        onClose={() => setOptimizerLevel(null)}
+        onApplied={() => void reload()}
+      />
+
+      <ConfirmDialog
+        isOpen={pendingDelete !== null}
+        title="Delete skill"
+        body={
+          <span>
+            Delete “{pendingDelete?.name}” and its folder? This removes it from{" "}
+            <code>{pendingDelete?.absolutePath}</code> and cannot be undone.
+          </span>
+        }
+        confirmLabel="Delete"
+        confirmVariant="danger"
+        onConfirm={() => void confirmDelete()}
+        onClose={() => setPendingDelete(null)}
+      />
+
+      <ConfirmDialog
+        isOpen={pendingOverwrite !== null}
+        title="Overwrite skill"
+        body={
+          <span>
+            “{pendingOverwrite?.skill.name}” already exists in{" "}
+            {pendingOverwrite ? scopeLabel(pendingOverwrite.toScope.id) : ""}. Overwrite that copy
+            with this one?
+          </span>
+        }
+        confirmLabel="Overwrite"
+        confirmVariant="danger"
+        onConfirm={() => void confirmOverwrite()}
+        onClose={() => setPendingOverwrite(null)}
+      />
+    </div>
+  );
+}
+
+function LevelGroup(props: {
+  level: SkillScopeLevel;
+  scopes: SkillScope[];
+  allScopes: SkillScope[];
+  skillsByScope: Map<string, SkillSummary[]>;
+  onNewSkill: (scope: SkillScope) => void;
+  onEdit: (skill: SkillSummary) => void;
+  onDelete: (skill: SkillSummary) => void;
+  onTransfer: (skill: SkillSummary, toScope: SkillScope, move: boolean) => void;
+  onOpenMarketplace: () => void;
+  onOptimize: () => void;
+  onReveal: (absolutePath: string) => void;
+}) {
+  const { level, scopes, allScopes, skillsByScope } = props;
+
+  return (
+    <section>
+      <div className="mb-2 flex items-end justify-between gap-3 border-b border-default-200 pb-2">
+        <div>
+          <h2 className="text-sm font-semibold text-foreground">{LEVEL_TITLE[level]}</h2>
+          <p className="text-xs text-muted">{LEVEL_SUBTITLE[level]}</p>
+        </div>
+        <div className="flex shrink-0 items-center gap-1.5">
+          <Button
+            size="sm"
+            variant="ghost"
+            className="gap-1.5 text-muted"
+            onPress={props.onOpenMarketplace}
+          >
+            <Store className="size-3.5" />
+            Marketplace
+          </Button>
+          <Tooltip>
+            <Button
+              size="sm"
+              variant="ghost"
+              className="gap-1.5 text-muted"
+              onPress={props.onOptimize}
+            >
+              <Wand2 className="size-3.5" />
+              Sync providers
+            </Button>
+            <Tooltip.Content>
+              Copy each skill into every provider folder that&apos;s missing or out of date.
+            </Tooltip.Content>
+          </Tooltip>
+        </div>
+      </div>
+
+      <div className="space-y-3">
+        {scopes.map((scope) => (
+          <ScopeCard
+            key={scope.id}
+            scope={scope}
+            skills={skillsByScope.get(scope.id) ?? []}
+            transferTargets={allScopes.filter((other) => other.id !== scope.id)}
+            onNewSkill={() => props.onNewSkill(scope)}
+            onEdit={props.onEdit}
+            onDelete={props.onDelete}
+            onTransfer={props.onTransfer}
+            onReveal={props.onReveal}
+          />
+        ))}
+      </div>
+    </section>
+  );
+}
+
+function ScopeCard(props: {
+  scope: SkillScope;
+  skills: SkillSummary[];
+  transferTargets: SkillScope[];
+  onNewSkill: () => void;
+  onEdit: (skill: SkillSummary) => void;
+  onDelete: (skill: SkillSummary) => void;
+  onTransfer: (skill: SkillSummary, toScope: SkillScope, move: boolean) => void;
+  onReveal: (absolutePath: string) => void;
+}) {
+  const { scope, skills, transferTargets } = props;
+
+  return (
+    <div className="overflow-hidden rounded-xl border border-default-200">
+      <div className="flex items-center justify-between gap-3 bg-content2/40 px-3 py-2">
+        <div className="min-w-0">
+          <div className="flex items-center gap-2">
+            <span className="truncate text-sm font-medium text-foreground">{scope.rootLabel}</span>
+            <code className="truncate rounded bg-content2 px-1.5 py-0.5 text-[10px] text-muted">
+              {scope.dirName}
+            </code>
+            {!scope.exists ? (
+              <span className="rounded bg-content2 px-1.5 py-0.5 text-[10px] text-muted/70">
+                not created
+              </span>
+            ) : null}
+          </div>
+          <p className="mt-0.5 truncate text-[11px] text-muted">Read by {scope.consumerLabel}</p>
+        </div>
+        <div className="flex shrink-0 items-center gap-1">
+          {scope.exists ? (
+            <Tooltip>
+              <Button
+                size="sm"
+                variant="tertiary"
+                aria-label="Open folder"
+                onPress={() => props.onReveal(scope.absolutePath)}
+              >
+                <FolderOpen className="size-3.5" />
+              </Button>
+              <Tooltip.Content>Reveal in file manager</Tooltip.Content>
+            </Tooltip>
+          ) : null}
+          <Button size="sm" variant="tertiary" className="gap-1.5" onPress={props.onNewSkill}>
+            <Plus className="size-3.5" />
+            New
+          </Button>
+        </div>
+      </div>
+
+      {skills.length === 0 ? (
+        <p className="px-3 py-4 text-center text-xs text-muted">No skills here yet.</p>
+      ) : (
+        <ul className="divide-y divide-default-100">
+          {skills.map((skill) => (
+            <li key={skill.id} className="flex items-center gap-3 px-3 py-2">
+              <div className="min-w-0 flex-1">
+                <div className="flex items-center gap-2">
+                  <span className="truncate text-sm font-medium text-foreground">{skill.name}</span>
+                  {!skill.hasSkillFile ? (
+                    <Tooltip>
+                      <span className="flex items-center text-warning">
+                        <FileWarning className="size-3.5" />
+                      </span>
+                      <Tooltip.Content>No SKILL.md in this folder</Tooltip.Content>
+                    </Tooltip>
+                  ) : null}
+                  <span className="shrink-0 text-[10px] text-muted/60">
+                    {skill.fileCount} file{skill.fileCount === 1 ? "" : "s"}
+                  </span>
+                </div>
+                {skill.description ? (
+                  <p className="line-clamp-1 text-xs text-muted">{skill.description}</p>
+                ) : (
+                  <p className="text-xs text-muted/50">No description</p>
+                )}
+              </div>
+              <div className="flex shrink-0 items-center gap-0.5">
+                <Tooltip>
+                  <Button
+                    size="sm"
+                    variant="tertiary"
+                    aria-label="Edit skill"
+                    onPress={() => props.onEdit(skill)}
+                  >
+                    <Pencil className="size-3.5" />
+                  </Button>
+                  <Tooltip.Content>Edit</Tooltip.Content>
+                </Tooltip>
+
+                {transferTargets.length > 0 ? (
+                  <Dropdown>
+                    <Button
+                      size="sm"
+                      variant="tertiary"
+                      aria-label="Move or copy"
+                      className="gap-1"
+                    >
+                      <ChevronDown className="size-3.5" />
+                    </Button>
+                    <Dropdown.Popover className="min-w-[220px]">
+                      <Dropdown.Menu
+                        aria-label="Move or copy skill"
+                        onAction={(key) => {
+                          const value = String(key);
+                          const [action, scopeId] = value.split("::");
+                          const target = transferTargets.find((t) => t.id === scopeId);
+                          if (target) props.onTransfer(skill, target, action === "move");
+                        }}
+                      >
+                        <Dropdown.Section>
+                          {transferTargets.map((target) => (
+                            <Dropdown.Item
+                              key={`copy::${target.id}`}
+                              id={`copy::${target.id}`}
+                              textValue={`Copy to ${target.rootLabel} ${target.level}`}
+                            >
+                              <Label>
+                                Copy to {target.rootLabel} · {target.level}
+                              </Label>
+                            </Dropdown.Item>
+                          ))}
+                        </Dropdown.Section>
+                        <Separator />
+                        <Dropdown.Section>
+                          {transferTargets.map((target) => (
+                            <Dropdown.Item
+                              key={`move::${target.id}`}
+                              id={`move::${target.id}`}
+                              textValue={`Move to ${target.rootLabel} ${target.level}`}
+                            >
+                              <Label>
+                                Move to {target.rootLabel} · {target.level}
+                              </Label>
+                            </Dropdown.Item>
+                          ))}
+                        </Dropdown.Section>
+                      </Dropdown.Menu>
+                    </Dropdown.Popover>
+                  </Dropdown>
+                ) : null}
+
+                <Tooltip>
+                  <Button
+                    size="sm"
+                    variant="tertiary"
+                    aria-label="Delete skill"
+                    className="text-danger"
+                    onPress={() => props.onDelete(skill)}
+                  >
+                    <Trash2 className="size-3.5" />
+                  </Button>
+                  <Tooltip.Content>Delete</Tooltip.Content>
+                </Tooltip>
+              </div>
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
diff --git a/src/renderer/components/skills/index.ts b/src/renderer/components/skills/index.ts
new file mode 100644
index 00000000..f687f5ea
--- /dev/null
+++ b/src/renderer/components/skills/index.ts
@@ -0,0 +1,2 @@
+export { SkillsManager } from "./SkillsManager";
+export { useSkills } from "./useSkills";
diff --git a/src/renderer/components/skills/useSkills.ts b/src/renderer/components/skills/useSkills.ts
new file mode 100644
index 00000000..c68da96a
--- /dev/null
+++ b/src/renderer/components/skills/useSkills.ts
@@ -0,0 +1,75 @@
+import { useEffect, useRef, useState } from "react";
+import type { ProjectLocation, SkillScan } from "@/shared/contracts";
+import { readBridge } from "@/renderer/bridge";
+
+export interface UseSkillsResult {
+  scan: SkillScan | null;
+  loading: boolean;
+  error: string | null;
+  reload: () => Promise<void>;
+}
+
+function errorMessage(error: unknown, fallback: string): string {
+  return error instanceof Error ? error.message : fallback;
+}
+
+async function loadSkills(input: {
+  projectLocation?: ProjectLocation;
+  run: number;
+  currentRun: () => number;
+  setScan: (scan: SkillScan) => void;
+  setLoading: (loading: boolean) => void;
+  setError: (error: string | null) => void;
+}): Promise<void> {
+  const { projectLocation, run, currentRun, setScan, setLoading, setError } = input;
+  setLoading(true);
+  setError(null);
+  try {
+    const result = await readBridge().scanSkills(projectLocation ? { projectLocation } : {});
+    if (currentRun() === run) setScan(result);
+  } catch (err) {
+    if (currentRun() === run) setError(errorMessage(err, "Couldn't load skills."));
+  } finally {
+    if (currentRun() === run) setLoading(false);
+  }
+}
+
+/**
+ * Load the skill scan for the given project (or just the global scopes when no
+ * location is provided). Re-runs whenever the location changes; `reload()`
+ * re-scans on demand after a mutation.
+ */
+export function useSkills(projectLocation?: ProjectLocation): UseSkillsResult {
+  const [scan, setScan] = useState<SkillScan | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const runRef = useRef(0);
+
+  async function reload(): Promise<void> {
+    const run = runRef.current + 1;
+    runRef.current = run;
+    await loadSkills({
+      ...(projectLocation ? { projectLocation } : {}),
+      run,
+      currentRun: () => runRef.current,
+      setScan,
+      setLoading,
+      setError,
+    });
+  }
+
+  useEffect(() => {
+    const run = runRef.current + 1;
+    runRef.current = run;
+    void loadSkills({
+      ...(projectLocation ? { projectLocation } : {}),
+      run,
+      currentRun: () => runRef.current,
+      setScan,
+      setLoading,
+      setError,
+    });
+  }, [projectLocation]);
+
+  return { scan, loading, error, reload };
+}
diff --git a/src/renderer/views/ProjectSettingsOverlay/ProjectSettingsOverlay.tsx b/src/renderer/views/ProjectSettingsOverlay/ProjectSettingsOverlay.tsx
index 75648326..ffc60a3f 100644
--- a/src/renderer/views/ProjectSettingsOverlay/ProjectSettingsOverlay.tsx
+++ b/src/renderer/views/ProjectSettingsOverlay/ProjectSettingsOverlay.tsx
@@ -7,6 +7,7 @@ import { GeneralSection } from "./parts/GeneralSection";
 import { ScriptsSection } from "./parts/ScriptsSection";
 import { ActionsSection } from "./parts/ActionsSection";
 import { SearchSection } from "./parts/SearchSection";
+import { SkillsSection } from "./parts/SkillsSection";
 import type { ProjectSettingsSection } from "./parts/types";
 
 export { resolveActionIcon } from "@/renderer/utils/actionIcons";
@@ -38,6 +39,8 @@ export function ProjectSettingsOverlay(props: { projectId: string; onClose: () =
           <ActionsSection projectId={projectId} />
         ) : activeSection === "search" ? (
           <SearchSection projectId={projectId} />
+        ) : activeSection === "skills" ? (
+          <SkillsSection projectId={projectId} />
         ) : null
       }
     />
diff --git a/src/renderer/views/ProjectSettingsOverlay/parts/SettingsSidebar.tsx b/src/renderer/views/ProjectSettingsOverlay/parts/SettingsSidebar.tsx
index 6e0402aa..cf64ca60 100644
--- a/src/renderer/views/ProjectSettingsOverlay/parts/SettingsSidebar.tsx
+++ b/src/renderer/views/ProjectSettingsOverlay/parts/SettingsSidebar.tsx
@@ -1,6 +1,7 @@
 import {
   ArrowLeft,
   GitFork,
+  Lightbulb,
   PanelLeft,
   PanelLeftClose,
   Play,
@@ -33,6 +34,7 @@ export function SettingsSidebar(props: {
     { id: "worktrees", icon: <GitFork className="size-4" />, label: t`Worktrees` },
     { id: "actions", icon: <Play className="size-4" />, label: t`Actions` },
     { id: "search", icon: <Search className="size-4" />, label: t`Search` },
+    { id: "skills", icon: <Lightbulb className="size-4" />, label: t`Skills` },
   ];
 
   return (
diff --git a/src/renderer/views/ProjectSettingsOverlay/parts/SkillsSection.tsx b/src/renderer/views/ProjectSettingsOverlay/parts/SkillsSection.tsx
new file mode 100644
index 00000000..a251f590
--- /dev/null
+++ b/src/renderer/views/ProjectSettingsOverlay/parts/SkillsSection.tsx
@@ -0,0 +1,26 @@
+import { useAppStore } from "@/renderer/state/appStore";
+import { SkillsManager } from "@/renderer/components/skills";
+
+/**
+ * Project settings → Skills. Shows the project's `.claude/skills` and
+ * `.agents/skills` scopes plus the inherited global skills underneath.
+ */
+export function SkillsSection(props: { projectId: string }) {
+  const project = useAppStore((s) => s.projects.find((p) => p.id === props.projectId));
+
+  // If the project was removed while the overlay is open, say so rather than
+  // silently degrading to a global-only view that still claims to be project-scoped.
+  if (!project) {
+    return (
+      <div className="flex h-full items-center justify-center px-6 text-sm text-muted">
+        This project is no longer available.
+      </div>
+    );
+  }
+
+  return (
+    <div className="h-full min-h-0 overflow-y-auto px-6 pb-8 pt-4">
+      <SkillsManager mode="project" projectLocation={project.location} />
+    </div>
+  );
+}
diff --git a/src/renderer/views/ProjectSettingsOverlay/parts/types.ts b/src/renderer/views/ProjectSettingsOverlay/parts/types.ts
index c92e4c05..db9c1a14 100644
--- a/src/renderer/views/ProjectSettingsOverlay/parts/types.ts
+++ b/src/renderer/views/ProjectSettingsOverlay/parts/types.ts
@@ -1 +1 @@
-export type ProjectSettingsSection = "general" | "worktrees" | "actions" | "search";
+export type ProjectSettingsSection = "general" | "worktrees" | "actions" | "search" | "skills";
diff --git a/src/renderer/views/SettingsOverlay/SettingsOverlay.tsx b/src/renderer/views/SettingsOverlay/SettingsOverlay.tsx
index 9c51b1e9..ebf1c139 100644
--- a/src/renderer/views/SettingsOverlay/SettingsOverlay.tsx
+++ b/src/renderer/views/SettingsOverlay/SettingsOverlay.tsx
@@ -22,6 +22,7 @@ import { AcpRegistrySettings } from "./parts/AcpRegistrySettings";
 import { AgentsGeneralSettings } from "./parts/AgentsGeneralSettings";
 import { SearchSettings } from "./parts/SearchSettings";
 import { ShortcutsSettings } from "./parts/ShortcutsSettings";
+import { SkillsSettings } from "./parts/SkillsSettings";
 import { TerminalSettings } from "./parts/TerminalSettings";
 import { ThreadSettings } from "./parts/ThreadSettings";
 import { ArchivedThreadsSettings } from "./parts/ArchivedThreadsSettings";
@@ -42,6 +43,7 @@ const SECTION_VIEWS: Partial<Record<SettingsSection, () => ReactNode>> = {
   worktrees: () => <WorktreeSettings />,
   notifications: () => <NotificationSettings />,
   ai: () => <AISettings />,
+  skills: () => <SkillsSettings />,
   search: () => <SearchSettings />,
   shortcuts: () => <ShortcutsSettings />,
   agents: () => <AgentSettingsEmpty />,
diff --git a/src/renderer/views/SettingsOverlay/parts/SettingsSidebar.tsx b/src/renderer/views/SettingsOverlay/parts/SettingsSidebar.tsx
index 1bcb085c..c8ecdfac 100644
--- a/src/renderer/views/SettingsOverlay/parts/SettingsSidebar.tsx
+++ b/src/renderer/views/SettingsOverlay/parts/SettingsSidebar.tsx
@@ -12,6 +12,7 @@ import {
   Globe,
   Info,
   Keyboard,
+  Lightbulb,
   Mic,
   MessageSquare,
   PanelLeft,
@@ -175,6 +176,7 @@ export function SettingsSidebar(props: {
       icon: <Sparkles className="size-4" />,
       label: t({ message: "AI", comment: "Settings section: AI / assistant configuration" }),
     },
+    { id: "skills", icon: <Lightbulb className="size-4" />, label: t`Skills` },
     { id: "search", icon: <Search className="size-4" />, label: t`Search` },
     { id: "shortcuts", icon: <Keyboard className="size-4" />, label: t`Shortcuts` },
   ];
@@ -314,6 +316,13 @@ export function SettingsSidebar(props: {
               isActive={activeSection === "ai"}
               onPress={() => onSectionChange("ai")}
             />
+            <SidebarButton
+              iconOnly
+              icon={<Lightbulb className="size-4" />}
+              label={t`Skills`}
+              isActive={activeSection === "skills"}
+              onPress={() => onSectionChange("skills")}
+            />
             <SidebarButton
               iconOnly
               icon={<Search className="size-4" />}
diff --git a/src/renderer/views/SettingsOverlay/parts/SkillsSettings.tsx b/src/renderer/views/SettingsOverlay/parts/SkillsSettings.tsx
new file mode 100644
index 00000000..f2d4642c
--- /dev/null
+++ b/src/renderer/views/SettingsOverlay/parts/SkillsSettings.tsx
@@ -0,0 +1,6 @@
+import { SkillsManager } from "@/renderer/components/skills";
+
+/** Global settings → Skills. Shows the home-directory (global) skill scopes. */
+export function SkillsSettings() {
+  return <SkillsManager mode="global" />;
+}
diff --git a/src/renderer/views/SettingsOverlay/parts/types.ts b/src/renderer/views/SettingsOverlay/parts/types.ts
index 9e32a2f6..9afff0ca 100644
--- a/src/renderer/views/SettingsOverlay/parts/types.ts
+++ b/src/renderer/views/SettingsOverlay/parts/types.ts
@@ -9,6 +9,7 @@ export type SettingsSection =
   | "worktrees"
   | "notifications"
   | "ai"
+  | "skills"
   | "acpRegistry"
   | "agentsGeneral"
   | "search"
diff --git a/src/shared/contracts.ts b/src/shared/contracts.ts
index 67fadb9e..a8527ceb 100644
--- a/src/shared/contracts.ts
+++ b/src/shared/contracts.ts
@@ -5,6 +5,7 @@ export * from "./contracts/project";
 export * from "./contracts/thread";
 export * from "./contracts/git";
 export * from "./contracts/projectTree";
+export * from "./contracts/skills";
 export * from "./contracts/github";
 export * from "./contracts/appView";
 export * from "./contracts/agentEvent";
diff --git a/src/shared/contracts/skills.ts b/src/shared/contracts/skills.ts
new file mode 100644
index 00000000..d185b237
--- /dev/null
+++ b/src/shared/contracts/skills.ts
@@ -0,0 +1,214 @@
+import { z } from "zod";
+import { projectLocationSchema } from "./common";
+
+/**
+ * Skills domain (shared contracts).
+ *
+ * A "skill" is a directory containing a `SKILL.md` file (YAML frontmatter with
+ * `name`/`description`/`metadata`, followed by markdown). Skills live in
+ * "scopes" — the cross product of a *level* (global ~ vs project repo root) and
+ * a *root* (a provider-specific folder convention such as `.claude/skills` or
+ * the shared `.agents/skills`). See `src/shared/skills.ts` for the root table
+ * and the marketplace catalog; this file only declares payloads/results.
+ */
+
+export const skillScopeLevelSchema = z.enum(["global", "project"]);
+export type SkillScopeLevel = z.infer<typeof skillScopeLevelSchema>;
+
+/** A resolved place where skills can live, e.g. "Claude (global)". */
+export interface SkillScope {
+  /** Stable id, `${level}:${rootId}` (e.g. "project:claude"). */
+  id: string;
+  level: SkillScopeLevel;
+  /** Root id from SKILL_ROOTS (e.g. "claude", "agents"). */
+  rootId: string;
+  /** Human label, e.g. "Claude" / "Shared agents". */
+  rootLabel: string;
+  /** Which agents read this root, for display ("Copilot, Codex, …"). */
+  consumerLabel: string;
+  /** The relative directory convention, e.g. ".claude/skills". */
+  dirName: string;
+  /** Absolute on-disk path to this scope's skills directory. */
+  absolutePath: string;
+  /** Whether the directory currently exists on disk. */
+  exists: boolean;
+}
+
+/** A single discovered skill (one folder containing a SKILL.md). */
+export interface SkillSummary {
+  /** Stable id, `${scopeId}/${folderName}`. */
+  id: string;
+  scopeId: string;
+  level: SkillScopeLevel;
+  rootId: string;
+  /** Directory name of the skill folder. */
+  folderName: string;
+  absolutePath: string;
+  /** From frontmatter `name`, falling back to the folder name. */
+  name: string;
+  /** From frontmatter `description` (may be empty). */
+  description: string;
+  /** Number of files in the skill folder (incl. SKILL.md). */
+  fileCount: number;
+  /** False when the folder has no SKILL.md (malformed skill). */
+  hasSkillFile: boolean;
+  /** `metadata.source` from the frontmatter — the marketplace id it was installed from, if any. */
+  source?: string;
+}
+
+export interface SkillScan {
+  scopes: SkillScope[];
+  skills: SkillSummary[];
+  /**
+   * Scopes that could not be scanned (e.g. WSL project roots, unreadable
+   * dirs). Surfaced so the UI can explain partial results instead of silently
+   * dropping them.
+   */
+  unavailable: { scopeId: string; reason: string }[];
+}
+
+export interface SkillFileInfo {
+  /** Path relative to the skill folder. */
+  path: string;
+  sizeBytes: number;
+}
+
+export interface SkillDetail {
+  absolutePath: string;
+  folderName: string;
+  name: string;
+  description: string;
+  /** Full raw SKILL.md text (frontmatter + body), for editing. */
+  content: string;
+  files: SkillFileInfo[];
+}
+
+export const scanSkillsPayloadSchema = z.object({
+  projectLocation: projectLocationSchema.optional(),
+});
+export type ScanSkillsPayload = z.infer<typeof scanSkillsPayloadSchema>;
+
+const skillOperationContextSchema = z.object({
+  projectLocation: projectLocationSchema.optional(),
+});
+export type SkillOperationContext = z.infer<typeof skillOperationContextSchema>;
+
+export const readSkillPayloadSchema = z.object({
+  ...skillOperationContextSchema.shape,
+  absolutePath: z.string().min(1),
+});
+export type ReadSkillPayload = z.infer<typeof readSkillPayloadSchema>;
+
+export const writeSkillPayloadSchema = z.object({
+  ...skillOperationContextSchema.shape,
+  absolutePath: z.string().min(1),
+  content: z.string(),
+});
+export type WriteSkillPayload = z.infer<typeof writeSkillPayloadSchema>;
+
+export const createSkillPayloadSchema = z.object({
+  ...skillOperationContextSchema.shape,
+  /** Absolute path to the destination scope's skills directory. */
+  scopeDir: z.string().min(1),
+  folderName: z.string().min(1),
+  name: z.string().min(1),
+  description: z.string().default(""),
+  /** Optional markdown body (after the frontmatter). */
+  body: z.string().optional(),
+});
+export type CreateSkillPayload = z.infer<typeof createSkillPayloadSchema>;
+
+export const deleteSkillPayloadSchema = z.object({
+  ...skillOperationContextSchema.shape,
+  absolutePath: z.string().min(1),
+});
+export type DeleteSkillPayload = z.infer<typeof deleteSkillPayloadSchema>;
+
+export const renameSkillPayloadSchema = z.object({
+  ...skillOperationContextSchema.shape,
+  absolutePath: z.string().min(1),
+  nextFolderName: z.string().min(1),
+});
+export type RenameSkillPayload = z.infer<typeof renameSkillPayloadSchema>;
+
+export const transferSkillPayloadSchema = z.object({
+  ...skillOperationContextSchema.shape,
+  /** Absolute path to the skill folder to copy/move. */
+  fromPath: z.string().min(1),
+  /** Absolute path to the destination scope's skills directory. */
+  toScopeDir: z.string().min(1),
+  /** When true the source folder is removed after a successful copy. */
+  move: z.boolean().default(false),
+  /** When true an existing destination folder is overwritten. */
+  overwrite: z.boolean().default(false),
+});
+export type TransferSkillPayload = z.infer<typeof transferSkillPayloadSchema>;
+
+export interface TransferSkillResult {
+  absolutePath: string;
+}
+
+export const optimizeSkillsPayloadSchema = z.object({
+  projectLocation: projectLocationSchema.optional(),
+  level: skillScopeLevelSchema,
+  /**
+   * When false, returns the planned operations without writing anything
+   * (used to preview the optimizer before the user confirms).
+   */
+  apply: z.boolean().default(false),
+});
+export type OptimizeSkillsPayload = z.infer<typeof optimizeSkillsPayloadSchema>;
+
+export interface SkillSyncOp {
+  folderName: string;
+  skillName: string;
+  fromScopeId: string;
+  toScopeId: string;
+  /** Absolute destination path the skill was (or would be) copied to. */
+  toPath: string;
+  /**
+   * `create` — the destination root has no copy at all.
+   * `update` — a copy exists but its contents differ from the (newest) source,
+   * so it would be overwritten to bring the providers back in sync.
+   */
+  kind: "create" | "update";
+}
+
+export interface OptimizeSkillsResult {
+  applied: boolean;
+  ops: SkillSyncOp[];
+}
+
+export const installMarketplaceSkillPayloadSchema = z.object({
+  ...skillOperationContextSchema.shape,
+  catalogId: z.string().min(1),
+  /** Absolute path to the destination scope's skills directory. */
+  targetScopeDir: z.string().min(1),
+  /** Optional override for the installed folder name. */
+  folderName: z.string().optional(),
+});
+export type InstallMarketplaceSkillPayload = z.infer<typeof installMarketplaceSkillPayloadSchema>;
+
+export interface InstallMarketplaceSkillResult {
+  absolutePath: string;
+  folderName: string;
+}
+
+export const installSkillFromGitPayloadSchema = z.object({
+  ...skillOperationContextSchema.shape,
+  /** A git clone URL, e.g. https://github.com/owner/repo. */
+  repoUrl: z.string().min(1),
+  /** Optional path within the repo to the skill folder (defaults to repo root). */
+  sourcePath: z.string().optional(),
+  /** Absolute path to the destination scope's skills directory. */
+  targetScopeDir: z.string().min(1),
+  /** Optional override for the installed folder name. */
+  folderName: z.string().optional(),
+});
+export type InstallSkillFromGitPayload = z.infer<typeof installSkillFromGitPayloadSchema>;
+
+export const revealSkillPayloadSchema = z.object({
+  ...skillOperationContextSchema.shape,
+  absolutePath: z.string().min(1),
+});
+export type RevealSkillPayload = z.infer<typeof revealSkillPayloadSchema>;
diff --git a/src/shared/ipc/procedureMap.ts b/src/shared/ipc/procedureMap.ts
index e40a2b99..f6eb5082 100644
--- a/src/shared/ipc/procedureMap.ts
+++ b/src/shared/ipc/procedureMap.ts
@@ -7,6 +7,7 @@ import { lspProcedures } from "./procedures/lsp";
 import { profileProcedures } from "./procedures/profile";
 import { projectTreeProcedures } from "./procedures/projectTree";
 import { settingsProcedures } from "./procedures/settings";
+import { skillsProcedures } from "./procedures/skills";
 import { threadProcedures } from "./procedures/thread";
 import { updatesProcedures } from "./procedures/updates";
 import { usageProcedures } from "./procedures/usage";
@@ -18,6 +19,7 @@ export const groupedIpcProcedures = {
   github: githubProcedures,
   projectTree: projectTreeProcedures,
   settings: settingsProcedures,
+  skills: skillsProcedures,
   db: dbProcedures,
   updates: updatesProcedures,
   lsp: lspProcedures,
@@ -33,6 +35,7 @@ export const ipcProcedureMap = {
   ...githubProcedures,
   ...projectTreeProcedures,
   ...settingsProcedures,
+  ...skillsProcedures,
   ...dbProcedures,
   ...updatesProcedures,
   ...lspProcedures,
@@ -69,6 +72,7 @@ export const MAIN_LOCAL_PROCEDURE_NAMES = [
   "getKeybindings",
   "setKeybindings",
   "revealProjectEntry",
+  "revealSkill",
   "getSharedSettings",
   "setSharedSettings",
   "setClaudeProfileEnvironment",
diff --git a/src/shared/ipc/procedures/skills.ts b/src/shared/ipc/procedures/skills.ts
new file mode 100644
index 00000000..73657f06
--- /dev/null
+++ b/src/shared/ipc/procedures/skills.ts
@@ -0,0 +1,90 @@
+import {
+  createSkillPayloadSchema,
+  deleteSkillPayloadSchema,
+  installMarketplaceSkillPayloadSchema,
+  installSkillFromGitPayloadSchema,
+  optimizeSkillsPayloadSchema,
+  readSkillPayloadSchema,
+  renameSkillPayloadSchema,
+  revealSkillPayloadSchema,
+  scanSkillsPayloadSchema,
+  transferSkillPayloadSchema,
+  writeSkillPayloadSchema,
+} from "../../contracts";
+import type {
+  CreateSkillPayload,
+  DeleteSkillPayload,
+  InstallMarketplaceSkillPayload,
+  InstallMarketplaceSkillResult,
+  InstallSkillFromGitPayload,
+  OptimizeSkillsPayload,
+  OptimizeSkillsResult,
+  ReadSkillPayload,
+  RenameSkillPayload,
+  RevealSkillPayload,
+  ScanSkillsPayload,
+  SkillDetail,
+  SkillScan,
+  TransferSkillPayload,
+  TransferSkillResult,
+  WriteSkillPayload,
+} from "../../contracts";
+import { definePayloadProcedure } from "../core";
+
+export const skillsProcedures = {
+  scanSkills: definePayloadProcedure<ScanSkillsPayload, SkillScan, "supervisor">(
+    "scanSkills",
+    "supervisor",
+    scanSkillsPayloadSchema,
+  ),
+  readSkill: definePayloadProcedure<ReadSkillPayload, SkillDetail, "supervisor">(
+    "readSkill",
+    "supervisor",
+    readSkillPayloadSchema,
+  ),
+  writeSkill: definePayloadProcedure<WriteSkillPayload, void, "supervisor">(
+    "writeSkill",
+    "supervisor",
+    writeSkillPayloadSchema,
+  ),
+  createSkill: definePayloadProcedure<CreateSkillPayload, TransferSkillResult, "supervisor">(
+    "createSkill",
+    "supervisor",
+    createSkillPayloadSchema,
+  ),
+  deleteSkill: definePayloadProcedure<DeleteSkillPayload, void, "supervisor">(
+    "deleteSkill",
+    "supervisor",
+    deleteSkillPayloadSchema,
+  ),
+  renameSkill: definePayloadProcedure<RenameSkillPayload, TransferSkillResult, "supervisor">(
+    "renameSkill",
+    "supervisor",
+    renameSkillPayloadSchema,
+  ),
+  transferSkill: definePayloadProcedure<TransferSkillPayload, TransferSkillResult, "supervisor">(
+    "transferSkill",
+    "supervisor",
+    transferSkillPayloadSchema,
+  ),
+  optimizeSkills: definePayloadProcedure<OptimizeSkillsPayload, OptimizeSkillsResult, "supervisor">(
+    "optimizeSkills",
+    "supervisor",
+    optimizeSkillsPayloadSchema,
+  ),
+  installMarketplaceSkill: definePayloadProcedure<
+    InstallMarketplaceSkillPayload,
+    InstallMarketplaceSkillResult,
+    "supervisor"
+  >("installMarketplaceSkill", "supervisor", installMarketplaceSkillPayloadSchema),
+  installSkillFromGit: definePayloadProcedure<
+    InstallSkillFromGitPayload,
+    InstallMarketplaceSkillResult,
+    "supervisor"
+  >("installSkillFromGit", "supervisor", installSkillFromGitPayloadSchema),
+  revealSkill: definePayloadProcedure<RevealSkillPayload, void, "main-local">(
+    "revealSkill",
+    "main-local",
+    revealSkillPayloadSchema,
+  ),
+} as const;
diff --git a/src/shared/skills.ts b/src/shared/skills.ts
new file mode 100644
index 00000000..397000c0
--- /dev/null
+++ b/src/shared/skills.ts
@@ -0,0 +1,316 @@
+import type { SkillScopeLevel } from "./contracts/skills";
+
+/**
+ * Skill "roots": folder conventions that agents read for skills. Each root is
+ * consumed by one or more installed agents. The two canonical roots today:
+ *
+ *  - `.claude/skills` — read by Claude Code and Claude profiles.
+ *  - `.agents/skills` — the shared convention read by the ACP-speaking agents
+ *    (Copilot, Codex, Cursor, Gemini, Grok, OpenCode, and custom ACP agents).
+ *
+ * The "optimizer" mirrors skills across roots at a given level so that whichever
+ * agent the user runs can see every skill (some read `.agents`, some read their
+ * own folder). To extend: add a root here and the manager picks it up.
+ */
+export interface SkillRoot {
+  id: string;
+  label: string;
+  /** Relative directory, POSIX-style, e.g. ".claude/skills". */
+  dirName: string;
+  /** Short human description of which agents read this root. */
+  consumerLabel: string;
+  /**
+   * Agent kinds that read this root. Matched by exact kind or by `${kind}:`
+   * prefix (covers Claude profiles `claude:<id>` and `acp-generic:<id>`).
+   */
+  consumerKinds: string[];
+}
+
+export const SKILL_ROOTS: SkillRoot[] = [
+  {
+    id: "claude",
+    label: "Claude",
+    dirName: ".claude/skills",
+    consumerLabel: "Claude Code & Claude profiles",
+    consumerKinds: ["claude"],
+  },
+  {
+    id: "agents",
+    label: "Shared agents",
+    dirName: ".agents/skills",
+    consumerLabel: "Copilot, Codex, Cursor, Gemini, Grok, OpenCode",
+    consumerKinds: ["copilot", "codex", "cursor", "gemini", "grok", "opencode", "acp-generic"],
+  },
+];
+
+export function makeScopeId(level: SkillScopeLevel, rootId: string): string {
+  return `${level}:${rootId}`;
+}
+
+/** Slugify a free-form skill name into a safe folder name. */
+export function slugifySkillName(name: string): string {
+  const slug = name
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return slug || "skill";
+}
+
+/**
+ * Build a SKILL.md document from structured fields. Frontmatter mirrors the
+ * format used by the bundled skills (`name`, `description`, optional metadata).
+ */
+export function buildSkillMarkdown(input: {
+  name: string;
+  description: string;
+  body?: string;
+  metadata?: Record<string, string>;
+}): string {
+  // Quote both name and description so colons/quotes/newlines in them can't
+  // corrupt the YAML frontmatter that downstream agents parse with strict YAML.
+  const lines = ["---", `name: ${JSON.stringify(input.name)}`];
+  lines.push(`description: ${JSON.stringify(input.description)}`);
+  if (input.metadata && Object.keys(input.metadata).length > 0) {
+    lines.push("metadata:");
+    for (const [key, value] of Object.entries(input.metadata)) {
+      lines.push(`  ${key}: ${JSON.stringify(value)}`);
+    }
+  }
+  lines.push("---", "");
+  const body = (input.body ?? "").trim();
+  lines.push(body.length > 0 ? body : `# ${input.name}\n`);
+  lines.push("");
+  return lines.join("\n");
+}
+
+/** A curated, popular skill the user can install with one click. */
+export interface MarketplaceSkill {
+  id: string;
+  name: string;
+  folderName: string;
+  description: string;
+  author: string;
+  tags: string[];
+  /** Link to the canonical upstream source. */
+  homepage?: string;
+  /** Rough popularity weight, used only for default ordering. */
+  popularity: number;
+  /** Embedded markdown body written into the installed SKILL.md. */
+  template: string;
+}
+
+/**
+ * Curated marketplace. Entries install as self-contained templates (offline,
+ * always-correct) and link out to their canonical source. For anything not
+ * listed here, the UI also offers "Install from Git URL", which clones a repo
+ * and copies a skill folder out of it.
+ */
+export const SKILL_MARKETPLACE: MarketplaceSkill[] = [
+  {
+    id: "systematic-debugging",
+    name: "Systematic Debugging",
+    folderName: "systematic-debugging",
+    description:
+      "Use when stuck on a bug: form a hypothesis, add instrumentation, bisect, and verify the root cause before changing code. Keywords: debug, root cause, stack trace, reproduce.",
+    author: "Lightcode",
+    tags: ["debugging", "workflow"],
+    homepage: "https://github.com/obra/superpowers",
+    popularity: 95,
+    template: `# Systematic Debugging
+
+Use this skill when you are stuck on a bug or unexpected behavior.
+
+## Method
+1. **Reproduce reliably.** Find the smallest input/steps that trigger it. If you can't reproduce it, you can't fix it.
+2. **State the hypothesis.** Write down what you believe is happening and why, in one sentence.
+3. **Instrument.** Add logging / asserts / a breakpoint at the boundary where the hypothesis predicts the divergence.
+4. **Bisect.** Narrow the failure to a single function/commit (git bisect, binary search the data).
+5. **Confirm the root cause.** Prove it — don't guess. Change one thing and watch the prediction hold.
+6. **Fix + regression test.** Add a test that fails before the fix and passes after.
+
+## Anti-patterns
+- Changing several things at once.
+- "Fixing" symptoms without confirming the cause.
+- Deleting logging before the fix is verified.
+`,
+  },
+  {
+    id: "code-review",
+    name: "Code Review",
+    folderName: "code-review",
+    description:
+      "Use when reviewing a diff or PR. Checks correctness, edge cases, security, tests, and readability, and reports findings by severity. Keywords: review, PR, diff, audit.",
+    author: "Lightcode",
+    tags: ["review", "quality"],
+    popularity: 90,
+    template: `# Code Review
+
+Review the changed code (the diff), not the whole repo, unless asked.
+
+## Pass order
+1. **Correctness** — does it do what the PR says? Off-by-one, null/empty, async races, error paths.
+2. **Edge cases** — boundaries, large/empty inputs, concurrency, failure/retry.
+3. **Security** — injection, authz, secrets, unsafe deserialization, path traversal.
+4. **Tests** — is the new behavior covered? Do tests assert the right thing?
+5. **Readability** — naming, dead code, duplication, comment/altitude.
+
+## Output
+Report findings grouped by severity (blocker / should-fix / nit) with \`file:line\` references and a concrete suggested change. Lead with what's correct so the author has signal, then the findings.
+`,
+  },
+  {
+    id: "writing-commits",
+    name: "Conventional Commits",
+    folderName: "writing-commits",
+    description:
+      "Use when writing git commit messages. Produces a concise, imperative, conventional-commit subject plus a body explaining why. Keywords: commit, git, message, changelog.",
+    author: "Lightcode",
+    tags: ["git", "workflow"],
+    homepage: "https://www.conventionalcommits.org",
+    popularity: 80,
+    template: `# Conventional Commits
+
+Write commit messages as: \`type(scope): summary\`.
+
+- **type**: feat, fix, docs, refactor, perf, test, build, chore.
+- **summary**: imperative, lower-case, no trailing period, ≤ 72 chars.
+- **body** (optional): explain *why*, not *what* the diff already shows. Wrap at 72.
+- **footer** (optional): \`BREAKING CHANGE:\`, issue refs.
+
+## Example
+\`\`\`
+fix(auth): reject expired refresh tokens
+
+Tokens past their exp were silently accepted because the clock-skew
+window was applied with the wrong sign. Compare against now() and
+allow only a 30s skew.
+\`\`\`
+`,
+  },
+  {
+    id: "test-driven-development",
+    name: "Test-Driven Development",
+    folderName: "test-driven-development",
+    description:
+      "Use when implementing a feature or fix. Drives the change with a failing test first (red → green → refactor). Keywords: TDD, tests, red green refactor.",
+    author: "Lightcode",
+    tags: ["testing", "workflow"],
+    popularity: 78,
+    template: `# Test-Driven Development
+
+Drive the change with tests.
+
+1. **Red** — write the smallest test that expresses the next bit of behavior. Run it; watch it fail for the right reason.
+2. **Green** — write the least code that makes it pass. Don't gold-plate.
+3. **Refactor** — clean up names/duplication with the test as a safety net.
+
+## Tips
+- One behavior per test; assert on outcomes, not implementation details.
+- If a test is hard to write, the design is probably hard to use — fix the design.
+- Keep the loop tight: seconds, not minutes.
+`,
+  },
+  {
+    id: "pdf-processing",
+    name: "PDF Processing",
+    folderName: "pdf",
+    description:
+      "Use when extracting text/tables from PDFs or filling/merging/splitting PDF files. Keywords: pdf, extract, form, merge, pypdf.",
+    author: "Anthropic",
+    tags: ["documents", "data"],
+    homepage: "https://github.com/anthropics/skills",
+    popularity: 88,
+    template: `# PDF Processing
+
+Use when working with PDF files (extraction, forms, merge/split).
+
+## Tools
+- **pypdf** — pure-python read/merge/split, form fields.
+- **pdfplumber** — text + table extraction with layout.
+- **pdf2image + an OCR engine** — scanned/image PDFs.
+
+## Recipes
+- *Extract text*: \`pdfplumber\` page-by-page; prefer \`extract_table()\` for tabular data.
+- *Merge*: \`pypdf.PdfWriter\` — append pages, then write once.
+- *Fill a form*: read the field names first, then \`update_page_form_field_values\`.
+
+Always verify output: page counts, that no text was dropped, that tables kept their columns.
+`,
+  },
+  {
+    id: "web-research",
+    name: "Web Research",
+    folderName: "web-research",
+    description:
+      "Use when answering a question that needs current or external facts. Searches multiple sources, cross-checks, and cites. Keywords: research, search, sources, cite, verify.",
+    author: "Lightcode",
+    tags: ["research"],
+    popularity: 72,
+    template: `# Web Research
+
+Use when a task needs facts you can't derive from the repo.
+
+## Method
+1. **Decompose** the question into sub-claims.
+2. **Search broadly** — multiple queries/phrasings; don't stop at the first hit.
+3. **Cross-check** each claim against ≥ 2 independent sources; prefer primary sources.
+4. **Note recency** — flag anything that may be stale.
+5. **Cite** — every non-obvious claim gets a source link.
+
+## Output
+A short synthesis answering the question, followed by a sources list. Separate what's well-supported from what's uncertain.
+`,
+  },
+  {
+    id: "brainstorming",
+    name: "Brainstorming",
+    folderName: "brainstorming",
+    description:
+      "Use when exploring options or designing an approach. Generates diverse alternatives, then evaluates against constraints before committing. Keywords: brainstorm, design, options, tradeoffs.",
+    author: "Lightcode",
+    tags: ["design", "workflow"],
+    popularity: 60,
+    template: `# Brainstorming
+
+Use before committing to an approach.
+
+1. **Diverge** — list 3–5 genuinely different options (not variations of one). Include a "boring" and a "bold" one.
+2. **State constraints** — what must be true (time, deps, compatibility, risk).
+3. **Score** each option against the constraints; note the failure mode of each.
+4. **Recommend one** with a one-line rationale, and name the runner-up.
+
+Don't silently pick the first idea. Make the tradeoff explicit.
+`,
+  },
+  {
+    id: "slides",
+    name: "Slide Decks (PPTX)",
+    folderName: "pptx",
+    description:
+      "Use when creating or editing PowerPoint presentations programmatically. Keywords: pptx, slides, powerpoint, python-pptx, deck.",
+    author: "Anthropic",
+    tags: ["documents", "presentation"],
+    homepage: "https://github.com/anthropics/skills",
+    popularity: 65,
+    template: `# Slide Decks (PPTX)
+
+Use when generating/editing \`.pptx\` files.
+
+## Tool
+- **python-pptx** — programmatic slides, layouts, text frames, tables, images.
+
+## Recipe
+1. Start from a template \`.pptx\` to inherit theme/fonts.
+2. Add slides by layout index; set title + body placeholders by index, not by guessing.
+3. For charts/tables, build data first, then render.
+4. Save and re-open to verify nothing overflowed the slide bounds.
+
+Keep one idea per slide; prefer few words + a visual over paragraphs.
+`,
+  },
+];
+
+export function marketplaceSkillById(id: string): MarketplaceSkill | undefined {
+  return SKILL_MARKETPLACE.find((skill) => skill.id === id);
+}
diff --git a/src/supervisor/ipcHandlers.ts b/src/supervisor/ipcHandlers.ts
index 7d7db8b6..af81ad08 100644
--- a/src/supervisor/ipcHandlers.ts
+++ b/src/supervisor/ipcHandlers.ts
@@ -98,6 +98,16 @@ export function createSupervisorIpcHandlers(runtime: SupervisorRuntime): Supervi
     renameProjectEntry: (payload) => runtime.renameProjectEntry(payload),
     moveProjectEntry: (payload) => runtime.moveProjectEntry(payload),
     deleteProjectEntry: (payload) => runtime.deleteProjectEntry(payload),
+    scanSkills: (payload) => runtime.scanSkills(payload),
+    readSkill: (payload) => runtime.readSkill(payload),
+    writeSkill: (payload) => runtime.writeSkill(payload),
+    createSkill: (payload) => runtime.createSkill(payload),
+    deleteSkill: (payload) => runtime.deleteSkill(payload),
+    renameSkill: (payload) => runtime.renameSkill(payload),
+    transferSkill: (payload) => runtime.transferSkill(payload),
+    optimizeSkills: (payload) => runtime.optimizeSkills(payload),
+    installMarketplaceSkill: (payload) => runtime.installMarketplaceSkill(payload),
+    installSkillFromGit: (payload) => runtime.installSkillFromGit(payload),
     detectSetupScript: (payload) => runtime.detectSetupScript(payload),
     ghCheckAvailable: (payload) => runtime.ghCheckAvailable(payload),
     ghCreatePr: (payload) => runtime.ghCreatePr(payload),
diff --git a/src/supervisor/runtime.ts b/src/supervisor/runtime.ts
index 16872554..a74ac409 100644
--- a/src/supervisor/runtime.ts
+++ b/src/supervisor/runtime.ts
@@ -152,6 +152,21 @@ import type {
   StartThreadResult,
   StageThreadInputPayload,
   ThreadRuntimeSnapshot,
+  ScanSkillsPayload,
+  SkillScan,
+  ReadSkillPayload,
+  SkillDetail,
+  WriteSkillPayload,
+  CreateSkillPayload,
+  DeleteSkillPayload,
+  RenameSkillPayload,
+  TransferSkillPayload,
+  TransferSkillResult,
+  OptimizeSkillsPayload,
+  OptimizeSkillsResult,
+  InstallMarketplaceSkillPayload,
+  InstallMarketplaceSkillResult,
+  InstallSkillFromGitPayload,
   WriteExternalFilePayload,
   WriteExternalFileResult,
   WriteProjectFilePayload,
@@ -209,6 +224,7 @@ import { GitHubService } from "./github";
 import { ProjectWatcher } from "./projectWatcher";
 import { LanguageServerManager } from "./lsp";
 import { ProjectTreeService } from "./projectTree";
+import { SkillsService } from "./skills";
 import { generatePrSummary } from "./prSummaryGenerator";
 import { detectWindowsShell, type WindowsShellPreference } from "./shellPreference";
 import { generateTitle } from "./titleGenerator";
@@ -241,6 +257,7 @@ export class SupervisorRuntime {
   private readonly githubService = new GitHubService();
   private readonly fileIndexService = new FileIndexService();
   private readonly projectTreeService = new ProjectTreeService();
+  private readonly skillsService = new SkillsService();
   private readonly adapters = new Map<AgentKind, AgentAdapter>();
   private readonly windowsShell: WindowsShellPreference;
   private readonly agentStatusService: AgentStatusService;
@@ -1469,6 +1486,50 @@ export class SupervisorRuntime {
     return this.projectTreeService.deleteProjectEntry(payload);
   }
 
+  async scanSkills(payload: ScanSkillsPayload): Promise<SkillScan> {
+    return this.skillsService.scanSkills(payload);
+  }
+
+  async readSkill(payload: ReadSkillPayload): Promise<SkillDetail> {
+    return this.skillsService.readSkill(payload);
+  }
+
+  async writeSkill(payload: WriteSkillPayload): Promise<void> {
+    return this.skillsService.writeSkill(payload);
+  }
+
+  async createSkill(payload: CreateSkillPayload): Promise<TransferSkillResult> {
+    return this.skillsService.createSkill(payload);
+  }
+
+  async deleteSkill(payload: DeleteSkillPayload): Promise<void> {
+    return this.skillsService.deleteSkill(payload);
+  }
+
+  async renameSkill(payload: RenameSkillPayload): Promise<TransferSkillResult> {
+    return this.skillsService.renameSkill(payload);
+  }
+
+  async transferSkill(payload: TransferSkillPayload): Promise<TransferSkillResult> {
+    return this.skillsService.transferSkill(payload);
+  }
+
+  async optimizeSkills(payload: OptimizeSkillsPayload): Promise<OptimizeSkillsResult> {
+    return this.skillsService.optimizeSkills(payload);
+  }
+
+  async installMarketplaceSkill(
+    payload: InstallMarketplaceSkillPayload,
+  ): Promise<InstallMarketplaceSkillResult> {
+    return this.skillsService.installMarketplaceSkill(payload);
+  }
+
+  async installSkillFromGit(
+    payload: InstallSkillFromGitPayload,
+  ): Promise<InstallMarketplaceSkillResult> {
+    return this.skillsService.installSkillFromGit(payload);
+  }
+
   async detectSetupScript(payload: DetectSetupScriptPayload): Promise<DetectSetupScriptResult> {
     const candidates: { file: string; command: string }[] = [
       { file: "pnpm-lock.yaml", command: "pnpm install" },
diff --git a/src/supervisor/skills.test.ts b/src/supervisor/skills.test.ts
new file mode 100644
index 00000000..c5ab3c63
--- /dev/null
+++ b/src/supervisor/skills.test.ts
@@ -0,0 +1,330 @@
+import { mkdir, mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import type { ProjectLocation } from "@/shared/contracts";
+import { buildSkillMarkdown } from "@/shared/skills";
+import { parseSkillFrontmatter, SkillsService } from "./skills";
+
+describe("parseSkillFrontmatter", () => {
+  it("reads name and description", () => {
+    const md = "---\nname: my-skill\ndescription: Use when testing.\n---\n\n# Body\n";
+    expect(parseSkillFrontmatter(md)).toEqual({
+      name: "my-skill",
+      description: "Use when testing.",
+    });
+  });
+
+  it("unquotes a JSON-quoted description with colons", () => {
+    const md = '---\nname: x\ndescription: "Use when: building. Keywords: a, b."\n---\nbody';
+    expect(parseSkillFrontmatter(md).description).toBe("Use when: building. Keywords: a, b.");
+  });
+
+  it("ignores nested metadata keys", () => {
+    const md = "---\nname: x\ndescription: d\nmetadata:\n  name: not-this\n---\n";
+    expect(parseSkillFrontmatter(md)).toEqual({ name: "x", description: "d" });
+  });
+
+  it("returns empty when there is no frontmatter", () => {
+    expect(parseSkillFrontmatter("# Just markdown")).toEqual({});
+  });
+
+  it("parses CRLF (Windows) files", () => {
+    const md = "---\r\nname: my-skill\r\ndescription: Use when testing.\r\n---\r\n\r\n# Body\r\n";
+    expect(parseSkillFrontmatter(md)).toEqual({
+      name: "my-skill",
+      description: "Use when testing.",
+    });
+  });
+
+  it("strips a leading UTF-8 BOM", () => {
+    const md = "---\nname: x\ndescription: d\n---\n";
+    expect(parseSkillFrontmatter(md)).toEqual({ name: "x", description: "d" });
+  });
+
+  it("captures metadata.source", () => {
+    const md = "---\nname: x\ndescription: d\nmetadata:\n  source: code-review\n---\n";
+    expect(parseSkillFrontmatter(md).source).toBe("code-review");
+  });
+
+  it("round-trips a name containing a colon via buildSkillMarkdown", () => {
+    const md = buildSkillMarkdown({ name: "Use: this thing", description: "d" });
+    expect(parseSkillFrontmatter(md)).toMatchObject({ name: "Use: this thing", description: "d" });
+  });
+});
+
+describe("SkillsService (project scopes)", () => {
+  let dir: string;
+  let location: ProjectLocation;
+  const service = new SkillsService();
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), "lc-skills-test-"));
+    location = { kind: "posix", path: dir };
+  });
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  const claudeDir = () => join(dir, ".claude", "skills");
+  const agentsDir = () => join(dir, ".agents", "skills");
+  const skillContext = () => ({ projectLocation: location });
+
+  function projectSkills(scan: Awaited<ReturnType<SkillsService["scanSkills"]>>) {
+    return scan.skills.filter((s) => s.level === "project");
+  }
+
+  it("creates, scans, and reads a skill in a project scope", async () => {
+    const created = await service.createSkill({
+      ...skillContext(),
+      scopeDir: claudeDir(),
+      folderName: "demo",
+      name: "Demo Skill",
+      description: "Use when demoing.",
+      body: "# Demo\n\nDo the thing.",
+    });
+    expect(created.absolutePath).toBe(join(claudeDir(), "demo"));
+
+    const scan = await service.scanSkills({ projectLocation: location });
+    const found = projectSkills(scan).find((s) => s.folderName === "demo");
+    expect(found).toBeDefined();
+    expect(found?.name).toBe("Demo Skill");
+    expect(found?.description).toBe("Use when demoing.");
+    expect(found?.rootId).toBe("claude");
+    expect(found?.hasSkillFile).toBe(true);
+
+    const detail = await service.readSkill({
+      ...skillContext(),
+      absolutePath: created.absolutePath,
+    });
+    expect(detail.content).toContain('name: "Demo Skill"');
+    expect(detail.files.some((f) => f.path === "SKILL.md")).toBe(true);
+  });
+
+  it("rejects creating outside a skills directory", async () => {
+    await expect(
+      service.createSkill({
+        ...skillContext(),
+        scopeDir: join(dir, "random"),
+        folderName: "x",
+        name: "X",
+        description: "",
+      }),
+    ).rejects.toThrow(/not a skills directory/i);
+  });
+
+  it("copies a skill to another provider root", async () => {
+    await service.createSkill({
+      ...skillContext(),
+      scopeDir: claudeDir(),
+      folderName: "shared",
+      name: "Shared",
+      description: "d",
+    });
+    await service.transferSkill({
+      ...skillContext(),
+      fromPath: join(claudeDir(), "shared"),
+      toScopeDir: agentsDir(),
+      move: false,
+      overwrite: false,
+    });
+
+    const scan = await service.scanSkills({ projectLocation: location });
+    const roots = projectSkills(scan)
+      .filter((s) => s.folderName === "shared")
+      .map((s) => s.rootId)
+      .sort();
+    expect(roots).toEqual(["agents", "claude"]);
+  });
+
+  it("optimizer plans copies for missing roots, then reports in-sync", async () => {
+    await service.createSkill({
+      ...skillContext(),
+      scopeDir: claudeDir(),
+      folderName: "only-claude",
+      name: "Only Claude",
+      description: "d",
+    });
+
+    const plan = await service.optimizeSkills({
+      projectLocation: location,
+      level: "project",
+      apply: false,
+    });
+    expect(plan.applied).toBe(false);
+    expect(plan.ops).toHaveLength(1);
+    expect(plan.ops[0]?.fromScopeId).toBe("project:claude");
+    expect(plan.ops[0]?.toScopeId).toBe("project:agents");
+
+    const applied = await service.optimizeSkills({
+      projectLocation: location,
+      level: "project",
+      apply: true,
+    });
+    expect(applied.applied).toBe(true);
+    expect(applied.ops).toHaveLength(1);
+
+    const after = await service.optimizeSkills({
+      projectLocation: location,
+      level: "project",
+      apply: false,
+    });
+    expect(after.ops).toHaveLength(0);
+  });
+
+  it("re-syncs a divergent copy after an edit (the newest wins)", async () => {
+    // Same folder in both roots, then edit only the claude copy.
+    await service.createSkill({
+      ...skillContext(),
+      scopeDir: claudeDir(),
+      folderName: "shared",
+      name: "Shared",
+      description: "v1",
+    });
+    await service.transferSkill({
+      ...skillContext(),
+      fromPath: join(claudeDir(), "shared"),
+      toScopeDir: agentsDir(),
+      move: false,
+      overwrite: false,
+    });
+
+    // Edit the claude copy so the two roots diverge.
+    await service.writeSkill({
+      ...skillContext(),
+      absolutePath: join(claudeDir(), "shared"),
+      content: "---\nname: Shared\ndescription: v2-edited\n---\n\n# Updated body\n",
+    });
+
+    const plan = await service.optimizeSkills({
+      projectLocation: location,
+      level: "project",
+      apply: true,
+    });
+    expect(plan.ops).toHaveLength(1);
+    expect(plan.ops[0]?.kind).toBe("update");
+    expect(plan.ops[0]?.fromScopeId).toBe("project:claude");
+    expect(plan.ops[0]?.toScopeId).toBe("project:agents");
+
+    // The agents copy now matches the edited claude copy.
+    const agentsContent = await readFile(join(agentsDir(), "shared", "SKILL.md"), "utf8");
+    expect(agentsContent).toContain("v2-edited");
+
+    const after = await service.optimizeSkills({
+      projectLocation: location,
+      level: "project",
+      apply: false,
+    });
+    expect(after.ops).toHaveLength(0);
+  });
+
+  it("does not mirror malformed folders (no SKILL.md) across roots", async () => {
+    // A stray folder with no SKILL.md under .claude/skills should be ignored.
+    await mkdir(join(claudeDir(), "junk"), { recursive: true });
+    const plan = await service.optimizeSkills({
+      projectLocation: location,
+      level: "project",
+      apply: false,
+    });
+    expect(plan.ops).toHaveLength(0);
+  });
+
+  it("records metadata.source for a marketplace-installed skill", async () => {
+    await service.installMarketplaceSkill({
+      ...skillContext(),
+      catalogId: "code-review",
+      targetScopeDir: agentsDir(),
+    });
+    const scan = await service.scanSkills({ projectLocation: location });
+    const found = projectSkills(scan).find((s) => s.folderName === "code-review");
+    expect(found?.source).toBe("code-review");
+  });
+
+  it("renames a skill folder", async () => {
+    const created = await service.createSkill({
+      ...skillContext(),
+      scopeDir: claudeDir(),
+      folderName: "old-name",
+      name: "Renamable",
+      description: "",
+    });
+    const renamed = await service.renameSkill({
+      ...skillContext(),
+      absolutePath: created.absolutePath,
+      nextFolderName: "new-name",
+    });
+    expect(renamed.absolutePath).toBe(join(claudeDir(), "new-name"));
+    const scan = await service.scanSkills({ projectLocation: location });
+    const folders = projectSkills(scan).map((s) => s.folderName);
+    expect(folders).toContain("new-name");
+    expect(folders).not.toContain("old-name");
+  });
+
+  it("rejects mutating a relative or non-skills path", async () => {
+    await expect(service.deleteSkill({ absolutePath: ".claude/skills/x" })).rejects.toThrow(
+      /must be absolute/i,
+    );
+    await expect(
+      service.writeSkill({
+        ...skillContext(),
+        absolutePath: join(dir, "notskills", "x"),
+        content: "",
+      }),
+    ).rejects.toThrow(/outside a skills directory/i);
+  });
+
+  it("rejects a lookalike skills directory outside the operation context", async () => {
+    await expect(
+      service.writeSkill({
+        ...skillContext(),
+        absolutePath: join(dir, "outside", ".agents", "skills", "outside"),
+        content: "x",
+      }),
+    ).rejects.toThrow(/outside a skills directory/i);
+  });
+
+  it("writeSkill ignores '..' traversal by normalizing the path", async () => {
+    // Resolves to <dir>/.claude/skills/x — still inside a skills dir, so allowed,
+    // but a traversal that escaped would be rejected.
+    await expect(
+      service.writeSkill({
+        ...skillContext(),
+        absolutePath: join(claudeDir(), "sub", "..", "..", "..", "..", "etc", "passwd"),
+        content: "x",
+      }),
+    ).rejects.toThrow(/outside a skills directory/i);
+  });
+
+  it("installs a marketplace skill and refuses duplicates", async () => {
+    const result = await service.installMarketplaceSkill({
+      ...skillContext(),
+      catalogId: "code-review",
+      targetScopeDir: agentsDir(),
+    });
+    expect(result.folderName).toBe("code-review");
+    const body = await readFile(join(result.absolutePath, "SKILL.md"), "utf8");
+    expect(body).toContain('name: "Code Review"');
+
+    await expect(
+      service.installMarketplaceSkill({
+        ...skillContext(),
+        catalogId: "code-review",
+        targetScopeDir: agentsDir(),
+      }),
+    ).rejects.toThrow(/already exists/i);
+  });
+
+  it("deletes a skill", async () => {
+    const created = await service.createSkill({
+      ...skillContext(),
+      scopeDir: claudeDir(),
+      folderName: "temp",
+      name: "Temp",
+      description: "",
+    });
+    await service.deleteSkill({ ...skillContext(), absolutePath: created.absolutePath });
+    const scan = await service.scanSkills({ projectLocation: location });
+    expect(projectSkills(scan).some((s) => s.folderName === "temp")).toBe(false);
+  });
+});
diff --git a/src/supervisor/skills.ts b/src/supervisor/skills.ts
new file mode 100644
index 00000000..b21a0e62
--- /dev/null
+++ b/src/supervisor/skills.ts
@@ -0,0 +1,629 @@
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import type { Dirent, Stats } from "node:fs";
+import {
+  cp,
+  mkdir,
+  mkdtemp,
+  readdir,
+  readFile,
+  rename,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { promisify } from "node:util";
+import type {
+  CreateSkillPayload,
+  DeleteSkillPayload,
+  InstallMarketplaceSkillPayload,
+  InstallMarketplaceSkillResult,
+  InstallSkillFromGitPayload,
+  OptimizeSkillsPayload,
+  OptimizeSkillsResult,
+  ProjectLocation,
+  ReadSkillPayload,
+  RenameSkillPayload,
+  ScanSkillsPayload,
+  SkillDetail,
+  SkillFileInfo,
+  SkillScan,
+  SkillScope,
+  SkillSummary,
+  SkillSyncOp,
+  TransferSkillPayload,
+  TransferSkillResult,
+  WriteSkillPayload,
+} from "@/shared/contracts";
+import {
+  buildSkillMarkdown,
+  makeScopeId,
+  marketplaceSkillById,
+  SKILL_ROOTS,
+  slugifySkillName,
+  type SkillRoot,
+} from "@/shared/skills";
+import { getProjectFsPath } from "@/shared/wsl";
+
+const execFileAsync = promisify(execFile);
+
+const SKILL_FILE = "SKILL.md";
+const MAX_LISTED_FILES = 500;
+const MAX_FRONTMATTER_BYTES = 64_000;
+
+interface SkillSignature {
+  hash: string;
+  mtimeMs: number;
+}
+
+function normalizeName(name: string): string {
+  return name.trim().replace(/^["']|["']$/g, "");
+}
+
+/** Validate a single path segment used as a skill folder name. */
+function validateFolderName(name: string): string {
+  const trimmed = name.trim();
+  if (!trimmed) throw new Error("Skill folder name cannot be empty.");
+  if (trimmed.includes("/") || trimmed.includes("\\")) {
+    throw new Error("Skill folder name cannot contain path separators.");
+  }
+  if (trimmed === "." || trimmed === "..") throw new Error("Invalid skill folder name.");
+  return trimmed;
+}
+
+interface SkillOperationContext {
+  projectLocation?: ProjectLocation | undefined;
+}
+
+/**
+ * Guard every mutating operation. The renderer always passes paths that came
+ * from {@link SkillsService.scanSkills}, but these methods sit on a trusted IPC
+ * boundary that performs destructive fs ops. Require absolute paths and confirm
+ * that they match the global skill roots, or the supplied project skill roots,
+ * rather than trusting any folder on disk named `.agents/skills`.
+ */
+function assertSkillFolder(folderPath: string, context: SkillOperationContext): void {
+  if (!isAbsolute(folderPath)) {
+    throw new Error("Skill path must be absolute.");
+  }
+  if (!isAllowedScopeDir(dirname(resolve(folderPath)), context)) {
+    throw new Error("Refusing to operate outside a skills directory.");
+  }
+}
+
+function assertSkillsScopeDir(scopeDir: string, context: SkillOperationContext): void {
+  if (!isAbsolute(scopeDir)) {
+    throw new Error("Skill scope path must be absolute.");
+  }
+  if (!isAllowedScopeDir(scopeDir, context)) {
+    throw new Error("Destination is not a skills directory.");
+  }
+}
+
+function isAllowedScopeDir(scopeDir: string, context: SkillOperationContext): boolean {
+  const normalized = normalizeFsPath(scopeDir);
+  return allowedScopeDirs(context).some((allowed) => sameFsPath(normalized, allowed));
+}
+
+function allowedScopeDirs(context: SkillOperationContext): string[] {
+  const bases = [homedir()];
+  if (context.projectLocation) bases.push(getProjectFsPath(context.projectLocation));
+  return bases.flatMap((base) =>
+    SKILL_ROOTS.map((root) => normalizeFsPath(join(base, ...root.dirName.split("/")))),
+  );
+}
+
+function normalizeFsPath(path: string): string {
+  return resolve(path);
+}
+
+function sameFsPath(left: string, right: string): boolean {
+  if (process.platform === "win32") return left.toLowerCase() === right.toLowerCase();
+  return left === right;
+}
+
+function unquoteScalar(raw: string): string {
+  const value = raw.trim();
+  if (
+    (value.startsWith('"') && value.endsWith('"')) ||
+    (value.startsWith("'") && value.endsWith("'"))
+  ) {
+    try {
+      return value.startsWith('"') ? (JSON.parse(value) as string) : value.slice(1, -1);
+    } catch {
+      return value.slice(1, -1);
+    }
+  }
+  return value;
+}
+
+/**
+ * Parse a SKILL.md's leading YAML frontmatter for `name`, `description`, and
+ * the `metadata.source` provenance tag we write on marketplace installs.
+ * Intentionally minimal (no YAML dependency) — handles the simple
+ * `key: value` / quoted-value shapes the skill format uses. Line endings are
+ * normalized (CRLF) and a leading UTF-8 BOM is stripped so Windows / git-cloned
+ * files parse the same as LF files.
+ */
+export function parseSkillFrontmatter(content: string): {
+  name?: string;
+  description?: string;
+  source?: string;
+} {
+  const text = content
+    .slice(0, MAX_FRONTMATTER_BYTES)
+    .replace(/^\uFEFF/, "")
+    .replace(/\r\n?/g, "\n");
+  if (!text.startsWith("---")) return {};
+  const end = text.indexOf("\n---", 3);
+  if (end === -1) return {};
+  const block = text.slice(text.indexOf("\n", 3) + 1, end);
+  const result: { name?: string; description?: string; source?: string } = {};
+  for (const rawLine of block.split("\n")) {
+    // Top-level name/description.
+    const top = /^(name|description)\s*:\s*(.*)$/.exec(rawLine);
+    if (top) {
+      result[top[1] as "name" | "description"] = unquoteScalar(top[2] ?? "");
+      continue;
+    }
+    // `source` lives under `metadata:` (indented); capture it for provenance.
+    const source = /^\s+source\s*:\s*(.*)$/.exec(rawLine);
+    if (source) result.source = unquoteScalar(source[1] ?? "");
+  }
+  return result;
+}
+
+export class SkillsService {
+  /** Resolve the absolute base directory for a given scope level. */
+  private scopeBase(level: "global" | "project", projectLocation?: ProjectLocation): string | null {
+    if (level === "global") return homedir();
+    if (!projectLocation) return null;
+    return getProjectFsPath(projectLocation);
+  }
+
+  private scopeFor(root: SkillRoot, level: "global" | "project", base: string): SkillScope {
+    const absolutePath = join(base, ...root.dirName.split("/"));
+    return {
+      id: makeScopeId(level, root.id),
+      level,
+      rootId: root.id,
+      rootLabel: root.label,
+      consumerLabel: root.consumerLabel,
+      dirName: root.dirName,
+      absolutePath,
+      exists: false,
+    };
+  }
+
+  async scanSkills(payload: ScanSkillsPayload): Promise<SkillScan> {
+    const scopes: SkillScope[] = [];
+    const skills: SkillSummary[] = [];
+    const unavailable: { scopeId: string; reason: string }[] = [];
+
+    const levels: ("global" | "project")[] = payload.projectLocation
+      ? ["global", "project"]
+      : ["global"];
+
+    for (const level of levels) {
+      const base = this.scopeBase(level, payload.projectLocation);
+      if (!base) continue;
+      for (const root of SKILL_ROOTS) {
+        const scope = this.scopeFor(root, level, base);
+        try {
+          const found = await this.scanScope(scope);
+          scope.exists = found.exists;
+          skills.push(...found.skills);
+        } catch (error) {
+          unavailable.push({ scopeId: scope.id, reason: errorMessage(error) });
+        }
+        scopes.push(scope);
+      }
+    }
+
+    return { scopes, skills, unavailable };
+  }
+
+  private async scanScope(scope: SkillScope): Promise<{ exists: boolean; skills: SkillSummary[] }> {
+    let entries: Dirent[];
+    try {
+      entries = await readdir(scope.absolutePath, { withFileTypes: true });
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+        return { exists: false, skills: [] };
+      }
+      throw error;
+    }
+
+    const dirs = entries.filter((entry) => entry.isDirectory() || entry.isSymbolicLink());
+    const skills = await Promise.all(dirs.map((entry) => this.summarizeSkill(scope, entry.name)));
+    return {
+      exists: true,
+      skills: skills.filter((skill): skill is SkillSummary => skill !== null),
+    };
+  }
+
+  private async summarizeSkill(
+    scope: SkillScope,
+    folderName: string,
+  ): Promise<SkillSummary | null> {
+    const folderPath = join(scope.absolutePath, folderName);
+    let dirStat: Stats;
+    try {
+      dirStat = await stat(folderPath);
+    } catch {
+      return null;
+    }
+    if (!dirStat.isDirectory()) return null;
+
+    let fileCount = 0;
+    let hasSkillFile = false;
+    try {
+      const inner = await readdir(folderPath, { withFileTypes: true });
+      fileCount = inner.filter((entry) => entry.isFile()).length;
+      hasSkillFile = inner.some((entry) => entry.isFile() && entry.name === SKILL_FILE);
+    } catch {
+      // Unreadable folder — still surface it so the user can fix/remove it.
+    }
+
+    let name = folderName;
+    let description = "";
+    let source: string | undefined;
+    if (hasSkillFile) {
+      try {
+        const content = await readFile(join(folderPath, SKILL_FILE), "utf8");
+        const front = parseSkillFrontmatter(content);
+        if (front.name) name = normalizeName(front.name);
+        if (front.description) description = front.description;
+        if (front.source) source = front.source;
+      } catch {
+        // Ignore read errors; fall back to folder name.
+      }
+    }
+
+    return {
+      id: `${scope.id}/${folderName}`,
+      scopeId: scope.id,
+      level: scope.level,
+      rootId: scope.rootId,
+      folderName,
+      absolutePath: folderPath,
+      name,
+      description,
+      fileCount,
+      hasSkillFile,
+      ...(source !== undefined ? { source } : {}),
+    };
+  }
+
+  async readSkill(payload: ReadSkillPayload): Promise<SkillDetail> {
+    // Guard the read path like the mutating ones — it walks the folder tree and
+    // returns file contents, so keep it confined to skills directories.
+    assertSkillFolder(payload.absolutePath, payload);
+    const folderPath = payload.absolutePath;
+    const skillFile = join(folderPath, SKILL_FILE);
+    let content = "";
+    try {
+      content = await readFile(skillFile, "utf8");
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+    const front = parseSkillFrontmatter(content);
+    const files = await this.listSkillFiles(folderPath);
+    return {
+      absolutePath: folderPath,
+      folderName: basename(folderPath),
+      name: front.name ? normalizeName(front.name) : basename(folderPath),
+      description: front.description ?? "",
+      content,
+      files,
+    };
+  }
+
+  private async listSkillFiles(folderPath: string): Promise<SkillFileInfo[]> {
+    const out: SkillFileInfo[] = [];
+    const walk = async (relDir: string): Promise<void> => {
+      if (out.length >= MAX_LISTED_FILES) return;
+      const absDir = relDir ? join(folderPath, relDir) : folderPath;
+      let entries: Dirent[];
+      try {
+        entries = await readdir(absDir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const entry of entries) {
+        if (out.length >= MAX_LISTED_FILES) return;
+        const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+          await walk(rel);
+        } else if (entry.isFile()) {
+          try {
+            const info = await stat(join(folderPath, rel));
+            out.push({ path: rel, sizeBytes: info.size });
+          } catch {
+            // skip unreadable file
+          }
+        }
+      }
+    };
+    await walk("");
+    out.sort((a, b) => a.path.localeCompare(b.path));
+    return out;
+  }
+
+  async writeSkill(payload: WriteSkillPayload): Promise<void> {
+    assertSkillFolder(payload.absolutePath, payload);
+    await mkdir(payload.absolutePath, { recursive: true });
+    await writeFile(join(payload.absolutePath, SKILL_FILE), payload.content, "utf8");
+  }
+
+  async createSkill(payload: CreateSkillPayload): Promise<TransferSkillResult> {
+    assertSkillsScopeDir(payload.scopeDir, payload);
+    const folderName = validateFolderName(payload.folderName);
+    const folderPath = join(payload.scopeDir, folderName);
+    if (await pathExists(folderPath)) {
+      throw new Error(`A skill named "${folderName}" already exists here.`);
+    }
+    await mkdir(folderPath, { recursive: true });
+    const markdown = buildSkillMarkdown({
+      name: payload.name,
+      description: payload.description,
+      ...(payload.body !== undefined ? { body: payload.body } : {}),
+    });
+    await writeFile(join(folderPath, SKILL_FILE), markdown, "utf8");
+    return { absolutePath: folderPath };
+  }
+
+  async deleteSkill(payload: DeleteSkillPayload): Promise<void> {
+    assertSkillFolder(payload.absolutePath, payload);
+    await rm(payload.absolutePath, { recursive: true, force: false });
+  }
+
+  async renameSkill(payload: RenameSkillPayload): Promise<TransferSkillResult> {
+    assertSkillFolder(payload.absolutePath, payload);
+    const nextName = validateFolderName(payload.nextFolderName);
+    const nextPath = join(dirname(payload.absolutePath), nextName);
+    if (nextPath === payload.absolutePath) return { absolutePath: payload.absolutePath };
+    if (await pathExists(nextPath)) {
+      throw new Error(`A skill named "${nextName}" already exists here.`);
+    }
+    await rename(payload.absolutePath, nextPath);
+    return { absolutePath: nextPath };
+  }
+
+  async transferSkill(payload: TransferSkillPayload): Promise<TransferSkillResult> {
+    assertSkillFolder(payload.fromPath, payload);
+    assertSkillsScopeDir(payload.toScopeDir, payload);
+    const folderName = basename(payload.fromPath);
+    const destPath = join(payload.toScopeDir, folderName);
+    if (destPath === payload.fromPath) {
+      throw new Error("Source and destination are the same.");
+    }
+    const destExists = await pathExists(destPath);
+    if (destExists && !payload.overwrite) {
+      throw new Error(`A skill named "${folderName}" already exists in the destination.`);
+    }
+    await mkdir(payload.toScopeDir, { recursive: true });
+    if (destExists) await rm(destPath, { recursive: true, force: true });
+    // dereference so a copied symlinked skill becomes real files, not a link
+    // that still points at the source location.
+    await cp(payload.fromPath, destPath, { recursive: true, dereference: true });
+    if (payload.move) {
+      await rm(payload.fromPath, { recursive: true, force: true });
+    }
+    return { absolutePath: destPath };
+  }
+
+  /**
+   * Mirror skills across every root at a level so all installed agents see the
+   * same set — the "optimizer". For each skill folder present in any root we:
+   *  - copy it into roots that lack it (`kind: "create"`), and
+   *  - re-copy it into roots whose copy has *diverged* from the most recently
+   *    edited copy (`kind: "update"`), so editing a shared skill in one root no
+   *    longer leaves a stale copy behind in another.
+   * The newest copy (by max file mtime) wins. With `apply: false`, returns the
+   * plan without writing.
+   */
+  async optimizeSkills(payload: OptimizeSkillsPayload): Promise<OptimizeSkillsResult> {
+    const base = this.scopeBase(payload.level, payload.projectLocation);
+    if (!base) {
+      return { applied: false, ops: [] };
+    }
+
+    const allScopes = SKILL_ROOTS.map((root) => this.scopeFor(root, payload.level, base));
+    // scopeId -> folderName -> { skill, signature }
+    const present = new Map<string, Map<string, { skill: SkillSummary; sig: SkillSignature }>>();
+    // Only scopes we could actually read participate — a root that errors mid-scan
+    // must NOT be treated as empty (that would plan spurious copies into it).
+    const scopes: SkillScope[] = [];
+    for (const scope of allScopes) {
+      let found: { exists: boolean; skills: SkillSummary[] };
+      try {
+        found = await this.scanScope(scope);
+      } catch {
+        continue;
+      }
+      const byFolder = new Map<string, { skill: SkillSummary; sig: SkillSignature }>();
+      for (const skill of found.skills) {
+        // Don't mirror malformed folders (no SKILL.md) or non-skill junk dirs.
+        if (!skill.hasSkillFile) continue;
+        byFolder.set(skill.folderName, {
+          skill,
+          sig: await this.skillSignature(skill.absolutePath),
+        });
+      }
+      present.set(scope.id, byFolder);
+      scopes.push(scope);
+    }
+
+    const allFolders = new Set<string>();
+    for (const byFolder of present.values()) {
+      for (const folder of byFolder.keys()) allFolders.add(folder);
+    }
+
+    const ops: SkillSyncOp[] = [];
+    for (const folder of allFolders) {
+      // The most recently edited copy is the source of truth for this skill.
+      let source: SkillScope | undefined;
+      let sourceEntry: { skill: SkillSummary; sig: SkillSignature } | undefined;
+      for (const scope of scopes) {
+        const entry = present.get(scope.id)?.get(folder);
+        if (!entry) continue;
+        if (!sourceEntry || entry.sig.mtimeMs > sourceEntry.sig.mtimeMs) {
+          source = scope;
+          sourceEntry = entry;
+        }
+      }
+      if (!source || !sourceEntry) continue;
+
+      for (const target of scopes) {
+        if (target.id === source.id) continue;
+        const targetEntry = present.get(target.id)?.get(folder);
+        if (targetEntry && targetEntry.sig.hash === sourceEntry.sig.hash) continue;
+        ops.push({
+          folderName: folder,
+          skillName: sourceEntry.skill.name,
+          fromScopeId: source.id,
+          toScopeId: target.id,
+          toPath: join(target.absolutePath, folder),
+          kind: targetEntry ? "update" : "create",
+        });
+      }
+    }
+
+    if (payload.apply) {
+      for (const op of ops) {
+        const source = scopes.find((scope) => scope.id === op.fromScopeId)!;
+        await mkdir(dirname(op.toPath), { recursive: true });
+        // Replace divergent copies wholesale so files removed upstream don't linger.
+        if (op.kind === "update") await rm(op.toPath, { recursive: true, force: true });
+        await cp(join(source.absolutePath, op.folderName), op.toPath, {
+          recursive: true,
+          dereference: true,
+        });
+      }
+    }
+
+    return { applied: payload.apply, ops };
+  }
+
+  /**
+   * A content fingerprint for a skill folder: a hash over every file's relative
+   * path and full bytes, plus the newest file mtime (used only to pick the
+   * freshest source). The optimizer compares hashes to detect divergence, so we
+   * hash actual contents — not just sizes — otherwise a same-size in-place edit
+   * to an auxiliary file would look "in sync". Skill folders are small (capped
+   * at MAX_LISTED_FILES), so reading each file on demand is acceptable.
+   */
+  private async skillSignature(folderPath: string): Promise<SkillSignature> {
+    const hash = createHash("sha1");
+    let mtimeMs = 0;
+    const files = await this.listSkillFiles(folderPath);
+    for (const file of files) {
+      hash.update(` ${file.path} `);
+      try {
+        hash.update(await readFile(join(folderPath, file.path)));
+        const info = await stat(join(folderPath, file.path));
+        if (info.mtimeMs > mtimeMs) mtimeMs = info.mtimeMs;
+      } catch {
+        // Unreadable file — fold its size in so it still affects the hash.
+        hash.update(`size:${file.sizeBytes}`);
+      }
+    }
+    return { hash: hash.digest("hex"), mtimeMs };
+  }
+
+  async installMarketplaceSkill(
+    payload: InstallMarketplaceSkillPayload,
+  ): Promise<InstallMarketplaceSkillResult> {
+    assertSkillsScopeDir(payload.targetScopeDir, payload);
+    const entry = marketplaceSkillById(payload.catalogId);
+    if (!entry) throw new Error(`Unknown marketplace skill: ${payload.catalogId}`);
+    const folderName = validateFolderName(payload.folderName ?? entry.folderName);
+    const folderPath = join(payload.targetScopeDir, folderName);
+    if (await pathExists(folderPath)) {
+      throw new Error(`A skill named "${folderName}" already exists here.`);
+    }
+    await mkdir(folderPath, { recursive: true });
+    const markdown = buildSkillMarkdown({
+      name: entry.name,
+      description: entry.description,
+      body: entry.template,
+      metadata: { author: entry.author, source: entry.id },
+    });
+    await writeFile(join(folderPath, SKILL_FILE), markdown, "utf8");
+    return { absolutePath: folderPath, folderName };
+  }
+
+  async installSkillFromGit(
+    payload: InstallSkillFromGitPayload,
+  ): Promise<InstallMarketplaceSkillResult> {
+    assertSkillsScopeDir(payload.targetScopeDir, payload);
+    const temp = await mkdtemp(join(tmpdir(), "lightcode-skill-"));
+    try {
+      try {
+        // `--` stops a `-`-prefixed repoUrl from being read as a git option;
+        // the hardened env makes auth-required remotes fail fast instead of
+        // hanging on a credential prompt for the full timeout.
+        await execFileAsync(
+          "git",
+          ["clone", "--depth", "1", "--single-branch", "--no-tags", "--", payload.repoUrl, "repo"],
+          {
+            cwd: temp,
+            timeout: 60_000,
+            env: {
+              ...process.env,
+              GIT_TERMINAL_PROMPT: "0",
+              GIT_ASKPASS: "",
+              GCM_INTERACTIVE: "never",
+            },
+          },
+        );
+      } catch (error) {
+        throw new Error(`git clone failed: ${errorMessage(error)}`, { cause: error });
+      }
+      const repoRoot = resolve(join(temp, "repo"));
+      const sourceDir = payload.sourcePath
+        ? join(repoRoot, ...payload.sourcePath.split("/").filter(Boolean))
+        : repoRoot;
+      // Reject a sourcePath that escapes the clone via `..`.
+      const resolvedSource = resolve(sourceDir);
+      if (resolvedSource !== repoRoot && !resolvedSource.startsWith(repoRoot + sep)) {
+        throw new Error("Invalid source path inside the repository.");
+      }
+      if (!(await pathExists(join(resolvedSource, SKILL_FILE)))) {
+        throw new Error(
+          `No ${SKILL_FILE} found at ${payload.sourcePath ?? "the repository root"}.`,
+        );
+      }
+      const folderName = validateFolderName(
+        payload.folderName ??
+          slugifySkillName(basename(payload.sourcePath || payload.repoUrl).replace(/\.git$/, "")),
+      );
+      const folderPath = join(payload.targetScopeDir, folderName);
+      if (await pathExists(folderPath)) {
+        throw new Error(`A skill named "${folderName}" already exists here.`);
+      }
+      await mkdir(payload.targetScopeDir, { recursive: true });
+      await cp(resolvedSource, folderPath, { recursive: true, dereference: true });
+      await rm(join(folderPath, ".git"), { recursive: true, force: true });
+      return { absolutePath: folderPath, folderName };
+    } finally {
+      await rm(temp, { recursive: true, force: true }).catch(() => undefined);
+    }
+  }
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}