@supatent/skills 0.3.0 → 0.5.0

package/README.md

@@ -1,10 +1,10 @@
 # @supatent/skills
 
-Claude Code content authoring skills for [Supatent CMS](https://supatent.ai).
+Claude Code and Codex CLI content authoring skills for [Supatent CMS](https://supatent.ai).
 
 ## What this does
 
-Installs AI-powered content authoring skills into your Claude Code environment. Once installed, Claude Code can create and manage CMS content through natural conversation — blog posts, landing pages, and more.
+Installs AI-powered content authoring skills for Claude Code and Codex CLI. Once installed, agents can create and manage CMS content through natural conversation — blog posts, landing pages, and more.
 
 ## Quick start
 
@@ -12,15 +12,40 @@ Installs AI-powered content authoring skills into your Claude Code environment.
 npx @supatent/skills
 ```
 
-This installs skills as a Claude Code plugin to `.claude/plugins/supatent/` in your project. Then use `/supatent:core` in Claude Code to get started.
+In interactive terminals, the installer prompts for a target:
+
+- `claude`
+- `codex`
+- `both`
+
+In non-interactive environments (CI), the default is `claude`.
+
+### Explicit target selection
+
+```bash
+# Claude Code
+npx @supatent/skills --target claude
+
+# Codex CLI
+npx @supatent/skills --target codex
+
+# Both
+npx @supatent/skills --target both
+```
+
+Use `--codex-home` to override Codex install location (default: `$CODEX_HOME` or `~/.codex`):
+
+```bash
+npx @supatent/skills --target codex --codex-home /path/to/codex-home
+```
 
 ## Included skills
 
-| Skill | Command | Description |
-|-------|---------|-------------|
-| Core | `/supatent:core` | Schema management, content operations, validation |
-| Blog | `/supatent:blog` | Create and edit blog posts with structured fields |
-| Landing | `/supatent:landing` | Build landing pages with configurable sections |
+| Skill | Claude Code | Codex CLI | Description |
+|-------|-------------|-----------|-------------|
+| Core | `/supatent:core` | `supatent-core` | Schema management, content operations, validation |
+| Blog | `/supatent:content-blog` | `supatent-content-blog` | Create and edit blog posts with structured fields |
+| Landing | `/supatent:content-landing` | `supatent-content-landing` | Build landing pages with configurable sections |
 
 ## Updating
 
@@ -36,7 +61,7 @@ npx @supatent/skills --force
 
 - Node.js >= 20
 - A Supatent CMS project with `@supatent/cli` configured
-- Claude Code
+- Claude Code and/or Codex CLI
 
 ## License
 

package/bin/install.mjs

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
 
 // bin/install.mjs - Self-contained zero-dependency installer for @supatent/skills
-// Copies bundled skill files to .claude/skills/supatent/ with manifest tracking.
+// Copies bundled skill files to Claude Code and/or Codex CLI skill directories.
 
 import { readFile, writeFile, mkdir, copyFile, readdir, stat } from 'node:fs/promises';
 import { realpathSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { join, dirname, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
 import { createInterface } from 'node:readline/promises';
 
 // ---------------------------------------------------------------------------
@@ -16,10 +17,10 @@ import { createInterface } from 'node:readline/promises';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const SKILLS_SOURCE_DIR = join(__dirname, '..', 'skills');
-const PLUGIN_JSON_SOURCE = join(__dirname, '..', '.claude-plugin', 'plugin.json');
-const PLUGIN_ROOT_SUBDIR = join('.claude', 'plugins', 'supatent');
-const TARGET_SUBDIR = join(PLUGIN_ROOT_SUBDIR, 'skills');
+const CLAUDE_SKILLS_SOURCE_DIR = join(__dirname, '..', 'skills');
+const CODEX_SKILLS_SOURCE_DIR = join(__dirname, '..', 'skills-codex');
+const CLAUDE_TARGET_SUBDIR = join('.claude', 'skills');
+const VALID_TARGETS = new Set(['claude', 'codex', 'both']);
 
 // ---------------------------------------------------------------------------
 // Exported helpers (for testability)
@@ -67,6 +68,109 @@ export async function confirm(message, { force = false } = {}) {
   }
 }
 
+/**
+ * Prompt install target when not explicitly provided.
+ * Defaults to "claude" when stdin is non-interactive.
+ */
+export async function promptInstallTarget({ force = false } = {}) {
+  if (force || !process.stdin.isTTY) return 'claude';
+
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  try {
+    console.log('Select installation target:');
+    console.log('  1) Claude Code');
+    console.log('  2) Codex CLI');
+    console.log('  3) Both');
+
+    while (true) {
+      const answer = (await rl.question('Target [1/2/3] (default: 1): ')).trim().toLowerCase();
+
+      if (answer === '' || answer === '1' || answer === 'claude') {
+        return 'claude';
+      }
+      if (answer === '2' || answer === 'codex') {
+        return 'codex';
+      }
+      if (answer === '3' || answer === 'both') {
+        return 'both';
+      }
+
+      console.log('Invalid choice. Enter 1, 2, 3, claude, codex, or both.');
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * Parse command line args.
+ */
+export function parseArgs(argv) {
+  const parsed = {
+    force: false,
+    help: false,
+    target: null,
+    codexHome: null,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+
+    if (arg === '--force' || arg === '-f' || arg === '--yes' || arg === '-y') {
+      parsed.force = true;
+      continue;
+    }
+
+    if (arg === '--help' || arg === '-h') {
+      parsed.help = true;
+      continue;
+    }
+
+    if (arg === '--target') {
+      i += 1;
+      if (!argv[i]) {
+        throw new Error('Missing value for --target. Use: claude, codex, or both.');
+      }
+      parsed.target = argv[i];
+      continue;
+    }
+
+    if (arg.startsWith('--target=')) {
+      parsed.target = arg.slice('--target='.length);
+      continue;
+    }
+
+    if (arg === '--codex-home') {
+      i += 1;
+      if (!argv[i]) {
+        throw new Error('Missing value for --codex-home.');
+      }
+      parsed.codexHome = argv[i];
+      continue;
+    }
+
+    if (arg.startsWith('--codex-home=')) {
+      parsed.codexHome = arg.slice('--codex-home='.length);
+      continue;
+    }
+
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  if (parsed.target) {
+    parsed.target = parsed.target.toLowerCase();
+    if (!VALID_TARGETS.has(parsed.target)) {
+      throw new Error(`Invalid --target value: ${parsed.target}. Use: claude, codex, or both.`);
+    }
+  }
+
+  return parsed;
+}
+
 /**
  * Read and parse .manifest.json. Returns null if missing or invalid.
  */
@@ -163,60 +267,76 @@ export async function getVersion() {
   return pkg.version;
 }
 
-// ---------------------------------------------------------------------------
-// Main installer flow
-// ---------------------------------------------------------------------------
-
-async function main() {
-  const args = process.argv.slice(2);
-  const force = args.includes('--force');
+/**
+ * Resolve default Codex home.
+ */
+export function getDefaultCodexHome() {
+  return process.env.CODEX_HOME ? resolve(process.env.CODEX_HOME) : join(homedir(), '.codex');
+}
 
-  const version = await getVersion();
-  const cwd = process.cwd();
-  const claudeDir = join(cwd, '.claude');
-  const targetDir = join(cwd, TARGET_SUBDIR);
-  const manifestPath = join(targetDir, '.manifest.json');
+function printHelp() {
+  console.log('Usage: npx @supatent/skills [options]');
+  console.log('');
+  console.log('Options:');
+  console.log('  --target <claude|codex|both>  Installation target (prompts when omitted in TTY)');
+  console.log('  --codex-home <path>           Override Codex home (default: $CODEX_HOME or ~/.codex)');
+  console.log('  -f, --force                   Auto-confirm prompts and overwrite user-modified files');
+  console.log('  -y, --yes                     Alias for --force');
+  console.log('  -h, --help                    Show this help');
+}
 
-  // -----------------------------------------------------------------------
-  // Step a: Check .claude/ directory
-  // -----------------------------------------------------------------------
-  let claudeExists = false;
+async function ensureDirectoryExists(dirPath, missingMessage, { force }) {
+  let exists = false;
   try {
-    const s = await stat(claudeDir);
-    claudeExists = s.isDirectory();
+    const s = await stat(dirPath);
+    exists = s.isDirectory();
   } catch {
     // does not exist
   }
 
-  if (!claudeExists) {
-    console.log('\x1b[33m!\x1b[0m No .claude/ directory found. This installer creates skill files for Claude Code.');
-    const ok = await confirm('Create .claude/ directory and continue?', { force });
-    if (!ok) {
-      console.log('Aborted.');
-      process.exitCode = 1;
-      return;
-    }
-    await mkdir(claudeDir, { recursive: true });
+  if (exists) return true;
+
+  if (missingMessage) {
+    console.log(`\x1b[33m!\x1b[0m ${missingMessage}`);
   }
 
+  const ok = await confirm(`Create ${dirPath} and continue?`, { force });
+  if (!ok) {
+    console.log('Aborted.');
+    return false;
+  }
+
+  await mkdir(dirPath, { recursive: true });
+  return true;
+}
+
+async function installSkillBundle({
+  sourceDir,
+  targetDir,
+  manifestPath,
+  targetLabel,
+  startHint,
+  force,
+  version,
+}) {
   // -----------------------------------------------------------------------
-  // Step b: Walk source skills/ directory and build source map
+  // Step a: Build source map
   // -----------------------------------------------------------------------
-  const sourceMap = await buildSourceMap(SKILLS_SOURCE_DIR);
+  const sourceMap = await buildSourceMap(sourceDir);
   const sourceFiles = Object.keys(sourceMap);
 
   // -----------------------------------------------------------------------
-  // Step c: Read existing manifest
+  // Step b: Read existing manifest
   // -----------------------------------------------------------------------
   const manifest = await readManifest(manifestPath);
 
   // -----------------------------------------------------------------------
-  // Step d: Compute diff
+  // Step c: Compute diff
   // -----------------------------------------------------------------------
   const diff = await computeDiff(sourceMap, manifest, targetDir);
 
   // -----------------------------------------------------------------------
-  // Step e: Handle user-modified files
+  // Step d: Handle user-modified files
   // -----------------------------------------------------------------------
   const filesToCopy = [...diff.newFiles, ...diff.changed];
   const skippedFiles = [];
@@ -234,14 +354,14 @@ async function main() {
   // Check if anything to do
   // -----------------------------------------------------------------------
   if (filesToCopy.length === 0 && skippedFiles.length === 0) {
-    console.log(`\x1b[32m\u2713\x1b[0m Already up to date (v${version})`);
+    console.log(`\x1b[32m\u2713\x1b[0m Already up to date (${targetLabel}, v${version})`);
     console.log('');
-    console.log('  Run \x1b[36m/supatent:core\x1b[0m to get started');
+    console.log(`  ${startHint}`);
     return;
   }
 
   // -----------------------------------------------------------------------
-  // Step f: Copy files
+  // Step e: Copy files
   // -----------------------------------------------------------------------
   const isFreshInstall = !manifest;
 
@@ -265,14 +385,7 @@ async function main() {
   }
 
   // -----------------------------------------------------------------------
-  // Step f2: Copy plugin.json
-  // -----------------------------------------------------------------------
-  const pluginDir = join(cwd, PLUGIN_ROOT_SUBDIR, '.claude-plugin');
-  await mkdir(pluginDir, { recursive: true });
-  await copyFile(PLUGIN_JSON_SOURCE, join(pluginDir, 'plugin.json'));
-
-  // -----------------------------------------------------------------------
-  // Step g: Write manifest
+  // Step f: Write manifest
   // -----------------------------------------------------------------------
   const manifestFiles = {};
 
@@ -302,16 +415,103 @@ async function main() {
   await writeFile(manifestPath, JSON.stringify(manifestData, null, 2) + '\n');
 
   // -----------------------------------------------------------------------
-  // Step h: Print summary
+  // Step g: Print summary
   // -----------------------------------------------------------------------
   console.log('');
   if (isFreshInstall) {
-    console.log(`\x1b[32m\u2713\x1b[0m Installed ${filesToCopy.length} files to ${PLUGIN_ROOT_SUBDIR}/ (v${version})`);
+    console.log(`\x1b[32m\u2713\x1b[0m Installed ${filesToCopy.length} files to ${targetDir} (${targetLabel}, v${version})`);
   } else {
-    console.log(`\x1b[32m\u2713\x1b[0m Updated ${filesToCopy.length} file${filesToCopy.length === 1 ? '' : 's'} in ${PLUGIN_ROOT_SUBDIR}/ (v${version})`);
+    console.log(`\x1b[32m\u2713\x1b[0m Updated ${filesToCopy.length} file${filesToCopy.length === 1 ? '' : 's'} in ${targetDir} (${targetLabel}, v${version})`);
   }
   console.log('');
-  console.log('  Run \x1b[36m/supatent:core\x1b[0m to get started');
+  console.log(`  ${startHint}`);
+}
+
+async function installClaude({ cwd, force, version }) {
+  const claudeDir = join(cwd, '.claude');
+  const targetDir = join(cwd, CLAUDE_TARGET_SUBDIR);
+  const manifestPath = join(targetDir, 'supatent-core', '.manifest.json');
+
+  const ok = await ensureDirectoryExists(
+    claudeDir,
+    'No .claude/ directory found. This installer creates skill files for Claude Code.',
+    { force },
+  );
+  if (!ok) {
+    process.exitCode = 1;
+    return;
+  }
+
+  await installSkillBundle({
+    sourceDir: CLAUDE_SKILLS_SOURCE_DIR,
+    targetDir,
+    manifestPath,
+    targetLabel: 'Claude Code',
+    startHint: 'Run \x1b[36m/supatent:core\x1b[0m to get started',
+    force,
+    version,
+  });
+}
+
+async function installCodex({ force, version, codexHomeOverride = null }) {
+  const codexHome = codexHomeOverride ? resolve(codexHomeOverride) : getDefaultCodexHome();
+  const targetDir = join(codexHome, 'skills');
+  const manifestPath = join(targetDir, 'supatent-core', '.manifest.json');
+
+  const ok = await ensureDirectoryExists(
+    codexHome,
+    `No Codex home directory found at ${codexHome}.`,
+    { force },
+  );
+  if (!ok) {
+    process.exitCode = 1;
+    return;
+  }
+
+  await installSkillBundle({
+    sourceDir: CODEX_SKILLS_SOURCE_DIR,
+    targetDir,
+    manifestPath,
+    targetLabel: 'Codex CLI',
+    startHint: 'Restart Codex CLI to pick up new skills',
+    force,
+    version,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Main installer flow
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help) {
+    printHelp();
+    return;
+  }
+
+  const version = await getVersion();
+  const cwd = process.cwd();
+  const force = args.force;
+
+  const target = args.target || await promptInstallTarget({ force });
+
+  if (target === 'both') {
+    console.log('Installing Supatent skills for Claude Code...');
+    await installClaude({ cwd, force, version });
+    console.log('');
+    console.log('Installing Supatent skills for Codex CLI...');
+    await installCodex({ force, version, codexHomeOverride: args.codexHome });
+    return;
+  }
+
+  if (target === 'codex') {
+    await installCodex({ force, version, codexHomeOverride: args.codexHome });
+    return;
+  }
+
+  await installClaude({ cwd, force, version });
 }
 
 // ---------------------------------------------------------------------------

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@supatent/skills",
-  "version": "0.3.0",
-  "description": "Claude Code content authoring skills for Supatent CMS",
+  "version": "0.5.0",
+  "description": "Claude Code and Codex CLI content authoring skills for Supatent CMS",
   "type": "module",
   "bin": {
     "supatent-skills": "bin/install.mjs"
@@ -9,7 +9,7 @@
   "files": [
     "bin",
     "skills",
-    ".claude-plugin"
+    "skills-codex"
   ],
   "devDependencies": {
     "eslint": "^9.16.0",
@@ -22,6 +22,7 @@
     "supatent",
     "cms",
     "claude-code",
+    "codex-cli",
     "skills",
     "content-authoring"
   ],

package/skills/{content-blog → supatent-content-blog}/SKILL.md

@@ -18,8 +18,8 @@ Load these files on-demand, not upfront. Read each file only when the situation
 | File | When to Read |
 |------|-------------|
 | `./blog-sections.md` | Creating or modifying blog schemas -- contains full JSON definitions for blog-post, blog-author, and blog-settings |
-| `../references/schema-reference.md` | Troubleshooting validation errors, checking field types, or looking up JSON-LD type details |
-| `../references/workflow-reference.md` | Running CLI operations (init, dev, push, pull, validate), fixing errors, or understanding dev mode behavior |
+| `../supatent-references/schema-reference.md` | Troubleshooting validation errors, checking field types, or looking up JSON-LD type details |
+| `../supatent-references/workflow-reference.md` | Running CLI operations (init, dev, push, pull, validate), fixing errors, or understanding dev mode behavior |
 
 ## Intent Detection
 
@@ -155,7 +155,7 @@ Read `./blog-sections.md` to get the schema definitions.
 
 If schemas already exist, skip this section entirely.
 
-After writing schema files, check `.supatent/.validation-status.json` to confirm validation passes. If errors appear, read `../references/workflow-reference.md` for fix instructions.
+After writing schema files, check `.supatent/.validation-status.json` to confirm validation passes. If errors appear, read `../supatent-references/workflow-reference.md` for fix instructions.
 
 ## Content Generation
 

package/skills/supatent-content-blog/blog-sections.md

@@ -0,0 +1,99 @@
+# Blog Schema Catalog
+
+Defines the schemas created by the blog content skill. The SKILL.md references this file for schema generation.
+
+## blog-post (Collection)
+
+Blog articles with title, body, SEO, and metadata.
+
+### Core Fields (always created)
+
+```json
+{
+  "slug": "blog-post",
+  "name": "Blog Post",
+  "description": "Blog articles with title, body, SEO, and metadata",
+  "isSingleton": false,
+  "fields": [
+    { "slug": "title", "name": "Title", "type": "text", "interface": "textInput", "order": 0 },
+    { "slug": "excerpt", "name": "Excerpt", "type": "text", "interface": "textarea", "order": 1 },
+    { "slug": "cover-image", "name": "Cover Image", "type": "image", "interface": "singleImage", "order": 2 },
+    { "slug": "body", "name": "Body", "type": "markdown", "interface": "markdownEditor", "order": 3 },
+    { "slug": "json-ld", "name": "Structured Data", "type": "jsonLd", "interface": "jsonLdEditor", "order": 4 }
+  ]
+}
+```
+
+### Optional Fields (suggest to user, add if they agree)
+
+Append these after core fields, adjusting `order` values accordingly:
+
+- `date-published` (text/textInput) -- publication date in YYYY-MM-DD format
+- `author` (text/textInput) -- author slug reference (matches blog-author item slug)
+- `category` (text/textInput) -- post category
+
+```json
+{ "slug": "date-published", "name": "Date Published", "type": "text", "interface": "textInput" }
+{ "slug": "author", "name": "Author", "type": "text", "interface": "textInput" }
+{ "slug": "category", "name": "Category", "type": "text", "interface": "textInput" }
+```
+
+## blog-author (Collection)
+
+Blog post authors. Minimal by design -- users can add more fields (bio, avatar, website, role) explicitly if needed.
+
+```json
+{
+  "slug": "blog-author",
+  "name": "Blog Author",
+  "description": "Blog post authors",
+  "isSingleton": false,
+  "fields": [
+    { "slug": "name", "name": "Name", "type": "text", "interface": "textInput", "order": 0 }
+  ]
+}
+```
+
+## blog-settings (Singleton)
+
+Global blog configuration. Singleton content files must use slug `default` (e.g., `default.en.json`).
+
+```json
+{
+  "slug": "blog-settings",
+  "name": "Blog Settings",
+  "description": "Global blog configuration",
+  "isSingleton": true,
+  "fields": [
+    { "slug": "blog-title", "name": "Blog Title", "type": "text", "interface": "textInput", "order": 0 },
+    { "slug": "blog-description", "name": "Blog Description", "type": "text", "interface": "textarea", "order": 1 },
+    { "slug": "posts-per-page", "name": "Posts Per Page", "type": "number", "interface": "numberInput", "order": 2 }
+  ]
+}
+```
+
+## JSON-LD Guidance (Article Type)
+
+Blog posts use `@type: "Article"` -- NOT `BlogPosting`. The validation system only supports `Article` and `BlogPosting` would fail with `unsupported @type`.
+
+**Recommended properties:** headline, author (Person with required name), datePublished, description, wordCount, articleSection
+
+**Image:** Requires URI format. Omit if actual URL is not known; note as TODO for user. Do NOT use asset slugs.
+
+### Minimal Example
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Article",
+  "headline": "Post Title Here",
+  "author": {
+    "@type": "Person",
+    "name": "Author Name"
+  },
+  "datePublished": "2026-01-15",
+  "description": "Brief summary of the post for search engines.",
+  "wordCount": 1200,
+  "articleSection": "Category"
+}
+```

package/skills/{content-landing → supatent-content-landing}/SKILL.md

@@ -18,8 +18,8 @@ Load these files on-demand, not upfront. Read each file only when the situation
 | File | When to Read |
 |------|-------------|
 | `./landing-sections.md` | Creating or modifying landing page schemas -- contains all 12 section definitions with field schemas and image guidance |
-| `../references/schema-reference.md` | Troubleshooting validation errors, checking field types, or looking up JSON-LD type details |
-| `../references/workflow-reference.md` | Running CLI operations (init, dev, push, pull, validate), fixing errors, or understanding dev mode behavior |
+| `../supatent-references/schema-reference.md` | Troubleshooting validation errors, checking field types, or looking up JSON-LD type details |
+| `../supatent-references/workflow-reference.md` | Running CLI operations (init, dev, push, pull, validate), fixing errors, or understanding dev mode behavior |
 
 ## Intent Detection
 
@@ -209,7 +209,7 @@ For the `landing-metadata` schema, add conditional JSON-LD fields based on secti
 
 Singleton content files use slug `default` (e.g., `default.en.json`).
 
-After writing schema files, check `.supatent/.validation-status.json` to confirm validation passes. If errors appear, read `../references/workflow-reference.md` for fix instructions.
+After writing schema files, check `.supatent/.validation-status.json` to confirm validation passes. If errors appear, read `../supatent-references/workflow-reference.md` for fix instructions.
 
 ## Content Generation