skillex 0.2.4 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-04-08
+
+### Added
+- `skillex ui` now launches a local HTTP server serving the interactive Vue/Vite SPA instead of a terminal TUI
+- New Vue 3 + Vite single-page application under `ui/` with catalog browser, skill detail pages, and router-based navigation
+- `src/web-ui.ts`: self-contained HTTP server with `/api/skills` and `/api/catalog` JSON endpoints and graceful shutdown
+- `src/markdown.ts`: shared Markdown-to-HTML renderer used by the web API
+- Terminal browser detection: `skillex ui` opens the local server in the platform default browser or a detected terminal viewer
+
+### Changed
+- `src/cli.ts`: `ui` command now delegates to the local web-UI server
+- `src/ui.ts`: updated to detect and delegate to terminal browser when available
+- Build: `npm run build` now runs `build:ui` (Vite) followed by `tsc`
+
+## [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

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`.
 
@@ -75,6 +71,23 @@ npm install -D skillex
 npx skillex <command>
 ```
 
+### Local Web UI development
+
+When working on the repository itself, the browser UI is a standalone Vue 3 + Vite frontend under [`ui/`](/Users/lgili/Documents/01%20-%20Codes/01%20-%20Github/Skill/ui). The CLI serves the built assets from [`dist-ui/`](/Users/lgili/Documents/01%20-%20Codes/01%20-%20Github/Skill/dist-ui) and keeps all install/remove/update/sync logic in the local TypeScript backend.
+
+```bash
+npm install
+npm run build:ui
+npm run build
+node ./bin/skillex.js ui
+```
+
+For frontend-only iteration:
+
+```bash
+npm run dev:ui
+```
+
 ---
 
 ## Commands
@@ -88,6 +101,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 +109,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 +187,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 +222,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 +251,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.
 
 ---
 
@@ -267,12 +276,25 @@ skillex run git-master:cleanup --yes   # skip confirmation
 
 ---
 
+### Default terminal browser
+
+Running `skillex` with no subcommand now opens the interactive terminal browser by default.
+
+```bash
+skillex
+skillex browse
+skillex tui
+```
+
+---
+
 ### `ui`
 
-Open an interactive terminal UI to browse and install skills.
+Open the local Web UI in your browser.
 
 ```bash
 skillex ui
+skillex ui --global
 ```
 
 ---
@@ -580,14 +602,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.d.ts

@@ -5,3 +5,4 @@
  * @throws {CliError} When the command or flag values are invalid.
  */
 export declare function main(argv: string[]): Promise<void>;
+export declare function resolveCommandRoute(command: string | undefined): string;

package/dist/cli.js

@@ -1,12 +1,13 @@
 import * as path from "node:path";
 import { listAdapters } from "./adapters.js";
-import { computeCatalogCacheKey, loadCatalog, readCatalogCache, searchCatalogSkills, } from "./catalog.js";
+import { computeCatalogCacheKey, readCatalogCache, searchCatalogSkills, } from "./catalog.js";
 import { DEFAULT_INSTALL_SCOPE, getScopedStatePaths } from "./config.js";
 import { addProjectSource, getInstalledSkills, initProject, installSkills, listProjectSources, loadProjectCatalogs, removeProjectSource, removeSkills, resolveProjectSource, syncInstalledSkills, updateInstalledSkills, } from "./install.js";
 import * as output from "./output.js";
 import { setVerbose } from "./output.js";
 import { parseSkillCommandReference, runSkillScript } from "./runner.js";
 import { runInteractiveUi } from "./ui.js";
+import { startWebUiServer } from "./web-ui.js";
 import { CliError } from "./types.js";
 import { VALID_CONFIG_KEYS, readUserConfig, writeUserConfig } from "./user-config.js";
 // ---------------------------------------------------------------------------
@@ -21,7 +22,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)
@@ -124,7 +125,9 @@ Options:
 
 Example:
   skillex run git-master:cleanup --yes`,
-    ui: `Usage: skillex ui [options]
+    browse: `Usage: skillex browse [options]
+         skillex tui [options]
+         skillex [options]
 
 Open the interactive terminal browser to browse and install skills.
 
@@ -133,7 +136,21 @@ Options:
   --no-cache            Bypass local catalog cache
 
 Example:
-  skillex ui`,
+  skillex
+  skillex browse`,
+    ui: `Usage: skillex ui [options]
+
+Open the local Web UI in your browser.
+
+Options:
+  --repo <owner/repo>   GitHub repository
+  --scope <scope>       local or global (default: local)
+  --global              Shortcut for --scope global
+  --no-cache            Bypass local catalog cache
+
+Example:
+  skillex ui
+  skillex ui --global`,
     status: `Usage: skillex status [options]
 
 Show the installation status of the selected scope.
