@almyty/skills 1.0.6 → 1.0.9

package/README.md

@@ -35,6 +35,64 @@ $ npx @almyty/skills install @acme/petstore
 $ npx @almyty/skills run @acme/petstore/get-pet --id 123
 ```
 
+## Where skills get installed
+
+`install` writes a `SKILL.md` file per skill into one or more agent
+directories. The CLI detects agents at two scopes:
+
+- **Project scope** — a config dir exists in the current project
+  (e.g. `./.codex/`). Skills install to `./.codex/skills/`, only
+  this checkout sees them.
+- **Home scope** — a config dir exists in your home directory
+  (e.g. `~/.codex/`). Skills install to `~/.codex/skills/`, every
+  project the agent opens picks them up.
+
+Default behavior:
+
+- **Interactive (TTY, no flags):** the picker lists every detected
+  agent at both scopes (each labeled `(project)` or `(home)`),
+  every other supported agent as opt-in, the universal
+  `.agents/skills/` convention, and a custom-path option. Pick any
+  combination.
+- **`--yes` or non-TTY:** project-detected agents + `.agents/skills/`.
+  Home-detected agents are NOT installed automatically — pass
+  `--global` to opt in.
+- **`--global` alone:** every home-detected agent. No project install.
+- **`--all`:** every project-detected agent + universal. Combine
+  with `--global` to also include home-detected.
+- **`--agent <name>`:** install to a specific agent. Picks the
+  detected scope (project preferred). With `--global`, prefers
+  home. If neither is detected, creates the project-scope dir
+  (the agent will pick it up on next scan).
+
+| Flag | Meaning |
+|------|---------|
+| `--agent <name>`, `-a` | Install to the named agent. Repeatable. Partial-match. |
+| `--agent '*'` | Every known agent at project scope, regardless of detection. |
+| `--path <dir>`, `-p` | Custom skills directory. Repeatable. Bypasses detection. |
+| `--all` | Every project-detected agent + `.agents/skills/`. |
+| `--global`, `-G` | Use home scope (`~/.<agent>/skills/`). Modifier on `--agent`, or standalone for "every home-detected". |
+| `--yes`, `-y` | Skip the picker; use the non-interactive defaults. |
+
+Examples:
+
+```bash
+$ npx @almyty/skills install @acme/petstore                          # interactive picker
+$ npx @almyty/skills install @acme/petstore --all                    # every project-detected
+$ npx @almyty/skills install @acme/petstore --all --global           # project AND home detected
+$ npx @almyty/skills install @acme/petstore --global                 # only home-detected agents
+$ npx @almyty/skills install @acme/petstore -a codex                 # codex at whichever scope it lives
+$ npx @almyty/skills install @acme/petstore -a codex --global        # force codex at ~/.codex/skills
+$ npx @almyty/skills install @acme/petstore --agent '*' -y           # every known agent at project
+$ npx @almyty/skills install @acme/petstore -p ./agents/skills       # custom directory
+```
+
+The 25+ supported agents include Claude Code, Codex, Cursor, Windsurf,
+GitHub Copilot, Gemini CLI, Amp, Cline, Continue, Goose, Junie, Roo
+Code, Trae, OpenHands, OpenCode, Augment, and others. See
+`src/agents.ts` for the full registry — each entry maps a detection
+directory to the `<dir>/skills` path that agent reads on session start.
+
 ## Configuration
 
 Create `.almytyrc` in your project or home directory:

package/dist/agents.d.ts

@@ -7,15 +7,49 @@
  *
  * Agent list aligned with https://github.com/vercel-labs/skills
  */
+/**
+ * Where an install ends up. `project` means the skill is bound to
+ * this directory's `.x/skills/` so only this checkout sees it;
+ * `home` means it's installed at the user's home-scope dir
+ * (e.g. `~/.codex/skills/`) and every project shares it. `custom`
+ * means the caller specified a `--path` and we don't track scope.
+ */
+export type InstallScope = 'project' | 'home' | 'custom';
 export interface AgentTarget {
     name: string;
     configDir: string;
     skillsDir: string;
+    scope?: InstallScope;
 }
+/**
+ * Known agent configurations (30+ agents).
+ * Aligned with Vercel's skills CLI.
+ * See: https://github.com/vercel-labs/skills/blob/main/src/agents.ts
+ */
+export declare const AGENT_CONFIGS: Array<{
+    name: string;
+    detectDirs: string[];
+    skillsDir: string;
+}>;
 /**
  * Detect which AI agents are configured in the given project directory.
+ * Project-scope only — for home-scope detection see detectHomeAgents.
  */
 export declare function detectAgents(projectDir: string): AgentTarget[];
+/**
+ * Detect agents the user has installed globally (home-scope) — i.e.
+ * `~/.codex/`, `~/.claude/`, etc. exist regardless of cwd. The
+ * skillsDir returned is the home-scope path (`~/.codex/skills/`),
+ * which Codex and Claude Code both read for cross-project skills.
+ *
+ * Mirrors the project-scope detection: same detectDirs but anchored
+ * at $HOME instead of the project root. The shared `.agents/skills/`
+ * universal convention is intentionally NOT emitted here — that
+ * convention is repo-local (it lives next to the project's source
+ * so the team sees it under version control); if a user wants
+ * universal installs they can use --path explicitly.
+ */
+export declare function detectHomeAgents(home?: string): AgentTarget[];
 /**
  * If no agents are detected, return defaults:
  * - .claude/skills/ (Claude Code native)

package/dist/agents.js

@@ -8,19 +8,26 @@
  * Agent list aligned with https://github.com/vercel-labs/skills
  */
 import { existsSync, mkdirSync } from 'fs';
+import { homedir } from 'os';
 import { join } from 'path';
 /**
  * Known agent configurations (30+ agents).
  * Aligned with Vercel's skills CLI.
  * See: https://github.com/vercel-labs/skills/blob/main/src/agents.ts
  */
-const AGENT_CONFIGS = [
+export const AGENT_CONFIGS = [
     // --- Major agents ---
     { name: 'Claude Code', detectDirs: ['.claude'], skillsDir: '.claude/skills' },
     { name: 'Cursor', detectDirs: ['.cursor', '.cursorrc'], skillsDir: '.agents/skills' },
     { name: 'GitHub Copilot', detectDirs: ['.github/copilot'], skillsDir: '.agents/skills' },
     { name: 'Windsurf', detectDirs: ['.windsurf'], skillsDir: '.windsurf/skills' },
-    { name: 'Codex', detectDirs: ['.codex'], skillsDir: '.agents/skills' },
+    // Codex reads skills from `.codex/skills/<skill>/SKILL.md` for repo-
+    // local skills (and `$CODEX_HOME/skills/...`, default ~/.codex/skills,
+    // for user-scoped). The agentskills.io universal `.agents/skills/`
+    // path is NOT consulted by Codex, so installs targeted at `.agents/`
+    // never appeared in the running agent. Source: Codex curated skill
+    // docs (~/.codex/vendor_imports/skills/skills/.curated/*/SKILL.md).
+    { name: 'Codex', detectDirs: ['.codex'], skillsDir: '.codex/skills' },
     // --- Additional agents ---
     { name: 'Amp', detectDirs: ['.amp'], skillsDir: '.agents/skills' },
     { name: 'Augment', detectDirs: ['.augment'], skillsDir: '.augment/skills' },
@@ -50,6 +57,7 @@ const AGENT_CONFIGS = [
 ];
 /**
  * Detect which AI agents are configured in the given project directory.
+ * Project-scope only — for home-scope detection see detectHomeAgents.
  */
 export function detectAgents(projectDir) {
     const agents = [];
@@ -65,12 +73,51 @@ export function detectAgents(projectDir) {
                     name: config.name,
                     configDir: config.detectDirs[0],
                     skillsDir: fullSkillsDir,
+                    scope: 'project',
                 });
             }
         }
     }
     return agents;
 }
+/**
+ * Detect agents the user has installed globally (home-scope) — i.e.
+ * `~/.codex/`, `~/.claude/`, etc. exist regardless of cwd. The
+ * skillsDir returned is the home-scope path (`~/.codex/skills/`),
+ * which Codex and Claude Code both read for cross-project skills.
+ *
+ * Mirrors the project-scope detection: same detectDirs but anchored
+ * at $HOME instead of the project root. The shared `.agents/skills/`
+ * universal convention is intentionally NOT emitted here — that
+ * convention is repo-local (it lives next to the project's source
+ * so the team sees it under version control); if a user wants
+ * universal installs they can use --path explicitly.
+ */
+export function detectHomeAgents(home = homedir()) {
+    const agents = [];
+    const seenSkillsDirs = new Set();
+    for (const config of AGENT_CONFIGS) {
+        const detected = config.detectDirs.some(dir => existsSync(join(home, dir)));
+        if (!detected)
+            continue;
+        // Home-scope install path: replace the project-prefixed
+        // skillsDir with a home-prefixed equivalent. Most agents store
+        // skills under <configDir>/skills, so just join home with the
+        // skillsDir from AGENT_CONFIGS — that's already the right
+        // structure (e.g., `.codex/skills` → `<home>/.codex/skills`).
+        const fullSkillsDir = join(home, config.skillsDir);
+        if (seenSkillsDirs.has(fullSkillsDir))
+            continue;
+        seenSkillsDirs.add(fullSkillsDir);
+        agents.push({
+            name: config.name,
+            configDir: config.detectDirs[0],
+            skillsDir: fullSkillsDir,
+            scope: 'home',
+        });
+    }
+    return agents;
+}
 /**
  * If no agents are detected, return defaults:
  * - .claude/skills/ (Claude Code native)

package/dist/auth.d.ts

@@ -1,20 +1,6 @@
 /**
- * Credential resolver for @almyty/skills.
- *
- * Authentication itself lives in the dedicated @almyty/auth package
- * (`npx @almyty/auth login`). This module just READS the shared
- * credentials store and surfaces them to the rest of the skills CLI.
- *
- * Lookup order:
- *   1. ALMYTY_TOKEN environment variable      (CI / scripts)
- *   2. ~/.almyty/credentials.json              (interactive use, written
- *                                               by `npx @almyty/auth login`)
+ * Thin re-export from the shared @almyty/client credential resolver.
+ * Keeps `./auth.js` imports working across the skills-cli codebase.
  */
-/**
- * Resolve token: env var > stored credentials. Exits with a clear hint
- * if no credentials are available.
- */
-export declare function resolveAuth(): {
-    url: string;
-    token: string;
-};
+export { resolveCredentials, resolveCredentialsOrExit, resolveCredentialsOrExit as resolveAuth, loadCredentials, CREDENTIALS_FILE, } from '@almyty/client';
+export type { StoredCredentials } from '@almyty/client';

package/dist/auth.js

@@ -1,57 +1,5 @@
 /**
- * Credential resolver for @almyty/skills.
- *
- * Authentication itself lives in the dedicated @almyty/auth package
- * (`npx @almyty/auth login`). This module just READS the shared
- * credentials store and surfaces them to the rest of the skills CLI.
- *
- * Lookup order:
- *   1. ALMYTY_TOKEN environment variable      (CI / scripts)
- *   2. ~/.almyty/credentials.json              (interactive use, written
- *                                               by `npx @almyty/auth login`)
+ * Thin re-export from the shared @almyty/client credential resolver.
+ * Keeps `./auth.js` imports working across the skills-cli codebase.
  */
-import { readFileSync, existsSync } from 'fs';
-import { homedir } from 'os';
-import { join } from 'path';
-const CREDENTIALS_FILE = join(homedir(), '.almyty', 'credentials.json');
-function loadCredentials() {
-    try {
-        if (!existsSync(CREDENTIALS_FILE))
-            return null;
-        return JSON.parse(readFileSync(CREDENTIALS_FILE, 'utf-8'));
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Resolve token: env var > stored credentials. Exits with a clear hint
- * if no credentials are available.
- */
-export function resolveAuth() {
-    const envToken = process.env.ALMYTY_TOKEN;
-    // Read URL from: env > config file > default
-    let configUrl;
-    try {
-        const { readFileSync, existsSync } = require('fs');
-        const { join } = require('path');
-        const { homedir } = require('os');
-        const configPath = join(homedir(), '.almyty', 'config.json');
-        if (existsSync(configPath)) {
-            configUrl = JSON.parse(readFileSync(configPath, 'utf-8')).apiUrl;
-        }
-    }
-    catch { }
-    const envUrl = process.env.ALMYTY_URL || configUrl || 'https://api.almyty.com';
-    if (envToken) {
-        return { url: envUrl, token: envToken };
-    }
-    const creds = loadCredentials();
-    if (creds?.token) {
-        return { url: creds.url, token: creds.token };
-    }
-    console.error('Not authenticated. Run one of:');
-    console.error('  npx @almyty/auth login        # browser-based login');
-    console.error('  export ALMYTY_TOKEN=<token>   # for CI');
-    process.exit(1);
-}
+export { resolveCredentials, resolveCredentialsOrExit, resolveCredentialsOrExit as resolveAuth, loadCredentials, CREDENTIALS_FILE, } from '@almyty/client';

package/dist/index.js

@@ -5,7 +5,8 @@ import { getAllTargets } from './agents.js';
 import { installSkills, removeSkills, listInstalledSkills } from './installer.js';
 import { loadConfig, resolveTargets } from './config.js';
 import { generateMetaSkill } from './meta-skill.js';
-const VERSION = '1.0.0';
+import { selectInstallTargetsAuto, selectInstallTargetsInteractive, } from './target-selector.js';
+const VERSION = '1.0.9';
 function printHelp() {
     console.log(`
 almyty Skills CLI v${VERSION}
