any-skills 0.1.1 → 0.1.2

package/README.md

@@ -7,7 +7,9 @@ When installed as a dependency, this package creates a shared skills directory (
 
 ## How it works
 
-The `postinstall` script runs at install time. It uses the user's install working directory as the root (prefers `INIT_CWD`, then `npm_config_local_prefix`, and falls back to `process.cwd()`). If the shared skills directory does not exist, it is created, then the tool-specific symlinks are generated (unless overridden by configuration).
+The `postinstall` script runs at install time. It uses the user's install working directory as the root (prefers `INIT_CWD`, then `npm_config_local_prefix`, and falls back to `process.cwd()`). If the shared skills directory does not exist, it is created, then the tool-specific symlinks are generated (unless overridden by configuration). By default it auto-detects the `claude`, `codex`, and `gemini` commands on your PATH.
+
+When installed globally, the postinstall step is skipped. Instead, run the CLI in the project you want to link.
 
 ## Configuration
 
@@ -17,6 +19,8 @@ Supported fields:
 
 - `target`: optional string. Overrides where skills are stored (default: `.skills`).
 - `links`: array of link definitions. Strings map to `target` by default.
+- `tools`: optional object mapping command names to link paths, used for auto-detection.
+- `linkRoot`: optional string. Controls where links are created (`cwd`, `home`, `~`, or a path).
 
 Example:
 
@@ -27,6 +31,26 @@ Example:
 }
 ```
 
+Example (auto-detect commands):
+
+```json
+{
+  "tools": {
+    "claude": ".claude/skills",
+    "codex": ".codex/skills",
+    "gemini": ".gemini/skills"
+  }
+}
+```
+
+Example (link into home directory):
+
+```json
+{
+  "linkRoot": "home"
+}
+```
+
 ## Cross-platform behavior
 
 - macOS / Linux uses `dir` symlinks
@@ -38,11 +62,32 @@ Example:
 npm install any-skills --save-dev
 ```
 
+## Global usage
+
+```sh
+npm install -g any-skills
+```
+
+Then, in the project directory where you want links created:
+
+```sh
+npx any-skills
+```
+
+If the project does not list `any-skills` as a dependency, the CLI defaults to linking into your home directory (for example `~/.claude/skills`). Use `linkRoot` in `.skillsrc` to override.
+
+You can also pass tool names to only create those links:
+
+```sh
+npx any-skills claude
+npx any-skills deepseek
+```
+
 ## Git ignore
 
 Add the tool-specific shared skill directories to your `.gitignore`:
 
 ```
-.claude.skills
-.codex.skills
+.claude/skills
+.codex/skills
 ```

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "any-skills",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Share skills between Claude, Codex, and similar tools via a shared .skills directory.",
   "type": "commonjs",
   "scripts": {
     "postinstall": "node scripts/postinstall.js"
+  },
+  "bin": {
+    "any-skills": "scripts/cli.js"
   }
 }

