@laitszkin/apollo-toolkit 3.1.0 → 3.1.1

package/CHANGELOG.md

@@ -7,6 +7,12 @@ All notable changes to this repository are documented in this file.
 ### Changed
 - None yet.
 
+## [v3.1.1] - 2026-04-22
+
+### Changed
+- Fix Apollo Toolkit installers so `codex`-only skills stay scoped to Codex targets, while shared skills continue to install across the selected destinations.
+- Align the CLI welcome/help text, non-interactive guidance, and README examples with the supported `agents` target and current installer behavior.
+
 ## [v3.1.0] - 2026-04-22
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # Apollo Toolkit Skills
 
-A curated skill catalog for Codex, OpenClaw, Trae, and Claude Code with a managed installer that keeps the toolkit in `~/.apollo-toolkit` and copies each skill into the targets you choose.
+A curated skill catalog for Codex, OpenClaw, Trae, Agents, and Claude Code with a managed installer that keeps the toolkit in `~/.apollo-toolkit` and copies each skill into the targets you choose.
 
 ## Included skills
 
@@ -63,7 +63,7 @@ npx @laitszkin/apollo-toolkit
 The interactive installer:
 - shows a branded `Apollo Toolkit` terminal welcome screen with a short staged reveal
 - installs a managed copy into `~/.apollo-toolkit`
-- lets you multi-select `codex`, `openclaw`, `trae`, `claude-code`, or `all`
+- lets you multi-select `codex`, `openclaw`, `trae`, `agents`, `claude-code`, or `all`
 - copies `~/.apollo-toolkit/<skill>` into each selected target
 - removes stale previously installed skill directories that existed in the previous installed version but no longer exist in the current package skill list
 - replaces legacy symlink-based installs created by older Apollo Toolkit installers with real copied directories
@@ -91,6 +91,7 @@ apltk open-github-issue --help
 
 ```bash
 npx @laitszkin/apollo-toolkit codex
+npx @laitszkin/apollo-toolkit agents
 npx @laitszkin/apollo-toolkit claude-code
 npx @laitszkin/apollo-toolkit codex openclaw
 npx @laitszkin/apollo-toolkit all
@@ -103,6 +104,7 @@ APOLLO_TOOLKIT_HOME=~/custom-toolkit npx @laitszkin/apollo-toolkit codex
 CODEX_SKILLS_DIR=~/custom-codex-skills npx @laitszkin/apollo-toolkit codex
 OPENCLAW_HOME=~/.openclaw npx @laitszkin/apollo-toolkit openclaw
 TRAE_SKILLS_DIR=~/.trae/skills npx @laitszkin/apollo-toolkit trae
+AGENTS_SKILLS_DIR=~/.agents/skills npx @laitszkin/apollo-toolkit agents
 CLAUDE_CODE_SKILLS_DIR=~/.claude/skills npx @laitszkin/apollo-toolkit claude-code
 ```
 
@@ -120,12 +122,14 @@ Installers still live in `scripts/` for local repository usage and curl / iwr in
 ./scripts/install_skills.sh codex
 ./scripts/install_skills.sh openclaw
 ./scripts/install_skills.sh trae
+./scripts/install_skills.sh agents
 ./scripts/install_skills.sh all
 ```
 
 ```powershell
 ./scripts/install_skills.ps1
 ./scripts/install_skills.ps1 codex
