skillex 0.2.3 → 0.2.5

package/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.5] - 2026-04-08
+
+### Added
+- `technical-writing-pro` first-party skill for structured technical writing and documentation
+
+### Changed
+- Auto-sync now enabled by default on `skillex init` (was `false`)
+- Auto-sync syncs **all detected adapters**, not only the active one — workspaces with multiple agents (e.g. `.claude/` and `.codex/`) are kept in sync automatically
+- `sync` and auto-sync output now lists each adapter individually with its target path, sync mode, and whether anything changed
+- Removed the restriction that required an active adapter to enable auto-sync
+
+### Fixed
+- Skill removal now cleans up the synced adapter target file and its generated source when the last skill is removed
+- `remove` correctly iterates all resolved adapters when propagating the removal
+
+## [0.2.4] - 2026-04-08
+
+### Changed
+- `skillex ui` skill list now shows compact labels: `Name (id) · tag1, tag2, tag3` — description and full compatibility list removed from each row
+- `skillex ui` shows "Fetching catalog..." while loading and limits visible rows to 12 at a time
+- `skillex install` and `skillex update` now render an inline progress bar (`[████░░░░] 1/5 skill-id`) instead of printing one line per skill
+
 ## [0.2.3] - 2026-04-08
 
 ### Fixed

package/README.md

@@ -41,13 +41,9 @@ npx skillex@latest list
 
 # 3. Install a skill
 npx skillex@latest install create-skills
-
-# 4. Write the installed skills into your agent's config file
-#    ⚠️  This step is required — without it, your agent cannot see the skills.
-npx skillex@latest sync
 ```
 
-> **Important:** `install` only stores skills in Skillex managed state. `sync` is what exposes them to your AI agent. For directory-native adapters such as Codex, Claude, and Gemini, `sync` materializes one folder per skill under the agent's `skills/` directory. For file-based adapters such as Copilot, Cursor, Cline, and Windsurf, `sync` updates the adapter's config file. **You must run `sync` after every install or update for your agent to pick up the changes.** Use `--auto-sync` at `init` time to have this happen automatically.
+> **Important:** auto-sync is enabled by default. After `init`, `install`, `update`, and `remove`, Skillex automatically synchronizes skills into every detected adapter target. For directory-native adapters such as Codex, Claude, and Gemini, this materializes one folder per skill under the agent's `skills/` directory. For file-based adapters such as Copilot, Cursor, Cline, and Windsurf, it updates the adapter config file. Use `skillex sync` when you want to preview, re-run manually, or target a specific adapter.
 
 After `init`, Skillex saves the configured source list in the local lockfile. New workspaces start with `lgili/skillex@main` by default, and you can add more sources later with `skillex source add`.
 
@@ -88,6 +84,7 @@ skillex init
 skillex init --repo <owner/repo>
 skillex init --repo lgili/skillex --adapter cursor
 skillex init --repo lgili/skillex --auto-sync
+skillex init --auto-sync=false
 skillex init --global --adapter codex
 ```
 
@@ -95,7 +92,7 @@ skillex init --global --adapter codex
 |------|-------------|
 | `--repo <owner/repo>` | Optional. Overrides the default first-party source for this workspace. |
 | `--adapter <id>` | Force a specific adapter instead of auto-detecting. |
-| `--auto-sync` | Automatically run `sync` after every install, update, and remove. |
+| `--auto-sync` | Enable or disable automatic sync after install, update, and remove. Default: `true`. |
 | `--ref <branch>` | Use a specific branch or tag (default: `main`). |
 | `--scope <local\|global>` | Choose whether Skillex manages workspace or user-global state. |
 | `--global` | Shortcut for `--scope global`. |
@@ -173,7 +170,7 @@ skillex install create-skills --global
 | `--scope <local\|global>` | Choose whether Skillex writes to `.agent-skills/` or `~/.skillex/`. |
 | `--global` | Shortcut for `--scope global`. |
 
-> **After installing,** run `skillex sync` to write the skills into your agent's config file. Without this step, the agent will not see the newly installed skills. If you initialized with `--auto-sync`, this happens automatically.
+> **After installing,** Skillex syncs automatically by default. Run `skillex sync` manually only when you want to preview changes, re-run synchronization, or force a specific adapter.
 
 ---
 
@@ -208,10 +205,10 @@ skillex remove create-skills --global
 
 ### `sync`
 