package/scripts/cli.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { linkSkills } = require('./link-skills');
+
+function readPackageJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (err) {
+    return null;
+  }
+}
+
+function hasAnySkillsDependency(pkg) {
+  const dependencyFields = [
+    'dependencies',
+    'devDependencies',
+    'optionalDependencies',
+    'peerDependencies',
+  ];
+  for (const field of dependencyFields) {
+    if (pkg && pkg[field] && pkg[field]['any-skills']) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function hasLocalInstall(startDir) {
+  let current = path.resolve(startDir);
+  while (true) {
+    const pkgPath = path.join(current, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      const pkg = readPackageJson(pkgPath);
+      if (hasAnySkillsDependency(pkg)) {
+        return true;
+      }
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return false;
+    }
+    current = parent;
+  }
+}
+
+const rootDir = process.cwd();
+const linkRoot = hasLocalInstall(rootDir) ? rootDir : os.homedir();
+const args = process.argv.slice(2).filter(Boolean);
+const explicitTools = args.length ? args : null;
+const exitCode = linkSkills(rootDir, { linkRoot, explicitTools });
+if (exitCode) {
+  process.exit(exitCode);
+}

package/scripts/link-skills.js

@@ -0,0 +1,384 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const targetName = '.skills';
+const configFileName = '.skillsrc';
+const defaultToolTargets = {
+  claude: '.claude/skills',
+  codex: '.codex/skills',
+  gemini: '.gemini/skills',
+};
+
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+function ensureTarget(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+    return true;
+  }
+
+  const stat = fs.lstatSync(dirPath);
+  if (stat.isSymbolicLink()) {
+    return true;
+  }
+
+  if (!stat.isDirectory()) {
+    console.error(`[any-skills] ${dirPath} exists and is not a directory.`);
+    return false;
+  }
+
+  return true;
+}
+
+function getSymlinkType() {
+  return process.platform === 'win32' ? 'junction' : 'dir';
+}
+
+function resolveSymlinkTarget(linkPath) {
+  const linkParent = path.dirname(linkPath);
+  const currentTarget = fs.readlinkSync(linkPath);
+  return path.resolve(linkParent, currentTarget);
+}
+
+function ensureSymlink(linkPath, targetPath) {
+  const linkParent = path.dirname(linkPath);
+  ensureDir(linkParent);
+
+  const resolvedLinkPath = path.resolve(linkPath);
+  const expectedTarget = path.resolve(targetPath);
+  if (resolvedLinkPath === expectedTarget) {
+    console.warn(`[any-skills] ${linkPath} resolves to the target; skipping.`);
+    return false;
+  }
+
+  try {
+    const stat = fs.lstatSync(linkPath);
+    if (stat.isSymbolicLink()) {
+      const resolvedTarget = resolveSymlinkTarget(linkPath);
+      if (resolvedTarget === expectedTarget) {
+        return true;
+      }
+      fs.unlinkSync(linkPath);
+    } else {
+      console.warn(
+        `[any-skills] ${linkPath} exists and is not a symlink; skipping.`
+      );
+      return false;
+    }
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      throw err;
+    }
+  }
+
+  const relativeTarget = path.relative(linkParent, targetPath) || '.';
+  fs.symlinkSync(relativeTarget, linkPath, getSymlinkType());
+  return true;
+}
+
+function readSkillsConfig(configRoot) {
+  const configPath = path.join(configRoot, configFileName);
+  let rawConfig = null;
+
+  try {
+    rawConfig = fs.readFileSync(configPath, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      return { config: null, configPath, exists: false, error: null };
+    }
+    throw err;
+  }
+
+  let parsed = null;
+  try {
+    parsed = JSON.parse(rawConfig);
+  } catch (err) {
+    return { config: null, configPath, exists: true, error: err };
+  }
+
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return {
+      config: null,
+      configPath,
+      exists: true,
+      error: new Error('Config must be a JSON object.'),
+    };
+  }
+
+  return { config: parsed, configPath, exists: true, error: null };
+}
+
+function resolveRootPath(value, baseDir) {
+  return path.isAbsolute(value) ? value : path.join(baseDir, value);
+}
+
+function resolveLinkRoot(config, rootDir, defaultLinkRoot) {
+  if (
+    config &&
+    typeof config.linkRoot === 'string' &&
+    config.linkRoot.trim() !== ''
+  ) {
+    const raw = config.linkRoot.trim();
+    if (raw === 'home') {
+      return os.homedir();
+    }
+    if (raw === 'cwd') {
+      return rootDir;
+    }
+    if (raw === '~' || raw.startsWith('~/')) {
+      const suffix = raw.length > 2 ? raw.slice(2) : '';
+      return path.join(os.homedir(), suffix);
+    }
+    return resolveRootPath(raw, rootDir);
+  }
+
+  return defaultLinkRoot || rootDir;
+}
+
+function resolveTarget(config, rootDir) {
+  if (
+    config &&
+    typeof config.target === 'string' &&
+    config.target.trim() !== ''
+  ) {
+    return resolveRootPath(config.target, rootDir);
+  }
+
+  return path.join(rootDir, targetName);
+}
+
+function normalizeLinkEntry(entry, target, configPath, rootDir) {
+  if (typeof entry === 'string') {
+    return { link: entry, error: false };
+  }
+
+  if (entry && typeof entry === 'object') {
+    const link = entry.link;
+    if (typeof link !== 'string' || link.trim() === '') {
+      console.warn(
+        `[any-skills] Invalid link entry in ${configPath}; skipping.`
+      );
+      return null;
+    }
+
+    if (Object.prototype.hasOwnProperty.call(entry, 'target')) {
+      const targetValue = entry.target;
+      if (typeof targetValue !== 'string' || targetValue.trim() === '') {
+        console.error(
+          `[any-skills] Invalid target for ${link} in ${configPath}.`
+        );
+        return { error: true };
+      }
+
+      const resolvedTarget = resolveRootPath(targetValue, rootDir);
+      if (resolvedTarget !== target) {
+        console.error(
+          `[any-skills] Link entry in ${configPath} must not set a different target.`
+        );
+        return { error: true };
+      }
+
+      console.warn(
+        `[any-skills] Ignoring redundant target for ${link} in ${configPath}.`
+      );
+    }
+
+    return { link, error: false };
+  }
+
+  console.warn(
+    `[any-skills] Unsupported link entry in ${configPath}; skipping.`
+  );
+  return null;
+}
+
+function getConfigEntries(config) {
+  if (!config) {
+    return null;
+  }
+
+  if (Array.isArray(config.links)) {
+    return config.links;
+  }
+
+  if (Array.isArray(config.linkTargets)) {
+    return config.linkTargets;
+  }
+
+  return null;
+}
+
+function commandExists(command) {
+  const pathEnv = process.env.PATH || '';
+  const pathEntries = pathEnv.split(path.delimiter).filter(Boolean);
+  const isWindows = process.platform === 'win32';
+  const extensions = isWindows
+    ? (process.env.PATHEXT || '.EXE;.CMD;.BAT;.COM')
+        .split(';')
+        .filter(Boolean)
+    : [''];
+
+  for (const entry of pathEntries) {
+    for (const ext of extensions) {
+      const candidate = path.join(entry, `${command}${ext}`);
+      try {
+        fs.accessSync(candidate, fs.constants.X_OK);
+        return true;
+      } catch (err) {
+        if (err.code !== 'ENOENT') {
+          continue;
+        }
+      }
+    }
+  }
+
+  return false;
+}
+
+function detectLinkTargets(config) {
+  const toolTargets =
+    config && config.tools && typeof config.tools === 'object'
+      ? config.tools
+      : defaultToolTargets;
+
+  const targets = [];
+  for (const [command, linkTarget] of Object.entries(toolTargets)) {
+    if (typeof linkTarget !== 'string' || linkTarget.trim() === '') {
+      continue;
+    }
+    if (commandExists(command)) {
+      targets.push(linkTarget);
+    }
+  }
+
+  return targets;
+}
+
+function resolveExplicitTargets(config, toolNames) {
+  const toolTargets =
+    config && config.tools && typeof config.tools === 'object'
+      ? config.tools
+      : defaultToolTargets;
+
+  const targets = [];
+  for (const name of toolNames) {
+    const mappedTarget = toolTargets[name];
+    if (typeof mappedTarget === 'string' && mappedTarget.trim() !== '') {
+      targets.push(mappedTarget);
+      continue;
+    }
+    const safeName = name.trim();
+    if (safeName) {
+      targets.push(`.${safeName}/skills`);
+    }
+  }
+
+  return targets;
+}
+
+function buildLinkMappings({
+  config,
+  configPath,
+  exists,
+  target,
+  rootDir,
+  linkRoot,
+  explicitTools,
+}) {
+  const resolvedLinkRoot = resolveLinkRoot(config, rootDir, linkRoot);
+  const explicitTargets = Array.isArray(explicitTools)
+    ? resolveExplicitTargets(config, explicitTools)
+    : null;
+  const entries = getConfigEntries(config);
+  if (!entries) {
+    if (explicitTargets) {
+      return {
+        mappings: explicitTargets.map((linkTarget) => ({
+          linkPath: resolveRootPath(linkTarget, resolvedLinkRoot),
+          targetPath: target,
+        })),
+        error: false,
+      };
+    }
+
+    if (exists) {
+      console.warn(
+        `[any-skills] No link configuration found in ${configPath}; using auto-detected tools.`
+      );
+    }
+    const detectedTargets = detectLinkTargets(config);
+    return {
+      mappings: detectedTargets.map((linkTarget) => ({
+        linkPath: resolveRootPath(linkTarget, resolvedLinkRoot),
+        targetPath: target,
+      })),
+      error: false,
+    };
+  }
+
+  if (entries.length === 0) {
+    return { mappings: [], error: false };
+  }
+
+  const mappings = [];
+  for (const entry of entries) {
+    const normalized = normalizeLinkEntry(entry, target, configPath, rootDir);
+    if (!normalized) {
+      continue;
+    }
+    if (normalized.error) {
+      return { mappings: [], error: true };
+    }
+    mappings.push({
+      linkPath: resolveRootPath(normalized.link, resolvedLinkRoot),
+      targetPath: target,
+    });
+  }
+
+  return { mappings, error: false };
+}
+
+function linkSkills(rootDir, options = {}) {
+  const { config, configPath, exists, error } = readSkillsConfig(rootDir);
+  if (error) {
+    console.error(
+      `[any-skills] Failed to parse ${configPath}: ${error.message}`
+    );
+    return 1;
+  }
+
+  const target = resolveTarget(config, rootDir);
+  if (!ensureTarget(target)) {
+    return 1;
+  }
+
+  const { mappings, error: mappingError } = buildLinkMappings({
+    config,
+    configPath,
+    exists,
+    target,
+    rootDir,
+    linkRoot: options.linkRoot,
+    explicitTools: options.explicitTools,
+  });
+  if (mappingError) {
+    return 1;
+  }
+
+  for (const mapping of mappings) {
+    ensureSymlink(mapping.linkPath, mapping.targetPath);
+  }
+
+  return 0;
+}
+
+module.exports = {
+  linkSkills,
+};

