skillex 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.2] - 2026-04-08
+
+### Added
+- 9 first-party skills in the default catalog: `commit-craft`, `secure-defaults`, `error-handling`, `test-discipline`, `code-review`, `typescript-pro`, `python-pro`, `cpp-pro`, `latex-pro` — each with full reference files and bundled scripts
+- `create-skills` skill upgraded to advanced format: generates SKILL.md with Core Workflow, Reference Guide table, Constraints, and Output Template sections; `--references` flag scaffolds placeholder reference files automatically
+
+### Changed
+- `catalog.json` is now a slim index (`formatVersion: 2`): each entry contains only `{ "id" }` — no repeated metadata
+- Full skill metadata (name, version, description, tags, compatibility, files) now lives exclusively in each skill's `skill.json`
+- CLI catalog loader detects v2 format and fetches each `skill.json` in parallel to hydrate the full manifest
+
+## [0.2.1] - 2026-04-07
+
+### Changed
+- Skills and generated symlink sources are now stored in `~/.skillex/` (user-level) instead of `<project>/.agent-skills/`, so a single install is shared across all workspaces and symlinks always resolve correctly
+- `claude` adapter: switched from managed-block in `CLAUDE.md` to a dedicated file at `.claude/skills/skillex-skills.md`; old `CLAUDE.md` block cleaned up automatically on next `sync`
+- `gemini` adapter: switched from managed-block in `GEMINI.md` to a dedicated file at `.gemini/skills/skillex-skills.md`; old `GEMINI.md` block cleaned up automatically on next `sync`
+- `codex` adapter: switched from managed-block in `AGENTS.md` to a dedicated file at `.codex/skills/skillex-skills.md` (introduced in this cycle)
+- Symlinks are now absolute paths instead of relative, ensuring they work regardless of project depth
+- `copilot` is now the only adapter that uses managed-block injection
+- `--agent-skills-dir` flag still overrides to a project-local directory when isolation is needed
+
 ## [0.2.0] - 2026-04-07
 
 ### Added

package/README.md