@@ -40,19 +41,65 @@ Config:
   ALMYTY_TOKEN                   Override auth token
 
 Options:
+  --agent, -a <name>             Install target by name (repeatable; e.g.
+                                 -a codex -a claude). Accepts '*' or 'all'
+                                 for every known agent regardless of
+                                 detection. Partial match.
+  --path, -p <dir>               Custom skills dir, repeatable. Bypasses
+                                 agent detection.
+  --all                          Install to every PROJECT-detected agent
+                                 (plus the universal .agents/skills/).
+                                 Combine with --global to also include
+                                 home-detected. Skips the picker.
+  --global, -G                   Use home-scope (~/.codex/skills/, etc.)
+                                 instead of project-scope. With --all,
+                                 includes home-detected agents alongside
+                                 project-detected. With --agent <name>,
+                                 prefers home-scope when the agent is
+                                 detected at $HOME.
+  --yes, -y                      Skip the interactive picker. Falls back
+                                 to detected agents (or defaults).
   --interval, -i <seconds>       Daemon poll interval in seconds (default: 60)
   --url <url>                    almyty API URL (default: https://api.almyty.com)
   --dir <path>                   Project directory (default: current directory)
   --help, -h                     Show help
   --version, -v                  Show version
 
+Target selection (install):
+  Without flags in a TTY, install shows a multi-select picker of all
+  known agents (detected ones pre-checked) plus a "custom path…" option.
+  In a non-TTY, the picker is skipped: install writes to detected agents
+  and the universal .agents/skills/ directory.
+
 Examples:
   npx @almyty/skills daemon
   npx @almyty/skills install myorg/petstore/get-pet
+  npx @almyty/skills install @org/gw -a codex -a claude
+  npx @almyty/skills install @org/gw --path ./tmp/skills --yes
+  npx @almyty/skills install @org/gw --all
   npx @almyty/skills search "weather"
   npx @almyty/skills run myorg/petstore/get-pet --petId 123
 `);
 }
+/**
+ * Repeatable flags accumulate into a string[] when supplied more
+ * than once. Used by `--agent` and `--path` so callers can pick
+ * multiple targets without inventing comma syntax (the selector
+ * also splits on comma/space, so both styles work).
+ */
+const REPEATABLE_FLAGS = new Set(['agent', 'path']);
+function appendRepeatable(flags, key, value) {
+    const existing = flags[key];
+    if (existing === undefined || existing === true || existing === false) {
+        flags[key] = value;
+    }
+    else if (typeof existing === 'string') {
+        flags[key] = [existing, value];
+    }
+    else {
+        existing.push(value);
+    }
+}
 function parseArgs(argv) {
     const result = { positional: [], flags: {} };
     let i = 0;
@@ -70,6 +117,23 @@ function parseArgs(argv) {
         else if (arg === '--interval' || arg === '-i') {
             result.flags.interval = argv[++i] || '60';
         }
+        else if (arg === '--agent' || arg === '-a') {
+            appendRepeatable(result.flags, 'agent', argv[++i] || '');
+        }
+        else if (arg === '--path' || arg === '-p') {
+            appendRepeatable(result.flags, 'path', argv[++i] || '');
+        }
+        else if (arg === '--all') {
+            result.flags.all = true;
+        }
+        else if (arg === '--yes' || arg === '-y') {
+            result.flags.yes = true;
+        }
+        else if (arg === '--global' || arg === '-G') {
+            // --global / -G installs at home scope (~/.codex/skills/, etc.)
+            // -g remains aliased to --gateway for back-compat.
+            result.flags.global = true;
+        }
         else if (arg === '--help' || arg === '-h') {
             result.flags.help = true;
         }
@@ -83,7 +147,12 @@ function parseArgs(argv) {
             const key = arg.slice(2);
             const next = argv[i + 1];
             if (next && !next.startsWith('--')) {
-                result.flags[key] = next;
+                if (REPEATABLE_FLAGS.has(key)) {
+                    appendRepeatable(result.flags, key, next);
+                }
+                else {
+                    result.flags[key] = next;
+                }
                 i++;
             }
             else {
@@ -121,9 +190,12 @@ function requireRef(args, command) {
 }
 function parseRunParams(args) {
     const params = {};
-    const entries = Object.entries(args.flags);
-    for (const [key, value] of entries) {
-        if (['url', 'dir', 'help', 'version', 'interval', 'gateway'].includes(key))
+    const reserved = new Set([
+        'url', 'dir', 'help', 'version', 'interval', 'gateway',
+        'agent', 'path', 'all', 'yes', 'global',
+    ]);
+    for (const [key, value] of Object.entries(args.flags)) {
+        if (reserved.has(key))
             continue;
         params[key] = value;
     }
@@ -311,7 +383,24 @@ async function main() {
                 return;
             }
             console.log(`\n${gwName} (${skills.length} skill(s))`);
-            const targets = resolveTargets(projectDir, config);
+            const selection = {
+                projectDir,
+                config,
+                agentFlag: args.flags.agent,
+                pathFlag: args.flags.path,
+                all: !!args.flags.all,
+                yes: !!args.flags.yes,
+                global: !!args.flags.global,
+            };
+            let targets = selectInstallTargetsAuto(selection);
+            if (targets === null) {
+                // Interactive picker — TTY + no flags + no .almytyrc.
+                targets = await selectInstallTargetsInteractive(selection);
+            }
+            if (targets.length === 0) {
+                console.error('No install targets resolved. Pass --agent / --path / --all or run without flags in a TTY.');
+                process.exit(1);
+            }
             const results = targets.map(target => installSkills(skills, target));
             console.log('');
             for (const result of results) {

package/dist/installer.d.ts

@@ -1,5 +1,13 @@
 /**
  * Skill installer — writes SKILL.md files to agent directories.
+ *
+ * Naming: the skill's own name is used directly for both the
+ * directory and the SKILL.md frontmatter `name:` field. We used to
+ * prefix `almyty-` to flag installs as ours; that turned the agent-
+ * visible label into `$almyty-open-meteo-weather-get-v1-forecast`,
+ * which is noisy and uninformative. Identification for `remove`
+ * and `installed` now reads the `metadata.author: almyty` line
+ * already present in every SKILL.md we generate.
  */
 import type { SkillFile } from './client.js';
 import type { AgentTarget } from './agents.js';
@@ -11,14 +19,10 @@ export interface InstallResult {
 }
 /**
  * Install skill files into an agent's skills directory.
- * Each skill gets its own directory: <skillsDir>/almyty-<name>/SKILL.md
+ * Each skill lives at `<skillsDir>/<skill-name>/SKILL.md`.
  */
 export declare function installSkills(skills: SkillFile[], target: AgentTarget): InstallResult;
-/**
- * Remove all almyty-installed skills from an agent's skills directory.
- */
+/** Remove every almyty-installed skill from an agent's skills directory. */
 export declare function removeSkills(target: AgentTarget): number;
-/**
- * List installed almyty skills in an agent's skills directory.
- */
+/** List almyty-installed skills in an agent's skills directory. */
 export declare function listInstalledSkills(target: AgentTarget): string[];

package/dist/installer.js

@@ -1,22 +1,68 @@
 /**
  * Skill installer — writes SKILL.md files to agent directories.
+ *
+ * Naming: the skill's own name is used directly for both the
+ * directory and the SKILL.md frontmatter `name:` field. We used to
+ * prefix `almyty-` to flag installs as ours; that turned the agent-
+ * visible label into `$almyty-open-meteo-weather-get-v1-forecast`,
+ * which is noisy and uninformative. Identification for `remove`
+ * and `installed` now reads the `metadata.author: almyty` line
+ * already present in every SKILL.md we generate.
  */
-import { writeFileSync, mkdirSync, existsSync, readdirSync, rmSync } from 'fs';
+import { writeFileSync, mkdirSync, existsSync, readdirSync, rmSync, readFileSync } from 'fs';
 import { join } from 'path';
-const SKILL_PREFIX = 'almyty-';
+/** Legacy prefix from <=v1.0.9 — older installs still use this dir
+ *  name. Kept here so `remove`/`installed` continue to find them. */
+const LEGACY_SKILL_PREFIX = 'almyty-';
+/** Marker line we expect inside every SKILL.md frontmatter we wrote. */
+const ALMYTY_MARKER = /^\s*author:\s*almyty\s*$/m;
+/**
+ * Strip the legacy `name: almyty-<x>` line in the SKILL.md frontmatter
+ * to `name: <x>` so the agent-visible identifier is the skill's own
+ * slug. Backend currently writes the prefixed form; once that's
+ * cleaned up upstream this becomes a no-op.
+ */
+function rewriteNameInFrontmatter(content) {
+    return content.replace(/^name:\s*almyty-/m, 'name: ');
+}
+/**
+ * Read SKILL.md and decide whether it was installed by this CLI
+ * (or its predecessor). Two signals: the legacy `almyty-` directory
+ * prefix, OR the `metadata.author: almyty` line in the frontmatter.
+ */
+function isAlmytyInstall(skillsDir, dirName) {
+    if (dirName.startsWith(LEGACY_SKILL_PREFIX))
+        return true;
+    const skillFile = join(skillsDir, dirName, 'SKILL.md');
+    if (!existsSync(skillFile))
+        return false;
+    try {
+        return ALMYTY_MARKER.test(readFileSync(skillFile, 'utf-8'));
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Install skill files into an agent's skills directory.
- * Each skill gets its own directory: <skillsDir>/almyty-<name>/SKILL.md
+ * Each skill lives at `<skillsDir>/<skill-name>/SKILL.md`.
  */
 export function installSkills(skills, target) {
     const files = [];
     mkdirSync(target.skillsDir, { recursive: true });
     for (const skill of skills) {
-        const dirName = `${SKILL_PREFIX}${skill.name}`;
+        const dirName = skill.name;
         const skillDir = join(target.skillsDir, dirName);
         const skillFile = join(skillDir, 'SKILL.md');
+        // Cleanup: if a previous install used the `almyty-<name>` dir
+        // shape, remove it before writing the new shape so the agent
+        // doesn't see two copies of the same skill.
+        const legacyDir = join(target.skillsDir, `${LEGACY_SKILL_PREFIX}${skill.name}`);
+        if (legacyDir !== skillDir && existsSync(legacyDir)) {
+            rmSync(legacyDir, { recursive: true, force: true });
+        }
         mkdirSync(skillDir, { recursive: true });
-        writeFileSync(skillFile, skill.content, 'utf-8');
+        writeFileSync(skillFile, rewriteNameInFrontmatter(skill.content), 'utf-8');
         files.push(skillFile);
     }
     return {
@@ -26,30 +72,28 @@ export function installSkills(skills, target) {
         files,
     };
 }
-/**
- * Remove all almyty-installed skills from an agent's skills directory.
- */
+/** Remove every almyty-installed skill from an agent's skills directory. */
 export function removeSkills(target) {
     if (!existsSync(target.skillsDir))
         return 0;
     const entries = readdirSync(target.skillsDir, { withFileTypes: true });
     let removed = 0;
     for (const entry of entries) {
-        if (entry.isDirectory() && entry.name.startsWith(SKILL_PREFIX)) {
-            rmSync(join(target.skillsDir, entry.name), { recursive: true, force: true });
-            removed++;
-        }
+        if (!entry.isDirectory())
+            continue;
+        if (!isAlmytyInstall(target.skillsDir, entry.name))
+            continue;
+        rmSync(join(target.skillsDir, entry.name), { recursive: true, force: true });
+        removed++;
     }
     return removed;
 }
-/**
- * List installed almyty skills in an agent's skills directory.
- */
+/** List almyty-installed skills in an agent's skills directory. */
 export function listInstalledSkills(target) {
     if (!existsSync(target.skillsDir))
         return [];
     const entries = readdirSync(target.skillsDir, { withFileTypes: true });
     return entries
-        .filter(e => e.isDirectory() && e.name.startsWith(SKILL_PREFIX))
-        .map(e => e.name.replace(SKILL_PREFIX, ''));
+        .filter((e) => e.isDirectory() && isAlmytyInstall(target.skillsDir, e.name))
+        .map((e) => e.name.replace(LEGACY_SKILL_PREFIX, ''));
 }

package/dist/target-selector.d.ts

@@ -0,0 +1,30 @@
+import { AgentTarget } from './agents.js';
+import type { AlmytyConfig } from './config.js';
+export interface SelectionInput {
+    projectDir: string;
+    config: AlmytyConfig;
+    /** `--agent <name>` (repeatable, comma/space split, supports `*` / `all`). */
+    agentFlag?: string | string[];
+    /** `--path <dir>` (repeatable, comma split). */
+    pathFlag?: string | string[];
+    /** `--all`: every project-detected agent + universal. */
+    all?: boolean;
+    /** `--yes` / `-y`: skip the interactive picker. */
+    yes?: boolean;
+    /** `--global` / `-G`: include / prefer home-scope installs. */
+    global?: boolean;
+    /** Override $HOME (test seam). */
+    home?: string;
+}
+/**
+ * Resolve targets for non-interactive paths. Returns null when the
+ * caller must fall through to the interactive picker (TTY + no
+ * resolving flag/config).
+ */
+export declare function selectInstallTargetsAuto(input: SelectionInput): AgentTarget[] | null;
+/**
+ * Drive the multi-select picker. Lists every detected agent at
+ * BOTH scopes, with detection scope shown as a hint, plus a custom
+ * path option. Returns the chosen targets.
+ */
+export declare function selectInstallTargetsInteractive(input: SelectionInput): Promise<AgentTarget[]>;

package/dist/target-selector.js

@@ -0,0 +1,311 @@
+/**
+ * Target selection for the install path.
+ *
+ * Two scopes:
+ *   - **project**: writes to `<cwd>/.<agent>/skills/` so the skill
+ *     is part of this checkout. Detected by an `.x/` config dir in
+ *     `projectDir`.
+ *   - **home**: writes to `~/.<agent>/skills/`, shared across every
+ *     project the user opens with that agent. Detected by an `.x/`
+ *     config dir in `$HOME`.
+ *
+ * Order of precedence (highest first):
+ *   1. CLI `--path` — explicit custom dir(s); detection ignored.
+ *   2. CLI `--all`                — every PROJECT-detected agent + universal
+ *      CLI `--all --global`       — every PROJECT-detected + every HOME-detected
+ *      CLI `--global` (alone)     — every HOME-detected agent
+ *   3. CLI `--agent foo`          — the named agent at whichever scope it's
+ *      detected in (project preferred); home if `--global` is set.
+ *      `--agent '*'` / `--agent all` — every known agent dir at project scope
+ *      regardless of detection.
+ *   4. `.almytyrc` skillsDir / agents whitelist.
+ *   5. Interactive picker (TTY) — multi-select listing every detected
+ *      agent in both scopes plus a "custom path…" option.
+ *   6. Non-TTY fallback — project-detected + universal, or defaults.
+ */
+import { resolve, join } from 'path';
+import { homedir } from 'os';
+import { AGENT_CONFIGS, detectAgents, detectHomeAgents, getDefaultTargets, } from './agents.js';
+function toList(v) {
+    if (!v)
+        return [];
+    const arr = Array.isArray(v) ? v : [v];
+    return arr
+        .flatMap((s) => s.split(/[,\s]+/))
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+function customPathTarget(projectDir, p) {
+    const abs = resolve(projectDir, p);
+    return {
+        name: `custom (${p})`,
+        configDir: p,
+        skillsDir: abs,
+        scope: 'custom',
+    };
+}
+function projectAgentTarget(projectDir, name) {
+    const cfg = AGENT_CONFIGS.find((c) => c.name === name);
+    if (!cfg)
+        return null;
+    return {
+        name: cfg.name,
+        configDir: cfg.detectDirs[0],
+        skillsDir: join(projectDir, cfg.skillsDir),
+        scope: 'project',
+    };
+}
+function homeAgentTarget(home, name) {
+    const cfg = AGENT_CONFIGS.find((c) => c.name === name);
+    if (!cfg)
+        return null;
+    return {
+        name: cfg.name,
+        configDir: cfg.detectDirs[0],
+        skillsDir: join(home, cfg.skillsDir),
+        scope: 'home',
+    };
+}
+function universalTarget(projectDir) {
+    return {
+        name: 'Universal (.agents/skills)',
+        configDir: '.agents',
+        skillsDir: join(projectDir, '.agents/skills'),
+        scope: 'project',
+    };
+}
+function dedupeBySkillsDir(targets) {
+    const seen = new Set();
+    const out = [];
+    for (const t of targets) {
+        if (seen.has(t.skillsDir))
+            continue;
+        seen.add(t.skillsDir);
+        out.push(t);
+    }
+    return out;
+}
+function matchAgentName(filter, candidate) {
+    const norm = (s) => s.toLowerCase().replace(/[\s-]/g, '');
+    return norm(candidate).includes(norm(filter));
+}
+/**
+ * Resolve targets for non-interactive paths. Returns null when the
+ * caller must fall through to the interactive picker (TTY + no
+ * resolving flag/config).
+ */
+export function selectInstallTargetsAuto(input) {
+    const { projectDir, config, all, yes, global } = input;
+    const home = input.home ?? homedir();
+    const agentFlag = toList(input.agentFlag);
+    const pathFlag = toList(input.pathFlag);
+    // 1. Explicit `--path` wins outright. Detection ignored.
+    if (pathFlag.length > 0) {
+        return dedupeBySkillsDir(pathFlag.map((p) => customPathTarget(projectDir, p)));
+    }
+    // 2. Bulk install via `--all` and/or `--global`. Only fires when
+    //    no `--agent` filter is set — otherwise `--global` is a
+    //    *modifier* on the agent-by-name resolution below, not a
+    //    standalone "every home-detected" command.
+    if ((all || global) && agentFlag.length === 0) {
+        const projectDetected = all ? detectAgents(projectDir) : [];
+        const homeDetected = global ? detectHomeAgents(home) : [];
+        const universal = all ? [universalTarget(projectDir)] : [];
+        const combined = [...projectDetected, ...homeDetected, ...universal];
+        if (combined.length === 0) {
+            throw new Error(global && !all
+                ? 'No agents detected at home scope (~/.<agent>/). Run `npx @almyty/skills install` interactively or pass `--agent <name>`.'
+                : 'No agents detected in this project. Try --agent <name> or --path <dir>.');
+        }
+        return dedupeBySkillsDir(combined);
+    }
+    // 3. `--agent foo,bar`. Wildcard expands to every known agent at
+    //    project scope. Otherwise: prefer project scope when detected,
+    //    else fall through to home scope when detected, else
+    //    project-scope at the default path (the agent's not installed
+    //    anywhere yet; the user is opting in by name).
+    if (agentFlag.length > 0) {
+        if (agentFlag.some((f) => f === '*' || f.toLowerCase() === 'all')) {
+            const everyKnown = AGENT_CONFIGS
+                .map((c) => projectAgentTarget(projectDir, c.name))
+                .filter(Boolean);
+            return dedupeBySkillsDir([...everyKnown, universalTarget(projectDir)]);
+        }
+        const projectDetectedNames = new Set(detectAgents(projectDir).map((a) => a.name));
+        const homeDetectedNames = new Set(detectHomeAgents(home).map((a) => a.name));
+        const targets = [];
+        const unmatched = [];
+        for (const filter of agentFlag) {
+            const cfg = AGENT_CONFIGS.find((c) => matchAgentName(filter, c.name));
+            if (!cfg) {
+                unmatched.push(filter);
+                continue;
+            }
+            // Pick the right scope. With `--global` always take home if
+            // available; otherwise prefer project, fall through to home.
+            if (global && homeDetectedNames.has(cfg.name)) {
+                targets.push(homeAgentTarget(home, cfg.name));
+            }
+            else if (projectDetectedNames.has(cfg.name)) {
+                targets.push(projectAgentTarget(projectDir, cfg.name));
+            }
+            else if (homeDetectedNames.has(cfg.name)) {
+                targets.push(homeAgentTarget(home, cfg.name));
+            }
+            else {
+                // Not detected anywhere — install at project scope by name
+                // request. The agent picks it up next time it scans.
+                targets.push(projectAgentTarget(projectDir, cfg.name));
+            }
+        }
+        if (unmatched.length > 0) {
+            throw new Error(`No known agents matched --agent ${unmatched.join(',')}. ` +
+                `Run with --help to see supported names.`);
+        }
+        return dedupeBySkillsDir([...targets, universalTarget(projectDir)]);
+    }
+    // 4. Project `.almytyrc` skillsDir override.
+    if (config.skillsDir) {
+        return [
+            {
+                name: 'custom (.almytyrc)',
+                configDir: config.skillsDir,
+                skillsDir: resolve(projectDir, config.skillsDir),
+                scope: 'custom',
+            },
+        ];
+    }
+    // 5. Project `.almytyrc` agents whitelist (project-scope only).
+    if (config.agents && config.agents.length > 0) {
+        const matched = [];
+        for (const filter of config.agents) {
+            const cfg = AGENT_CONFIGS.find((c) => matchAgentName(filter, c.name));
+            if (cfg)
+                matched.push(projectAgentTarget(projectDir, cfg.name));
+        }
+        if (matched.length > 0) {
+            return dedupeBySkillsDir([...matched, universalTarget(projectDir)]);
+        }
+    }
+    // 6. `--yes` / non-TTY: pick a sensible default WITHOUT prompting.
+    //    Project-detected + universal first; if nothing project-side,
+    //    show home-detected as a hint (the user probably wants the
+    //    interactive picker for this; here we just return defaults
+    //    so scripted use doesn't hang).
+    if (yes || !process.stdin.isTTY) {
+        const projectDetected = detectAgents(projectDir);
+        if (projectDetected.length > 0) {
+            return dedupeBySkillsDir([
+                ...projectDetected,
+                universalTarget(projectDir),
+            ]);
+        }
+        return dedupeBySkillsDir([
+            ...getDefaultTargets(projectDir),
+            universalTarget(projectDir),
+        ]);
+    }
+    // Interactive picker required.
+    return null;
+}
+/**
+ * Drive the multi-select picker. Lists every detected agent at
+ * BOTH scopes, with detection scope shown as a hint, plus a custom
+ * path option. Returns the chosen targets.
+ */
+export async function selectInstallTargetsInteractive(input) {
+    const { projectDir } = input;
+    const home = input.home ?? homedir();
+    const clack = await import('@clack/prompts');
+    const projectDetected = detectAgents(projectDir);
+    const homeDetected = detectHomeAgents(home);
+    // Build options: project entries first (preferred), then home,
+    // then known-but-not-detected as a separate group, then universal,
+    // then custom-path. We use synthetic value tokens so we can
+    // resolve back to AgentTargets after the multiselect returns.
+    const seen = new Set();
+    const options = [];
+    for (const a of projectDetected) {
+        options.push({
+            value: `project:${a.name}`,
+            label: `${a.name}  (project)`,
+            hint: a.skillsDir.replace(projectDir, '.'),
+        });
+        seen.add(`${a.scope}:${a.name}`);
+    }
+    for (const a of homeDetected) {
+        if (seen.has(`project:${a.name}`)) {
+            // Same agent also detected locally — already shown above; the
+            // user can still install both scopes by adding the home line
+            // here, so keep it.
+        }
+        options.push({
+            value: `home:${a.name}`,
+            label: `${a.name}  (home)`,
+            hint: a.skillsDir.replace(home, '~'),
+        });
+    }
+    options.push({
+        value: '__universal__',
+        label: 'Universal (.agents/skills)',
+        hint: 'cross-client convention; project scope',
+    });
+    // List the agents that are recognized but not detected anywhere
+    // so users can opt in by checkbox without retyping the name.
+    const detectedNames = new Set([...projectDetected, ...homeDetected].map((a) => a.name));
+    for (const cfg of AGENT_CONFIGS) {
+        if (detectedNames.has(cfg.name))
+            continue;
+        options.push({
+            value: `project:${cfg.name}`,
+            label: `${cfg.name}`,
+            hint: `not detected — would create ${cfg.skillsDir}`,
+        });
+    }
+    options.push({
+        value: '__custom__',
+        label: 'Custom path…',
+        hint: 'enter a directory after this prompt',
+    });
+    const initialValues = projectDetected.map((a) => `project:${a.name}`);
+    if (initialValues.length === 0)
+        initialValues.push('__universal__');
+    const picked = await clack.multiselect({
+        message: 'Where should the skills be installed?',
+        options,
+        initialValues,
+        required: true,
+    });
+    if (clack.isCancel(picked)) {
+        clack.cancel('Install cancelled.');
+        process.exit(0);
+    }
+    const values = picked;
+    const targets = [];
+    for (const v of values) {
+        if (v === '__universal__') {
+            targets.push(universalTarget(projectDir));
+            continue;
+        }
+        if (v === '__custom__') {
+            const path = await clack.text({
+                message: 'Custom skills directory path:',
+                placeholder: 'e.g. .my-agent/skills',
+                validate: (s) => (s && s.trim() ? undefined : 'Required'),
+            });
+            if (clack.isCancel(path)) {
+                clack.cancel('Install cancelled.');
+                process.exit(0);
+            }
+            targets.push(customPathTarget(projectDir, String(path).trim()));
+            continue;
+        }
+        const [scope, name] = v.split(':');
+        const t = scope === 'home'
+            ? homeAgentTarget(home, name)
+            : projectAgentTarget(projectDir, name);
+        if (t)
+            targets.push(t);
+    }
+    return dedupeBySkillsDir(targets);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@almyty/skills",
-  "version": "1.0.6",
-  "description": "Install API skills into AI coding agents — Claude Code, Cursor, Windsurf, Copilot, Codex",
+  "version": "1.0.9",
+  "description": "Install API skills into AI coding agents \u2014 Claude Code, Cursor, Windsurf, Copilot, Codex",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -11,7 +11,7 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && chmod +x dist/index.js",
     "dev": "tsx src/index.ts",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -31,10 +31,14 @@
   ],
   "author": "almyty",
   "license": "BSL-1.1",
+  "dependencies": {
+    "@almyty/client": "^0.1.0",
+    "@clack/prompts": "^1.2.0"
+  },
   "devDependencies": {
     "@types/node": "^25.4.0",
     "tsx": "^4.7.0",
     "typescript": "^5.3.0",
     "vitest": "^4.1.0"
   }
-}
+}