@maccesar/titools 3.2.0 → 4.0.0

package/README.md

@@ -8,14 +8,12 @@
 
 </div>
 
-TiTools is a Titanium SDK toolkit for AI coding assistants. It ships 3 opinionated skills (`ti-expert`, `purgetss`, `ti-ui`), a research agent, and reference files covering Titanium architecture, PurgeTSS styling, and UI/UX patterns.
+TiTools is a Titanium SDK toolkit for AI coding assistants. It ships 8 skills — 3 opinionated (`ti-expert`, `purgetss`, `ti-ui`) plus 5 documentation-mirror skills (`ti-api`, `ti-guides`, `ti-howtos`, `alloy-guides`, `alloy-howtos`) — a research agent, and reference files covering Titanium architecture, API reference, native how-tos, Alloy MVC, PurgeTSS styling, and UI/UX patterns.
 
 The reference files are maintained against official documentation whenever an official source exists, so the assistant can retrieve current framework behavior instead of guessing from generic training data.
 
 Without TiTools, assistants rely on general training data. That data can be outdated or too generic for Titanium work. With TiTools, the assistant can look up Alloy architecture, memory cleanup patterns, PurgeTSS utility classes, and platform-specific APIs.
 
-> **v3.0.0 — doc-based skills moved to `tidev/skills`.** Five documentation-only skills (`ti-api`, `ti-guides`, `ti-howtos`, `alloy-guides`, `alloy-howtos`) are now maintained in the official [`tidev/skills`](https://github.com/tidev/skills) repository alongside the rest of the TiDev community tooling. TiTools now focuses on the three opinionated skills above. See [Doc-based skills moved to tidev/skills](#doc-based-skills-moved-to-tidevskills) below for upgrade notes.
-
 Vercel's AGENTS.md evaluation reports a 100% pass rate for the knowledge index approach, compared to 53-79% using skills alone.
 
 ---
@@ -74,9 +72,9 @@ claude   # or gemini, or codex
 ```
 
 What gets installed:
-- The 3 TiTools skills to `~/.agents/skills/`
+- The 8 TiTools skills to `~/.agents/skills/`
 - ti-pro agent for Claude Code
-- Platform symlinks for Claude Code and Gemini CLI (Codex CLI auto-discovers from `~/.agents/skills/` — no symlink needed)
+- Platform symlinks for Claude Code (Gemini CLI and Codex CLI auto-discover from `~/.agents/skills/` — no symlinks needed)
 - Knowledge index in your project's `AGENTS.md`/`CLAUDE.md`/`GEMINI.md`
 - Claude Code SessionStart hook for auto-updates
 
@@ -101,47 +99,15 @@ Use **Option A** if you only use Claude Code. Use **Option B** if you use multip
 
 ---
 
-## Doc-based skills moved to tidev/skills
-
-Starting with **v3.0.0**, five documentation-only skills migrated to the official [`tidev/skills`](https://github.com/tidev/skills) repository:
-
-- `ti-api` — Complete Titanium API reference
-- `ti-guides` — SDK fundamentals (Hyperloop, distribution, tiapp.xml)
-- `ti-howtos` — Native feature integration (location, push, media, platform-specific APIs)
-- `alloy-guides` — Alloy MVC framework reference
-- `alloy-howtos` — Alloy CLI, configuration, debugging
-
-**Why the move?** These skills are pure documentation mirrors of official Titanium and Alloy docs, so they belong in the community-maintained TiDev repository alongside the SDK source itself. Hansemann ([@hansemannn](https://github.com/hansemannn)) — TiDev maintainer — accepted the first batch in [tidev/skills#1](https://github.com/tidev/skills/pull/1) and `ti-howtos` followed in [tidev/skills#2](https://github.com/tidev/skills/pull/2).
-
-**What stays in TiTools:** the three *opinionated* skills that reflect personal Titanium conventions and toolchain choices (PurgeTSS-first styling, specific architecture patterns).
-
-### Upgrading from v2.x
-
-If you have v2.x installed, the five migrated skills will be **auto-removed** the next time you run `titools update` (they're listed in `LEGACY_SKILLS`). To get them back, install from `tidev/skills` directly:
-
-```bash
-git clone https://github.com/tidev/skills.git ~/Developer/git-clones/tidev-skills
-# Then symlink the five skills into ~/.agents/skills/ or your AI assistant's skills dir
-ln -s ~/Developer/git-clones/tidev-skills/skills/ti-api        ~/.agents/skills/ti-api
-ln -s ~/Developer/git-clones/tidev-skills/skills/ti-guides     ~/.agents/skills/ti-guides
-ln -s ~/Developer/git-clones/tidev-skills/skills/ti-howtos     ~/.agents/skills/ti-howtos
-ln -s ~/Developer/git-clones/tidev-skills/skills/alloy-guides  ~/.agents/skills/alloy-guides
-ln -s ~/Developer/git-clones/tidev-skills/skills/alloy-howtos  ~/.agents/skills/alloy-howtos
-```
-
-Refer to the [`tidev/skills` README](https://github.com/tidev/skills#readme) for the canonical install instructions, which may evolve independently of TiTools.
-
----
-
 ## Compatible platforms
 
-| Platform                                                  | Status           | Installation Path   |
-| --------------------------------------------------------- | ---------------- | ------------------- |
-| [Claude Code](https://claude.ai/claude-code)              | Fully Compatible | `~/.claude/skills/` |
-| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | Fully Compatible | `~/.gemini/skills/` |
+| Platform                                                  | Status           | Skills Path                           |
+| --------------------------------------------------------- | ---------------- | ------------------------------------- |
+| [Claude Code](https://claude.ai/claude-code)              | Fully Compatible | `~/.claude/skills/` (symlinked)       |
+| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | Fully Compatible | `~/.agents/skills/` (auto-discovered) |
 | [Codex CLI](https://developers.openai.com/codex/cli/)     | Fully Compatible | `~/.agents/skills/` (auto-discovered) |
 
-All three platforms use the Agent Skills open standard: a `SKILL.md` file with YAML frontmatter.
+All three platforms use the Agent Skills open standard: a `SKILL.md` file with YAML frontmatter. Gemini CLI and Codex CLI auto-discover skills from `~/.agents/skills/` per [agentskills.io](https://agentskills.io), so TiTools does not create redundant platform-specific symlinks for them.
 
 ---
 
@@ -194,7 +160,7 @@ Together they work like this:
 | ------------------------------- | ------------------------------- | ----------------------------- |
 | "Create a login screen"         | Context about project structure | `ti-expert`, `ti-ui`          |
 | "Optimize ListView performance" | Points to docs location         | `ti-ui` reads specific files  |
-| "Implement push notifications"  | API reference paths             | `ti-howtos` (via tidev/skills) |
+| "Implement push notifications"  | API reference paths             | `ti-howtos`                   |
 
 You do not need to explicitly invoke skills. The AI detects when to use them based on your question.
 
@@ -206,16 +172,21 @@ The knowledge index is based on the latest Titanium SDK documentation. If your p
 
 ## Skills overview
 
-| Skill     | Purpose                         | Best For                                |
-| --------- | ------------------------------- | --------------------------------------- |
-| ti-expert | Architecture and implementation | Starting point for most tasks           |
-| purgetss  | Utility-first styling           | UI styling and animations               |
-| ti-ui     | UI/UX patterns                  | Complex layouts, ListViews, platform UI |
+| Skill        | Purpose                             | Best For                                |
+| ------------ | ----------------------------------- | --------------------------------------- |
+| ti-expert    | Architecture and implementation     | Starting point for most tasks           |
+| purgetss     | Utility-first styling               | UI styling and animations               |
+| ti-ui        | UI/UX patterns                      | Complex layouts, ListViews, platform UI |
+| ti-api       | Complete Titanium API reference     | Looking up properties, methods, events  |
+| ti-guides    | SDK fundamentals                    | tiapp.xml, Hyperloop, distribution      |
+| ti-howtos    | Native feature integration          | Location, push, media, platform APIs    |
+| alloy-guides | Alloy MVC framework reference       | Controllers, models, views, widgets     |
+| alloy-howtos | Alloy CLI, configuration, debugging | alloy.jmk, config.json, custom XML tags |
 
 Notes:
-- `purgetss` reference files are audited against the official PurgeTSS documentation, but the workflow conventions are opinionated.
-- `ti-expert` and `ti-ui` reflect personal Titanium conventions (biased toward PurgeTSS, Alloy-first).
-- For purely doc-based references (API surface, native-feature how-tos, Alloy MVC, SDK guides, Alloy CLI), install [`tidev/skills`](https://github.com/tidev/skills) — it pairs cleanly with TiTools.
+- The first three (`ti-expert`, `purgetss`, `ti-ui`) are opinionated workflow skills reflecting TiTools' Titanium conventions.
+- The latter five are documentation-mirror skills sourced from the official Titanium SDK docs (`tidev/titanium-docs`) and audited against them via the internal `titools-skill-auditor`.
+- `purgetss` reference files are audited against the official PurgeTSS documentation, but its workflow conventions are opinionated.
 
 ---
 
@@ -441,10 +412,6 @@ Key rules:
 
 ---
 
-> **Looking for `ti-api`, `ti-guides`, `ti-howtos`, `alloy-guides`, or `alloy-howtos`?** Those five documentation-only skills now live in [`tidev/skills`](https://github.com/tidev/skills). See [Doc-based skills moved to tidev/skills](#doc-based-skills-moved-to-tidevskills) for install instructions.
-
----
-
 ## Usage examples and best practices
 
 ### Example prompts
@@ -540,13 +507,12 @@ Behavior depends on where you run it:
 | With `--local` flag        | Installs skills locally to `./.agents/skills/` in the current project |
 
 What it does:
-- Installs the 3 TiTools skills (global or local depending on context)
+- Installs the 8 TiTools skills (global or local depending on context)
 - Installs ti-pro agent for Claude Code
-- Detects installed AI platforms and lets you choose which to link
-- Creates symlinks from platform directories to central skills
-- Cleans up legacy artifacts (`alloy-expert` skill, `ti-researcher` agent)
+- Detects installed AI platforms and lets you choose which to link (only Claude Code needs platform symlinks; Gemini CLI and Codex CLI auto-discover from `~/.agents/skills/`)
+- Creates symlinks from `~/.claude/skills/` to the central `~/.agents/skills/`
+- Cleans up legacy artifacts (`alloy-expert` skill, `ti-researcher` agent, redundant Gemini/Codex symlinks)
 - If run inside a Titanium project, prompts to run `titools sync` afterward
-- Warns Gemini users if local skills override existing global Gemini skills
 - Installs Claude Code SessionStart hook for auto-updates
 
 ### titools auto-update
@@ -736,7 +702,7 @@ This pattern is documented across three TiTools skills: `ti-ui`, `ti-expert`, an
 | Skill     | SKILL.md                      | References                                            |
 | --------- | ----------------------------- | ----------------------------------------------------- |
 | ti-expert | Architecture + Implementation | 21 files (patterns, testing, security, etc.)          |
-| purgetss  | Setup + Critical Rules        | 29 files (grid, animations, icons, class-index, etc.) |
+| purgetss  | Setup + Critical Rules        | 33 files (grid, animations, icons, class-index, SVG pipeline, etc.) |
 | ti-ui     | UI Rules + Platform Diffs     | 14 files (layouts, lists, gestures, etc.)             |
 
 ---

package/lib/cleanup.js

@@ -10,6 +10,7 @@ import {
   getAgentsSkillsDir,
   getClaudeAgentsDir,
   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 TiTools-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 v3.x and
+// earlier 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,
   removeAgents,
   cleanupLegacyArtifacts,

package/lib/commands/agents.js

@@ -43,10 +43,12 @@ export async function agentsCommand(projectPath, options) {
     console.log('Run this command from the project root.');
     process.exit(1);
   }
-  // Check for local vs global skills
+  // Check for local vs global skills.
+  // Gemini CLI auto-discovers from ./.agents/skills/ (agentskills.io standard),
+  // so it shares the same local path as AGENTS.md.
   const localSkillsPaths = {
     'CLAUDE.md': join(projectDir, '.claude', 'skills'),
-    'GEMINI.md': join(projectDir, '.gemini', 'skills'),
+    'GEMINI.md': join(projectDir, '.agents', 'skills'),
     'AGENTS.md': join(projectDir, '.agents', 'skills'),
   };
 
@@ -63,7 +65,7 @@ export async function agentsCommand(projectPath, options) {
     if (options?.verbose) {
       console.log(
         chalk.gray(
-          `Searched: ${agentsSkillsDir} | ./.agents/skills, ./.claude/skills, ./.gemini/skills`
+          `Searched: ${agentsSkillsDir} | ./.agents/skills, ./.claude/skills`
         )
       );
     }
@@ -158,10 +160,9 @@ export async function agentsCommand(projectPath, options) {
         let rootPath = '~/.agents/skills';
         const localPath = localSkillsPaths[filename];
         if (localPath && existsSync(localPath)) {
-          rootPath = `./${filename === 'CLAUDE.md' ? '.claude' : filename === 'GEMINI.md' ? '.gemini' : '.agents'}/skills`;
-        } else {
-          if (filename === 'CLAUDE.md') rootPath = '~/.claude/skills';
-          if (filename === 'GEMINI.md') rootPath = '~/.gemini/skills';
+          rootPath = filename === 'CLAUDE.md' ? './.claude/skills' : './.agents/skills';
+        } else if (filename === 'CLAUDE.md') {
+          rootPath = '~/.claude/skills';
         }
 
         addOrUpdateBlock(filePath, rootPath);

package/lib/commands/skills.js

@@ -22,6 +22,9 @@ import {
   removeLegacySkillSymlinks,
   removeSkills,
   removeAgents,
+  removeUnselectedSkills,
+  removeUnselectedSymlinks,
+  cleanupLegacyArtifacts,
 } from '../cleanup.js';
 import {
   installSkills,
@@ -32,7 +35,12 @@ import { agentsCommand } from './agents.js';
 import { downloadRepoArchive } from '../downloader.js';
 import { createSkillSymlinks } from '../symlink.js';
 import { installHook } from '../hooks.js';
-import { formatList, isTitaniumProject } from '../utils.js';
+import {
+  formatList,
+  isTitaniumProject,
+  readSkillDescription,
+  shortenSkillDescription,
+} from '../utils.js';
 import { mkdtemp } from 'fs/promises';
 import { existsSync } from 'fs';
 import { join, resolve } from 'path';
@@ -98,6 +106,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
@@ -119,9 +143,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 TiTools 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: titools install --local');
     process.exit(1);
   }
@@ -186,12 +210,6 @@ export async function skillsCommand(options) {
   if (removeOnly) {
     console.log(chalk.yellow('No platforms selected. Removing all platform symlinks and agents.'));
   }
-  const showGeminiWarning = (() => {
-    if (removeOnly || !isLocal) return false;
-    const globalGemini = globalPlatforms.find((platform) => platform.name === 'gemini');
-    const geminiSelected = selectedPlatforms.some((platform) => platform.name === 'gemini');
-    return !!(geminiSelected && globalGemini && hasAnySkillSymlink(globalGemini.skillsDir));
-  })();
 
   // Get repository directory (local or download)
   const spinner = ora();
@@ -218,6 +236,52 @@ 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));
   const removedPlatformNames = [];
   const claudeSelected = selectedPlatformNames.has('claude');
@@ -226,8 +290,21 @@ export async function skillsCommand(options) {
     if (!removeOnly) {
       // Install skills
       spinner.start('Installing skills...');
-      const skillsResult = await installSkills(repoDir, baseDir);
-      spinner.succeed(`${SKILLS.length} skills 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 agents, and redundant symlinks at platforms
+      // that no longer need TiTools-managed mirrors (Gemini, Codex). Without
+      // this, users that ran older TiTools versions keep stale symlinks at
+      // ~/.gemini/skills/ and ~/.codex/skills/ that Gemini reports as "Skill
+      // conflict detected" warnings on startup.
+      cleanupLegacyArtifacts(baseDir);
 
       if (claudeSelected) {
         // Install agents
@@ -251,19 +328,22 @@ 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) {
-        spinner.succeed(`${platform.displayName}: Skills linked`);
-      } else {
-        spinner.warn(
-          `${platform.displayName}: ${symlinkResult.linked.length}/${SKILLS.length} skills linked`
-        );
-      }
+        if (symlinkResult.linked.length === skillsToInstall.length) {
+          spinner.succeed(`${platform.displayName}: Skills linked`);
+        } else {
+          spinner.warn(
+            `${platform.displayName}: ${symlinkResult.linked.length}/${skillsToInstall.length} skills linked`
+          );
+        }
       }
 
       // Install Claude Code auto-update hook