@@ -5,7 +5,7 @@
 [![Node.js >=20](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-**Skillex** is a CLI that installs and synchronizes AI agent skills from a GitHub-hosted catalog into your workspace. It automatically injects skill instructions into the configuration file of whichever AI agent you use — Codex, Copilot, Cline, Cursor, Claude, Gemini, or Windsurf.
+**Skillex** is a CLI that installs and synchronizes AI agent skills from a GitHub-hosted catalog. It supports both workspace-local installs and user-global installs, and it exposes skills to major AI agents such as Codex, Copilot, Cline, Cursor, Claude, Gemini, and Windsurf.
 
 ---
 
@@ -42,10 +42,13 @@ npx skillex@latest list
 # 3. Install a skill
 npx skillex@latest install create-skills
 
-# 4. Sync skills into your agent's config file
+# 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.
+
 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`.
 
 ---
@@ -78,13 +81,14 @@ npx skillex <command>
 
 ### `init`
 
-Initialize (or re-initialize) the workspace. Creates `.agent-skills/skills.json`, detects your adapter, and writes `.agent-skills/.gitignore`.
+Initialize local or global Skillex state. Local scope creates `.agent-skills/skills.json` in the current workspace. Global scope creates `~/.skillex/skills.json`.
 
 ```bash
 skillex init
 skillex init --repo <owner/repo>
 skillex init --repo lgili/skillex --adapter cursor
 skillex init --repo lgili/skillex --auto-sync
+skillex init --global --adapter codex
 ```
 
 | Flag | Description |
@@ -93,6 +97,8 @@ skillex init --repo lgili/skillex --auto-sync
 | `--adapter <id>` | Force a specific adapter instead of auto-detecting. |
 | `--auto-sync` | Automatically run `sync` after every install, update, and remove. |
 | `--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`. |
 
 ---
 
@@ -154,6 +160,9 @@ skillex install code-review --repo myorg/my-skills
 
 # Install directly from a GitHub repository (no catalog needed)
 skillex install owner/repo/path/to/skill@main --trust
+
+# Install once for all workspaces
+skillex install create-skills --global
 ```
 
 | Flag | Description |
@@ -161,6 +170,10 @@ skillex install owner/repo/path/to/skill@main --trust
 | `--all` | Install every skill in the catalog. |
 | `--repo <owner/repo>` | Limit resolution to a single source when needed. |
 | `--trust` | Skip confirmation prompt for direct GitHub installs. |
+| `--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.
 
 ---
 
@@ -174,6 +187,9 @@ skillex update
 
 # Update a specific skill
 skillex update git-master
+
+# Update global skills
+skillex update --global
 ```
 
 ---
@@ -185,13 +201,14 @@ Remove one or more installed skills. Aliases: `rm`, `uninstall`.
 ```bash
 skillex remove git-master
 skillex rm git-master code-review
+skillex remove create-skills --global
 ```
 
 ---
 
 ### `sync`
 
-Write all installed skills into the active adapter's config file.
+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`.
 
 ```bash
 # Sync to the detected adapter
@@ -205,13 +222,37 @@ skillex sync --adapter codex
 
 # Copy files instead of using symlinks
 skillex sync --mode copy
+
+# Sync globally to your user-level Codex skills directory
+skillex sync --global --adapter codex
 ```
 
 | Flag | Description |
 |------|-------------|
 | `--dry-run` | Show what would change without writing anything. |
 | `--adapter <id>` | Override the active adapter for this sync. |
-| `--mode copy\|symlink` | File write strategy (default: `symlink` for dedicated-file adapters). |
+| `--mode copy\|symlink` | File write strategy (default: `symlink` for dedicated targets). |
+| `--scope <local\|global>` | Choose whether the sync reads local or global Skillex state. |
+| `--global` | Shortcut for `--scope global`. |
+
+#### 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:
+
+```bash
+# Write skill folders into .claude/skills/<skill-id>/
+skillex sync --adapter claude
+
+# Write skill folders into .codex/skills/<skill-id>/
+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
+```
 
 ---
 
@@ -238,10 +279,11 @@ skillex ui
 
 ### `status`
 
-Show the current local workspace state: adapter, installed skills, last sync.
+Show the current Skillex state for the selected scope: adapter, installed skills, last sync.
 
 ```bash
 skillex status
+skillex status --global
 ```
 
 ---
@@ -337,17 +379,23 @@ Skillex auto-detects the AI agent you use by looking for known marker files in y
 
 | Adapter ID | Agent | Detection Markers | Sync Target |
 |------------|-------|-------------------|-------------|
-| `codex` | OpenAI Codex | `AGENTS.md`, `.codex/` | `AGENTS.md` |
+| `codex` | OpenAI Codex | `AGENTS.md`, `.codex/` | `.codex/skills/<skill-id>/` |
 | `copilot` | GitHub Copilot | `.github/copilot-instructions.md` | `.github/copilot-instructions.md` |
 | `cline` | Cline / Roo Code | `.cline/`, `.roo/`, `.clinerules` | `.clinerules/skillex-skills.md` |
 | `cursor` | Cursor | `.cursor/`, `.cursorrules` | `.cursor/rules/skillex-skills.mdc` |
-| `claude` | Claude Code | `CLAUDE.md`, `.claude/` | `CLAUDE.md` |
-| `gemini` | Gemini CLI | `GEMINI.md`, `.gemini/` | `GEMINI.md` |
+| `claude` | Claude Code | `CLAUDE.md`, `.claude/` | `.claude/skills/<skill-id>/` |
+| `gemini` | Gemini CLI | `GEMINI.md`, `.gemini/` | `.gemini/skills/<skill-id>/` |
 | `windsurf` | Windsurf | `.windsurf/`, `.windsurf/rules/` | `.windsurf/rules/skillex-skills.md` |
 
-**Shared-file adapters** (`codex`, `copilot`, `claude`, `gemini`) use a **managed block** — Skillex writes between `<!-- SKILLEX:START -->` and `<!-- SKILLEX:END -->` markers while preserving everything else in the file.
+**Shared-file adapter** (`copilot`) uses a **managed block** — Skillex writes between `<!-- SKILLEX:START -->` and `<!-- SKILLEX:END -->` markers inside `.github/copilot-instructions.md`, preserving everything else in the file.
+
+**Directory-native adapters** (`codex`, `claude`, `gemini`) expose one folder per installed skill and symlink each `<skill-id>/` directory to the managed Skillex store by default.
+
+**Dedicated-file adapters** (`cline`, `cursor`, `windsurf`) still generate a file in `.agent-skills/generated/<adapter>/` and symlink the adapter target to that generated file by default.
 
-**Dedicated-file adapters** (`cline`, `cursor`, `windsurf`) generate a file in `.agent-skills/generated/` and create a relative symlink at the adapter's target path. Use `--mode copy` to write directly instead.
+**Shared-file adapter** (`copilot`) updates a managed block inside `.github/copilot-instructions.md`.
+
+> **Migrating from a previous version?** If you previously had `skillex-skills.md` inside `.codex/skills/`, `.claude/skills/`, or `.gemini/skills/`, those legacy aggregate files are cleaned up automatically on the next `sync`.
 
 Compatibility aliases are normalized automatically: `claude-code` → `claude`, `github-copilot` → `copilot`, `roo-code` → `cline`, `gemini-cli` → `gemini`.
 
@@ -435,7 +483,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 at the top of the adapter's config file so the agent always has that context loaded.
+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.
 
 ---
 
@@ -484,7 +532,7 @@ CLI flags  >  GITHUB_TOKEN env var  >  ~/.askillrc.json  >  defaults
 
 ## Workspace Structure
 
-After `init` and a few installs, your workspace will look like this:
+After `skillex init` and a few local installs, your workspace will look like this:
 
 ```
 .agent-skills/
@@ -512,13 +560,27 @@ The `skills.json` lockfile records:
 - All installed skills with their versions, tags, compatibility, and install timestamps
 - Installation source (e.g. `github:owner/repo@ref` for direct installs)
 
-> **Tip:** Commit `.agent-skills/skills.json` and `.agent-skills/skills/` to version-control your skill setup. The `.cache/` directory is automatically excluded.
+For global installs, the same structure is stored under `~/.skillex/` instead of `.agent-skills/`.
+
+For directory-native adapters, `sync` creates per-skill directories such as:
+
+```text
+.codex/
+  skills/
+    git-master -> ../../.agent-skills/skills/git-master
+
+.claude/
+  skills/
+    git-master -> ../../.agent-skills/skills/git-master
+```
+
+> **Tip:** Commit `.agent-skills/skills.json` and `.agent-skills/skills/` to version-control your local team setup. The `.cache/` directory is automatically excluded.
 
 ---
 
 ## Auto-sync
 
-When `--auto-sync` is enabled at `init`, Skillex runs `sync` automatically after every `install`, `update`, and `remove`. This keeps your agent's config file always up to date.
+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.
 
 ```bash
 # Enable at init time
@@ -526,6 +588,9 @@ skillex init --auto-sync
 
 # Or re-initialize to enable it
 skillex init --repo lgili/skillex --auto-sync
+
+# Enable it for global installs
+skillex init --global --adapter codex --auto-sync
 ```
 
 ---

package/dist/adapters.js

@@ -1,3 +1,4 @@
+import * as os from "node:os";
 import * as path from "node:path";
 import { pathExists } from "./fs.js";
 import { AdapterNotFoundError } from "./types.js";
@@ -10,8 +11,10 @@ const ADAPTERS = [
             { path: ".codex", weight: 12 },
             { path: ".codex/skills", weight: 16 },
         ],
-        syncTarget: "AGENTS.md",
-        syncMode: "managed-block",
+        syncTarget: ".codex/skills",
+        globalSyncTarget: path.join(os.homedir(), ".codex", "skills"),
+        legacySyncTargets: [".codex/skills/skillex-skills.md", ".codex/skills/askill-skills.md"],
+        syncMode: "managed-directory",
     },
     {
         id: "copilot",
@@ -51,9 +54,12 @@ const ADAPTERS = [
         markers: [
             { path: "CLAUDE.md", weight: 16 },
             { path: ".claude", weight: 18 },
+            { path: ".claude/skills", weight: 20 },
         ],
-        syncTarget: "CLAUDE.md",
-        syncMode: "managed-block",
+        syncTarget: ".claude/skills",
+        globalSyncTarget: path.join(os.homedir(), ".claude", "skills"),
+        legacySyncTargets: [".claude/skills/skillex-skills.md", ".claude/skills/askill-skills.md"],
+        syncMode: "managed-directory",
     },
     {
         id: "gemini",
@@ -61,9 +67,12 @@ const ADAPTERS = [
         markers: [
             { path: "GEMINI.md", weight: 16 },
             { path: ".gemini", weight: 18 },
+            { path: ".gemini/skills", weight: 20 },
         ],
-        syncTarget: "GEMINI.md",
-        syncMode: "managed-block",
+        syncTarget: ".gemini/skills",
+        globalSyncTarget: path.join(os.homedir(), ".gemini", "skills"),
+        legacySyncTargets: [".gemini/skills/skillex-skills.md", ".gemini/skills/askill-skills.md"],
+        syncMode: "managed-directory",
     },
     {
         id: "windsurf",

package/dist/catalog.js

@@ -78,7 +78,7 @@ export async function loadCatalog(options = {}) {
         }
         const catalogUrl = source.catalogUrl ?? buildRawGitHubUrl(source.repo, source.ref, source.catalogPath);
         const remoteCatalog = await fetchOptionalJson(catalogUrl);
-        const result = remoteCatalog ? normalizeCatalog(remoteCatalog, source) : await loadCatalogFromTree(source);
+        const result = remoteCatalog ? await normalizeCatalog(remoteCatalog, source) : await loadCatalogFromTree(source);
         // Write to cache (fire-and-forget; never fail the caller)
         if (cacheDir) {
             writeCatalogCache(cacheDir, cacheKey, result).catch(() => { });
@@ -262,16 +262,37 @@ function collectFilesUnderPath(treeFiles, skillPath) {
         .filter((item) => item.type === "blob" && item.path.startsWith(`${skillPath}/`))
         .map((item) => assertSafeRelativePath(item.path.slice(skillPath.length + 1)));
 }
-function normalizeCatalog(remoteCatalog, source) {
+async function normalizeCatalog(remoteCatalog, source) {
     const remoteSkills = Array.isArray(remoteCatalog.skills) ? remoteCatalog.skills : [];
     if (remoteSkills.length === 0) {
         throw new CatalogError("catalog.json found but the skills array is empty.", "CATALOG_EMPTY");
     }
+    // v2 format: slim index entries (only `id`). Fetch each skill.json for full metadata.
+    const isV2 = Number(remoteCatalog.formatVersion) >= 2 ||
+        remoteSkills.every((s) => Object.keys(s).length === 1 && "id" in s);
+    let skills;
+    if (isV2) {
+        skills = await Promise.all(remoteSkills.map(async (entry) => {
+            const id = entry.id;
+            if (!id) {
+                throw new CatalogError("Every skill must have an id field.", "MALFORMED_SKILL");
+            }
+            const skillPath = `${source.skillsDir}/${id}`;
+            const manifestUrl = buildRawGitHubUrl(source.repo, source.ref, `${skillPath}/skill.json`);
+            const manifest = await fetchJson(manifestUrl, {
+                headers: { Accept: "application/json" },
+            });
+            return normalizeSkill({ ...manifest, id, path: skillPath }, source);
+        }));
+    }
+    else {
+        skills = remoteSkills.map((skill) => normalizeSkill(skill, source));
+    }
     return {
         formatVersion: Number(remoteCatalog.formatVersion || 1),
         repo: remoteCatalog.repo || source.repo,
         ref: remoteCatalog.ref || source.ref,
-        skills: sortSkills(remoteSkills.map((skill) => normalizeSkill(skill, source))),
+        skills: sortSkills(skills),
     };
 }
 function normalizeSkill(skill, source) {

package/dist/cli.js

@@ -1,7 +1,7 @@
 import * as path from "node:path";
 import { listAdapters } from "./adapters.js";
 import { computeCatalogCacheKey, loadCatalog, readCatalogCache, searchCatalogSkills, } from "./catalog.js";
-import { DEFAULT_AGENT_SKILLS_DIR, getStatePaths } from "./config.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";
@@ -15,18 +15,21 @@ import { VALID_CONFIG_KEYS, readUserConfig, writeUserConfig } from "./user-confi
 const COMMAND_HELP = {
     init: `Usage: skillex init [--repo <owner/repo>] [options]
 
-Initialize the local Skillex workspace.
+Initialize Skillex state for the local workspace or global user scope.
 
 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
+  --scope <scope>       local or global (default: local)
+  --global              Shortcut for --scope global
   --cwd <path>          Target project directory (default: current directory)
 
 Example:
   skillex init
-  skillex init --repo myorg/my-skills`,
+  skillex init --repo myorg/my-skills
+  skillex init --global --adapter codex`,
     list: `Usage: skillex list [options]
 
 List all skills in the configured sources.
@@ -65,6 +68,8 @@ Options:
   --ref <ref>           Branch, tag, or commit
   --trust               Skip confirmation for direct GitHub installs
   --adapter <id>        Target adapter
+  --scope <scope>       local or global (default: local)
+  --global              Shortcut for --scope global
   --no-cache            Bypass local catalog cache
 
 Example:
@@ -77,29 +82,38 @@ Update installed skills to the latest catalog version.
 
 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 update
   skillex update git-master`,
-    remove: `Usage: skillex remove <skill-id...>
+    remove: `Usage: skillex remove <skill-id...> [options]
 
-Remove installed skills from the local workspace.
+Remove installed skills from the selected scope.
+
+Options:
+  --scope <scope>       local or global (default: local)
+  --global              Shortcut for --scope global
 
 Example:
   skillex remove git-master code-review`,
     sync: `Usage: skillex sync [options]
 
-Synchronize installed skills to adapter target files.
+Synchronize installed skills to adapter targets.
 
 Options:
   --adapter <id>        Target adapter (overrides saved config)
   --dry-run             Preview changes without writing to disk
   --mode <symlink|copy> Sync write mode (default: symlink)
+  --scope <scope>       local or global (default: local)
+  --global              Shortcut for --scope global
 
 Example:
   skillex sync
-  skillex sync --adapter cursor --dry-run`,
+  skillex sync --adapter cursor --dry-run
+  skillex sync --global --adapter codex`,
     run: `Usage: skillex run <skill-id:command> [options]
 
 Execute a script bundled inside an installed skill.
@@ -122,10 +136,12 @@ Example:
   skillex ui`,
     status: `Usage: skillex status [options]
 
-Show the installation status of the current workspace.
+Show the installation status of the selected scope.
 
 Options:
   --cwd <path>          Target project directory
+  --scope <scope>       local or global (default: local)
+  --global              Shortcut for --scope global
   --json                Output as JSON
 
 Example:
@@ -262,7 +278,7 @@ async function handleInit(flags, userConfig) {
         ...(repo ? { repo } : {}),
     });
     if (result.created) {
-        output.success(`Initialized at ${result.statePaths.stateDir}`);
+        output.success(`Initialized ${result.statePaths.scope} state at ${result.statePaths.stateDir}`);
     }
     else {
         output.info(`Already configured at ${result.statePaths.stateDir}`);
@@ -350,7 +366,7 @@ async function handleInstall(positionals, flags, userConfig) {
             output.info(`[${current}/${total}] Installing ${skillId}...`);
         },
     });
-    output.success(`Installed ${result.installedCount} skill(s) to ${result.statePaths.stateDir}`);
+    output.success(`Installed ${result.installedCount} skill(s) to ${result.statePaths.scope} state at ${result.statePaths.stateDir}`);
     for (const skill of result.installedSkills) {
         output.info(`  + ${skill.id}@${skill.version}`);
     }
@@ -390,16 +406,16 @@ 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 file : ${result.sync.targetPath}`);
+        output.info(`Target path : ${result.sync.targetPath}`);
         output.info(`Sync mode   : ${result.syncMode}`);
         process.stdout.write(result.diff);
         return;
     }
     output.success(`Synced ${result.skillCount} skill(s) → ${result.sync.adapter}`);
-    output.info(`Target file : ${result.sync.targetPath}`);
+    output.info(`Target path : ${result.sync.targetPath}`);
     output.info(`Sync mode   : ${result.syncMode}`);
     if (!result.changed) {
-        output.info("No changes to the target file.");
+        output.info("No changes to the target path.");
     }
 }
 async function handleRun(positionals, flags, userConfig) {
@@ -449,16 +465,25 @@ async function handleUi(flags, userConfig) {
     }
 }
 async function handleStatus(flags, userConfig) {
-    const state = await getInstalledSkills(commonOptions(flags, userConfig));
+    const options = commonOptions(flags, userConfig);
+    const state = await getInstalledSkills(options);
     if (!state) {
-        output.warn("No local installation found. Run: skillex init");
+        output.warn(resolveScope(flags) === "global"
+            ? "No global installation found. Run: skillex init --global --adapter <id>"
+            : "No local installation found. Run: skillex init");
         return;
     }
     if (flags.json === true) {
         output.info(JSON.stringify(state, null, 2));
         return;
     }
+    const statePaths = getScopedStatePaths(options.cwd ?? process.cwd(), {
+        scope: options.scope,
+        baseDir: options.agentSkillsDir,
+    });
     const installedEntries = Object.entries(state.installed || {});
+    output.info(`Scope        : ${resolveScope(flags)}`);
+    output.info(`State root   : ${statePaths.stateDir}`);
     output.info(`Sources      : ${state.sources.map((source) => `${source.repo}@${source.ref}`).join(", ")}`);
     output.info(`Active adapter: ${state.adapters.active || "(none)"}`);
     output.info(`Auto-sync    : ${state.settings.autoSync ? "enabled" : "disabled"}`);
@@ -483,7 +508,10 @@ async function handleStatus(flags, userConfig) {
 async function handleDoctor(flags, userConfig) {
     const opts = commonOptions(flags, userConfig);
     const cwd = opts.cwd ?? process.cwd();
-    const statePaths = getStatePaths(cwd, opts.agentSkillsDir ?? DEFAULT_AGENT_SKILLS_DIR);
+    const statePaths = getScopedStatePaths(cwd, {
+        scope: opts.scope,
+        baseDir: opts.agentSkillsDir,
+    });
     const checks = [];
     // 1. Lockfile
     const state = await getInstalledSkills(opts);
@@ -707,6 +735,7 @@ function resolveAlias(command) {
 function commonOptions(flags, userConfig = {}) {
     const options = {
         cwd: path.resolve(asOptionalString(flags.cwd) || process.cwd()),
+        scope: resolveScope(flags),
     };
     const repo = asOptionalString(flags.repo) ?? userConfig.defaultRepo;
     const ref = asOptionalString(flags.ref);
@@ -755,12 +784,29 @@ function commonOptions(flags, userConfig = {}) {
 /** Returns cache-related options to spread into a loadCatalog call. */
 function cacheOptions(opts) {
     const cwd = opts.cwd ?? process.cwd();
-    const stateDir = path.join(cwd, opts.agentSkillsDir ?? DEFAULT_AGENT_SKILLS_DIR);
+    const stateDir = getScopedStatePaths(cwd, {
+        scope: opts.scope ?? DEFAULT_INSTALL_SCOPE,
+        baseDir: opts.agentSkillsDir,
+    }).stateDir;
     return {
         cacheDir: path.join(stateDir, ".cache"),
         ...(opts.noCache !== undefined ? { noCache: opts.noCache } : {}),
     };
 }
+function resolveScope(flags) {
+    const rawScope = asOptionalString(flags.scope);
+    const globalFlag = parseBooleanFlag(flags.global);
+    if (rawScope && rawScope !== "local" && rawScope !== "global") {
+        throw new CliError(`Invalid scope: ${rawScope}. Use "local" or "global".`, "INVALID_SCOPE");
+    }
+    if (rawScope === "local" && globalFlag === true) {
+        throw new CliError('Conflicting scope flags: use either "--scope local" or "--global".', "CONFLICTING_SCOPE");
+    }
+    if (globalFlag === true) {
+        return "global";
+    }
+    return rawScope || DEFAULT_INSTALL_SCOPE;
+}
 function parseArgs(argv) {
     const flags = {};
     const positionals = [];
@@ -824,6 +870,8 @@ Global flags:
   --adapter <id>        Force adapter: ${listAdapters()
         .map((a) => a.id)
         .join(", ")}
+  --scope <scope>       local or global (default: local)
+  --global              Shortcut for --scope global
   --cwd <path>          Project directory (default: current)
   --verbose, -v         Enable debug output
   --json                Machine-readable JSON output

package/dist/config.d.ts

@@ -1,5 +1,10 @@
-import type { StatePaths } from "./types.js";
+import type { InstallScope, StatePaths } from "./types.js";
 export declare const DEFAULT_AGENT_SKILLS_DIR = ".agent-skills";
+export declare const DEFAULT_INSTALL_SCOPE: InstallScope;
+/**
+ * Returns the default user-level Skillex directory (`~/.skillex`).
+ */
+export declare function getDefaultSkillsDir(): string;
 export declare const DEFAULT_LOCKFILE = "skills.json";
 export declare const DEFAULT_LOCAL_SKILLS_DIR = "skills";
 export declare const DEFAULT_GENERATED_DIR = "generated";
@@ -15,3 +20,21 @@ export declare const DEFAULT_REF = "main";
  * @returns Absolute paths for the state directory and lockfile.
  */
 export declare function getStatePaths(cwd: string, baseDir?: string): StatePaths;
+/**
+ * Resolves the managed user-level state paths used by Skillex.
+ *
+ * @param baseDir - Managed global state directory.
+ * @returns Absolute paths for the global state directory and lockfile.
+ */
+export declare function getGlobalStatePaths(baseDir?: string): StatePaths;
+/**
+ * Resolves the managed state paths for either local or global scope.
+ *
+ * @param cwd - Workspace root.
+ * @param options - Scope and optional base directory override.
+ * @returns Absolute paths for the selected state scope.
+ */
+export declare function getScopedStatePaths(cwd: string, options?: {
+    scope?: InstallScope | undefined;
+    baseDir?: string | undefined;
+}): StatePaths;

package/dist/config.js

@@ -1,5 +1,13 @@
+import * as os from "node:os";
 import * as path from "node:path";
 export const DEFAULT_AGENT_SKILLS_DIR = ".agent-skills";
+export const DEFAULT_INSTALL_SCOPE = "local";
+/**
+ * Returns the default user-level Skillex directory (`~/.skillex`).
+ */
+export function getDefaultSkillsDir() {
+    return path.join(os.homedir(), ".skillex");
+}
 export const DEFAULT_LOCKFILE = "skills.json";
 export const DEFAULT_LOCAL_SKILLS_DIR = "skills";
 export const DEFAULT_GENERATED_DIR = "generated";
@@ -17,9 +25,39 @@ export const DEFAULT_REF = "main";
 export function getStatePaths(cwd, baseDir = DEFAULT_AGENT_SKILLS_DIR) {
     const stateDir = path.resolve(cwd, baseDir);
     return {
+        scope: "local",
+        stateDir,
+        lockfilePath: path.join(stateDir, DEFAULT_LOCKFILE),
+        skillsDirPath: path.join(stateDir, DEFAULT_LOCAL_SKILLS_DIR),
+        generatedDirPath: path.join(stateDir, DEFAULT_GENERATED_DIR),
+    };
+}
+/**
+ * Resolves the managed user-level state paths used by Skillex.
+ *
+ * @param baseDir - Managed global state directory.
+ * @returns Absolute paths for the global state directory and lockfile.
+ */
+export function getGlobalStatePaths(baseDir = getDefaultSkillsDir()) {
+    const stateDir = path.resolve(baseDir);
+    return {
+        scope: "global",
         stateDir,
         lockfilePath: path.join(stateDir, DEFAULT_LOCKFILE),
         skillsDirPath: path.join(stateDir, DEFAULT_LOCAL_SKILLS_DIR),
         generatedDirPath: path.join(stateDir, DEFAULT_GENERATED_DIR),
     };
 }
+/**
+ * Resolves the managed state paths for either local or global scope.
+ *
+ * @param cwd - Workspace root.
+ * @param options - Scope and optional base directory override.
+ * @returns Absolute paths for the selected state scope.
+ */
+export function getScopedStatePaths(cwd, options = {}) {
+    if (options.scope === "global") {
+        return getGlobalStatePaths(options.baseDir || getDefaultSkillsDir());
+    }
+    return getStatePaths(cwd, options.baseDir || DEFAULT_AGENT_SKILLS_DIR);
+}