@maccesar/aiskills 1.16.0 → 1.16.1

package/lib/claude-plugin.js

@@ -0,0 +1,105 @@
+/**
+ * Detection of the maccesar-aiskills Claude Code marketplace plugin.
+ *
+ * When the plugin is installed, Claude Code already lists our skills and slash
+ * commands from its plugin cache, so the CLI must not also install its own copy
+ * into ~/.claude/ — that produces duplicate entries in the autocomplete.
+ *
+ * The subtlety, and the reason this lives in its own module: **the cache on disk
+ * does not mean the plugin is installed.** Uninstalling a plugin removes it from
+ * `enabledPlugins` in settings.json but leaves the cache directory behind.
+ * Treating that leftover directory as proof of installation makes the CLI skip
+ * work it should do, which leaves Claude Code with no skills at all and no way
+ * for the user to repair it by re-running install. So the question we answer here
+ * is "is the plugin enabled AND does it carry this file", never just the latter.
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+import {
+  CLAUDE_PLUGIN_KEY,
+  getClaudePluginSkillsPath,
+  getClaudeSettingsPaths,
+} from './config.js';
+
+/**
+ * Whether Claude Code currently has the aiskills plugin enabled.
+ * @param {string} baseDir - Optional base directory (defaults to homedir via config)
+ * @returns {boolean} True only when a settings file explicitly enables the plugin
+ */
+export function isClaudePluginEnabled(baseDir) {
+  for (const settingsPath of getClaudeSettingsPaths(baseDir)) {
+    try {
+      const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+      if (settings?.enabledPlugins?.[CLAUDE_PLUGIN_KEY] === true) {
+        return true;
+      }
+    } catch {
+      // Missing or malformed settings: nothing here says the plugin is enabled.
+      // Falling through to `false` is the safe direction — the cost of a wrong
+      // `false` is a duplicate entry, the cost of a wrong `true` is a user with
+      // no skills installed.
+    }
+  }
+  return false;
+}
+
+/**
+ * Whether a plugin cache directory exists at all, regardless of whether the
+ * plugin is enabled. An enabled plugin implies a cache; a cache implies nothing,
+ * because uninstalling leaves it behind. Diagnostics use this to tell "never
+ * installed" apart from "uninstalled, leftovers on disk".
+ * @param {string} baseDir - Optional base directory
+ * @returns {boolean}
+ */
+export function hasClaudePluginCache(baseDir) {
+  return existsSync(getClaudePluginSkillsPath(baseDir));
+}
+
+/**
+ * Whether any cached version of the plugin carries the given file.
+ * @param {string} kind - Subdirectory inside the plugin ('skills' or 'commands')
+ * @param {string} entry - Entry to look for (skill directory or command file)
+ * @param {string} baseDir - Optional base directory
+ * @returns {boolean} True if a cached version contains it
+ */
+function pluginCacheContains(kind, entry, baseDir) {
+  const pluginBase = getClaudePluginSkillsPath(baseDir);
+  if (!existsSync(pluginBase)) return false;
+  try {
+    return readdirSync(pluginBase).some((version) =>
+      existsSync(join(pluginBase, version, kind, entry))
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Whether the installed plugin already provides this skill to Claude Code.
+ * @param {string} skillName - Skill name (e.g. 'session-log')
+ * @param {string} baseDir - Optional base directory
+ * @returns {boolean}
+ */
+export function pluginProvidesSkill(skillName, baseDir) {
+  return isClaudePluginEnabled(baseDir) && pluginCacheContains('skills', skillName, baseDir);
+}
+
+/**
+ * Whether the installed plugin already provides this slash command.
+ * @param {string} commandName - Command name without the .md extension
+ * @param {string} baseDir - Optional base directory
+ * @returns {boolean}
+ */
+export function pluginProvidesCommand(commandName, baseDir) {
+  return (
+    isClaudePluginEnabled(baseDir) && pluginCacheContains('commands', `${commandName}.md`, baseDir)
+  );
+}
+
+export default {
+  isClaudePluginEnabled,
+  hasClaudePluginCache,
+  pluginProvidesSkill,
+  pluginProvidesCommand,
+};

package/lib/commands/doctor.js

@@ -16,6 +16,11 @@ import {
 } from '../config.js';
 import { hasHook } from '../hooks.js';
 import { readLastCheck } from '../cache.js';
+import {
+  isClaudePluginEnabled,
+  hasClaudePluginCache,
+  pluginProvidesSkill,
+} from '../claude-plugin.js';
 
 const CHECK = chalk.green('✓');
 const CROSS = chalk.red('✗');
@@ -79,8 +84,18 @@ export async function doctorCommand() {
   for (const platform of platforms) {
     const missing = [];
     const broken = [];
+    const servedByPlugin = [];
 
     for (const skill of SKILLS) {
+      // A skill the marketplace plugin provides is *supposed* to have no mirror
+      // here — the CLI removes it on purpose to avoid a duplicate entry. Counting
+      // it as missing turns a healthy marketplace install into a wall of errors
+      // telling the user to run a command that will correctly do nothing.
+      if (platform.name === 'claude' && pluginProvidesSkill(skill, homeDir)) {
+        servedByPlugin.push(skill);
+        continue;
+      }
+
       const linkPath = join(platform.skillsDir, skill);
       try {
         const stat = lstatSync(linkPath);
@@ -96,15 +111,26 @@ export async function doctorCommand() {
       }
     }
 
-    const linkedCount = SKILLS.length - missing.length - broken.length;
+    const expected = SKILLS.length - servedByPlugin.length;
+    const linkedCount = expected - missing.length - broken.length;
+    const pluginNote =
+      servedByPlugin.length > 0
+        ? chalk.dim(` (+${servedByPlugin.length} served by the marketplace plugin)`)
+        : '';
 
     if (missing.length === 0 && broken.length === 0) {
-      console.log(`    ${CHECK} ${platform.displayName}: ${SKILLS.length}/${SKILLS.length} skills linked`);
+      const summary =
+        expected === 0
+          ? `all ${servedByPlugin.length} skills served by the marketplace plugin`
+          : `${linkedCount}/${expected} skills linked${pluginNote}`;
+      console.log(`    ${CHECK} ${platform.displayName}: ${summary}`);
     } else {
       const problems = [];
       if (missing.length > 0) problems.push(`missing: ${missing.join(', ')}`);
       if (broken.length > 0) problems.push(`broken: ${broken.join(', ')}`);
-      console.log(`    ${CROSS} ${platform.displayName}: ${linkedCount}/${SKILLS.length} skills linked (${problems.join('; ')})`);
+      console.log(
+        `    ${CROSS} ${platform.displayName}: ${linkedCount}/${expected} skills linked${pluginNote} (${problems.join('; ')})`
+      );
       issues += missing.length + broken.length;
 
       // Collect symlink issues for detailed report
@@ -117,6 +143,27 @@ export async function doctorCommand() {
     }
   }
 
+  // Marketplace plugin
+  //
+  // Worth its own section because the two channels look identical from the
+  // outside and produce opposite expectations: with the plugin enabled, absent
+  // mirrors are correct; without it, absent mirrors mean no skills at all.
+  console.log('');
+  console.log('  Marketplace plugin:');
+  const pluginEnabled = isClaudePluginEnabled(homeDir);
+  const pluginCached = hasClaudePluginCache(homeDir);
+
+  if (pluginEnabled) {
+    console.log(`    ${CHECK} Enabled — Claude Code is served by the plugin, mirrors intentionally absent`);
+  } else if (pluginCached) {
+    console.log(`    ${WARN} Not enabled, but a cache directory remains from a previous install`);
+    console.log(`      ${chalk.dim('Harmless on this version. On aiskills < 1.16.1 it made install skip')}`);
+    console.log(`      ${chalk.dim('every symlink, leaving Claude Code with no skills. Remove it with:')}`);
+    console.log(`      ${chalk.cyan('rm -rf ~/.claude/plugins/cache/maccesar-aiskills')}`);
+  } else {
+    console.log(`    ${CHECK} Not installed — skills reach Claude Code through npm mirrors`);
+  }
+
   // Symlink issues detail
   if (symlinkIssues.length > 0) {
     console.log('');

package/lib/commands/skills.js

@@ -79,10 +79,12 @@ export async function skillsCommand(options) {
     chalk.dim('(agentskills.io standard)')
   );
   console.log(
-    '  ' + chalk.dim('Read directly by Gemini, Codex, Cursor, Cline, Amp, GitHub Copilot, +more.')
+    '  ' + chalk.green('✓'),
+    chalk.dim('Gemini, Codex, Cursor, Cline, Amp, GitHub Copilot +more read it directly —')
   );
+  console.log('    ' + chalk.dim('nothing else to configure for them.'));
   console.log(
-    '  ' + chalk.dim('Below: extra symlink mirrors for Claude Code.')
+    '  ' + chalk.dim('Claude Code needs symlink mirrors, created below.')
   );
   console.log('');
 
@@ -112,10 +114,19 @@ export async function skillsCommand(options) {
     process.exit(1);
   }
 
-  // Show detected platforms
+  // Show detected platforms.
+  //
+  // Only assistants that need aiskills-managed mirrors appear here, so a bare
+  // "Claude Code detected" reads as if the other assistants were not found at
+  // all. They were never looked for: Gemini, Codex and the rest read
+  // ~/.agents/skills/ directly and are already served by the install itself.
   if (detectedPlatforms.length > 0) {
     for (const platform of detectedPlatforms) {
-      console.log(chalk.green('✓'), `${platform.displayName} detected`);
+      console.log(
+        chalk.green('✓'),
+        `${platform.displayName} detected`,
+        chalk.dim('— needs mirrors, linked below')
+      );
     }
     console.log('');
   } else if (isLocal) {
@@ -269,6 +280,10 @@ export async function skillsCommand(options) {
           spinner.succeed(
             `${commandsResult.installed.length} slash command${commandsResult.installed.length !== 1 ? 's' : ''} installed`
           );
+        } else if (commandsResult.skipped.length > 0) {
+          spinner.info(
+            `${commandsResult.skipped.length} slash command${commandsResult.skipped.length !== 1 ? 's' : ''} already provided by the marketplace plugin`
+          );
         } else {
           spinner.info('No slash commands to install');
         }

package/lib/commands/update.js

@@ -67,6 +67,10 @@ async function performUpdate(baseDir, repoDir, spinner) {
       spinner.succeed(
         `${commandsResult.installed.length} slash command${commandsResult.installed.length !== 1 ? 's' : ''} synced`
       );
+    } else if (commandsResult.skipped.length > 0) {
+      spinner.info(
+        `${commandsResult.skipped.length} slash command${commandsResult.skipped.length !== 1 ? 's' : ''} already provided by the marketplace plugin`
+      );
     } else {
       spinner.info('No slash commands to sync');
     }

package/lib/config.js

@@ -64,6 +64,17 @@ export const CLAUDE_PLUGIN_NAME = 'aiskills';
 export const getClaudePluginSkillsPath = (baseDir = os.homedir()) =>
   path.join(baseDir, '.claude', 'plugins', 'cache', CLAUDE_PLUGIN_MARKETPLACE, CLAUDE_PLUGIN_NAME);
 
+// The key Claude Code writes under "enabledPlugins" when the plugin is installed.
+export const CLAUDE_PLUGIN_KEY = `${CLAUDE_PLUGIN_NAME}@${CLAUDE_PLUGIN_MARKETPLACE}`;
+
+// Where Claude Code records which plugins are enabled. Both files are consulted
+// because the local variant overrides the shared one, and either may carry the
+// entry depending on how the plugin was installed.
+export const getClaudeSettingsPaths = (baseDir = os.homedir()) => [
+  path.join(baseDir, '.claude', 'settings.json'),
+  path.join(baseDir, '.claude', 'settings.local.json'),
+];
+
 // AI platform detection
 //
 // Only platforms that need aiskills-managed symlinks appear here.

package/lib/installer.js

@@ -135,6 +135,7 @@ export async function installCommands(repoDir, baseDir = os.homedir()) {
     installed: [],
     failed: [],
     removed: [],
+    skipped: [],
   };
 
   const legacyLocal = removeCommands(baseDir, { legacyOnly: true });
@@ -147,7 +148,24 @@ export async function installCommands(repoDir, baseDir = os.homedir()) {
     results.failed.push(...legacyGlobal.failed);
   }
 
+  const { pluginProvidesCommand } = await import('./claude-plugin.js');
+  const commandsDir = getClaudeCommandsDir(baseDir);
+
   for (const cmd of COMMANDS) {
+    // Same rule the symlink step applies to skills: when the marketplace plugin
+    // already provides the command, installing our own copy makes it show up
+    // twice in the autocomplete. Clean up any copy left from before the plugin
+    // was installed.
+    if (pluginProvidesCommand(cmd, baseDir)) {
+      const stalePath = join(commandsDir, `${cmd}.md`);
+      if (existsSync(stalePath)) {
+        await remove(stalePath);
+        results.removed.push(cmd);
+      }
+      results.skipped.push(cmd);
+      continue;
+    }
+
     if (await installCommand(repoDir, cmd, baseDir)) {
       results.installed.push(cmd);
     } else {

package/lib/symlink.js

@@ -75,21 +75,16 @@ async function removePath(path) {
  * and an additional symlink at ~/.claude/skills/<skill> produces a duplicate
  * entry in the slash-command autocomplete. This helper lets the symlink step
  * skip Claude when the plugin already covers it.
+ *
+ * Requires the plugin to be *enabled*, not merely cached — see `claude-plugin.js`
+ * for why the distinction matters.
  * @param {string} skillName - Skill name (e.g. 'stitch-showcase')
  * @param {string} baseDir - Optional base directory (defaults to homedir via config)
  * @returns {Promise<boolean>} True if the plugin provides this skill
  */
 export async function isClaudePluginSkillInstalled(skillName, baseDir) {
-  const { readdir } = await import('fs/promises');
-  const { getClaudePluginSkillsPath } = await import('./config.js');
-  const pluginBase = getClaudePluginSkillsPath(baseDir);
-  if (!existsSync(pluginBase)) return false;
-  try {
-    const versions = await readdir(pluginBase);
-    return versions.some((v) => existsSync(join(pluginBase, v, 'skills', skillName)));
-  } catch {
-    return false;
-  }
+  const { pluginProvidesSkill } = await import('./claude-plugin.js');
+  return pluginProvidesSkill(skillName, baseDir);
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/aiskills",
-  "version": "1.16.0",
+  "version": "1.16.1",
   "description": "AI coding assistant skills for Claude Code, Gemini CLI, and Codex CLI",
   "type": "module",
   "bin": {