skillex 0.3.1 → 0.4.1

package/CHANGELOG.md

@@ -7,6 +7,282 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-05-02
+
+A developer-experience patch on top of 0.4.0. Same runtime behaviour for end
+users; one-command Web UI dev workflow for contributors.
+
+### Added
+- **`npm run dev`** — one-command dev orchestrator (`scripts/dev.mjs`). Spawns the Skillex backend with `--no-open --port 4174`, parses the token from the first `Skillex Web UI running at <url>` line, spawns the Vite dev server on port 4175 with `VITE_SKILLEX_BACKEND` pre-wired, and opens the browser at `http://127.0.0.1:4175?token=<token>` automatically. Ctrl+C cleanly tears both processes down.
+- New convenience npm scripts:
+  - `npm run dev` — full dev loop (above)
+  - `npm run web` — alias for `npm run build && node ./bin/skillex.js ui`
+  - `npm run tui` — open the interactive terminal browser
+  - `npm run skillex -- <args>` — run any CLI command without typing `node ./bin/skillex.js`
+- `skillex ui` gains `--host`, `--port`, and `--no-open` flags so the dev orchestrator (and any other automation) can run the backend on a known port without auto-opening the browser.
+- Env vars to override the dev orchestrator: `SKILLEX_DEV_BACKEND_PORT`, `SKILLEX_DEV_VITE_PORT`, `SKILLEX_DEV_NO_OPEN=1`.
+
+### Fixed
+- **Web UI dev mode (`npm run dev:ui`)** no longer throws `Missing Skillex Web UI bootstrap payload` and a blank page. When no bootstrap is injected (Vite serves `index.html` directly without the backend's substitution), an in-page overlay now explains exactly how to wire the dev server to a running `skillex ui` backend.
+- The dev page can also recover the bootstrap from a query string (e.g. `http://127.0.0.1:4174?token=<token>&scope=local`); the token is cached in `localStorage` so subsequent reloads work.
+
+### Changed
+- `vite.config.ts` reads a new `VITE_SKILLEX_BACKEND` env var. When set, the Vite dev server proxies `/api/*` to that backend so the UI talks to a real `skillex ui` instance with HMR enabled. The new `npm run dev` script sets this automatically.
+- README "Local Web UI development" rewritten: `npm run dev` is now the primary workflow; production-style (`npm run web`) is documented as a single one-liner.
+
+## [0.4.0] - 2026-05-02
+
+A substantial release focused on **reliability, security, and UX**. The CLI is
+now production-grade (HTTP timeouts, host-restricted token, parallel
+downloads, hardened parser); the Web UI grew bulk actions, keyboard
+shortcuts, multi-select, persistent state, an accessible doctor panel, and a
+mobile drawer; and the codebase was refactored for maintainability without
+breaking the public API.
+
+Test count went from 63 → 88 (no regressions).
+
+### Highlights
+
+- **Reliability & security pass** — HTTP timeouts everywhere, GitHub token
+  scoped to GitHub-owned hosts, lockfile path safety, symlink confinement,
+  ref-character validation, mode `0o600` on `~/.askillrc.json`, parallel
+  file downloads (5–10× speedup on multi-file skills).
+- **CLI parser hardened** — unknown flags rejected with "did you mean"
+  suggestions, `--` sentinel honored, missing-value detection, unknown
+  commands suggest the closest match, `parseBooleanFlag` names the flag and
+  lists accepted values, `skillex doctor` differentiates DNS / TLS /
+  refused / timeout failures.
+- **Three new top-level commands / flags** — `skillex show <id>` previews a
+  skill's SKILL.md without installing, `skillex init --install-recommended`
+  ships a curated starter pack, `skillex sync --dry-run --exit-code`
+  mirrors `git diff --exit-code` for CI drift detection.
+- **Web UI marketplace overhaul** — Install all + Install recommended +
+  Remove all bulk actions; per-card optimistic UI; Shift+click multi-select
+  with range select; sticky selection bar; persistent selection across
+  refreshes; search highlight; group-by-source; related skills; mobile
+  drawer; Doctor panel + sidebar health dot; breadcrumbs; first-load
+  skeletons; `⌘K` and `⇧⌘A` shortcuts.
+- **Internationalization & regression guard** — every user-facing string
+  is now English; `scripts/check-language.mjs` runs in `npm test` and fails
+  CI if banned Portuguese tokens reappear without an explicit
+  `i18n-allow:` annotation.
+- **Refactor** — `src/install.ts` (1326 LOC) split into focused modules
+  (`lockfile.ts`, `direct-github.ts`, `auto-sync.ts`, `downloader.ts`,
+  `doctor.ts`) with re-exports preserving every existing import path.
+
+### Added — Core / CLI
+
+- `skillex show <skill-id>` — preview a skill's manifest + rendered SKILL.md
+  from the configured sources without installing. `--raw` prints the
+  markdown verbatim; `--json` returns the manifest plus the entry content
+  as a single object.
+- `skillex init --install-recommended` — after writing the lockfile, install
+  a curated 5-skill starter pack (`commit-craft`, `code-review`,
+  `secure-defaults`, `error-handling`, `test-discipline`) using the same
+  progress bar as `install --all`. The recommended list lives in
+  `src/recommended.ts` (single source of truth).
+- `skillex sync --dry-run --exit-code` — exit `1` whenever the dry-run
+  would change at least one adapter (mirrors `git diff --exit-code`). CI
+  scripts can detect drift without parsing the diff output.
+- `--tags <tag>` is accepted as a hidden alias of `--tag` on
+  `skillex search` so previously documented examples keep working.
+- `src/doctor.ts` exports `runDoctorChecks(options): Promise<DoctorReport>`
+  — the canonical six health checks reused by both the CLI and the Web UI.
+- `HttpError` typed error class with codes `HTTP_TIMEOUT`,
+  `HTTP_RATE_LIMIT`, `HTTP_AUTH_FAILED`, `HTTP_NOT_FOUND`,
+  `HTTP_SERVER_ERROR`, and `HTTP_ERROR`.
+- `RemoveSkillsResult.autoSyncs: SyncCommandResult[]` — full per-adapter
+  sync aggregate (the existing `autoSync` field is preserved as the first
+  result for backward compat).
+- `createSymlink(target, link, { allowedRoot })` overload that refuses
+  targets resolving outside the managed root.
+- `SkillManifest.category?: string` (optional). Catalog publishers can
+  group skills explicitly instead of relying on consumer-side regex
+  inference. Read from both `skill.json` and SKILL.md frontmatter.
+- `suggestClosest(actual, candidates, threshold = 2)` helper in
+  `src/output.ts` powers "did you mean" hints across the parser and
+  dispatcher.
+
+### Added — Web UI
+
+- **Doctor panel** + `GET /api/doctor` endpoint mirroring the CLI's six
+  checks, with a sidebar status dot (green / yellow / red + pulse)
+  refreshed after every mutation.
+- **Bulk install / remove / install-recommended** buttons in the catalog
+  hero, each guarded by an accessible `ConfirmDialog` (role=dialog,
+  aria-modal, focus on Cancel, Esc cancels, Enter only fires when no
+  button has focus).
+- **Per-card optimistic UI** — single-skill install / remove / update show
+  a localized spinner inside the card and dim only that card. Backed by
+  `state.busyCards: Set<string>` and a `runCardAction(skillId, label, fn)`
+  store helper. Bulk actions still use the global overlay.
+- **Bulk select via Shift+click** — sticky selection bar shows
+  `N selected`, `Select all visible (M)` link, and `Install N` /
+  `Remove N` buttons that count only the eligible subset. Plain click in
+  selection mode toggles. Esc clears (priority cascade — see Changed).
+- **Range select** — Shift+click on a second card selects the range
+  between the anchor and the target in the visible-id ordering
+  (Finder/Excel behavior). The anchor moves with each interaction so
+  successive Shift+clicks extend from the latest endpoint.
+- **Persistent selection** — selection (ids + anchor + scope) is mirrored
+  to `localStorage["skillex.selection"]`. Restored on startup, filtered to
+  ids that still exist in the loaded catalog under the same scope.
+- **Search highlight** — query matches in skill name and description are
+  wrapped in `<mark class="search-mark">` with an accent background. Pure
+  template rendering (no `v-html`) — XSS-safe.
+- **Group-by-source toggle** — when more than one source is configured, a
+  toggle in the category-pill row buckets the grid by source.repo with
+  per-bucket headers and counts.
+- **Related skills** on the SkillDetailPage — up to 4 cards scored by tag
+  overlap (+ 0.5 bonus for matching `category`). Cards are keyboard
+  accessible, show a 2-line description clamp, up to 3 tags, and a ✓ when
+  the related skill is already installed.
+- **Breadcrumbs** on the SkillDetailPage —
+  `Catalog (link, home icon) / category / skill-name (current)`.
+  Category resolves from the explicit manifest field first, falls back to
+  the regex inference, hidden when no signal.
+- **Onboarding card** for fresh workspaces — replaces the generic empty
+  state with a bright Install-all CTA + count when the workspace has zero
+  installed skills and no filter is active.
+- **Installed-only filter** — the "Installed" overview card is now a
+  toggle (`role=button`, Enter/Space, `aria-pressed`); active state filters
+  the grid to installed skills only. The stat now reads `N / total`.
+- **Inferred category chip** on cards whose category came from regex
+  fallback rather than an explicit manifest field.
+- **First-load skeletons** — new `Skeleton.vue` (variants `card` / `row`).
+  Catalog page renders 6 card-skeletons until `state.catalog` resolves;
+  Doctor page renders 4 row-skeletons; SkillDetailPage renders metadata
+  + body + related skeletons during its first fetch.
+- **Mobile drawer** — sidebar slides in/out on viewports ≤680 px instead
+  of being hidden entirely. Triggered by a topbar hamburger; tap backdrop
+  or Esc to close; route changes auto-close.
+- **Adapter dropdown** for compact viewports (≤1100 px) — replaces the 7
+  icon row with a single trigger + listbox menu (`role=listbox`,
+  `role=option`, `aria-selected`).
+- **`⌘K` / `Ctrl+K` shortcut** — focuses the topbar search. Navigates back
+  to `/` first when invoked from another route. Adaptive hint badge.
+- **`⇧⌘A` / `Ctrl+Shift+A` shortcut** — opens the Install-all confirm on
+  the catalog page. Skipped when typing in inputs. Shift required so the
+  browser's native "select all" (Cmd+A) is preserved. Discoverable via the
+  shortcut chip on the Install-all button.
+- **Demo media placeholder** — new `docs/media/` with a README describing
+  how to regenerate `tui.gif`, `web-ui.png`, `web-ui-doctor.png` (vhs +
+  asciinema). Main README has a "Demo" section that references the media
+  via raw GitHub URLs (no binaries in the npm tarball).
+- **"Why Skillex" section** in the README plus a Quick Start that leads
+  with `npx skillex@latest` (the TUI) and frames the
+  `init` → `install` chain as scriptable mode.
+
+### Changed
+
+- **Reliability:** all HTTP helpers now abort after a default 30-second
+  timeout when the caller does not provide an `AbortSignal`, raising
+  `HttpError("HTTP_TIMEOUT")` instead of hanging.
+- **HTTP errors:** 403 responses split into `HTTP_RATE_LIMIT` (when
+  `X-RateLimit-Remaining: 0`) and `HTTP_AUTH_FAILED`, each with an
+  actionable message. The rate-limit message includes the reset hint.
+- **`maybeSyncAfterRemove`** now runs adapter syncs in parallel via
+  `Promise.all` and returns the full aggregate; the CLI prints one line
+  per adapter (was previously dropping all but the last adapter's
+  outcome).
+- **`toInstallError`** preserves the underlying `error.code` (HTTP error
+  codes, `EACCES`, `ENOENT`, etc.) on the wrapped `InstallError`.
+- **CLI parser** is now schema-driven via `STRING_FLAGS` / `BOOLEAN_FLAGS`
+  / `KNOWN_FLAGS` sets. Unknown flags raise `CliError("UNKNOWN_FLAG")`
+  with a Levenshtein-based "did you mean" suggestion (typos like
+  `--scop=global` are no longer silently accepted).
+- **CLI parser** detects missing values for string flags and raises
+  `CliError("MISSING_FLAG_VALUE")` naming the offending flag.
+- **CLI parser** honors the literal `--` end-of-options sentinel and
+  exposes everything after it via `ParsedArgs.positionalAfter`, so
+  `skillex run x:cmd -- --foo` forwards `--foo` to the underlying script
+  without flag interpretation.
+- **CLI dispatcher** suggests the closest match for unknown commands
+  (e.g. `skillex insall git-master` → `Did you mean: install?`).
+- **`parseBooleanFlag`** error now names the flag and lists every accepted
+  value: `Invalid value "maybe" for --auto-sync. Use true, false, yes,
+  no, on, off, 1, or 0.`
+- **`INSTALL_NO_TARGETS`** (`skillex install` with no args) now prints a
+  3-line inline usage block instead of a one-liner hint.
+- **`skillex doctor`** differentiates DNS, connection-refused, TLS,
+  timeout, and 5xx failures and surfaces the underlying `error.message`
+  instead of collapsing every failure into "GitHub API is unreachable".
+- **`skillex init`** ends with a three-line "Next steps" block (TUI /
+  starter pack / full catalog) instead of a single line. Suppressed when
+  `--install-recommended` was used.
+- **SkillDetailPage** action order rewritten following "primary action
+  last": Sync (ghost) → Update (secondary, only when installed) →
+  Install (primary) or Remove (danger).
+- **Web UI Esc cascade** — the Esc key now follows a priority chain:
+  ConfirmDialog → adapter dropdown → mobile drawer → CatalogPage
+  selection. Each handler checks `event.defaultPrevented` before acting,
+  so only one consumer fires per keypress.
+- **Refactor:** `src/install.ts` (1326 LOC) split into `src/lockfile.ts`,
+  `src/direct-github.ts`, `src/auto-sync.ts`, `src/downloader.ts`. Public
+  `package.json#exports` and import paths preserved via re-exports.
+- Consolidated SKILL.md frontmatter parsing on `parseSkillFrontmatter`
+  (`src/skill.ts`); the duplicated inline parser in `src/catalog.ts` was
+  removed.
+
+### Fixed
+
+- All remaining Portuguese user-facing strings translated to English: TUI
+  prompt label, sync symlink-fallback warnings, runner errors,
+  direct-install confirmation, non-TTY confirm prompt, filesystem path
+  errors, and Web UI labels (sidebar, catalog, skill card buttons,
+  detail page).
+- Sync warnings now route through `output.warn` instead of bare
+  `console.error` so they respect color and stream conventions.
+- New `scripts/check-language.mjs` regression guard runs as part of
+  `npm test` and fails CI if banned Portuguese tokens reappear in
+  `src/**/*.ts` or `ui/src/**/*.{vue,ts}` without an explicit
+  `i18n-allow:` annotation.
+- `toLockfileSource` boolean expression no longer contains a duplicated
+  `(label || repo === DEFAULT_REPO)` test (copy-paste artifact); behavior
+  unchanged.
+- **README** example at the search section now uses the canonical
+  `--tag <tag>` flag instead of the silently-ignored `--tags`.
+- **Web UI:** version badge in the sidebar reads the actual
+  `package.json#version` at build time via
+  `import.meta.env.VITE_SKILLEX_VERSION` instead of the previously
+  hardcoded `v0.2.4` (with a tautological ternary).
+- **Web UI:** dead `⌘K` hint badge removed (no shortcut was wired) — and
+  brought back once `Cmd+K` was actually implemented.
+- **Web UI:** misleading "Oficial" badge that every skill card displayed
+  (without any verification model) removed.
+- **Web UI:** mobile (≤680 px) sidebar no longer disappears entirely.
+- **Web UI:** `Remover` and `Carregando detalhes...` strings on the detail
+  page translated to English.
+
+### Security
+
+- **Token confinement:** `Authorization: Bearer ${GITHUB_TOKEN}` is only
+  attached when the request host is `api.github.com`,
+  `raw.githubusercontent.com`, or any `*.githubusercontent.com` mirror.
+  Tokens are no longer leaked to third-party `--catalog-url` targets.
+- **File mode:** `~/.askillrc.json` (which may contain `githubToken`) is
+  written with mode `0o600`. Existing world-readable files are tightened
+  on next save with a one-time warning.
+- **Lockfile path safety:** `removeSkill` validates `metadata.path`
+  against the managed skills store before deleting; tampered lockfile
+  paths raise `INSTALL_PATH_UNSAFE` instead of removing arbitrary
+  directories.
+- **Symlink confinement:** sync per-skill symlinks now refuse targets
+  that resolve outside the workspace state directory.
+- **Direct-install ref:** `parseDirectGitHubRef` validates the ref segment
+  against `^[A-Za-z0-9_.\-/]+$` and rejects empty refs after `@`;
+  previously dangerous refs would land in the lockfile.
+- **Web UI avatars:** skill author avatars are now a deterministic
+  CSS-only initials chip. The previous `<img>` to `dicebear.com` is gone
+  — the UI works offline and no longer leaks page-load telemetry to a
+  third-party host.
+
+### Performance
+
+- **Parallel file downloads:** `downloadSkillFiles` fetches every file in
+  a skill via `Promise.all` instead of a sequential loop. Multi-file
+  skills now scale with bandwidth instead of file count.
+
 ## [0.3.1] - 2026-04-08
 
 ### Fixed
@@ -127,7 +403,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Adapter detection and managed-block sync for Copilot, Cline, Cursor, Claude, Gemini, Windsurf, Codex
 - Lockfile-based workspace state at `.agent-skills/skills.json`
 
-[Unreleased]: https://github.com/lgili/skillex/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/lgili/skillex/compare/v0.4.1...HEAD
+[0.4.1]: https://github.com/lgili/skillex/compare/v0.4.0...v0.4.1
+[0.4.0]: https://github.com/lgili/skillex/compare/v0.3.1...v0.4.0
+[0.3.1]: https://github.com/lgili/skillex/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/lgili/skillex/compare/v0.2.5...v0.3.0
+[0.2.5]: https://github.com/lgili/skillex/compare/v0.2.4...v0.2.5
+[0.2.4]: https://github.com/lgili/skillex/compare/v0.2.3...v0.2.4
+[0.2.3]: https://github.com/lgili/skillex/compare/v0.2.2...v0.2.3
+[0.2.2]: https://github.com/lgili/skillex/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/lgili/skillex/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/lgili/skillex/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/lgili/skillex/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/lgili/skillex/releases/tag/v0.1.0

package/README.md

@@ -28,21 +28,40 @@
 
 ---
 
+## Why Skillex?
+
+- **One install, every agent.** Skills get exposed to Claude / Codex / Cursor / Copilot / Cline / Gemini / Windsurf at once, instead of copy-pasting the same prompt into seven config files.
+- **Catalog-driven, not folder-driven.** Skills live in versioned GitHub repos with manifests, descriptions, and tags. Update them with one command instead of `git submodule` gymnastics.
+- **Lockfile + auto-sync.** Skillex tracks what's installed and re-syncs after every change so the agent surface in your repo always matches the lockfile.
+
 ## Quick Start
 
 Get up and running in under two minutes using the built-in first-party skills catalog:
 
 ```bash
-# 1. Initialize your workspace (auto-detects your AI agent)
-npx skillex@latest init
-
-# 2. Browse available skills
-npx skillex@latest list
+# Easiest: open the interactive terminal browser
+npx skillex@latest
 
-# 3. Install a skill
-npx skillex@latest install create-skills
+# Or, scriptable mode:
+npx skillex@latest init                                  # set up the workspace
+npx skillex@latest init --install-recommended            # ...with a curated starter pack
+npx skillex@latest install create-skills                 # install one skill by id
+npx skillex@latest show code-review                      # preview a skill before installing
+npx skillex@latest list                                  # list every available skill
 ```
 
+> **Tip:** after the first `npx skillex@latest` call, the binary is cached on your machine, so subsequent invocations can drop the `npx skillex@latest` prefix and just call `skillex`.
+
+## Demo
+
+| Surface | Preview |
+|---------|---------|
+| Terminal browser (`skillex` with no args) | ![TUI demo](https://raw.githubusercontent.com/lgili/skillex/main/docs/media/tui.gif) |
+| Web UI catalog page (`skillex ui`) | ![Web UI catalog](https://raw.githubusercontent.com/lgili/skillex/main/docs/media/web-ui.png) |
+| Web UI Doctor panel | ![Web UI Doctor](https://raw.githubusercontent.com/lgili/skillex/main/docs/media/web-ui-doctor.png) |
+
+> The media files live in [`docs/media/`](https://github.com/lgili/skillex/tree/main/docs/media) and are referenced via raw GitHub URLs so the npm tarball stays small. See [`docs/media/README.md`](https://github.com/lgili/skillex/blob/main/docs/media/README.md) for re-recording instructions.
+
 > **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`.
@@ -73,21 +92,40 @@ 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.
+When working on the repository itself, the browser UI is a standalone Vue 3 + Vite frontend under `ui/`. The CLI serves the built assets from `dist-ui/` and keeps all install/remove/update/sync logic in the local TypeScript backend.
+
+**One-command dev mode** — `npm run dev` spawns the backend, the Vite dev server with `/api/*` proxied, and opens the browser with the right token. Edit a `.vue` file and HMR reloads instantly.
 
 ```bash
 npm install
-npm run build:ui
-npm run build
-node ./bin/skillex.js ui
+npm run dev
+# ➜ Backend: http://127.0.0.1:4174  (token captured automatically)
+# ➜ UI:      http://127.0.0.1:4175  (opens in your browser)
+```
+
+Override the ports if you need to:
+
+```bash
+SKILLEX_DEV_BACKEND_PORT=5000 SKILLEX_DEV_VITE_PORT=5001 npm run dev
+SKILLEX_DEV_NO_OPEN=1 npm run dev   # keep the URL on stdout, don't open
 ```
 
-For frontend-only iteration:
+**Production-style local run** — builds everything and serves it exactly like an end user gets via `npx skillex ui`:
 
 ```bash
-npm run dev:ui
+npm run web   # alias for `npm run build && node ./bin/skillex.js ui`
 ```
 
+**Other handy aliases:**
+
+| Command | What it does |
+|---|---|
+| `npm run dev` | Backend + Vite + auto-open (full HMR loop) |
+| `npm run web` | Production-style: build + run the local Web UI server |
+| `npm run tui` | Open the interactive terminal browser |
+| `npm run skillex -- <args>` | Run any CLI command without `node ./bin/skillex.js` (e.g. `npm run skillex -- list`) |
+| `npm run dev:ui` | Vite dev server only (advanced; needs `VITE_SKILLEX_BACKEND=…` env var pointing at a running backend) |
+
 ---
 
 ## Commands
@@ -110,6 +148,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` | Enable or disable automatic sync after install, update, and remove. Default: `true`. |
+| `--install-recommended` | After init, install a curated starter pack (`commit-craft`, `code-review`, `secure-defaults`, `error-handling`, `test-discipline`). |
 | `--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`. |
@@ -150,7 +189,7 @@ skillex search code-review --repo myorg/my-skills
 |------|-------------|
 | `--repo <owner/repo>` | Limit the command to a single source instead of aggregating all configured sources. |
 | `--compatibility <adapter>` | Filter by adapter (e.g. `cursor`, `claude`, `codex`). |
-| `--tags <tag>` | Filter by tag. |
+| `--tag <tag>` | Filter by tag. (`--tags` is also accepted for backward compatibility with earlier docs.) |
 | `--json` | Print raw JSON. |
 
 ---
@@ -271,11 +310,34 @@ Execute a script declared in a skill's `skill.json`.
 
 ```bash
 skillex run git-master:cleanup
-skillex run git-master:cleanup --yes   # skip confirmation
+skillex run git-master:cleanup --yes              # skip confirmation
+skillex run git-master:cleanup -- --extra=arg     # forward "--extra=arg" to the script
 ```
 
 ---
 
+### `show`
+
+Print a skill's manifest summary plus its rendered `SKILL.md` content from the
+configured catalog sources, **without installing anything**. Use this to
+preview a skill before deciding to install.
+
+```bash
+skillex show git-master                          # human-friendly summary + content
+skillex show code-review --raw                   # SKILL.md verbatim, no header
+skillex show secure-defaults --json              # manifest + entry content as JSON
+skillex show foo --repo myorg/my-skills          # disambiguate when multiple sources match
+```
+
+| Flag | Description |
+|------|-------------|
+| `--repo <owner/repo>` | Limit resolution to one source. |
+| `--raw` | Print SKILL.md verbatim with no manifest header. |
+| `--json` | Print the resolved manifest plus the raw SKILL.md as a single JSON object. |
+| `--no-cache` | Bypass local catalog cache. |
+
+---
+
 ### Default terminal browser
 
 Running `skillex` with no subcommand now opens the interactive terminal browser by default.
@@ -481,6 +543,7 @@ catalog.json          ← optional but recommended
   "description": "Teaches the agent to write semantic commits and manage branches.",
   "author": "your-name",
   "tags": ["git", "workflow"],
+  "category": "workflow",
   "compatibility": ["codex", "copilot", "cline", "cursor", "claude", "gemini", "windsurf"],
   "entry": "SKILL.md",
   "files": ["SKILL.md", "tools/git-cleanup.js"],
@@ -490,12 +553,15 @@ catalog.json          ← optional but recommended
 }
 ```
 
+The `category` field is **optional**. When present, the Web UI groups the skill under that category explicitly. When absent, the catalog falls back to a regex-based inference and tags the resulting badge with a small `(inferred)` chip so contributors can see when their metadata is incomplete.
+
 ### `SKILL.md` frontmatter
 
 ```markdown
 ---
 name: "git-master"
 description: "Git workflow instructions"
+category: "workflow"
 autoInject: true
 activationPrompt: "Always apply Git Master rules when the user asks for Git help."
 ---
@@ -505,7 +571,7 @@ activationPrompt: "Always apply Git Master rules when the user asks for Git help
 Your skill content goes here...
 ```
 
-When `autoInject: true` and `activationPrompt` are set, `skillex sync` injects the activation prompt in a separate managed block for adapters that use a shared or dedicated config file.
+When `autoInject: true` and `activationPrompt` are set, `skillex sync` injects the activation prompt in a separate managed block for adapters that use a shared or dedicated config file. `category` is optional and behaves the same whether declared in `skill.json` or in the SKILL.md frontmatter.
 
 ---
 

package/dist/auto-sync.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Auto-sync orchestration after install / update / remove operations.
+ *
+ * Decoupled from `install.ts` so the install/update/remove handlers focus on
+ * lockfile mutations only. The `syncFn` parameter (typically
+ * `syncInstalledSkills` from `install.ts`) is injected to avoid an import
+ * cycle.
+ */
+import type { InstallScope, LockfileState, NowFn, SyncCommandResult, SyncHistory, SyncWriteMode } from "./types.js";
+/**
+ * Resolves the list of adapter ids that should receive a sync. When an
+ * explicit override is provided, only that adapter is targeted. Otherwise,
+ * the active adapter (if any) is listed first followed by the remaining
+ * detected adapters in workspace order.
+ */
+export declare function resolveSyncAdapterIds(adapters: LockfileState["adapters"], adapterOverride?: string): string[];
+/** Options passed to `maybeAutoSync` after install / update operations. */
+export interface MaybeAutoSyncOptions {
+    cwd: string;
+    scope?: InstallScope | undefined;
+    agentSkillsDir?: string | undefined;
+    adapters: LockfileState["adapters"];
+    adapterOverride?: string | undefined;
+    enabled: boolean;
+    now: NowFn;
+    changed: boolean;
+    mode?: SyncWriteMode | undefined;
+}
+/** Sync function shape injected by callers (typically `syncInstalledSkills`). */
+export type SyncFn = (options: {
+    cwd: string;
+    scope: InstallScope;
+    agentSkillsDir?: string;
+    adapter?: string;
+    mode?: SyncWriteMode;
+    now: NowFn;
+}) => Promise<SyncCommandResult>;
+/**
+ * Triggers a sync after install/update when auto-sync is enabled and at
+ * least one skill changed. Returns `null` when no sync was performed.
+ */
+export declare function maybeAutoSync(options: MaybeAutoSyncOptions, syncFn: SyncFn): Promise<SyncCommandResult | null>;
+/** Options passed to `maybeSyncAfterRemove`. */
+export interface MaybeSyncAfterRemoveOptions {
+    cwd: string;
+    scope?: InstallScope | undefined;
+    agentSkillsDir?: string | undefined;
+    adapters: LockfileState["adapters"];
+    adapterOverride?: string | undefined;
+    syncHistory: SyncHistory;
+    legacySync: LockfileState["sync"];
+    enabled: boolean;
+    now: NowFn;
+    changed: boolean;
+    mode?: SyncWriteMode | undefined;
+}
+/**
+ * Triggers a sync after remove operations across every previously-synced
+ * adapter (so that removed skills are dropped from each adapter's view).
+ *
+ * Each adapter is synced concurrently via `Promise.all` and the results are
+ * aggregated into an array so callers can report each adapter's outcome
+ * individually. Returns `null` when no sync was performed (no changes or
+ * no adapters to sync).
+ */
+export declare function maybeSyncAfterRemove(options: MaybeSyncAfterRemoveOptions, syncFn: SyncFn): Promise<SyncCommandResult[] | null>;

package/dist/auto-sync.js

@@ -0,0 +1,91 @@
+/**
+ * Auto-sync orchestration after install / update / remove operations.
+ *
+ * Decoupled from `install.ts` so the install/update/remove handlers focus on
+ * lockfile mutations only. The `syncFn` parameter (typically
+ * `syncInstalledSkills` from `install.ts`) is injected to avoid an import
+ * cycle.
+ */
+import { DEFAULT_INSTALL_SCOPE } from "./config.js";
+/**
+ * Resolves the list of adapter ids that should receive a sync. When an
+ * explicit override is provided, only that adapter is targeted. Otherwise,
+ * the active adapter (if any) is listed first followed by the remaining
+ * detected adapters in workspace order.
+ */
+export 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;
+}
+/**
+ * Triggers a sync after install/update when auto-sync is enabled and at
+ * least one skill changed. Returns `null` when no sync was performed.
+ */
+export async function maybeAutoSync(options, syncFn) {
+    if (!options.enabled || !options.changed) {
+        return null;
+    }
+    if (resolveSyncAdapterIds(options.adapters, options.adapterOverride).length === 0) {
+        return null;
+    }
+    return syncFn({
+        cwd: options.cwd,
+        scope: options.scope || DEFAULT_INSTALL_SCOPE,
+        ...(options.agentSkillsDir ? { agentSkillsDir: options.agentSkillsDir } : {}),
+        ...(options.adapterOverride ? { adapter: options.adapterOverride } : {}),
+        ...(options.mode ? { mode: options.mode } : {}),
+        now: options.now,
+    });
+}
+/**
+ * Triggers a sync after remove operations across every previously-synced
+ * adapter (so that removed skills are dropped from each adapter's view).
+ *
+ * Each adapter is synced concurrently via `Promise.all` and the results are
+ * aggregated into an array so callers can report each adapter's outcome
+ * individually. Returns `null` when no sync was performed (no changes or
+ * no adapters to sync).
+ */
+export async function maybeSyncAfterRemove(options, syncFn) {
+    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);
+        }
+    }
+    if (adapters.size === 0) {
+        return null;
+    }
+    const results = await Promise.all([...adapters].map((adapterId) => syncFn({
+        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 results;
+}