@kurokeita/add-skill 1.9.0 → 1.10.0

package/README.md

@@ -87,11 +87,14 @@ pnpm dev import https://github.com/owner/repo/tree/main/skills/skill-name
 | Platform | Agents Path | Skills Path | Workflows Path |
 | :--- | :--- | :--- | :--- |
 | Antigravity | *Not Supported* | `~/.gemini/antigravity/global_skills` | `~/.gemini/antigravity/global_workflows` |
+| Codex | `~/.codex/skills` | `~/.codex/skills` | `~/.codex/skills` |
 | Gemini CLI | `~/.gemini/agents` | `~/.gemini/skills` | `~/.gemini/commands` |
 | GitHub Copilot | `~/.copilot/agents` | `~/.copilot/skills` | `~/.copilot/prompts` |
 | Windsurf | *Not Supported* | `~/.codeium/windsurf/skills` | `~/.codeium/windsurf/global_workflows` |
 <!-- SUPPORTED_AGENTS_END -->
 
+For Codex, this package installs skills directly and converts agents and workflows into Codex skill packages under `~/.codex/skills`.
+
 ## Development
 
 1. **Clone the repository:**

package/dist/bin/cli.js

@@ -7,7 +7,7 @@ import pc5 from "picocolors";
 
 // src/commands/add.ts
 import os3 from "node:os";