+./scripts/install_skills.ps1 agents
 ./scripts/install_skills.ps1 all
 ```
 

package/lib/cli.js

@@ -3,6 +3,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const {
+  TARGET_DEFINITIONS,
   VALID_MODES,
   installLinks,
   normalizeModes,
@@ -15,11 +16,7 @@ const { checkForPackageUpdate } = require('./updater');
 
 const TARGET_OPTIONS = [
   { id: 'all', label: 'All', description: 'Install every supported target below' },
-  { id: 'codex', label: 'Codex', description: '~/.codex/skills' },
-  { id: 'openclaw', label: 'OpenClaw', description: '~/.openclaw/workspace*/skills' },
-  { id: 'trae', label: 'Trae', description: '~/.trae/skills' },
-  { id: 'agents', label: 'Agents', description: '~/.agents/skills' },
-  { id: 'claude-code', label: 'Claude Code', description: '~/.claude/skills' },
+  ...TARGET_DEFINITIONS,
 ];
 
 const WORDMARK_LINES = [
@@ -64,6 +61,22 @@ function buildBanner({ version, colorEnabled }) {
   ].join('\n');
 }
 
+function buildModeUsagePattern() {
+  return `${VALID_MODES.join('|')}|all`;
+}
+
+function buildInteractiveModeHint() {
+  const quotedModes = [...VALID_MODES, 'all'].map((mode) => `\`${mode}\``);
+  return `${quotedModes.slice(0, -1).join(', ')}, or ${quotedModes.at(-1)}`;
+}
+
+function buildSupportedTargetLines({ colorEnabled }) {
+  const labelWidth = TARGET_DEFINITIONS.reduce((max, target) => Math.max(max, target.label.length), 0);
+  return TARGET_DEFINITIONS.map((target) => (
+    `  ${color(target.label.padEnd(labelWidth, ' '), '1', colorEnabled)} ${target.description}`
+  )).join('\n');
+}
+
 function buildWelcomeScreen({ version, colorEnabled, stage = 4 }) {
   const lines = [buildBanner({ version, colorEnabled })];
 
@@ -90,11 +103,7 @@ function buildWelcomeScreen({ version, colorEnabled, stage = 4 }) {
     lines.push(
       '',
       color('Supported targets:', '2', colorEnabled),
-      `  ${color('Codex', '1', colorEnabled)}     ~/.codex/skills`,
-      `  ${color('OpenClaw', '1', colorEnabled)}  ~/.openclaw/workspace*/skills`,
-      `  ${color('Trae', '1', colorEnabled)}      ~/.trae/skills`,
-      `  ${color('Agents', '1', colorEnabled)}     ~/.agents/skills`,
-      `  ${color('Claude Code', '1', colorEnabled)} ~/.claude/skills`,
+      buildSupportedTargetLines({ colorEnabled }),
     );
   }
 
@@ -123,8 +132,8 @@ function buildHelpText({ version, colorEnabled }) {
     buildBanner({ version, colorEnabled }),
     '',
     'Usage:',
-    '  apltk [install] [codex|openclaw|trae|agents|claude-code|all]...',
-    '  apollo-toolkit [install] [codex|openclaw|trae|agents|claude-code|all]...',
+    `  apltk [install] [${buildModeUsagePattern()}]...`,
+    `  apollo-toolkit [install] [${buildModeUsagePattern()}]...`,
     '  apltk tools',
     '  apltk <tool> [...args]',
     '  apltk tools <tool> [...args]',
@@ -270,7 +279,7 @@ function renderSelectionScreen({ output, version, cursor, selected, message, env
 
 async function promptForModes({ stdin, stdout, version, env }) {
   if (!stdin.isTTY || !stdout.isTTY) {
-    throw new Error('Interactive install requires a TTY. Re-run with targets like `codex`, `openclaw`, `trae`, `claude-code`, or `all`.');
+    throw new Error(`Interactive install requires a TTY. Re-run with targets like ${buildInteractiveModeHint()}.`);
   }
 
   await animateWelcomeScreen({ output: stdout, version, env });

package/lib/installer.js

@@ -3,7 +3,14 @@ const fsp = require('node:fs/promises');
 const os = require('node:os');
 const path = require('node:path');
 
-const VALID_MODES = ['codex', 'openclaw', 'trae', 'agents', 'claude-code'];
+const TARGET_DEFINITIONS = Object.freeze([
+  { id: 'codex', label: 'Codex', description: '~/.codex/skills' },
+  { id: 'openclaw', label: 'OpenClaw', description: '~/.openclaw/workspace*/skills' },
+  { id: 'trae', label: 'Trae', description: '~/.trae/skills' },
+  { id: 'agents', label: 'Agents', description: '~/.agents/skills' },
+  { id: 'claude-code', label: 'Claude Code', description: '~/.claude/skills' },
+]);
+const VALID_MODES = TARGET_DEFINITIONS.map(({ id }) => id);
 const COPY_FILES = new Set(['AGENTS.md', 'CHANGELOG.md', 'LICENSE', 'README.md', 'package.json']);
 const COPY_DIRS = new Set(['scripts']);
 
@@ -63,7 +70,7 @@ function normalizeModes(inputModes) {
 
 async function listSkillNames(rootDir, modes = []) {
   const entries = await fsp.readdir(rootDir, { withFileTypes: true });
-  const skillNames = [];
+  const skillNames = new Set();
 
   for (const entry of entries) {
     if (!entry.isDirectory()) {
@@ -71,7 +78,7 @@ async function listSkillNames(rootDir, modes = []) {
     }
 
     if (fs.existsSync(path.join(rootDir, entry.name, 'SKILL.md'))) {
-      skillNames.push(entry.name);
+      skillNames.add(entry.name);
     }
   }
 
@@ -82,13 +89,42 @@ async function listSkillNames(rootDir, modes = []) {
       const codexEntries = await fsp.readdir(codexDir, { withFileTypes: true });
       for (const entry of codexEntries) {
         if (entry.isDirectory() && fs.existsSync(path.join(codexDir, entry.name, 'SKILL.md'))) {
-          skillNames.push(entry.name);
+          skillNames.add(entry.name);
         }
       }
     }
   }
 
-  return skillNames.sort();
+  return [...skillNames].sort();
+}
+
+async function listCodexSkillNames(rootDir) {
+  const codexDir = path.join(rootDir, 'codex');
+  if (!fs.existsSync(codexDir)) {
+    return [];
+  }
+
+  const entries = await fsp.readdir(codexDir, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isDirectory() && fs.existsSync(path.join(codexDir, entry.name, 'SKILL.md')))
+    .map((entry) => entry.name)
+    .sort();
+}
+
+function getTargetSkillNames({ targetMode, sharedSkillNames, codexSkillNames }) {
+  if (targetMode !== 'codex') {
+    return sharedSkillNames;
+  }
+
+  return [...new Set([...sharedSkillNames, ...codexSkillNames])].sort();
+}
+
+function resolveInstallSourcePath({ toolkitHome, targetMode, skillName, codexSkillNames }) {
+  if (targetMode === 'codex' && codexSkillNames.includes(skillName)) {
+    return path.join(toolkitHome, 'codex', skillName);
+  }
+
+  return path.join(toolkitHome, skillName);
 }
 
 function shouldCopyEntry(sourceRoot, entry) {
@@ -265,24 +301,33 @@ async function replaceWithCopy(sourcePath, targetPath) {
 
 async function installLinks({ toolkitHome, modes, env = process.env, previousSkillNames = [] }) {
   const normalizedModes = normalizeModes(modes);
-  const skillNames = await listSkillNames(toolkitHome, normalizedModes);
+  const sharedSkillNames = await listSkillNames(toolkitHome);
+  const codexSkillNames = normalizedModes.includes('codex') ? await listCodexSkillNames(toolkitHome) : [];
+  const skillNames = normalizedModes.includes('codex')
+    ? [...new Set([...sharedSkillNames, ...codexSkillNames])].sort()
+    : sharedSkillNames;
   const targets = await getTargetRoots(normalizedModes, env);
   const copiedPaths = [];
-  const staleSkillNames = previousSkillNames.filter((skillName) => !skillNames.includes(skillName));
 
   for (const target of targets) {
+    const targetSkillNames = getTargetSkillNames({
+      targetMode: target.mode,
+      sharedSkillNames,
+      codexSkillNames,
+    });
+    const staleSkillNames = previousSkillNames.filter((skillName) => !targetSkillNames.includes(skillName));
+
     await ensureDirectory(target.root);
     for (const staleSkillName of staleSkillNames) {
       await fsp.rm(path.join(target.root, staleSkillName), { recursive: true, force: true });
     }
-    for (const skillName of skillNames) {
-      // For codex skills, use the ./codex/ subdirectory as source
-      let sourcePath;
-      if (normalizedModes.includes('codex') && fs.existsSync(path.join(toolkitHome, 'codex', skillName))) {
-        sourcePath = path.join(toolkitHome, 'codex', skillName);
-      } else {
-        sourcePath = path.join(toolkitHome, skillName);
-      }
+    for (const skillName of targetSkillNames) {
+      const sourcePath = resolveInstallSourcePath({
+        toolkitHome,
+        targetMode: target.mode,
+        skillName,
+        codexSkillNames,
+      });
       const targetPath = path.join(target.root, skillName);
       await replaceWithCopy(sourcePath, targetPath);
       copiedPaths.push({ target: target.label, path: targetPath, skillName });
@@ -298,6 +343,7 @@ async function installLinks({ toolkitHome, modes, env = process.env, previousSki
 
 module.exports = {
   expandUserPath,
+  TARGET_DEFINITIONS,
   VALID_MODES,
   getTargetRoots,
   installLinks,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laitszkin/apollo-toolkit",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "description": "Apollo Toolkit npm installer for managed skill copying across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",

package/scripts/install_skills.ps1

@@ -110,15 +110,16 @@ else {
   $RepoRoot = $ToolkitHome
 }
 
-function Get-SkillPaths {
+function Get-SkillPathGroups {
   param([string[]]$SelectedModes)
 
   $dirs = Get-ChildItem -Path $RepoRoot -Directory | Sort-Object Name
-  $skills = @()
+  $sharedSkills = @()
+  $codexSkills = @()
 
   foreach ($dir in $dirs) {
     if (Test-Path -LiteralPath (Join-Path $dir.FullName "SKILL.md") -PathType Leaf) {
-      $skills += $dir.FullName
+      $sharedSkills += $dir.FullName
     }
   }
 
@@ -129,17 +130,20 @@ function Get-SkillPaths {
       $codexDirs = Get-ChildItem -Path $codexDir -Directory | Sort-Object Name
       foreach ($dir in $codexDirs) {
         if (Test-Path -LiteralPath (Join-Path $dir.FullName "SKILL.md") -PathType Leaf) {
-          $skills += $dir.FullName
+          $codexSkills += $dir.FullName
         }
       }
     }
   }
 
-  if ($skills.Count -eq 0) {
+  if ($sharedSkills.Count -eq 0) {
     throw "No skill folders found in: $RepoRoot"
   }
 
-  return $skills
+  [PSCustomObject]@{
+    Shared = $sharedSkills
+    Codex = $codexSkills
+  }
 }
 
 function Add-ModeOnce {
@@ -343,15 +347,15 @@ if ($Modes.Count -gt 0 -and ($Modes[0] -eq "-h" -or $Modes[0] -eq "--help")) {
 }
 
 $selectedModes = Resolve-Modes -Requested $Modes
-$skillPaths = Get-SkillPaths -SelectedModes $selectedModes
+$skillPathGroups = Get-SkillPathGroups -SelectedModes $selectedModes
 
 foreach ($mode in $selectedModes) {
   switch ($mode) {
-    "codex" { Install-Codex -SkillPaths $skillPaths }
-    "openclaw" { Install-OpenClaw -SkillPaths $skillPaths }
-    "trae" { Install-Trae -SkillPaths $skillPaths }
-    "agents" { Install-Agents -SkillPaths $skillPaths }
-    "claude-code" { Install-ClaudeCode -SkillPaths $skillPaths }
+    "codex" { Install-Codex -SkillPaths ($skillPathGroups.Shared + $skillPathGroups.Codex) }
+    "openclaw" { Install-OpenClaw -SkillPaths $skillPathGroups.Shared }
+    "trae" { Install-Trae -SkillPaths $skillPathGroups.Shared }
+    "agents" { Install-Agents -SkillPaths $skillPathGroups.Shared }
+    "claude-code" { Install-ClaudeCode -SkillPaths $skillPathGroups.Shared }
     default { throw "Unknown mode: $mode" }
   }
 }

package/scripts/install_skills.sh

@@ -78,14 +78,16 @@ else
   SCRIPT_DIR="$REPO_ROOT/scripts"
 fi
 SELECTED_MODES=()
-SKILL_PATHS=()
+SHARED_SKILL_PATHS=()
+CODEX_SKILL_PATHS=()
 
 collect_skills() {
   local dir
-  SKILL_PATHS=()
+  SHARED_SKILL_PATHS=()
+  CODEX_SKILL_PATHS=()
   while IFS= read -r dir; do
     if [[ -f "$dir/SKILL.md" ]]; then
-      SKILL_PATHS+=("$dir")
+      SHARED_SKILL_PATHS+=("$dir")
     fi
   done < <(find "$REPO_ROOT" -mindepth 1 -maxdepth 1 -type d | sort)
 
@@ -95,13 +97,13 @@ collect_skills() {
     if [[ -d "$codex_dir" ]]; then
       while IFS= read -r dir; do
         if [[ -f "$dir/SKILL.md" ]]; then
-          SKILL_PATHS+=("$dir")
+          CODEX_SKILL_PATHS+=("$dir")
         fi
       done < <(find "$codex_dir" -mindepth 1 -maxdepth 1 -type d | sort)
     fi
   fi
 
-  if [[ ${#SKILL_PATHS[@]} -eq 0 ]]; then
+  if [[ ${#SHARED_SKILL_PATHS[@]} -eq 0 ]]; then
     echo "No skill folders found in: $REPO_ROOT" >&2
     exit 1
   fi
@@ -124,17 +126,17 @@ replace_with_copy() {
 }
 
 install_codex() {
-  local codex_skills_dir
+  local codex_skills_dir src
   codex_skills_dir="$(expand_user_path "${CODEX_SKILLS_DIR:-$HOME/.codex/skills}")"
 
   echo "Installing to codex: $codex_skills_dir"
-  for src in "${SKILL_PATHS[@]}"; do
+  for src in "${SHARED_SKILL_PATHS[@]}" "${CODEX_SKILL_PATHS[@]}"; do
     replace_with_copy "$src" "$codex_skills_dir"
   done
 }
 
 install_openclaw() {
-  local openclaw_home workspace skills_dir
+  local openclaw_home workspace skills_dir src
   local -a workspaces
 
   openclaw_home="$(expand_user_path "${OPENCLAW_HOME:-$HOME/.openclaw}")"
@@ -152,38 +154,38 @@ install_openclaw() {
   for workspace in "${workspaces[@]}"; do
     skills_dir="$workspace/skills"
     echo "Installing to openclaw workspace: $skills_dir"
-    for src in "${SKILL_PATHS[@]}"; do
+    for src in "${SHARED_SKILL_PATHS[@]}"; do
       replace_with_copy "$src" "$skills_dir"
     done
   done
 }
 
 install_trae() {
-  local trae_skills_dir
+  local trae_skills_dir src
   trae_skills_dir="$(expand_user_path "${TRAE_SKILLS_DIR:-$HOME/.trae/skills}")"
 
   echo "Installing to trae: $trae_skills_dir"
-  for src in "${SKILL_PATHS[@]}"; do
+  for src in "${SHARED_SKILL_PATHS[@]}"; do
     replace_with_copy "$src" "$trae_skills_dir"
   done
 }
 
 install_agents() {
-  local agents_skills_dir
+  local agents_skills_dir src
   agents_skills_dir="$(expand_user_path "${AGENTS_SKILLS_DIR:-$HOME/.agents/skills}")"
 
   echo "Installing to agents: $agents_skills_dir"
-  for src in "${SKILL_PATHS[@]}"; do
+  for src in "${SHARED_SKILL_PATHS[@]}"; do
     replace_with_copy "$src" "$agents_skills_dir"
   done
 }
 
 install_claude_code() {
-  local claude_code_skills_dir
+  local claude_code_skills_dir src
   claude_code_skills_dir="$(expand_user_path "${CLAUDE_CODE_SKILLS_DIR:-$HOME/.claude/skills}")"
 
   echo "Installing to claude-code: $claude_code_skills_dir"
-  for src in "${SKILL_PATHS[@]}"; do
+  for src in "${SHARED_SKILL_PATHS[@]}"; do
     replace_with_copy "$src" "$claude_code_skills_dir"
   done
 }
@@ -233,7 +235,7 @@ read_choice_from_user() {
   elif [[ -r /dev/tty ]]; then
     read -r -p "$prompt" result < /dev/tty
   else
-    echo "Interactive input unavailable. Pass mode arguments (e.g. codex/openclaw/trae/all)." >&2
+    echo "Interactive input unavailable. Pass mode arguments (e.g. codex/openclaw/trae/agents/claude-code/all)." >&2
     exit 1
   fi
 
@@ -264,7 +266,7 @@ choose_modes_interactive() {
       3) add_mode_once "trae" ;;
       4) add_mode_once "agents" ;;
       5) add_mode_once "claude-code" ;;
-      6) add_mode_once "codex"; add_mode_once "openclaw"; add_mode_once "trae"; add_mode_once "claude-code" ;;
+      6) add_mode_once "codex"; add_mode_once "openclaw"; add_mode_once "trae"; add_mode_once "agents"; add_mode_once "claude-code" ;;
       *)
         echo "Invalid choice: $raw_choice" >&2
         exit 1