package/scripts/postinstall.js

@@ -1,7 +1,7 @@
 'use strict';
 
-const fs = require('fs');
 const path = require('path');
+const { linkSkills } = require('./link-skills');
 
 function getInstallRoot() {
   const initCwd = process.env.INIT_CWD;
@@ -17,262 +17,17 @@ function getInstallRoot() {
   return process.cwd();
 }
 
-const rootDir = getInstallRoot();
-const targetName = '.skills';
-const configFileName = '.skillsrc';
-const defaultLinkTargets = ['.claude/skills', '.codex/skills'];
-
-function ensureDir(dirPath) {
-  if (!fs.existsSync(dirPath)) {
-    fs.mkdirSync(dirPath, { recursive: true });
-  }
-}
-
-function ensureTarget(dirPath) {
-  if (!fs.existsSync(dirPath)) {
-    fs.mkdirSync(dirPath, { recursive: true });
-    return true;
-  }
-
-  const stat = fs.lstatSync(dirPath);
-  if (stat.isSymbolicLink()) {
-    return true;
-  }
-
-  if (!stat.isDirectory()) {
-    console.error(`[any-skills] ${dirPath} exists and is not a directory.`);
-    return false;
-  }
+const isGlobalInstall =
+  process.env.npm_config_global === 'true' ||
+  process.env.npm_config_global === '1';
 
-  return true;
+if (isGlobalInstall) {
+  console.log('[any-skills] Global install detected; skipping postinstall.');
+  process.exit(0);
 }
 
-function getSymlinkType() {
-  return process.platform === 'win32' ? 'junction' : 'dir';
-}
-
-function resolveSymlinkTarget(linkPath) {
-  const linkParent = path.dirname(linkPath);
-  const currentTarget = fs.readlinkSync(linkPath);
-  return path.resolve(linkParent, currentTarget);
-}
-
-function ensureSymlink(linkPath, targetPath) {
-  const linkParent = path.dirname(linkPath);
-  ensureDir(linkParent);
-
-  const resolvedLinkPath = path.resolve(linkPath);
-  const expectedTarget = path.resolve(targetPath);
-  if (resolvedLinkPath === expectedTarget) {
-    console.warn(`[any-skills] ${linkPath} resolves to the target; skipping.`);
-    return false;
-  }
-
-  try {
-    const stat = fs.lstatSync(linkPath);
-    if (stat.isSymbolicLink()) {
-      const resolvedTarget = resolveSymlinkTarget(linkPath);
-      if (resolvedTarget === expectedTarget) {
-        return true;
-      }
-      fs.unlinkSync(linkPath);
-    } else {
-      console.warn(
-        `[any-skills] ${linkPath} exists and is not a symlink; skipping.`
-      );
-      return false;
-    }
-  } catch (err) {
-    if (err.code !== 'ENOENT') {
-      throw err;
-    }
-  }
-
-  const relativeTarget = path.relative(linkParent, targetPath) || '.';
-  fs.symlinkSync(relativeTarget, linkPath, getSymlinkType());
-  return true;
-}
-
-function readSkillsConfig(configRoot) {
-  const configPath = path.join(configRoot, configFileName);
-  let rawConfig = null;
-
-  try {
-    rawConfig = fs.readFileSync(configPath, 'utf8');
-  } catch (err) {
-    if (err.code === 'ENOENT') {
-      return { config: null, configPath, exists: false, error: null };
-    }
-    throw err;
-  }
-
-  let parsed = null;
-  try {
-    parsed = JSON.parse(rawConfig);
-  } catch (err) {
-    return { config: null, configPath, exists: true, error: err };
-  }
-
-  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-    return {
-      config: null,
-      configPath,
-      exists: true,
-      error: new Error('Config must be a JSON object.'),
-    };
-  }
-
-  return { config: parsed, configPath, exists: true, error: null };
-}
-
-function resolveRootPath(value, baseDir) {
-  return path.isAbsolute(value) ? value : path.join(baseDir, value);
-}
-
-function resolveTarget(config) {
-  if (
-    config &&
-    typeof config.target === 'string' &&
-    config.target.trim() !== ''
-  ) {
-    return resolveRootPath(config.target, rootDir);
-  }
-
-  return path.join(rootDir, targetName);
-}
-
-function normalizeLinkEntry(entry, target, configPath) {
-  if (typeof entry === 'string') {
-    return { link: entry, error: false };
-  }
-
-  if (entry && typeof entry === 'object') {
-    const link = entry.link;
-    if (typeof link !== 'string' || link.trim() === '') {
-      console.warn(
-        `[any-skills] Invalid link entry in ${configPath}; skipping.`
-      );
-      return null;
-    }
-
-    if (Object.prototype.hasOwnProperty.call(entry, 'target')) {
-      const targetValue = entry.target;
-      if (typeof targetValue !== 'string' || targetValue.trim() === '') {
-        console.error(
-          `[any-skills] Invalid target for ${link} in ${configPath}.`
-        );
-        return { error: true };
-      }
-
-      const resolvedTarget = resolveRootPath(targetValue, rootDir);
-      if (resolvedTarget !== target) {
-        console.error(
-          `[any-skills] Link entry in ${configPath} must not set a different target.`
-        );
-        return { error: true };
-      }
-
-      console.warn(
-        `[any-skills] Ignoring redundant target for ${link} in ${configPath}.`
-      );
-    }
-
-    return { link, error: false };
-  }
-
-  console.warn(
-    `[any-skills] Unsupported link entry in ${configPath}; skipping.`
-  );
-  return null;
-}
-
-function getConfigEntries(config) {
-  if (!config) {
-    return null;
-  }
-
-  if (Array.isArray(config.links)) {
-    return config.links;
-  }
-
-  if (Array.isArray(config.linkTargets)) {
-    return config.linkTargets;
-  }
-
-  return null;
-}
-
-function buildLinkMappings({ config, configPath, exists, target }) {
-  const entries = getConfigEntries(config);
-  if (!entries) {
-    if (exists) {
-      console.warn(
-        `[any-skills] No link configuration found in ${configPath}; using defaults.`
-      );
-    }
-    return {
-      mappings: defaultLinkTargets.map((linkTarget) => ({
-        linkPath: resolveRootPath(linkTarget, rootDir),
-        targetPath: target,
-      })),
-      error: false,
-    };
-  }
-
-  if (entries.length === 0) {
-    return { mappings: [], error: false };
-  }
-
-  const mappings = [];
-  for (const entry of entries) {
-    const normalized = normalizeLinkEntry(entry, target, configPath);
-    if (!normalized) {
-      continue;
-    }
-    if (normalized.error) {
-      return { mappings: [], error: true };
-    }
-    mappings.push({
-      linkPath: resolveRootPath(normalized.link, rootDir),
-      targetPath: target,
-    });
-  }
-
-  return { mappings, error: false };
-}
-
-function linkSkills() {
-  const { config, configPath, exists, error } = readSkillsConfig(rootDir);
-  if (error) {
-    console.error(
-      `[any-skills] Failed to parse ${configPath}: ${error.message}`
-    );
-    return 1;
-  }
-
-  const target = resolveTarget(config);
-  if (!ensureTarget(target)) {
-    return 1;
-  }
-
-  const { mappings, error: mappingError } = buildLinkMappings({
-    config,
-    configPath,
-    exists,
-    target,
-  });
-  if (mappingError) {
-    return 1;
-  }
-
-  for (const mapping of mappings) {
-    ensureSymlink(mapping.linkPath, mapping.targetPath);
-  }
-
-  return 0;
-}
-
-const exitCode = linkSkills();
+const rootDir = getInstallRoot();
+const exitCode = linkSkills(rootDir);
 if (exitCode) {
   process.exit(exitCode);
 }