-import path4 from "node:path";
+import path5 from "node:path";
 import {
   cancel,
   confirm,
@@ -19,7 +19,7 @@ import {
   select,
   spinner
 } from "@clack/prompts";
-import fs2 from "fs-extra";
+import fs3 from "fs-extra";
 import pc from "picocolors";
 
 // src/utils/github.ts
@@ -106,22 +106,26 @@ var __dirname = path2.dirname(__filename);
 var PROJECT_ROOT = path2.resolve(__dirname, "../..");
 var PLATFORM_LABELS = {
   antigravity: "Antigravity",
+  codex: "Codex",
   gemini: "Gemini CLI",
   copilot: "GitHub Copilot",
   windsurf: "Windsurf"
 };
 var PLATFORM_PATHS_SKILLS = {
   antigravity: path2.join(os2.homedir(), ".gemini/antigravity/global_skills"),
+  codex: path2.join(os2.homedir(), ".codex/skills"),
   copilot: path2.join(os2.homedir(), ".copilot/skills"),
   gemini: path2.join(os2.homedir(), ".gemini/skills"),
   windsurf: path2.join(os2.homedir(), ".codeium/windsurf/skills")
 };
 var PLATFORM_PATHS_AGENTS = {
+  codex: path2.join(os2.homedir(), ".codex/skills"),
   copilot: path2.join(os2.homedir(), ".copilot/agents"),
   gemini: path2.join(os2.homedir(), ".gemini/agents")
 };
 var PLATFORM_PATHS_WORKFLOWS = {
   antigravity: path2.join(os2.homedir(), ".gemini/antigravity/global_workflows"),
+  codex: path2.join(os2.homedir(), ".codex/skills"),
   copilot: path2.join(os2.homedir(), ".copilot/prompts"),
   gemini: path2.join(os2.homedir(), ".gemini/commands"),
   windsurf: path2.join(os2.homedir(), ".codeium/windsurf/global_workflows")
@@ -153,8 +157,118 @@ var AntigravityHandler = class {
   }
 };
 
-// src/utils/platforms/copilot.ts
+// src/utils/platforms/codex.ts
+import path3 from "node:path";
+import fs2 from "fs-extra";
 import yaml from "js-yaml";
+var frontmatterRegex = /^---\n([\s\S]*?)\n---/;
+var CODEX_TYPE_FIELD = "x-ai-agents-type";
+function extractTitle(body) {
+  const match = body.match(/^#\s+(.+)$/m);
+  return match?.[1]?.trim();
+}
+function buildDescription(type, itemName, title) {
+  const subject = title || itemName;
+  if (type === "agent") {
+    return `This skill should be used when Codex needs to follow the ${subject} agent instructions.`;
+  }
+  if (type === "workflow") {
+    return `This skill should be used when Codex needs to follow the ${subject} workflow instructions.`;
+  }
+  return `This skill should be used when Codex needs the ${subject} skill.`;
+}
+function toYamlFrontmatter(name, description, extraFields = {}) {
+  const normalizedName = name.replace(/\n+/g, " ").trim();
+  const normalizedDescription = description.replace(/\n+/g, " ").trim();
+  return yaml.dump(
+    {
+      name: normalizedName,
+      description: normalizedDescription,
+      ...extraFields
+    },
+    { lineWidth: -1 }
+  ).trimEnd();
+}
+function parseCodexType(content) {
+  const match = content.match(frontmatterRegex);
+  if (!match) return "skill";
+  try {
+    const parsed = yaml.load(match[1]);
+    if (parsed && typeof parsed === "object") {
+      const type = parsed[CODEX_TYPE_FIELD];
+      if (type === "agent" || type === "workflow" || type === "skill") {
+        return type;
+      }
+    }
+  } catch {
+    return "skill";
+  }
+  return "skill";
+}
+async function codexEntryMatchesType(basePath, entry, requestedType) {
+  let targetPath = null;
+  if (entry.isDirectory()) {
+    targetPath = path3.join(basePath, entry.name, "SKILL.md");
+  } else if (entry.isFile() && entry.name.endsWith(".md")) {
+    targetPath = path3.join(basePath, entry.name);
+  }
+  if (!targetPath) return false;
+  try {
+    const content = await fs2.readFile(targetPath, "utf-8");
+    return parseCodexType(content) === requestedType;
+  } catch {
+    return false;
+  }
+}
+var CodexHandler = class {
+  platform = "codex";
+  getTargetFileName(itemName, type) {
+    if (type === "agent" || type === "workflow") {
+      return path3.join(path3.parse(itemName).name, "SKILL.md");
+    }
+    return itemName;
+  }
+  transform(content, type, itemName) {
+    if (type === "skill") return content;
+    if (type !== "agent" && type !== "workflow") return content;
+    let name = itemName;
+    let description = "";
+    let body = content.trim();
+    const match = content.match(frontmatterRegex);
+    if (match) {
+      body = content.replace(frontmatterRegex, "").trim();
+      try {
+        const parsed = yaml.load(match[1]);
+        if (parsed && typeof parsed === "object") {
+          const frontmatter = parsed;
+          if (typeof frontmatter.name === "string" && frontmatter.name.trim()) {
+            name = frontmatter.name.trim();
+          }
+          if (typeof frontmatter.description === "string" && frontmatter.description.trim()) {
+            description = frontmatter.description.trim();
+          }
+        }
+      } catch {
+        name = itemName;
+        description = "";
+      }
+    }
+    if (!description) {
+      description = buildDescription(type, itemName, extractTitle(body));
+    }
+    const yamlStr = toYamlFrontmatter(name, description, {
+      [CODEX_TYPE_FIELD]: type
+    });
+    return `---
+${yamlStr}
+---
+
+${body}`;
+  }
+};
+
+// src/utils/platforms/copilot.ts
+import yaml2 from "js-yaml";
 var CopilotHandler = class {
   platform = "copilot";
   getTargetFileName(itemName, type) {
@@ -165,8 +279,8 @@ var CopilotHandler = class {
   }
   transform(content, type, itemName) {
     if (type !== "agent") return content;
-    const frontmatterRegex = /^---\n([\s\S]*?)\n---/;
-    const match = content.match(frontmatterRegex);
+    const frontmatterRegex2 = /^---\n([\s\S]*?)\n---/;
+    const match = content.match(frontmatterRegex2);
     let frontmatter = {
       name: itemName,
       description: "",
@@ -176,7 +290,7 @@ var CopilotHandler = class {
     let body = content;
     if (match) {
       try {
-        const parsed = yaml.load(match[1]);
+        const parsed = yaml2.load(match[1]);
         frontmatter = { ...frontmatter, ...parsed };
         frontmatter.target = "github-copilot";
         frontmatter.tools = [
@@ -186,11 +300,11 @@ var CopilotHandler = class {
           "grep_search",
           "githubRepo"
         ];
-        body = content.replace(frontmatterRegex, "").trim();
+        body = content.replace(frontmatterRegex2, "").trim();
       } catch (_) {
       }
     }
-    const yamlStr = yaml.dump(frontmatter);
+    const yamlStr = yaml2.dump(frontmatter);
     return `---
 ${yamlStr}---
 
@@ -212,7 +326,7 @@ var DefaultHandler = class {
 };
 
 // src/utils/platforms/gemini.ts
-import yaml2 from "js-yaml";
+import yaml3 from "js-yaml";
 
 // src/utils/toml.ts
 function convertToGeminiCommandTOML(markdownContent) {
@@ -255,8 +369,8 @@ var GeminiHandler = class {
       return convertToGeminiCommandTOML(content);
     }
     if (type === "agent") {
-      const frontmatterRegex = /^---\n([\s\S]*?)\n---/;
-      const match = content.match(frontmatterRegex);
+      const frontmatterRegex2 = /^---\n([\s\S]*?)\n---/;
+      const match = content.match(frontmatterRegex2);
       let frontmatter = {
         name: itemName,
         description: "",
@@ -278,7 +392,7 @@ var GeminiHandler = class {
       let body = content;
       if (match) {
         try {
-          const parsed = yaml2.load(match[1]);
+          const parsed = yaml3.load(match[1]);
           frontmatter = { ...frontmatter, ...parsed };
           frontmatter.tools = [
             "list_directory",
@@ -295,11 +409,11 @@ var GeminiHandler = class {
             "activate_skill"
           ];
           delete frontmatter.skills;
-          body = content.replace(frontmatterRegex, "").trim();
+          body = content.replace(frontmatterRegex2, "").trim();
         } catch (_) {
         }
       }
-      const yamlStr = yaml2.dump(frontmatter);
+      const yamlStr = yaml3.dump(frontmatter);
       return `---
 ${yamlStr}---
 
@@ -310,12 +424,12 @@ ${body}`;
 };
 
 // src/utils/platforms/windsurf.ts
-import path3 from "node:path";
+import path4 from "node:path";
 var WindsurfHandler = class {
   platform = "windsurf";
   getTargetFileName(itemName, type) {
     if (type === "agent") {
-      return path3.join(path3.parse(itemName).name, "AGENTS.md");
+      return path4.join(path4.parse(itemName).name, "AGENTS.md");
     }
     return itemName;
   }
@@ -330,6 +444,7 @@ function registerHandler(handler) {
   handlers.set(handler.platform, handler);
 }
 registerHandler(new AntigravityHandler());
+registerHandler(new CodexHandler());
 registerHandler(new CopilotHandler());
 registerHandler(new GeminiHandler());
 registerHandler(new WindsurfHandler());
@@ -347,15 +462,15 @@ function getPlatformOptions(type) {
   }));
 }
 async function installItem(itemName, overwrite, sourcePath, targetBaseDir) {
-  const targetPath = path4.join(targetBaseDir, itemName);
-  if (!await fs2.pathExists(sourcePath)) {
+  const targetPath = path5.join(targetBaseDir, itemName);
+  if (!await fs3.pathExists(sourcePath)) {
     throw new Error(`Item '${itemName}' not found at ${sourcePath}`);
   }
-  if (!overwrite && await fs2.pathExists(targetPath)) {
+  if (!overwrite && await fs3.pathExists(targetPath)) {
     return false;
   }
-  await fs2.ensureDir(targetBaseDir);
-  await fs2.copy(sourcePath, targetPath, { overwrite });
+  await fs3.ensureDir(targetBaseDir);
+  await fs3.copy(sourcePath, targetPath, { overwrite });
   return true;
 }
 async function add(type, url, options) {
@@ -403,12 +518,12 @@ async function add(type, url, options) {
         }
       } else {
         const sourceDir = TYPE_DIRS[normalizedType];
-        if (!await fs2.pathExists(sourceDir)) {
+        if (!await fs3.pathExists(sourceDir)) {
           cancel(`${normalizedType} directory not found!`);
           process.exit(1);
           return;
         }
-        const entries = await fs2.readdir(sourceDir, { withFileTypes: true });
+        const entries = await fs3.readdir(sourceDir, { withFileTypes: true });
         const availableItems = entries.filter(
           (entry) => entry.isDirectory() || (normalizedType === "workflow" || normalizedType === "agent") && entry.isFile() && entry.name.endsWith(".md")
         ).map((entry) => ({ label: entry.name, value: entry.name })).sort((a, b) => a.label.localeCompare(b.label));
@@ -443,7 +558,7 @@ async function add(type, url, options) {
         required: true
       });
       if (isCancel(platforms)) {
-        if (tempDir) await fs2.remove(tempDir);
+        if (tempDir) await fs3.remove(tempDir);
         if (isSingleShot) break;
         currentType = void 0;
         continue;
@@ -453,9 +568,11 @@ async function add(type, url, options) {
       for (const platform of selectedPlatforms) {
         const targetBase = supportedPaths[platform];
         if (!targetBase) continue;
+        const handler = getHandler(platform);
         for (const item of selectedItems) {
-          const targetPath = path4.join(targetBase, item);
-          if (await fs2.pathExists(targetPath)) {
+          const targetItemName = handler.getTargetFileName(item, normalizedType);
+          const targetPath = path5.join(targetBase, targetItemName);
+          if (await fs3.pathExists(targetPath)) {
             existingItems.push({ item, platform });
           }
         }
@@ -472,7 +589,7 @@ async function add(type, url, options) {
           initialValue: false
         });
         if (isCancel(shouldOverwrite)) {
-          if (tempDir) await fs2.remove(tempDir);
+          if (tempDir) await fs3.remove(tempDir);
           if (isSingleShot) break;
           currentType = void 0;
           continue;
@@ -497,15 +614,15 @@ async function add(type, url, options) {
           try {
             let currentSourcePath;
             if (url && tempDir) {
-              const potentialFile = path4.join(tempDir, item);
-              if (await fs2.pathExists(potentialFile) && (await fs2.stat(potentialFile)).isFile()) {
+              const potentialFile = path5.join(tempDir, item);
+              if (await fs3.pathExists(potentialFile) && (await fs3.stat(potentialFile)).isFile()) {
                 currentSourcePath = potentialFile;
               } else {
                 currentSourcePath = tempDir;
               }
             } else {
-              const src = path4.join(TYPE_DIRS[normalizedType], item);
-              if ((await fs2.stat(src)).isFile()) {
+              const src = path5.join(TYPE_DIRS[normalizedType], item);
+              if ((await fs3.stat(src)).isFile()) {
                 currentSourcePath = src;
               } else {
                 currentSourcePath = src;
@@ -517,18 +634,18 @@ async function add(type, url, options) {
               normalizedType
             );
             if ((normalizedType === "agent" || normalizedType === "workflow") && currentSourcePath.endsWith(".md")) {
-              const targetPath = path4.join(targetBase, targetItemName);
-              if (!overwrite && await fs2.pathExists(targetPath)) {
+              const targetPath = path5.join(targetBase, targetItemName);
+              if (!overwrite && await fs3.pathExists(targetPath)) {
                 skippedCount++;
               } else {
-                let content = await fs2.readFile(currentSourcePath, "utf-8");
+                let content = await fs3.readFile(currentSourcePath, "utf-8");
                 content = handler.transform(
                   content,
                   normalizedType,
-                  path4.parse(item).name
+                  path5.parse(item).name
                 );
-                await fs2.ensureDir(path4.dirname(targetPath));
-                await fs2.writeFile(targetPath, content);
+                await fs3.ensureDir(path5.dirname(targetPath));
+                await fs3.writeFile(targetPath, content);
                 installedCount++;
               }
               continue;
@@ -551,7 +668,7 @@ async function add(type, url, options) {
         }
       }
       if (tempDir) {
-        await fs2.remove(tempDir);
+        await fs3.remove(tempDir);
       }
       if (errors.length > 0) {
         s.stop(
@@ -571,7 +688,7 @@ async function add(type, url, options) {
         );
       }
     } catch (error) {
-      if (tempDir) await fs2.remove(tempDir);
+      if (tempDir) await fs3.remove(tempDir);
       cancel(`An error occurred: ${error}`);
       process.exit(1);
       return;
@@ -585,7 +702,7 @@ async function add(type, url, options) {
 }
 
 // src/commands/import.ts
-import path5 from "node:path";
+import path6 from "node:path";
 import {
   cancel as cancel2,
   confirm as confirm2,
@@ -596,7 +713,7 @@ import {
   spinner as spinner2,
   text
 } from "@clack/prompts";
-import fs3 from "fs-extra";
+import fs4 from "fs-extra";
 import pc2 from "picocolors";
 async function importItem(type, url, options) {
   if (!options?.skipIntro) {
@@ -654,12 +771,12 @@ async function importItem(type, url, options) {
       throw e;
     }
     const shouldFlatten = (normalizedType === "agent" || normalizedType === "workflow") && !isFile;
-    const targetPath = shouldFlatten ? targetBaseDir : path5.join(targetBaseDir, itemName);
+    const targetPath = shouldFlatten ? targetBaseDir : path6.join(targetBaseDir, itemName);
     if (shouldFlatten) {
-      const srcFiles = await fs3.readdir(tempDir);
+      const srcFiles = await fs4.readdir(tempDir);
       const conflicts = [];
       for (const file of srcFiles) {
-        if (await fs3.pathExists(path5.join(targetBaseDir, file))) {
+        if (await fs4.pathExists(path6.join(targetBaseDir, file))) {
           conflicts.push(file);
         }
       }
@@ -673,40 +790,40 @@ async function importItem(type, url, options) {
           initialValue: false
         });
         if (isCancel2(shouldOverwrite) || !shouldOverwrite) {
-          await fs3.remove(tempDir);
+          await fs4.remove(tempDir);
           return;
         }
       }
-    } else if (await fs3.pathExists(targetPath)) {
+    } else if (await fs4.pathExists(targetPath)) {
       const shouldOverwrite = await confirm2({
         message: `${normalizedType} '${itemName}' already exists in the repo. Overwrite?`,
         initialValue: false
       });
       if (isCancel2(shouldOverwrite) || !shouldOverwrite) {
-        await fs3.remove(tempDir);
+        await fs4.remove(tempDir);
         return;
       }
     }
     s.start(`Importing ${itemName} to ${targetBaseDir}...`);
-    await fs3.ensureDir(targetBaseDir);
+    await fs4.ensureDir(targetBaseDir);
     if (isFile) {
-      await fs3.copy(path5.join(tempDir, itemName), targetPath, {
+      await fs4.copy(path6.join(tempDir, itemName), targetPath, {
         overwrite: true
       });
     } else {
       if (shouldFlatten) {
-        await fs3.copy(tempDir, targetBaseDir, { overwrite: true });
+        await fs4.copy(tempDir, targetBaseDir, { overwrite: true });
       } else {
-        await fs3.copy(tempDir, targetPath, { overwrite: true });
+        await fs4.copy(tempDir, targetPath, { overwrite: true });
       }
     }
     s.stop(pc2.green(`Successfully imported ${itemName}!`));
-    await fs3.remove(tempDir);
+    await fs4.remove(tempDir);
     if (!options?.skipIntro) {
       outro2(`${normalizedType} available at: ${targetPath}`);
     }
   } catch (error) {
-    if (tempDir) await fs3.remove(tempDir);
+    if (tempDir) await fs4.remove(tempDir);
     cancel2(`An error occurred: ${error}`);
     process.exit(1);
     return;
@@ -715,7 +832,7 @@ async function importItem(type, url, options) {
 
 // src/commands/list.ts
 import { intro as intro3, isCancel as isCancel3, outro as outro3, select as select3 } from "@clack/prompts";
-import fs4 from "fs-extra";
+import fs5 from "fs-extra";
 import pc3 from "picocolors";
 async function performListing(type, local) {
   const normalizedType = type.toLowerCase().endsWith("s") ? type.slice(0, -1) : type.toLowerCase();
@@ -725,13 +842,23 @@ async function performListing(type, local) {
     let foundAny = false;
     for (const [platform, pathStr] of Object.entries(targetPaths)) {
       const fullPath = pathStr;
-      if (await fs4.pathExists(fullPath)) {
-        const entries = await fs4.readdir(fullPath, {
+      if (await fs5.pathExists(fullPath)) {
+        const entries = await fs5.readdir(fullPath, {
           withFileTypes: true
         });
-        const items = entries.filter(
-          (entry) => entry.isDirectory() || entry.isFile() && entry.name.endsWith(".md")
-        ).map((entry) => entry.name).sort();
+        const items = [];
+        for (const entry of entries) {
+          if (platform === "codex") {
+            if (await codexEntryMatchesType(fullPath, entry, normalizedType)) {
+              items.push(entry.name);
+            }
+            continue;
+          }
+          if (entry.isDirectory() || entry.isFile() && entry.name.endsWith(".md")) {
+            items.push(entry.name);
+          }
+        }
+        items.sort();
         if (items.length > 0) {
           foundAny = true;
           console.log(pc3.cyan(`  ${platform}:`));
@@ -755,13 +882,13 @@ async function performListing(type, local) {
       return;
     }
     const dirPath = TYPE_DIRS[normalizedType];
-    if (!await fs4.pathExists(dirPath)) {
+    if (!await fs5.pathExists(dirPath)) {
       console.log(
         pc3.yellow(`No ${normalizedType} directory found at: ${dirPath}`)
       );
       return;
     }
-    const entries = await fs4.readdir(dirPath, { withFileTypes: true });
+    const entries = await fs5.readdir(dirPath, { withFileTypes: true });
     const items = entries.filter(
       (entry) => entry.isDirectory() || normalizedType !== "skill" && entry.isFile() && entry.name.endsWith(".md")
     ).map((entry) => entry.name).sort();
@@ -825,7 +952,7 @@ async function list(type, options) {
 }
 
 // src/commands/remove.ts
-import path6 from "node:path";
+import path7 from "node:path";
 import {
   confirm as confirm3,
   intro as intro4,
@@ -836,7 +963,7 @@ import {
   select as select4,
   spinner as spinner3
 } from "@clack/prompts";
-import fs5 from "fs-extra";
+import fs6 from "fs-extra";
 import pc4 from "picocolors";
 async function remove(type, options) {
   if (!options?.skipIntro) {
@@ -865,12 +992,22 @@ async function remove(type, options) {
     const uniqueItems = /* @__PURE__ */ new Set();
     const s = spinner3();
     s.start("Scanning for installed items...");
-    for (const pathStr of Object.values(targetPaths)) {
-      if (await fs5.pathExists(pathStr)) {
-        const entries = await fs5.readdir(pathStr, {
+    for (const [platform, pathStr] of Object.entries(targetPaths)) {
+      if (await fs6.pathExists(pathStr)) {
+        const entries = await fs6.readdir(pathStr, {
           withFileTypes: true
         });
         for (const entry of entries) {
+          if (platform === "codex") {
+            if (await codexEntryMatchesType(
+              pathStr,
+              entry,
+              normalizedType
+            )) {
+              uniqueItems.add(entry.name);
+            }
+            continue;
+          }
           if (entry.isDirectory() || normalizedType === "workflow" && entry.isFile() && entry.name.endsWith(".md") || normalizedType === "agent" && entry.isFile() && entry.name.endsWith(".md")) {
             uniqueItems.add(entry.name);
           }
@@ -929,11 +1066,11 @@ async function remove(type, options) {
       const targetBase = targetPaths[platform];
       if (!targetBase) continue;
       for (const item of selectedItems) {
-        const targetPath = path6.join(targetBase, item);
-        if (await fs5.pathExists(targetPath)) {
+        const targetPath = path7.join(targetBase, item);
+        if (await fs6.pathExists(targetPath)) {
           sDel.message(`Removing ${pc4.bold(item)} from ${pc4.cyan(platform)}...`);
           try {
-            await fs5.remove(targetPath);
+            await fs6.remove(targetPath);
             removedCount++;
           } catch (err) {
             const msg = err instanceof Error ? err.message : String(err);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kurokeita/add-skill",
-	"version": "1.9.0",
+	"version": "1.10.0",
 	"description": "CLI to install AI agent skills to various platforms",
 	"type": "module",
 	"bin": {