@@ -323,12 +403,27 @@ 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 (showGeminiWarning) {
+    if (!removeOnly) {
       console.log('');
-      console.log(chalk.yellow('⚠ Gemini CLI: local skills will override global skills for this project.'));
+      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 (claudeSelected) {
+        console.log(
+          '  ' + chalk.dim('• symlinked: ') +
+          'Claude Code ' + chalk.dim('(~/.claude/skills/)')
+        );
+      }
     }
     console.log('');
     const isProjectDir = isTitaniumProject(process.cwd());

package/lib/config.js

@@ -33,18 +33,17 @@ export const SKILLS = [
   'ti-expert',
   'purgetss',
   'ti-ui',
-];
-// Legacy skills to remove during updates/uninstall
-// ti-api, ti-guides, ti-howtos, alloy-guides, alloy-howtos moved to https://github.com/tidev/skills in v3.0.0
-export const LEGACY_SKILLS = [
-  'alloy-expert',
-  'ti-branding',
   'ti-api',
   'ti-guides',
   'ti-howtos',
   'alloy-guides',
   'alloy-howtos',
 ];
+// Legacy skills to remove during updates/uninstall
+export const LEGACY_SKILLS = [
+  'alloy-expert',
+  'ti-branding',
+];
 
 // Agents to install
 export const AGENTS = [
@@ -65,6 +64,14 @@ export const getCodexSkillsDir = (baseDir = os.homedir()) => path.join(baseDir,
 export const getConfigDir = () => path.join(os.homedir(), '.titools');
 
 // AI platform detection
+//
+// Only platforms that need TiTools-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',
@@ -72,15 +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'),
-  },
-  // 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.
 ];
 
 // Files to install

package/lib/installer.js

@@ -69,12 +69,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: [],
@@ -91,7 +93,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/utils.js

@@ -14,6 +14,42 @@ const __dirname = dirname(__filename);
 const packageRoot = resolve(__dirname, '..');
 const packageSkillsDir = join(packageRoot, 'skills');
 
+/**
+ * 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() + '…';
+}
+
 /**
  * Check if Titanium knowledge block exists in a file
  * @param {string} filePath - Path to the file

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/titools",
-  "version": "3.2.0",
+  "version": "4.0.0",
   "description": "Titanium SDK skills and agents for AI coding assistants (Claude Code, Gemini CLI, Codex CLI)",
   "main": "lib/index.js",
   "type": "module",