skillex 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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

@@ -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` downloads skill files locally. `sync` is what actually writes the skill instructions into your agent's configuration file (e.g. `.claude/skills/skillex-skills.md`, `.codex/skills/skillex-skills.md`, `.github/copilot-instructions.md`). **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`.
 
 ---
@@ -162,6 +165,8 @@ skillex install owner/repo/path/to/skill@main --trust
 | `--repo <owner/repo>` | Limit resolution to a single source when needed. |
 | `--trust` | Skip confirmation prompt for direct GitHub installs. |
 
+> **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.
+
 ---
 
 ### `update`
@@ -191,7 +196,7 @@ skillex rm git-master code-review
 
 ### `sync`
 
-Write all installed skills into the active adapter's config file.
+Write all installed skills into the active adapter's config file (e.g. `.claude/skills/skillex-skills.md`, `.codex/skills/skillex-skills.md`, `.github/copilot-instructions.md`). **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
@@ -213,6 +218,25 @@ skillex sync --mode copy
 | `--adapter <id>` | Override the active adapter for this sync. |
 | `--mode copy\|symlink` | File write strategy (default: `symlink` for dedicated-file adapters). |
 
+#### 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 skills into .claude/skills/skillex-skills.md
+skillex sync --adapter claude
+
+# Write skills into .codex/skills/skillex-skills.md
+skillex sync --adapter codex
+```
+
+Each adapter writes to its own target file, 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
+```
+
 ---
 
 ### `run`
@@ -337,17 +361,19 @@ 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/skillex-skills.md` |
 | `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/skillex-skills.md` |
+| `gemini` | Gemini CLI | `GEMINI.md`, `.gemini/` | `.gemini/skills/skillex-skills.md` |
 | `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.
+
+**Dedicated-file adapters** (`codex`, `cline`, `claude`, `cursor`, `gemini`, `windsurf`) each generate a file in `~/.skillex/generated/<adapter>/` and create an absolute symlink at the adapter's target path (e.g. `.claude/skills/skillex-skills.md`). Use `--mode copy` to write directly instead.
 
-**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.
+> **Migrating from a previous version?** If you had skill content injected into `CLAUDE.md`, `GEMINI.md`, or `AGENTS.md` by an older version of Skillex, those legacy files are cleaned up automatically on the next `sync`. You can also remove the block manually.
 
 Compatibility aliases are normalized automatically: `claude-code` → `claude`, `github-copilot` → `copilot`, `roo-code` → `cline`, `gemini-cli` → `gemini`.
 

package/dist/adapters.js

@@ -10,8 +10,8 @@ const ADAPTERS = [
             { path: ".codex", weight: 12 },
             { path: ".codex/skills", weight: 16 },
         ],
-        syncTarget: "AGENTS.md",
-        syncMode: "managed-block",
+        syncTarget: ".codex/skills/skillex-skills.md",
+        syncMode: "managed-file",
     },
     {
         id: "copilot",
@@ -52,8 +52,9 @@ const ADAPTERS = [
             { path: "CLAUDE.md", weight: 16 },
             { path: ".claude", weight: 18 },
         ],
-        syncTarget: "CLAUDE.md",
-        syncMode: "managed-block",
+        syncTarget: ".claude/skills/skillex-skills.md",
+        legacySyncTargets: ["CLAUDE.md"],
+        syncMode: "managed-file",
     },
     {
         id: "gemini",
@@ -62,8 +63,9 @@ const ADAPTERS = [
             { path: "GEMINI.md", weight: 16 },
             { path: ".gemini", weight: 18 },
         ],
-        syncTarget: "GEMINI.md",
-        syncMode: "managed-block",
+        syncTarget: ".gemini/skills/skillex-skills.md",
+        legacySyncTargets: ["GEMINI.md"],
+        syncMode: "managed-file",
     },
     {
         id: "windsurf",

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_AGENT_SKILLS_DIR, getDefaultSkillsDir, getStatePaths } 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";
@@ -750,12 +750,15 @@ function commonOptions(flags, userConfig = {}) {
         options.timeout = timeout;
     if (noCache !== undefined)
         options.noCache = noCache;
+    // Default to user-level storage so symlinks always point to a stable path.
+    if (!options.agentSkillsDir)
+        options.agentSkillsDir = getDefaultSkillsDir();
     return options;
 }
 /** 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 = path.resolve(cwd, opts.agentSkillsDir ?? getDefaultSkillsDir());
     return {
         cacheDir: path.join(stateDir, ".cache"),
         ...(opts.noCache !== undefined ? { noCache: opts.noCache } : {}),

package/dist/config.d.ts

@@ -1,5 +1,9 @@
 import type { StatePaths } from "./types.js";
 export declare const DEFAULT_AGENT_SKILLS_DIR = ".agent-skills";
+/**
+ * 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";

package/dist/config.js

@@ -1,5 +1,12 @@
+import * as os from "node:os";
 import * as path from "node:path";
 export const DEFAULT_AGENT_SKILLS_DIR = ".agent-skills";
+/**
+ * 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";

package/dist/fs.js

@@ -97,15 +97,15 @@ export async function removePath(targetPath) {
  * @returns Symlink creation result.
  */
 export async function createSymlink(targetPath, linkPath) {
-    const relativeTarget = path.relative(path.dirname(linkPath), targetPath) || ".";
+    const absoluteTarget = path.resolve(targetPath);
     await ensureDir(path.dirname(linkPath));
     await removePath(linkPath);
     try {
-        await fs.symlink(relativeTarget, linkPath);
+        await fs.symlink(absoluteTarget, linkPath);
         return {
             ok: true,
             fallback: false,
-            relativeTarget,
+            relativeTarget: absoluteTarget,
         };
     }
     catch (error) {
@@ -116,7 +116,7 @@ export async function createSymlink(targetPath, linkPath) {
             return {
                 ok: false,
                 fallback: true,
-                relativeTarget,
+                relativeTarget: absoluteTarget,
             };
         }
         throw error;

package/dist/sync.js

@@ -139,7 +139,7 @@ export async function prepareSyncAdapterFiles(options) {
     const generatedSourcePath = path.join(options.statePaths.generatedDirPath, adapter.id, path.basename(adapter.syncTarget));
     const currentDescriptor = await describeTarget(targetPath);
     const currentVisibleContent = (await readText(targetPath, "")) || "";
-    const nextDescriptor = `symlink -> ${toPosix(path.relative(path.dirname(targetPath), generatedSourcePath))}\n`;
+    const nextDescriptor = `symlink -> ${toPosix(generatedSourcePath)}\n`;
     const descriptorChanged = normalizeComparableText(currentDescriptor) !== normalizeComparableText(nextDescriptor);
     const contentChanged = normalizeComparableText(currentVisibleContent) !== normalizeComparableText(nextContent);
     return {
@@ -154,7 +154,7 @@ export async function prepareSyncAdapterFiles(options) {
             targetPath: relativeTargetPath,
             currentDescriptor,
             nextDescriptor,
-            generatedPath: toPosix(path.relative(options.cwd, generatedSourcePath)),
+            generatedPath: toPosix(generatedSourcePath),
             currentContent: currentVisibleContent,
             nextContent,
         }),
@@ -237,6 +237,9 @@ function buildManagedFileContent(adapterId, body, autoInjectBlock) {
                 "",
             ].join("\n");
         case "cline":
+        case "codex":
+        case "claude":
+        case "gemini":
             return `${sections.join("\n\n")}\n`;
         default:
             throw new SyncError(`Adapter desconhecido: ${adapterId}`, "SYNC_ADAPTER_UNKNOWN");

package/package.json

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