-Expose all installed skills to the active adapter. For `codex`, `claude`, and `gemini`, this creates one folder per skill under the adapter's `skills/` directory. For file-based adapters, it updates the adapter's config file. **This is the step that makes skills visible to your AI agent.** Run it after every `install`, `update`, or `remove`.
+Expose all installed skills to the detected adapters. For `codex`, `claude`, and `gemini`, this creates one folder per skill under the adapter's `skills/` directory. For file-based adapters, it updates the adapter's config file. This is the same operation Skillex runs automatically after `install`, `update`, and `remove`.
 
 ```bash
-# Sync to the detected adapter
+# Sync to all detected adapters
 skillex sync
 
 # Preview changes without writing (shows a diff)
@@ -237,22 +234,17 @@ skillex sync --global --adapter codex
 
 #### Using multiple agents in the same workspace
 
-`sync` writes to one adapter at a time. If you use more than one AI agent in the same folder (e.g. Claude and Codex), run `sync` once for each:
+By default, `sync` writes to every detected adapter in the workspace. If you want to limit the operation to one adapter, pass `--adapter`:
 
 ```bash
-# Write skill folders into .claude/skills/<skill-id>/
+# Only sync Claude
 skillex sync --adapter claude
 
-# Write skill folders into .codex/skills/<skill-id>/
+# Only sync Codex
 skillex sync --adapter codex
 ```
 
-Each adapter writes to its own target path, so the two syncs are independent and non-destructive. To avoid running both commands manually after every change, initialize with `--auto-sync` and then re-run `skillex init --adapter <id>` for each adapter you want covered — or simply alias both commands in your workflow:
-
-```bash
-# Sync to all agents at once (shell alias / Makefile target)
-skillex sync --adapter claude && skillex sync --adapter codex
-```
+Each adapter writes to its own target path, so the syncs are independent and non-destructive. Automatic sync uses the same multi-adapter behavior.
 
 ---
 
@@ -580,14 +572,14 @@ For directory-native adapters, `sync` creates per-skill directories such as:
 
 ## Auto-sync
 
-When `--auto-sync` is enabled at `init`, Skillex runs `sync` automatically after every `install`, `update`, and `remove`. This keeps your agent target path always up to date.
+Auto-sync is enabled by default. After `init`, Skillex automatically runs sync after every `install`, `update`, and `remove`, targeting every detected adapter unless you explicitly override one with `--adapter`.
 
 ```bash
-# Enable at init time
+# Explicitly enable at init time
 skillex init --auto-sync
 
-# Or re-initialize to enable it
-skillex init --repo lgili/skillex --auto-sync
+# Explicitly disable it
+skillex init --auto-sync=false
 
 # Enable it for global installs
 skillex init --global --adapter codex --auto-sync

package/dist/cli.js

@@ -21,7 +21,7 @@ Options:
   --repo <owner/repo>   GitHub repository with skills (default: lgili/skillex)
   --ref <ref>           Branch, tag, or commit (default: main)
   --adapter <id>        Force a specific adapter
-  --auto-sync           Enable auto-sync after install/update/remove
+  --auto-sync           Enable or disable auto-sync (default: on)
   --scope <scope>       local or global (default: local)
   --global              Shortcut for --scope global
   --cwd <path>          Target project directory (default: current directory)
@@ -296,6 +296,9 @@ async function handleInit(flags, userConfig) {
             `  Use --adapter <id> to specify one. Available: ${listAdapters().map((a) => a.id).join(", ")}`);
     }
     output.info(`  Auto-sync: ${result.lockfile.settings.autoSync ? "enabled" : "disabled"}`);