@@ -206,9 +223,14 @@ export async function main(argv) {
     if (userConfig.githubToken && !process.env.GITHUB_TOKEN) {
         process.env.GITHUB_TOKEN = userConfig.githubToken;
     }
+    const resolvedCommand = resolveCommandRoute(command);
+    if (flags.help === true && !command) {
+        printHelp();
+        return;
+    }
     // Per-command --help
-    if (flags.help === true && command && command !== "help") {
-        const helpText = COMMAND_HELP[command];
+    if (flags.help === true && resolvedCommand && resolvedCommand !== "help") {
+        const helpText = COMMAND_HELP[resolvedCommand];
         if (helpText) {
             output.info(helpText);
         }
@@ -217,13 +239,13 @@ export async function main(argv) {
         }
         return;
     }
-    // Resolve command aliases
-    const resolvedCommand = resolveAlias(command);
     switch (resolvedCommand) {
         case "help":
-        case undefined:
             printHelp();
             return;
+        case "browse":
+            await handleBrowse(flags, userConfig);
+            return;
         case "init":
             await handleInit(flags, userConfig);
             return;
@@ -249,7 +271,7 @@ export async function main(argv) {
             await handleRun(positionals, flags, userConfig);
             return;
         case "ui":
-            await handleUi(flags, userConfig);
+            await handleWebUi(flags, userConfig);
             return;
         case "status":
             await handleStatus(flags, userConfig);
@@ -296,6 +318,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) {
@@ -406,17 +431,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) {
@@ -434,12 +461,11 @@ async function handleRun(positionals, flags, userConfig) {
         process.exitCode = exitCode;
     }
 }
-async function handleUi(flags, userConfig) {
+async function handleBrowse(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) });
+    const catalog = await loadProjectCatalogs({ ...options, ...cacheOptions(options) });
     output.clearStatus();
     if (catalog.skills.length === 0) {
         output.info("No skills available in the catalog.");
@@ -472,6 +498,15 @@ async function handleUi(flags, userConfig) {
     }
     printAutoSyncResult(installResult?.autoSync ?? removeResult?.autoSync ?? null);
 }
+async function handleWebUi(flags, userConfig) {
+    const options = commonOptions(flags, userConfig);
+    const session = await startWebUiServer(options);
+    output.success(`Skillex Web UI running at ${session.url}`);
+    if (!session.opened) {
+        output.warn("Could not open the browser automatically. Open the URL above manually.");
+    }
+    output.info("Press Ctrl+C to stop the local server.");
+}
 async function handleStatus(flags, userConfig) {
     const options = commonOptions(flags, userConfig);
     const state = await getInstalledSkills(options);
@@ -732,13 +767,17 @@ async function handleConfig(positionals, flags) {
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
-function resolveAlias(command) {
+export function resolveCommandRoute(command) {
     const ALIASES = {
         ls: "list",
         rm: "remove",
         uninstall: "remove",
+        tui: "browse",
     };
-    return command !== undefined ? (ALIASES[command] ?? command) : undefined;
+    if (command === undefined) {
+        return "browse";
+    }
+    return ALIASES[command] ?? command;
 }
 function commonOptions(flags, userConfig = {}) {
     const options = {
@@ -856,6 +895,7 @@ function printHelp() {
     output.info(`skillex — AI agent skill manager
 
 Commands:
+  skillex                                open the terminal browser
   skillex init [--repo owner/repo] [--ref main]
   skillex list [--json]
   skillex search [query] [--compatibility claude] [--tag git]
@@ -863,10 +903,11 @@ Commands:
   skillex install --all
   skillex update [skill-id...]
   skillex remove <skill-id...>           aliases: rm, uninstall
+  skillex browse                         aliases: tui
   skillex source <add|remove|list> [...]
   skillex sync [--adapter id] [--dry-run] [--mode copy]
   skillex run <skill-id:command> [--yes] [--timeout 30]
-  skillex ui
+  skillex ui                             open local Web UI
   skillex status [--json]
   skillex doctor [--json]
   skillex config set <key> <value>
@@ -933,8 +974,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;