@maccesar/aiskills 1.11.0 → 1.15.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/`, `~/.gemini/skills/`, or `~/.codex/skills/`
+- 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,8 +58,8 @@ 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/` |
-| [Codex CLI](https://developers.openai.com/codex/cli/)     | Supported | `~/.codex/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,11 @@ 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        |
 
 Use `aiskills list` to see available skills from the command line. Pull requests are welcome.
 
@@ -192,7 +193,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 +225,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 +240,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.

package/lib/cleanup.js

@@ -9,6 +9,8 @@ import {
   LEGACY_COMMANDS,
   getAgentsSkillsDir,
   getClaudeCommandsDir,
+  getCodexSkillsDir,
+  getGeminiSkillsDir,
 } from './config.js';
 import { detectPlatforms } from './platform.js';
 import { existsSync, lstatSync, rmSync } from 'fs';
@@ -53,6 +55,37 @@ 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.
+export function removeCodexRedundantSymlinks(baseDir) {
+  const codexSkillsDir = getCodexSkillsDir(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);
@@ -74,6 +107,9 @@ export function cleanupLegacyArtifacts(baseDir) {
     removeLegacySkillSymlinks(platform.skillsDir);
   }
 
+  removeCodexRedundantSymlinks(baseDir);
+  removeGeminiRedundantSymlinks(baseDir);
+
   if (baseDir) {
     removeSkills(undefined, { legacyOnly: true });
     removeCommands(undefined, { legacyOnly: true });
@@ -81,6 +117,8 @@ export function cleanupLegacyArtifacts(baseDir) {
     for (const platform of globalPlatforms) {
       removeLegacySkillSymlinks(platform.skillsDir);
     }
+    removeCodexRedundantSymlinks(undefined);
+    removeGeminiRedundantSymlinks(undefined);
   }
 }
 
@@ -89,6 +127,10 @@ export default {
   getCommandList,
   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,8 +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, Gemini CLI, or Codex CLI');
+    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);
   }
@@ -172,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')) {
@@ -202,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`
           );
         }
       }
@@ -268,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,6 +27,7 @@ export const REPO_API_URL = 'https://api.github.com/repos/macCesar/aiskills';
 
 // Skills to install
 export const SKILLS = [
+  'audit-codebase',
   'humaniza',
   'refactoring-ui',
   'stitch-showcase',
@@ -54,7 +55,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,18 +79,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'),
-  },
-  {
-    name: 'codex',
-    displayName: 'Codex CLI',
-    skillsDir: getCodexSkillsDir(baseDir),
-    configDir: path.join(baseDir, '.codex'),
-  },
 ];
 
 // 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/platform.js

@@ -26,7 +26,7 @@ export function detectPlatforms(baseDir) {
 
 /**
  * Get platform by name
- * @param {string} name - Platform name (claude, gemini, codex)
+ * @param {string} name - Platform name (claude, gemini)
  * @param {string} baseDir - Optional base directory
  * @returns {Object|null} Platform object or null
  */

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,6 +1,6 @@
 {
   "name": "@maccesar/aiskills",
-  "version": "1.11.0",
+  "version": "1.15.0",
   "description": "AI coding assistant skills for Claude Code, Gemini CLI, and Codex CLI",
   "type": "module",
   "bin": {

package/skills/audit-codebase/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: audit-codebase
+description: 'Audit a whole codebase, app, backend, or API as one unit and prepare or (once approved) implement an evidence-based correction plan, preserving legitimate use cases and avoiding disproportionate security controls. One sweep across security, production-readiness, architecture, dependencies, compatibility, performance, maintainability, and tests, in any language. Use even when the user just says "audit this project", "go through the whole app end to end", "is it safe to ship to prod / run on the public internet?", "do a real security review of my API", "find real problems before we launch", "what''s actually broken vs. just ugly?", "audit it and implement the fixes", or "implement the audit plan / decision matrix we already approved". Do NOT use for narrow work — a single bug, one regex or snippet, a small PR/diff, or tests for one module — nor for non-code audits like cloud bills or resumes.'
+allowed-tools: Read, Grep, Glob, Bash, Edit, Write, AskUserQuestion
+---
+
+# Audit Codebase
+
+Act as a senior software, security, and architecture auditor. Review the whole project end to end before drawing any conclusions.
+
+The work has two stages separated by an explicit user authorization. The separation exists because the value of an audit depends on a neutral diagnosis: if you edit while you audit, you contaminate the evidence and take away the user's decision about what to change. The first deliverable is always diagnosis and plan; code is only touched after the user approves the decision matrix.
+
+Respond in the user's language. This skill is written in English for portability, but the audit report should match whatever language the user is writing in.
+
+## How the user invokes this
+
+- **Audit only** ("audit this", "is it production-ready?", "security review") — run stage 1 and stop at the decision matrix + plan. Don't touch code.
+- **Audit and fix** ("audit and implement the fixes", "find problems and fix them", "clean this up before we ship") — run stage 1, then present the decision matrix and stop for a single go/no-go before stage 2. Even when the user asks up front to fix everything, show the matrix first: it takes seconds to approve and it's the checkpoint that lets you change code on their own repo without guessing which product tradeoffs are acceptable. Once they approve (a plain "yes, go" is enough), implement the full matrix.
+- **Implement a prior plan** ("implement the audit plan we approved") — skip discovery, go straight to stage 2 against the approved matrix.
+
+If the user explicitly says to skip the checkpoint ("just fix everything, don't ask"), honor it — but still surface any finding whose fix would break a documented use case before applying that specific change, because that's a product decision you can't infer.
+
+## Before you start
+
+Read `references/comprehensive-audit.md`. It holds the mandatory principles, the full technical scope (24 areas), the phased method, the severity classification, and the recommendation rules. Don't audit from memory: the file exists so the review is systematic and doesn't depend on which areas you happen to recall in the moment.
+
+Before writing any deliverable (diagnosis, decision matrix, or implementation report), read `references/report-format.md` and use those exact structures. A stable format lets audits be compared across projects and guarantees that no finding is left without a disposition.
+
+## Stage 1 — Audit (no modifications)
+
+Do not modify the project during this stage. This covers the whole project tree, not just source files: don't leave build output, compiled bytecode (`__pycache__`, `.pyc`), caches, lockfiles, `node_modules`, coverage reports, or any generated artifact behind. Verification tools often write into the tree as a side effect — `python -m py_compile` drops `__pycache__`, test runners and bundlers create caches, `npm install` writes `node_modules`. When you need to run such a tool, run it so its output lands outside the project (e.g. set `PYTHONPYCACHEPREFIX` to a temp dir, use a flag that disables writes, or copy the file elsewhere first); if you can't, skip it and record the check as unverified with the reason. A clean read-only pass is what lets the user trust that the diagnosis changed nothing.
+
+If a critical finding needs immediate attention, report it first, but continue the full audit — don't stop at the first serious problem.
+
+1. **Discovery** — Identify the stack and real versions. Inventory entrypoints, routes, models, migrations, services, and commands. Read README, CHANGELOG, configuration, tests, and examples to understand the project's intent.
+2. **Existing use cases** — Build the list of real capabilities and actors (anonymous visitor, authenticated user, resource owner, admin, API client, internal processes) **before** recommending any change. This list is the yardstick every restrictive recommendation is measured against.
+3. **Evidence** — Run available tests, lint, static analysis, and dependency audits. Verify authorization with at least two users/tenants when it applies. Confirm every claim before reporting it.
+4. **Findings** — Document each problem with concrete evidence (file, line, configuration, reproducible behavior) and a status: **Confirmed**, **Conditional risk**, or **Unverified**.
+5. **Decision matrix** — Every confirmed finding, medium and low included, gets an explicit proposed disposition. None is silently discarded.
+6. **Correction plan** — Organized by implementation phase, with compatibility, tests, and rollback. Stop here and wait for the user's approval.
+
+### Stage 1 critical rules
+
+- **Evidence before patterns.** Don't flag something as vulnerable just because it resembles a known pattern. A finding without evidence is noise that erodes trust in the real findings.
+- **Proportional security, not absolute.** Before recommending mandatory auth, allowlists, or route blocking, identify which legitimate use cases would break and evaluate the least-restrictive alternative (signatures, opaque tokens, ownership, rate limiting, expiration).
+- **Severity is not scope.** Severity signals risk; the disposition (fix now, later phase, accept, won't fix) is a separate decision that every finding must receive explicitly.
+- **Don't turn product decisions into technical assumptions.** Ask only what cannot be inferred from the repository.
+
+## Stage 2 — Authorized implementation
+
+Start only when the user approves the decision matrix.
+
+1. Implement the **full** approved matrix, not just the critical and high findings.
+2. If a change contradicts an existing use case discovered in stage 1, stop and present it before applying the restriction.
+3. Keep or add regression tests for every affected behavior.
+4. Update configuration, documentation, examples, and CHANGELOG when a public contract changes.
+5. Re-run all verifications and review the full diff: every changed line must trace back to an approved finding. No cosmetic cleanup, no unrelated features.
+6. Explicitly list any finding you did not implement and the approved reason it was left pending.
+
+## Closing condition
+
+The audit or implementation is complete only when:
+
+1. Every finding has evidence and a status.
+2. Every confirmed finding has an explicit disposition.
+3. Existing capabilities and legitimate use cases are documented.
+4. The plan (or final report) includes compatibility, tests, and rollback.
+5. In stage 1, no code was modified.
+
+Do not declare the work "complete" if any finding is left without an explicit disposition.

package/skills/audit-codebase/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Audit Codebase"
+  short_description: "End-to-end technical audit and evidence-based correction plan"
+  default_prompt: "Run a comprehensive technical audit of this project: architecture, security, compatibility, performance, maintainability, and tests. Deliver a diagnosis, decision matrix, and correction plan without modifying code."