+    if (result.lockfile.adapters.detected.length > 0) {
+        output.info(`  Detected : ${result.lockfile.adapters.detected.join(", ")}`);
+    }
     output.info("\nNext: run 'skillex list' to browse available skills");
 }
 async function handleList(flags, userConfig) {
@@ -362,11 +365,9 @@ async function handleInstall(positionals, flags, userConfig) {
     const result = await installSkills(positionals, {
         ...opts,
         installAll,
-        onProgress: (current, total, skillId) => {
-            output.info(`[${current}/${total}] Installing ${skillId}...`);
-        },
+        onProgress: (current, total, skillId) => output.progress(current, total, skillId),
     });
-    output.success(`Installed ${result.installedCount} skill(s) to ${result.statePaths.scope} state at ${result.statePaths.stateDir}`);
+    output.success(`Installed ${result.installedCount} skill(s)`);
     for (const skill of result.installedSkills) {
         output.info(`  + ${skill.id}@${skill.version}`);
     }
@@ -374,7 +375,10 @@ async function handleInstall(positionals, flags, userConfig) {
 }
 async function handleUpdate(positionals, flags, userConfig) {
     const opts = commonOptions(flags, userConfig);
-    const result = await updateInstalledSkills(positionals, opts);
+    const result = await updateInstalledSkills(positionals, {
+        ...opts,
+        onProgress: (current, total, skillId) => output.progress(current, total, skillId),
+    });
     if (result.updatedSkills.length === 0) {
         output.info("No skills updated.");
     }
@@ -405,17 +409,19 @@ async function handleRemove(positionals, flags, userConfig) {
 async function handleSync(flags, userConfig) {
     const result = await syncInstalledSkills(commonOptions(flags, userConfig));
     if (result.dryRun) {
-        output.info(`Preview: ${result.skillCount} skill(s) → ${result.sync.adapter}`);
-        output.info(`Target path : ${result.sync.targetPath}`);
-        output.info(`Sync mode   : ${result.syncMode}`);
+        output.info(`Preview: ${result.skillCount} skill(s)`);
+        for (const entry of result.syncs) {
+            output.info(`  ${entry.adapter} → ${entry.targetPath} [${entry.syncMode}]${entry.changed ? "" : " (no changes)"}`);
+        }
         process.stdout.write(result.diff);
         return;
     }
-    output.success(`Synced ${result.skillCount} skill(s) → ${result.sync.adapter}`);
-    output.info(`Target path : ${result.sync.targetPath}`);
-    output.info(`Sync mode   : ${result.syncMode}`);
+    output.success(`Synced ${result.skillCount} skill(s)`);
+    for (const entry of result.syncs) {
+        output.info(`  ${entry.adapter} → ${entry.targetPath} [${entry.syncMode}]${entry.changed ? "" : " (no changes)"}`);
+    }
     if (!result.changed) {
-        output.info("No changes to the target path.");
+        output.info("No changes to the target paths.");
     }
 }
 async function handleRun(positionals, flags, userConfig) {
@@ -437,7 +443,9 @@ async function handleUi(flags, userConfig) {
     const options = commonOptions(flags, userConfig);
     const state = await getInstalledSkills(options);
     const source = await resolveProjectSource(options);
+    output.statusLine("Fetching catalog...");
     const catalog = await loadCatalog({ ...source, ...cacheOptions(options) });
+    output.clearStatus();
     if (catalog.skills.length === 0) {
         output.info("No skills available in the catalog.");
         return;
@@ -450,19 +458,24 @@ async function handleUi(flags, userConfig) {
             : "No skills available in the catalog.");
         return;
     }
-    const installResult = selection.toInstall.length > 0 ? await installSkills(selection.toInstall, options) : null;
+    const installResult = selection.toInstall.length > 0
+        ? await installSkills(selection.toInstall, {
+            ...options,
+            onProgress: (current, total, skillId) => output.progress(current, total, skillId),
+        })
+        : null;
     const removeResult = selection.toRemove.length > 0 ? await removeSkills(selection.toRemove, options) : null;
     if (!installResult && !removeResult) {
         output.info("No changes applied.");
         return;
     }
-    output.success("UI summary:");
     if (installResult) {
-        output.info(`  Installed : ${installResult.installedSkills.map((s) => s.id).join(", ")}`);
+        output.success(`Installed: ${installResult.installedSkills.map((s) => s.id).join(", ")}`);
     }
     if (removeResult) {
-        output.info(`  Removed   : ${removeResult.removedSkills.join(", ")}`);
+        output.success(`Removed: ${removeResult.removedSkills.join(", ")}`);
     }
+    printAutoSyncResult(installResult?.autoSync ?? removeResult?.autoSync ?? null);
 }
 async function handleStatus(flags, userConfig) {
     const options = commonOptions(flags, userConfig);
@@ -925,8 +938,9 @@ function parseSyncMode(value) {
 function printAutoSyncResult(result) {
     if (!result)
         return;
-    const suffix = result.changed ? "" : " (no changes)";
-    output.info(`Auto-sync: ${result.sync.adapter} → ${result.sync.targetPath} [${result.syncMode}]${suffix}`);
+    for (const entry of result.syncs) {
+        output.info(`Sync: ${entry.adapter} → ${entry.targetPath} [${entry.syncMode}]${entry.changed ? "" : " (no changes)"}`);
+    }
 }
 function asOptionalString(value) {
     return typeof value === "string" ? value : undefined;

package/dist/install.js

@@ -36,9 +36,6 @@ export async function initProject(options = {}) {
             lockfile.sources = [toLockfileSource(source)];
         }
         lockfile.settings.autoSync = options.autoSync ?? lockfile.settings.autoSync;
-        if (lockfile.settings.autoSync && !lockfile.adapters.active) {
-            throw new InstallError("Auto-sync requires an active adapter. Use --adapter <id> or run in a detectable workspace.", "AUTO_SYNC_REQUIRES_ADAPTER");
-        }
         lockfile.updatedAt = now();
         await writeJson(statePaths.lockfilePath, lockfile);
         // Create .gitignore for the local state directory on first init.
@@ -129,7 +126,8 @@ export async function installSkills(requestedSkillIds, options = {}) {
         const autoSync = await maybeAutoSync(withAgentSkillsDir({
             cwd,
             scope: options.scope,
-            adapter: lockfile.adapters.active,
+            adapters: lockfile.adapters,
+            adapterOverride: options.adapter,
             enabled: lockfile.settings.autoSync,
             now,
             changed: installedSkills.length > 0,
@@ -217,7 +215,8 @@ export async function updateInstalledSkills(requestedSkillIds, options = {}) {
         const autoSync = await maybeAutoSync(withAgentSkillsDir({
             cwd,
             scope: options.scope,
-            adapter: lockfile.adapters.active,
+            adapters: lockfile.adapters,
+            adapterOverride: options.adapter,
             enabled: lockfile.settings.autoSync,
             now,
             changed: updatedSkills.length > 0,
@@ -272,10 +271,13 @@ export async function removeSkills(requestedSkillIds, options = {}) {
         }
         lockfile.updatedAt = now();
         await writeJson(statePaths.lockfilePath, lockfile);
-        const autoSync = await maybeAutoSync(withAgentSkillsDir({
+        const autoSync = await maybeSyncAfterRemove(withAgentSkillsDir({
             cwd,
             scope: options.scope,
-            adapter: lockfile.adapters.active,
+            adapters: lockfile.adapters,
+            adapterOverride: options.adapter,
+            syncHistory: lockfile.syncHistory,
+            legacySync: lockfile.sync,
             enabled: lockfile.settings.autoSync,
             now,
             changed: removedSkills.length > 0,
@@ -312,55 +314,93 @@ export async function syncInstalledSkills(options = {}) {
         }
         const defaultSource = resolveSource(toCatalogSourceInput(options, resolvePrimarySourceOverride(options, existing)));
         const lockfile = normalizeLockfile(existing, defaultSource, now);
-        const adapterId = options.adapter || lockfile.adapters.active;
-        if (!adapterId) {
+        const adapterIds = resolveSyncAdapterIds(lockfile.adapters, options.adapter);
+        if (adapterIds.length === 0) {
             throw new InstallError("No active adapter configured. Run: skillex init --adapter <id> or use --adapter.", "ACTIVE_ADAPTER_MISSING");
         }
         const skills = await loadInstalledSkillDocuments({
             cwd,
             lockfile,
         });
-        const syncResult = await syncAdapterFiles({
-            cwd,
-            scope: statePaths.scope,
-            adapterId,
-            statePaths,
-            skills,
-            previousSkillIds: lockfile.sync?.skillIds || [],
-            ...(options.mode ? { mode: options.mode } : {}),
-            ...(options.dryRun !== undefined ? { dryRun: options.dryRun } : {}),
-        });
+        const syncResults = [];
+        const diffParts = [];
+        for (const adapterId of adapterIds) {
+            const syncResult = await syncAdapterFiles({
+                cwd,
+                scope: statePaths.scope,
+                adapterId,
+                statePaths,
+                skills,
+                previousSkillIds: lockfile.syncHistory[adapterId]?.skillIds || lockfile.sync?.skillIds || [],
+                ...(options.mode ? { mode: options.mode } : {}),
+                ...(options.dryRun !== undefined ? { dryRun: options.dryRun } : {}),
+            });
+            syncResults.push(syncResult);
+            if (syncResult.diff.trim()) {
+                diffParts.push(syncResult.diff.trimEnd());
+            }
+        }
+        const primarySync = syncResults[0];
+        if (!primarySync) {
+            throw new InstallError("No adapter configured for synchronization. Use --adapter <id> or work in a detectable workspace.", "ACTIVE_ADAPTER_MISSING");
+        }
         if (options.dryRun) {
             return {
                 statePaths,
                 sync: {
-                    adapter: syncResult.adapter,
-                    targetPath: syncResult.targetPath,
+                    adapter: primarySync.adapter,
+                    targetPath: primarySync.targetPath,
                 },
+                syncs: syncResults.map((result) => ({
+                    adapter: result.adapter,
+                    targetPath: result.targetPath,
+                    syncMode: result.syncMode,
+                    changed: result.changed,
+                })),
                 skillCount: skills.length,
-                changed: syncResult.changed,
-                diff: syncResult.diff,
+                changed: syncResults.some((result) => result.changed),
+                diff: diffParts.length > 0 ? `${diffParts.join("\n\n")}\n` : "",
                 dryRun: true,
-                syncMode: syncResult.syncMode,
+                syncMode: primarySync.syncMode,
             };
         }
-        lockfile.sync = {
-            adapter: syncResult.adapter,
-            targetPath: syncResult.targetPath,
+        const primaryMetadata = {
+            adapter: primarySync.adapter,
+            targetPath: primarySync.targetPath,
             syncedAt: now(),
             skillIds: skills.map((skill) => skill.id),
         };
-        lockfile.syncMode = syncResult.syncMode;
+        const nextSyncHistory = {
+            ...lockfile.syncHistory,
+            [primarySync.adapter]: primaryMetadata,
+        };
+        for (const syncResult of syncResults.slice(1)) {
+            nextSyncHistory[syncResult.adapter] = {
+                adapter: syncResult.adapter,
+                targetPath: syncResult.targetPath,
+                syncedAt: now(),
+                skillIds: skills.map((skill) => skill.id),
+            };
+        }
+        lockfile.sync = primaryMetadata;
+        lockfile.syncHistory = nextSyncHistory;
+        lockfile.syncMode = primarySync.syncMode;
         lockfile.updatedAt = now();
         await writeJson(statePaths.lockfilePath, lockfile);
         return {
             statePaths,
-            sync: lockfile.sync,
+            sync: primaryMetadata,
+            syncs: syncResults.map((result) => ({
+                adapter: result.adapter,
+                targetPath: result.targetPath,
+                syncMode: result.syncMode,
+                changed: result.changed,
+            })),
             skillCount: skills.length,
-            changed: syncResult.changed,
-            diff: syncResult.diff,
+            changed: syncResults.some((result) => result.changed),
+            diff: diffParts.length > 0 ? `${diffParts.join("\n\n")}\n` : "",
             dryRun: false,
-            syncMode: syncResult.syncMode,
+            syncMode: primarySync.syncMode,
         };
     }
     catch (error) {
@@ -541,9 +581,10 @@ function createBaseLockfile(source, now) {
             detected: [],
         },
         settings: {
-            autoSync: false,
+            autoSync: true,
         },
         sync: null,
+        syncHistory: {},
         syncMode: null,
         installed: {},
     };
@@ -666,13 +707,35 @@ function normalizeLockfile(existing, source, now) {
             detected: [...new Set(detectedAdapters.filter(Boolean))],
         },
         settings: {
-            autoSync: Boolean(existing.settings?.autoSync),
+            autoSync: existing.settings?.autoSync ?? true,
         },
         sync: existing.sync || null,
+        syncHistory: normalizeSyncHistory(existing),
         syncMode: existing.syncMode || null,
         installed: existing.installed || {},
     };
 }
+function normalizeSyncHistory(existing) {
+    const history = {};
+    const candidate = existing && "syncHistory" in existing && existing.syncHistory && typeof existing.syncHistory === "object"
+        ? existing.syncHistory
+        : null;
+    if (candidate) {
+        for (const [adapterId, metadata] of Object.entries(candidate)) {
+            if (!metadata || typeof metadata !== "object") {
+                continue;
+            }
+            if (!("adapter" in metadata) || !("targetPath" in metadata) || !("syncedAt" in metadata)) {
+                continue;
+            }
+            history[adapterId] = metadata;
+        }
+    }
+    if (existing?.sync?.adapter && !history[existing.sync.adapter]) {
+        history[existing.sync.adapter] = existing.sync;
+    }
+    return history;
+}
 /** Repos that are known placeholder values written by older versions and must be ignored. */
 const PLACEHOLDER_REPOS = new Set(["owner/repo"]);
 function getLockfileSources(existing, fallbackSource) {
@@ -835,15 +898,65 @@ async function maybeAutoSync(options) {
     if (!options.enabled || !options.changed) {
         return null;
     }
+    if (resolveSyncAdapterIds(options.adapters, options.adapterOverride).length === 0) {
+        return null;
+    }
     return syncInstalledSkills({
         cwd: options.cwd,
         scope: options.scope || DEFAULT_INSTALL_SCOPE,
         ...(options.agentSkillsDir ? { agentSkillsDir: options.agentSkillsDir } : {}),
-        ...(options.adapter ? { adapter: options.adapter } : {}),
+        ...(options.adapterOverride ? { adapter: options.adapterOverride } : {}),
         ...(options.mode ? { mode: options.mode } : {}),
         now: options.now,
     });
 }
+async function maybeSyncAfterRemove(options) {
+    if (!options.changed) {
+        return null;
+    }
+    const adapters = new Set();
+    for (const adapterId of Object.keys(options.syncHistory || {})) {
+        adapters.add(adapterId);
+    }
+    if (options.legacySync?.adapter) {
+        adapters.add(options.legacySync.adapter);
+    }
+    if (options.adapterOverride) {
+        adapters.add(options.adapterOverride);
+    }
+    else if (options.enabled) {
+        for (const adapterId of resolveSyncAdapterIds(options.adapters)) {
+            adapters.add(adapterId);
+        }
+    }
+    let result = null;
+    for (const adapterId of adapters) {
+        result = await syncInstalledSkills({
+            cwd: options.cwd,
+            scope: options.scope || DEFAULT_INSTALL_SCOPE,
+            ...(options.agentSkillsDir ? { agentSkillsDir: options.agentSkillsDir } : {}),
+            adapter: adapterId,
+            ...(options.mode ? { mode: options.mode } : {}),
+            now: options.now,
+        });
+    }
+    return result;
+}
+function resolveSyncAdapterIds(adapters, adapterOverride) {
+    if (adapterOverride) {
+        return [adapterOverride];
+    }
+    const adapterIds = [];
+    if (adapters.active) {
+        adapterIds.push(adapters.active);
+    }
+    for (const adapterId of adapters.detected || []) {
+        if (!adapterIds.includes(adapterId)) {
+            adapterIds.push(adapterId);
+        }
+    }
+    return adapterIds;
+}
 function toCatalogSourceInput(options, overrides = {}) {
     const input = {};
     if (options.owner) {

package/dist/output.d.ts

@@ -44,3 +44,22 @@ export declare function error(message: string): void;
  * @param message - Debug message.
  */
 export declare function debug(message: string): void;
+/**
+ * Renders an inline progress bar that overwrites the current line.
+ * Prints a newline when current === total.
+ *
+ * @param current - Number of completed items (1-based).
+ * @param total - Total number of items.
+ * @param label - Short label shown after the bar.
+ */
+export declare function progress(current: number, total: number, label: string): void;
+/**
+ * Writes a transient status message on the current line (overwritable with clearStatus).
+ *
+ * @param message - Status message to display.
+ */
+export declare function statusLine(message: string): void;
+/**
+ * Clears the current status line written by {@link statusLine}.
+ */
+export declare function clearStatus(): void;

package/dist/output.js

@@ -76,3 +76,46 @@ export function debug(message) {
         process.stderr.write(applyColor("2", `[debug] ${message}`, process.stderr) + "\n");
     }
 }
+// ---------------------------------------------------------------------------
+// Progress and status helpers (TTY-only; fall back to plain lines otherwise)
+// ---------------------------------------------------------------------------
+/**
+ * Renders an inline progress bar that overwrites the current line.
+ * Prints a newline when current === total.
+ *
+ * @param current - Number of completed items (1-based).
+ * @param total - Total number of items.
+ * @param label - Short label shown after the bar.
+ */
+export function progress(current, total, label) {
+    if (!process.stdout.isTTY) {
+        console.log(`[${current}/${total}] ${label}`);
+        return;
+    }
+    const filled = total > 0 ? Math.round((current / total) * 16) : 0;
+    const bar = applyColor("32", "█".repeat(filled), process.stdout) + "░".repeat(16 - filled);
+    const counter = applyColor("2", `${current}/${total}`, process.stdout);
+    const line = `  [${bar}] ${counter}  ${label}`;
+    process.stdout.write(`\r${line}\x1b[K`);
+    if (current === total) {
+        process.stdout.write("\n");
+    }
+}
+/**
+ * Writes a transient status message on the current line (overwritable with clearStatus).
+ *
+ * @param message - Status message to display.
+ */
+export function statusLine(message) {
+    if (!process.stdout.isTTY)
+        return;
+    process.stdout.write(`\r  ${applyColor("2", message, process.stdout)}\x1b[K`);
+}
+/**
+ * Clears the current status line written by {@link statusLine}.
+ */
+export function clearStatus() {
+    if (!process.stdout.isTTY)
+        return;
+    process.stdout.write("\r\x1b[K");
+}

package/dist/sync.js

@@ -51,7 +51,16 @@ export async function syncAdapterFiles(options) {
     try {
         const prepared = await prepareSyncAdapterFiles(options);
         if (!options.dryRun) {
-            if (prepared.directoryEntries) {
+            if (prepared.removeTarget) {
+                if (prepared.generatedSourcePath) {
+                    await removePath(prepared.generatedSourcePath);
+                }
+                await removePath(prepared.absoluteTargetPath);
+                for (const cleanupPath of prepared.cleanupPaths) {
+                    await removePath(cleanupPath);
+                }
+            }
+            else if (prepared.directoryEntries) {
                 await ensureDir(prepared.absoluteTargetPath);
                 const createLink = options.linkFactory || createSymlink;
                 let finalMode = prepared.syncMode;
@@ -144,8 +153,28 @@ export async function prepareSyncAdapterFiles(options) {
     const autoInjectBlock = buildAutoInjectBlock(options.skills);
     if (adapter.syncMode === "managed-block") {
         const existing = (await readText(absoluteTargetPath, "")) || "";
-        const nextManaged = upsertManagedBlock(existing, wrapManagedBlock(MANAGED_START, MANAGED_END, body));
-        const nextContent = upsertAutoInjectBlock(nextManaged, autoInjectBlock);
+        const nextManaged = options.skills.length === 0
+            ? upsertManagedBlock(existing, null)
+            : upsertManagedBlock(existing, wrapManagedBlock(MANAGED_START, MANAGED_END, body));
+        const nextContent = upsertAutoInjectBlock(nextManaged, options.skills.length === 0 ? null : autoInjectBlock);
+        if (nextContent === "") {
+            return {
+                adapter: adapter.id,
+                absoluteTargetPath,
+                targetPath,
+                cleanupPaths,
+                removeTarget: true,
+                changed: Boolean(normalizeComparableText(existing)) || cleanupPaths.length > 0,
+                currentContent: existing,
+                nextContent: "",
+                diff: createManagedBlockRemovalDiff({
+                    targetPath,
+                    currentContent: existing,
+                    cleanupPaths: cleanupPaths.map((cleanupPath) => toDisplayPath(options.cwd, cleanupPath, options.statePaths.scope)),
+                }),
+                syncMode: "copy",
+            };
+        }
         return {
             adapter: adapter.id,
             absoluteTargetPath,
@@ -160,6 +189,35 @@ export async function prepareSyncAdapterFiles(options) {
     }
     const nextContent = buildManagedFileContent(adapter.id, body, autoInjectBlock);
     const requestedMode = options.mode || "symlink";
+    const generatedSourcePath = path.join(options.statePaths.generatedDirPath, adapter.id, path.basename(adapter.syncTarget));
+    if (options.skills.length === 0) {
+        const currentDescriptor = await describeTarget(absoluteTargetPath);
+        const currentVisibleContent = (await readText(absoluteTargetPath, "")) || "";
+        const generatedExists = await pathExists(generatedSourcePath);
+        return {
+            adapter: adapter.id,
+            absoluteTargetPath,
+            targetPath,
+            cleanupPaths,
+            removeTarget: true,
+            changed: Boolean(normalizeComparableText(currentDescriptor)) ||
+                Boolean(normalizeComparableText(currentVisibleContent)) ||
+                generatedExists ||
+                cleanupPaths.length > 0,
+            currentContent: currentDescriptor,
+            nextContent: "",
+            diff: createManagedFileRemovalDiff({
+                targetPath,
+                generatedPath: toDisplayPath(options.cwd, generatedSourcePath, options.statePaths.scope),
+                generatedExists,
+                currentDescriptor,
+                currentContent: currentVisibleContent,
+                cleanupPaths: cleanupPaths.map((cleanupPath) => toDisplayPath(options.cwd, cleanupPath, options.statePaths.scope)),
+            }),
+            syncMode: requestedMode,
+            generatedSourcePath,
+        };
+    }
     if (requestedMode === "copy") {
         const existing = (await readText(absoluteTargetPath, "")) || "";
         return {
@@ -174,7 +232,6 @@ export async function prepareSyncAdapterFiles(options) {
             syncMode: "copy",
         };
     }
-    const generatedSourcePath = path.join(options.statePaths.generatedDirPath, adapter.id, path.basename(adapter.syncTarget));
     const currentDescriptor = await describeTarget(absoluteTargetPath);
     const currentVisibleContent = (await readText(absoluteTargetPath, "")) || "";
     const nextDescriptor = `symlink -> ${toPosix(path.relative(path.dirname(absoluteTargetPath), generatedSourcePath))}\n`;
@@ -437,6 +494,35 @@ function createManagedFileDiff(context) {
     }
     return `${parts.join("\n")}\n`;
 }
+function createManagedBlockRemovalDiff(context) {
+    const parts = [];
+    if (normalizeComparableText(context.currentContent) !== "") {
+        parts.push(createTextDiff(context.currentContent, "", context.targetPath).trimEnd());
+    }
+    for (const cleanupPath of context.cleanupPaths) {
+        parts.push(`- remove ${cleanupPath}`);
+    }
+    if (parts.length === 0) {
+        return `Sem alteracoes em ${context.targetPath}.\n`;
+    }
+    return `${parts.join("\n")}\n`;
+}
+function createManagedFileRemovalDiff(context) {
+    const parts = [];
+    if (normalizeComparableText(context.currentDescriptor) !== "") {
+        parts.push(createTextDiff(context.currentDescriptor, "", context.targetPath).trimEnd());
+    }
+    if (normalizeComparableText(context.currentContent) !== "") {
+        parts.push(createTextDiff(context.currentContent, "", context.targetPath).trimEnd());
+    }
+    if (context.generatedExists) {
+        parts.push(`- remove ${context.generatedPath}`);
+    }
+    for (const cleanupPath of context.cleanupPaths) {
+        parts.push(`- remove ${cleanupPath}`);
+    }
+    return `${parts.join("\n")}\n`;
+}
 function createTextDiff(currentContent, nextContent, targetPath) {
     if (normalizeComparableText(currentContent) === normalizeComparableText(nextContent)) {
         return `Sem alteracoes em ${targetPath}.\n`;

package/dist/types.d.ts

@@ -172,6 +172,10 @@ export interface SyncMetadata {
     syncedAt: string;
     skillIds?: string[] | undefined;
 }
+/**
+ * Per-adapter synchronization metadata persisted in the lockfile.
+ */
+export type SyncHistory = Record<string, SyncMetadata>;
 /**
  * Full workspace lockfile structure.
  */
@@ -183,6 +187,7 @@ export interface LockfileState {
     adapters: LockfileAdapters;
     settings: LockfileSettings;
     sync: SyncMetadata | null;
+    syncHistory: SyncHistory;
     syncMode: SyncWriteMode | null;
     installed: Record<string, InstalledSkillMetadata>;
 }
@@ -263,6 +268,7 @@ export interface PreparedSyncResult {
     absoluteTargetPath: string;
     targetPath: string;
     cleanupPaths: string[];
+    removeTarget?: boolean | undefined;
     changed: boolean;
     currentContent: string;
     nextContent: string;
@@ -291,6 +297,15 @@ export interface SyncPreview {
     before: string;
     after: string;
 }
+/**
+ * Per-adapter sync summary returned to callers.
+ */
+export interface SyncExecutionSummary {
+    adapter: string;
+    targetPath: string;
+    syncMode: SyncWriteMode;
+    changed: boolean;
+}
 /**
  * Public sync result returned after writing or dry-run preparation.
  */
@@ -325,6 +340,7 @@ export interface SyncCommandResult {
         adapter: string;
         targetPath: string;
     } | SyncMetadata;
+    syncs: SyncExecutionSummary[];
     skillCount: number;
     changed: boolean;
     diff: string;

package/dist/ui.d.ts

@@ -12,6 +12,7 @@ interface UiPrompts {
     checkbox?: ((options: {
         message: string;
         instructions?: string | undefined;
+        pageSize?: number | undefined;
         choices: UiChoice[];
     }) => Promise<string[]>) | undefined;
 }

package/dist/ui.js

@@ -33,13 +33,21 @@ export async function runInteractiveUi(options) {
     const selectedIds = filteredSkills.length === 0
         ? []
         : await (prompts.checkbox || fallbackCheckbox)({
-            message: "Selecione as skills",
-            instructions: "Type to filter first • Space to select • Enter to install",
-            choices: filteredSkills.map((skill) => ({
-                name: `${skill.name} (${skill.id}) - ${skill.description || "Sem descricao"} [${skill.compatibility.join(",") || "sem-compat"}]`,
-                value: skill.id,
-                checked: installedSet.has(skill.id),
-            })),
+            message: "Select skills",
+            instructions: "↑↓ navigate  ·  space select  ·  enter confirm  ·  type to filter",
+            pageSize: 12,
+            choices: filteredSkills.map((skill) => {
+                const tags = (skill.tags ?? []).slice(0, 4).join(", ");
+                const detail = tags || (skill.description ?? "").slice(0, 55);
+                const label = detail
+                    ? `${skill.name}  (${skill.id})  ·  ${detail}`
+                    : `${skill.name}  (${skill.id})`;
+                return {
+                    name: label,
+                    value: skill.id,
+                    checked: installedSet.has(skill.id),
+                };
+            }),
         });
     const selectedSet = new Set(selectedIds);
     const toInstall = selectedIds.filter((skillId) => !installedSet.has(skillId));
@@ -62,6 +70,7 @@ async function loadPromptAdapters() {
         checkbox: async (options) => prompts.checkbox({
             message: options.message,
             ...(options.instructions ? { instructions: options.instructions } : {}),
+            ...(options.pageSize !== undefined ? { pageSize: options.pageSize } : {}),
             choices: options.choices.map((choice) => ({
                 name: choice.name,
                 value: choice.value,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillex",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "CLI to list, install, and synchronize AI agent skills from GitHub-hosted catalogs.",
   "type": "module",
   "repository": {