@maccesar/aiskills 1.12.0 → 1.16.0

package/README.md

@@ -40,7 +40,7 @@ claude   # or gemini, or codex
 
 Installed files:
 - All skills to `~/.agents/skills/`
-- Platform symlinks in `~/.claude/skills/` and `~/.gemini/skills/` (Codex CLI auto-discovers from `~/.agents/skills/` — no symlink needed)
+- Platform symlinks in `~/.claude/skills/` (Gemini CLI and Codex CLI auto-discover from `~/.agents/skills/` — no platform-specific symlink needed)
 
 ### Which option should I use?
 
@@ -58,7 +58,7 @@ Installed files:
 | Platform                                                  | Status    | Installation Path   |
 | --------------------------------------------------------- | --------- | ------------------- |
 | [Claude Code](https://claude.ai/claude-code)              | Supported | `~/.claude/skills/` |
-| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | Supported | `~/.gemini/skills/` |
+| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | Supported | `~/.agents/skills/` (auto-discovered) |
 | [Codex CLI](https://developers.openai.com/codex/cli/)     | Supported | `~/.agents/skills/` (auto-discovered) |
 
 All three platforms use the same Agent Skills format: a `SKILL.md` file with YAML frontmatter that tells the assistant when to use the skill and what to do.
@@ -69,10 +69,12 @@ All three platforms use the same Agent Skills format: a `SKILL.md` file with YAM
 
 | Skill                | Domain       | Source                               | Reference Files |
 | -------------------- | ------------ | ------------------------------------ | --------------- |
-| refactoring-ui       | Design       | "Refactoring UI" by Wathan & Schoger | 4 files         |
-| humaniza             | Writing (es) | Curated Spanish/es-MX style rules    | 6 files         |
-| vscode-extension-dev | VS Code      | VS Code Extension API docs           | 4 files         |
-| stitch-showcase      | Design Tools | Google Stitch export workflow        | 14 files        |
+| refactoring-ui       | Design       | "Refactoring UI" by Wathan & Schoger | 7 files         |
+| humaniza             | Writing (es) | Curated Spanish/es-MX style rules    | 7 files         |
+| audit-codebase       | Auditing     | Evidence-based audit methodology     | 2 files         |
+| vscode-extension-dev | VS Code      | VS Code Extension API docs           | 14 files        |
+| stitch-showcase      | Design Tools | Google Stitch export workflow        | 16 files        |
+| session-log          | Project      | Convention + 3 A/B rounds            | 2 files         |
 
 Use `aiskills list` to see available skills from the command line. Pull requests are welcome.
 
@@ -132,8 +134,6 @@ Hard restrictions:
 Distribution note:
 - Available via the plugin install (Option A above). Slash commands are not distributed by the npm CLI (Option B) because they are a Claude Code feature.
 
----
-
 ## How skills work
 
 Skills activate based on what you ask. You can write prompts normally:
@@ -192,7 +192,7 @@ Reference files:
 
 ### humaniza
 
-An editor for Spanish text (es-MX). It removes common AI writing patterns and rewrites the text so it sounds natural without changing the meaning.
+An editor for Spanish text (es-MX). Based on curated es-MX style rules and adapted techniques from Hardik Pandya's Stop Slop skill (cut filler, break formulaic structures, active voice, specificity, varied rhythm). It removes common AI writing patterns and rewrites the text so it sounds natural without changing the meaning.
 
 When it activates:
 - User asks to "humanize" a text in Spanish
@@ -224,6 +224,7 @@ Reference files:
 | ----------------- | --------------------------------------------------------------- |
 | ai-patterns-es.md | AI writing tics in Spanish: inflated phrases, filler, templates |
 | lexicon-es-mx.md  | Preferred es-MX vocabulary vs. Spain Spanish                    |
+| structures-es.md  | Structural patterns to avoid: binary contrasts, false agency... |
 | modes-es-mx.md    | Rules per mode (marketing, technical, support, etc.)            |
 | voice-es-mx.md    | How to add human voice: rhythm, concreteness, variety           |
 | checklist.md      | Final QA before delivering the text                             |
@@ -238,6 +239,39 @@ Scope:
 
 ---
 
+### audit-codebase
+
+A senior software auditor that reviews an entire project — architecture, security, compatibility, performance, maintainability, and tests — and delivers an evidence-based diagnosis with a decision matrix and correction plan. Works in two stages: a read-only audit first, then an authorized implementation of the approved plan. Every restrictive security recommendation must name the legitimate use cases it could break and the less-restrictive alternative that was evaluated. The report is written in the user's language.
+
+When it activates:
+- Asking for a full technical audit or security review of a project
+- Checking if a project is ready for production
+- Reviewing architecture, dependencies, compatibility, or test coverage
+- Implementing an approved audit correction plan
+
+Example prompts:
+```
+"Audit this project end to end"
+"Is this backend ready for production?"
+"Do a security review without breaking the anonymous flows"
+"Find real problems before we ship"
+"Implement the audit plan we approved"
+```
+
+Reference files:
+| File                   | Topics                                                                     |
+| ---------------------- | --------------------------------------------------------------------------- |
+| comprehensive-audit.md | Mandatory principles, 24-area technical scope, 5-phase method, severity     |
+| report-format.md       | Executive summary, findings table, decision matrix, correction plan formats |
+
+Scope:
+- Stage 1 never modifies files; the first deliverable is always diagnosis + plan
+- Every confirmed finding gets an explicit disposition (fix now, later, accept, won't fix)
+- Findings are classified as Confirmed / Conditional risk / Unverified — no pattern-matched "vulnerabilities" without evidence
+- Stage 2 only starts after the user approves the decision matrix, and implements it completely
+
+---
+
 ### vscode-extension-dev
 
 A guide for building VS Code extensions from scaffolding to publishing. Based on the official VS Code Extension API docs.
@@ -273,6 +307,52 @@ Reference files:
 
 ---
 
+### session-log
+
+Gives a project one predictable place for its working state, so both you and any assistant know where to look instead of hunting through scattered notes. It installs a fixed four-file convention under `docs/project/` and writes a short pointer into every context file the repo has — `CLAUDE.md`, `AGENTS.md`, `GEMINI.md` — so the notes stay findable no matter which assistant opens the project next.
+
+The convention:
+
+| File | Holds | Loaded at startup |
+| --- | --- | --- |
+| `status.md` | Where the work stands: half-done things, next step, what's blocked, deployment state | **No** |
+| `requirements.md` | What the system must do, and the acceptance criterion for each item | Yes |
+| `decisions.md` | What was chosen and why. Append-only, dated | Yes |
+| `context.md` | Documentation map, architecture, conventions, traps | Yes |
+
+**Why `status.md` is excluded from startup.** Cached context is matched as a prefix — the first byte that differs invalidates everything after it. Status written inside a startup-loaded file means every update throws away the cache for all the stable content behind it. The file you edit most often is the one that must not load at startup.
+
+How to use it — just say it, in whatever words you'd use anyway:
+
+```
+"set up the project notes here — the mobile app lives at ../../Apps/MyApp"
+"ya me voy, déjame anotado dónde quedé"
+"where did we leave off? I haven't touched this repo in weeks"
+"my CLAUDE.md has the progress and a date inside it — should I move that?"
+```
+
+Closing a session and resuming one are different jobs and it treats them differently. On the way out it writes; on the way back in it reads `status.md` and then checks it against the repo before repeating it to you — what landed since the file was written, whether the branch it names still exists, what's uncommitted that it never mentioned. A three-week-old note is a snapshot, and the most expensive way to use one is to trust it.
+
+There is no slash command, by design: a command and a skill doing the same job means two copies of the logic that drift apart, and a command only works in Claude Code. This is one file that Claude, Codex and Gemini all read the same way — point any of them at `skills/session-log/SKILL.md` if it doesn't pick it up on its own.
+
+Once the convention is installed, finding the notes no longer depends on the skill at all — the pointer in `CLAUDE.md`, `AGENTS.md` and `GEMINI.md` is what any assistant reads at startup.
+
+What it will not do:
+- Commit, tag, push, or write CHANGELOG entries — that is a release, and releasing assumes the work is finished, which is the opposite of why this exists. Use `/release` for that.
+- Edit your uncommitted code. It reports what it finds broken and leaves it alone.
+- Invent a completion percentage. Without a fixed denominator any number is made up, so it counts what is enumerable or describes status in words.
+- Write a token, a password or a client's private details into the files. They get committed, and a secret deleted in a later commit is still in the history — it records where the credential lives instead.
+- Overwrite the record on arrival. If a resumed file turns out to be badly out of date it says so and offers; rewriting is your call.
+
+Measured behaviour, across three A/B rounds against a no-skill baseline (18 runs, adversarially graded):
+
+| | With skill | Without |
+| --- | --- | --- |
+| Kept volatile status out of the startup chain | 9 / 9 | 0 / 9 |
+| Left the user's broken uncommitted code untouched | yes | no — fixed it unasked |
+
+Token cost is 3–13% higher per run. **Those rounds graded an earlier layout** — a single status file versus an imported memory index — so what they establish is the split itself, not the four filenames. The paths added since (resuming against a stale file, upgrading an earlier install, monorepos, a gitignored `docs/`) have prompts written for them and have not been run. The grading notes, and an explicit account of what is and isn't measured, are in `skills/session-log/evals/`.
+
 ### stitch-showcase
 
 A workflow skill for processing Google Stitch design exports. It handles the full lifecycle: from raw zips to a navigable showcase, component standardization, and a visual component catalog.

package/lib/cleanup.js

@@ -10,6 +10,7 @@ import {
   getAgentsSkillsDir,
   getClaudeCommandsDir,
   getCodexSkillsDir,
+  getGeminiSkillsDir,
 } from './config.js';
 import { detectPlatforms } from './platform.js';
 import { existsSync, lstatSync, rmSync } from 'fs';
@@ -54,6 +55,20 @@ export function removeLegacySkillSymlinks(platformSkillsDir) {
   return removeSkillSymlinks(platformSkillsDir, { legacyOnly: true });
 }
 
+// When the user de-selects some skills during an install, anything previously
+// installed for those skills (in ~/.agents/skills/ and as platform symlinks)
+// must be cleaned up so the on-disk state matches the user's selection.
+export function removeUnselectedSkills(baseDir, selectedSkills) {
+  const skillsDir = getAgentsSkillsDir(baseDir);
+  const unselected = SKILLS.filter((s) => !selectedSkills.includes(s));
+  return removeEntriesAtDir(skillsDir, unselected, { recursive: true });
+}
+
+export function removeUnselectedSymlinks(platformSkillsDir, selectedSkills) {
+  const unselected = SKILLS.filter((s) => !selectedSkills.includes(s));
+  return removeEntriesAtDir(platformSkillsDir, unselected, { recursive: true });
+}
+
 // Codex reads skills from the canonical ~/.agents/skills/, so any aiskills-managed
 // symlinks at ~/.codex/skills/ from earlier versions are redundant and should be
 // cleaned up. Targets both active and legacy skill names.
@@ -62,6 +77,15 @@ export function removeCodexRedundantSymlinks(baseDir) {
   return removeSkillSymlinks(codexSkillsDir);
 }
 
+// Gemini CLI also auto-discovers skills from ~/.agents/skills/ per the
+// agentskills.io standard. Symlinks at ~/.gemini/skills/ from earlier
+// versions produce "Skill conflict detected" warnings on Gemini startup
+// because the same skill is found in both locations.
+export function removeGeminiRedundantSymlinks(baseDir) {
+  const geminiSkillsDir = getGeminiSkillsDir(baseDir);
+  return removeSkillSymlinks(geminiSkillsDir);
+}
+
 export function removeSkills(baseDir, options = {}) {
   const skillsDir = getAgentsSkillsDir(baseDir);
   const skillList = getSkillList(options);
@@ -84,6 +108,7 @@ export function cleanupLegacyArtifacts(baseDir) {
   }
 
   removeCodexRedundantSymlinks(baseDir);
+  removeGeminiRedundantSymlinks(baseDir);
 
   if (baseDir) {
     removeSkills(undefined, { legacyOnly: true });
@@ -93,6 +118,7 @@ export function cleanupLegacyArtifacts(baseDir) {
       removeLegacySkillSymlinks(platform.skillsDir);
     }
     removeCodexRedundantSymlinks(undefined);
+    removeGeminiRedundantSymlinks(undefined);
   }
 }
 
@@ -102,6 +128,9 @@ export default {
   removeSkillSymlinks,
   removeLegacySkillSymlinks,
   removeCodexRedundantSymlinks,
+  removeGeminiRedundantSymlinks,
+  removeUnselectedSkills,
+  removeUnselectedSymlinks,
   removeSkills,
   removeCommands,
   cleanupLegacyArtifacts,

package/lib/commands/skills.js

@@ -22,6 +22,9 @@ import {
   removeLegacySkillSymlinks,
   removeSkills,
   removeCommands,
+  removeUnselectedSkills,
+  removeUnselectedSymlinks,
+  cleanupLegacyArtifacts,
 } from '../cleanup.js';
 import {
   installSkills,
@@ -31,6 +34,7 @@ import {
 import { downloadRepoArchive } from '../downloader.js';
 import { createSkillSymlinks } from '../symlink.js';
 import { installHook } from '../hooks.js';
+import { readSkillDescription, shortenSkillDescription } from '../utils.js';
 import { mkdtemp } from 'fs/promises';
 import { existsSync } from 'fs';
 import { join, resolve } from 'path';
@@ -64,6 +68,22 @@ export async function skillsCommand(options) {
   } else {
     console.log(chalk.cyan('Mode: Global installation (user home)'));
   }
+  const skillsLocation = isLocal
+    ? './.agents/skills/'
+    : (customPath ? `${baseDir}/.agents/skills/` : '~/.agents/skills/');
+  console.log('');
+  console.log(
+    chalk.yellow('▸'),
+    'Skills install to',
+    chalk.cyan.bold(skillsLocation),
+    chalk.dim('(agentskills.io standard)')
+  );
+  console.log(
+    '  ' + chalk.dim('Read directly by Gemini, Codex, Cursor, Cline, Amp, GitHub Copilot, +more.')
+  );
+  console.log(
+    '  ' + chalk.dim('Below: extra symlink mirrors for Claude Code.')
+  );
   console.log('');
 
   // Detect installed platforms at the target base directory
@@ -85,9 +105,9 @@ export async function skillsCommand(options) {
   }
 
   if (detectedPlatforms.length === 0 && !options.path && !isLocal) {
-    console.log(chalk.yellow('No AI coding assistants detected globally.'));
-    console.log('Install one of: Claude Code or Gemini CLI.');
-    console.log('(Codex CLI is supported via the canonical ~/.agents/skills/ — no platform-specific symlink needed.)');
+    console.log(chalk.yellow('No AI coding assistants detected globally that need platform symlinks.'));
+    console.log('Install Claude Code if you want aiskills to create skill symlinks for it.');
+    console.log('(Gemini CLI and Codex CLI auto-discover skills from ~/.agents/skills/ — no platform-specific symlink needed.)');
     console.log('Or use: aiskills install --local');
     process.exit(1);
   }
@@ -173,14 +193,73 @@ export async function skillsCommand(options) {
     }
   }
 
+  // Skill selection prompt — pre-checks all skills; the user can uncheck the
+  // ones they don't want. Skipped under --all (CI/automation) and removeOnly.
+  // Each line shows the skill name + a one-liner hint in dim gray, like
+  // skills.sh, so the rendered row height stays constant and the list does
+  // not "jump" when the cursor moves between skills with different-length
+  // descriptions.
+  let skillsToInstall = SKILLS;
+  if (!removeOnly && !options.all && !options.path) {
+    const skillChoices = SKILLS.map((name) => {
+      const fullDescription = readSkillDescription(repoDir, name);
+      const hint = shortenSkillDescription(fullDescription);
+      const label = hint
+        ? `${name} ${chalk.dim(`(${hint})`)}`
+        : name;
+      return { name: label, value: name, short: name, checked: true };
+    });
+
+    try {
+      const selected = await checkbox({
+        message: 'Select skills to install:',
+        choices: [...skillChoices, new Separator(' ')],
+        theme: {
+          style: {
+            renderSelectedChoices: () => '',
+            prefix: () => chalk.cyan('?'),
+          },
+        },
+      });
+
+      if (selected.includes('cancel')) {
+        console.log('Cancelled.');
+        process.exit(0);
+      }
+
+      skillsToInstall = SKILLS.filter((s) => selected.includes(s));
+    } catch (error) {
+      console.log('\nCancelled.');
+      process.exit(0);
+    }
+
+    if (skillsToInstall.length === 0) {
+      console.log(chalk.yellow('No skills selected. Nothing to install.'));
+      process.exit(0);
+    }
+  }
+
   const selectedPlatformNames = new Set(selectedPlatforms.map((platform) => platform.name));
 
   try {
     if (!removeOnly) {
       // Install skills
       spinner.start('Installing skills...');
-      const skillsResult = await installSkills(repoDir, baseDir);
-      spinner.succeed(`${SKILLS.length} skill${SKILLS.length !== 1 ? 's' : ''} installed`);
+      const skillsResult = await installSkills(repoDir, baseDir, skillsToInstall);
+      spinner.succeed(`${skillsToInstall.length} skill${skillsToInstall.length !== 1 ? 's' : ''} installed`);
+
+      // If the user deselected some skills, sweep any previously-installed
+      // copies and their platform symlinks so on-disk state matches selection.
+      if (skillsToInstall.length !== SKILLS.length) {
+        removeUnselectedSkills(baseDir, skillsToInstall);
+      }
+
+      // Sweep legacy skills, legacy commands, and redundant symlinks at platforms
+      // that no longer need aiskills-managed mirrors (Gemini, Codex). Without
+      // this, users that ran older aiskills versions keep stale symlinks at
+      // ~/.gemini/skills/ and ~/.codex/skills/ that Gemini reports as "Skill
+      // conflict detected" warnings on startup.
+      cleanupLegacyArtifacts(baseDir);
 
       // Install or remove slash commands based on Claude Code selection
       if (selectedPlatformNames.has('claude')) {
@@ -203,17 +282,20 @@ export async function skillsCommand(options) {
       // Create symlinks for selected platforms
       for (const platform of selectedPlatforms) {
         removeLegacySkillSymlinks(platform.skillsDir);
+        if (skillsToInstall.length !== SKILLS.length) {
+          removeUnselectedSymlinks(platform.skillsDir, skillsToInstall);
+        }
         spinner.start(`Linking ${platform.displayName}...`);
         const symlinkResult = await createSkillSymlinks(
           platform.skillsDir,
-          SKILLS,
+          skillsToInstall,
           baseDir
         );
-        if (symlinkResult.linked.length === SKILLS.length) {
+        if (symlinkResult.linked.length === skillsToInstall.length) {
           spinner.succeed(`${platform.displayName}: Skills linked`);
         } else {
           spinner.warn(
-            `${platform.displayName}: ${symlinkResult.linked.length}/${SKILLS.length} skills linked`
+            `${platform.displayName}: ${symlinkResult.linked.length}/${skillsToInstall.length} skills linked`
           );
         }
       }
@@ -269,9 +351,28 @@ export async function skillsCommand(options) {
       }
     }
 
-    // Summary
+    // Summary — show where the skills landed and which agents read them.
+    // This is the "did it actually work" confirmation the user needs.
     console.log('');
     console.log(chalk.green('✓ Skills sync complete!'));
+    if (!removeOnly) {
+      console.log('');
+      console.log(
+        '  ' + chalk.bold(skillsLocation) + chalk.dim('  (') +
+        chalk.dim(skillsToInstall.length + ' skill' + (skillsToInstall.length !== 1 ? 's' : '')) +
+        chalk.dim(')')
+      );
+      console.log(
+        '  ' + chalk.dim('• universal: ') +
+        'Gemini, Codex, Cursor, Cline, Amp, GitHub Copilot ' + chalk.dim('+more')
+      );
+      if (selectedPlatformNames.has('claude')) {
+        console.log(
+          '  ' + chalk.dim('• symlinked: ') +
+          'Claude Code ' + chalk.dim('(~/.claude/skills/)')
+        );
+      }
+    }
     console.log('');
 
     if (!removeOnly && !isLocal && detectOS() === 'windows') {

package/lib/config.js

@@ -27,8 +27,10 @@ export const REPO_API_URL = 'https://api.github.com/repos/macCesar/aiskills';
 
 // Skills to install
 export const SKILLS = [
+  'audit-codebase',
   'humaniza',
   'refactoring-ui',
+  'session-log',
   'stitch-showcase',
   'vscode-extension-dev',
 ];
@@ -54,7 +56,23 @@ export const getClaudeCommandsDir = (baseDir = os.homedir()) => path.join(baseDi
 export const getGeminiSkillsDir = (baseDir = os.homedir()) => path.join(baseDir, '.gemini', 'skills');
 export const getCodexSkillsDir = (baseDir = os.homedir()) => path.join(baseDir, '.codex', 'skills');
 
+// Name of the Claude marketplace and plugin where this CLI publishes itself.
+// Used to detect when a skill is already installed via the marketplace plugin
+// and avoid creating a duplicate symlink in ~/.claude/skills/.
+export const CLAUDE_PLUGIN_MARKETPLACE = 'maccesar-aiskills';
+export const CLAUDE_PLUGIN_NAME = 'aiskills';
+export const getClaudePluginSkillsPath = (baseDir = os.homedir()) =>
+  path.join(baseDir, '.claude', 'plugins', 'cache', CLAUDE_PLUGIN_MARKETPLACE, CLAUDE_PLUGIN_NAME);
+
 // AI platform detection
+//
+// Only platforms that need aiskills-managed symlinks appear here.
+// Gemini CLI and Codex CLI auto-discover skills from the canonical
+// ~/.agents/skills/ per the agentskills.io standard, so creating
+// platform-specific symlinks at ~/.gemini/skills/ or ~/.codex/skills/
+// would be redundant — and in Gemini's case actively harmful, since it
+// reads both locations and reports "Skill conflict detected" warnings
+// when the same skill exists in both.
 export const getPlatforms = (baseDir = os.homedir()) => [
   {
     name: 'claude',
@@ -62,15 +80,6 @@ export const getPlatforms = (baseDir = os.homedir()) => [
     skillsDir: getClaudeSkillsDir(baseDir),
     configDir: path.join(baseDir, '.claude'),
   },
-  {
-    name: 'gemini',
-    displayName: 'Gemini CLI',
-    skillsDir: getGeminiSkillsDir(baseDir),
-    configDir: path.join(baseDir, '.gemini'),
-  },
-  // Codex CLI is intentionally omitted: it auto-discovers skills from the
-  // canonical ~/.agents/skills/ per the agentskills.io standard, so a
-  // platform-specific symlink at ~/.codex/skills/ would be redundant.
 ];
 
 // API configuration

package/lib/installer.js

@@ -61,12 +61,14 @@ export async function installSkill(repoDir, skillName, baseDir = os.homedir()) {
 }
 
 /**
- * Install all skills to the agents skills directory
+ * Install skills to the agents skills directory
  * @param {string} repoDir - Repository directory
  * @param {string} baseDir - Base directory for installation
+ * @param {string[]} [skillsToInstall] - Subset of skills to install (defaults to all SKILLS)
  * @returns {Promise<Object>} Results object with success/failure counts
  */
-export async function installSkills(repoDir, baseDir = os.homedir()) {
+export async function installSkills(repoDir, baseDir = os.homedir(), skillsToInstall) {
+  const list = skillsToInstall || SKILLS;
   const results = {
     installed: [],
     failed: [],
@@ -83,7 +85,7 @@ export async function installSkills(repoDir, baseDir = os.homedir()) {
     results.failed.push(...legacyGlobal.failed);
   }
 
-  for (const skill of SKILLS) {
+  for (const skill of list) {
     if (await installSkill(repoDir, skill, baseDir)) {
       results.installed.push(skill);
     } else {

package/lib/symlink.js

@@ -69,19 +69,49 @@ async function removePath(path) {
 }
 
 /**
- * Create symlinks for all skills to a platform directory
+ * Check if a skill is already available via the maccesar-aiskills Claude marketplace plugin.
+ * When the plugin is installed, Claude Code lists the skill from
+ *   ~/.claude/plugins/cache/maccesar-aiskills/aiskills/<version>/skills/<skill>/
+ * 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.
+ * @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;
+  }
+}
+
+/**
+ * Create symlinks for all skills to a platform directory.
+ * For the Claude platform, skills already provided by the maccesar-aiskills
+ * marketplace plugin are skipped to avoid duplicate slash-command entries;
+ * if a stale symlink from a previous install exists, it is removed.
  * @param {string} platformSkillsDir - Platform skills directory
  * @param {Array} skills - List of skill names
  * @param {string} baseDir - Optional base directory for target resolution
- * @returns {Promise<Object>} Results object with success/failure counts
+ * @returns {Promise<Object>} Results object with linked / failed / skipped arrays
  */
 export async function createSkillSymlinks(platformSkillsDir, skills, baseDir) {
-  const { getAgentsSkillsDir } = await import('./config.js');
+  const { getAgentsSkillsDir, getClaudeSkillsDir } = await import('./config.js');
   const agentsSkillsDir = getAgentsSkillsDir(baseDir);
+  const claudeSkillsDir = getClaudeSkillsDir(baseDir);
+  const isClaudePlatform = platformSkillsDir === claudeSkillsDir;
 
   const results = {
     linked: [],
     failed: [],
+    skipped: [],
   };
 
   // Ensure platform directory exists
@@ -93,6 +123,17 @@ export async function createSkillSymlinks(platformSkillsDir, skills, baseDir) {
   const useRelative = !!baseDir;
 
   for (const skill of skills) {
+    // Skip Claude when the marketplace plugin already provides this skill;
+    // clean up any stale symlink left from a previous CLI install.
+    if (isClaudePlatform && await isClaudePluginSkillInstalled(skill, baseDir)) {
+      const stalePath = join(platformSkillsDir, skill);
+      if (existsSync(stalePath)) {
+        await removePath(stalePath);
+      }
+      results.skipped.push(skill);
+      continue;
+    }
+
     const target = join(agentsSkillsDir, skill);
     const linkPath = join(platformSkillsDir, skill);
 
@@ -148,6 +189,7 @@ export async function updateSymlink(target, path) {
 export default {
   createSymlinkOrCopy,
   createSkillSymlinks,
+  isClaudePluginSkillInstalled,
   isSymlink,
   resolveSymlink,
   updateSymlink,

package/lib/utils.js

@@ -2,6 +2,45 @@
  * Utility functions
  */
 
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Read the description field from a skill's SKILL.md frontmatter.
+ * @param {string} repoDir - Repository directory containing skills/
+ * @param {string} skillName - Skill name (directory under skills/)
+ * @returns {string} Description text, or empty string if not available.
+ */
+export function readSkillDescription(repoDir, skillName) {
+  try {
+    const skillPath = join(repoDir, 'skills', skillName, 'SKILL.md');
+    const content = readFileSync(skillPath, 'utf8');
+    const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
+    if (!fmMatch) return '';
+    const descMatch = fmMatch[1].match(/^description:\s*["']?(.+?)["']?\s*$/m);
+    return descMatch ? descMatch[1].trim() : '';
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Compress a skill description to a one-line summary suitable for an inline
+ * checkbox preview. Picks the first segment of the description and trims it
+ * to `maxLen` characters, appending an ellipsis when the source is longer.
+ *
+ * @param {string} description - The full SKILL.md description.
+ * @param {number} maxLen - Maximum characters of the output (excluding ellipsis).
+ * @returns {string} Trimmed one-liner, or empty string if input was empty.
+ */
+export function shortenSkillDescription(description, maxLen = 60) {
+  if (!description) return '';
+  let firstSegment = description.split(/\s*[—.:;]\s*/)[0].trim();
+  firstSegment = firstSegment.replace(/\s+/g, ' ');
+  if (firstSegment.length <= maxLen) return firstSegment;
+  return firstSegment.slice(0, maxLen).trimEnd() + '…';
+}
+
 /**
  * Format a list of items for display
  * @param {Array} items - Array of strings
@@ -43,6 +82,8 @@ export function compareVersions(v1, v2) {
 }
 
 export default {
+  readSkillDescription,
+  shortenSkillDescription,
   formatList,
   parseVersion,
   compareVersions,

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@maccesar/aiskills",
-  "version": "1.12.0",
+  "version": "1.16.0",
   "description": "AI coding assistant skills for Claude Code, Gemini CLI, and Codex CLI",
   "type": "module",
   "bin": {
     "aiskills": "./bin/aiskills.js"
   },
   "scripts": {
-    "test": "node --test test/**/*.test.js",
+    "test": "node --test test/*.test.js",
     "lint": "eslint lib/**/*.js",
     "format": "prettier --write lib/**/*.js"
   },