skls-mgr 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xavi <https://github.com/Xaviw>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,151 @@
+# skls-mgr
+
+[简体中文](./README-CN.md)
+
+Maintain Agent Skills in a centralized local directory; Install on-demand across projects; Edit once, sync everywhere.
+
+## Why not [vercel-labs/skills](https://github.com/vercel-labs/skills)?
+
+This project is inspired by [`vercel-labs/skills`](<https://www.google.com/search?q=%5Bhttps://github.com/vercel-labs/skills%5D(https://github.com/vercel-labs/skills)>). We are grateful to the Vercel Labs team for their contribution to the Agent ecosystem.
+
+`vercel-labs/skills` only supports installing skills directly to a project or globally, which often leads to skill files being scattered across multiple locations. Furthermore, when you need to install skills into different projects, you frequently have to look up the original installation commands.
+
+## Quick Start
+
+Find your target skills on [skills.sh](https://skills.sh/), and simply replace `skills` with `skls-mgr` in the installation command:
+
+```bash
+npx skls-mgr add https://github.com/vercel-labs/skills --skill find-skills
+
+```
+
+Once installed, the skills will be copied to the `~/.config/skls-mgr` directory. You can then run the following in any project:
+
+```bash
+npx skls-mgr install
+
+```
+
+Select the skills required for your project through the interactive interface. The installation is complete once confirmed.
+
+## Adding Skills
+
+```bash
+npx skls-mgr add <source>
+
+```
+
+By default, this opens an interactive interface listing all available skills from the source.
+
+### Options
+
+| Option                   | Description                                                    |
+| ------------------------ | -------------------------------------------------------------- |
+| `-s, --skill <names...>` | Specify skill names directly to skip the interactive selection |
+
+### Examples
+
+```bash
+# GitHub shorthand (owner/repo)
+npx skls-mgr add vercel-labs/skills
+
+# GitHub repository URL
+npx skls-mgr add https://github.com/vercel-labs/skills
+
+# Sub-path within a GitHub repository
+npx skls-mgr add https://github.com/vercel-labs/skills/tree/main/skills/find-skills
+
+# Any Git URL
+npx skls-mgr add https://github.com/vercel-labs/skills.git
+npx skls-mgr add git@github.com:vercel-labs/skills.git
+
+# Local path (copy)
+npx skls-mgr add ./my-local-skills
+
+# Install specific skills (repeated flags)
+npx skls-mgr add vercel-labs/agent-skills --skill frontend-design --skill skill-creator
+
+# Install specific skills (multiple names after a single flag)
+npx skls-mgr add vercel-labs/agent-skills --skill frontend-design skill-creator
+
+```
+
+### Conflict Resolution
+
+If the directory name of the skill being installed conflicts with an existing top-level directory in `~/.config/skls-mgr`:
+
+- **Interactive Mode**: You will be prompted to enter a new directory name.
+- **Non-interactive Mode**: If `--skill` is used, the command will terminate immediately without automatic renaming.
+
+## Installing to Projects
+
+```bash
+npx skls-mgr install
+
+```
+
+By default, this opens an interactive interface listing all top-level directories in `~/.config/skls-mgr` (including manually created skills).
+
+### Options
+
+| Option             | Description                                                                                         |
+| ------------------ | --------------------------------------------------------------------------------------------------- |
+| `-a, --all`        | Install all skills. If not specified, allows interactive selection.                                 |
+| `-d, --dir <path>` | Install to the target directory (absolute or relative). If not specified, allows interactive input. |
+| `-l, --link`       | Use symbolic links.                                                                                 |
+| `-c, --copy`       | Use direct copy.                                                                                    |
+
+### Examples
+
+```bash
+# Interactive installation to a project
+npx skls-mgr install
+
+# Copy all skills to the Claude Code skills directory
+npx skls-mgr install --all --dir ./.claude/skills --copy
+
+# Interactively select skills and link them to the .agents/skills directory
+# Flags can be combined; missing arguments will be prompted interactively
+npx skls-mgr install --dir ./.agents/skills --link
+
+```
+
+### Overwrite Policy
+
+If a skill directory with the same name already exists in the target project, `skls-mgr install` will overwrite it directly without further confirmation.
+
+When `--link` is selected, if the current environment does not support creating symbolic links, it will automatically fall back to a direct copy.
+
+## Other Commands
+
+| Command                      | Description                                                                            |
+| ---------------------------- | -------------------------------------------------------------------------------------- |
+| `npx skls-mgr list`              | List all skills in `~/.config/skls-mgr`, distinguishing between managed and manual skills. |
+| `npx skls-mgr update [names...]` | Update one or more skills. Opens interactive mode if no names are provided.            |
+| `npx skls-mgr remove [names...]` | Remove one or more skills. Opens interactive mode if no names are provided.            |
+
+### Examples
+
+```bash
+# Display all skills (including manually added ones)
+npx skls-mgr list
+
+# Interactive update
+npx skls-mgr update
+
+# Force update specific skills by name
+npx skls-mgr update skill1 skill2
+
+# Interactive removal
+npx skls-mgr remove
+
+# Remove specific skills by name
+npx skls-mgr remove skill1 skill2
+
+```
+
+> `skls-mgr update` relies on the GitHub API. To avoid rate limits for anonymous requests (60 per hour), it is recommended to configure `GITHUB_TOKEN` or `GH_TOKEN` in your environment variables to increase the quota (5000 per hour).
+
+## License
+
+MIT

package/bin/cli.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import('../dist/cli.js');

package/dist/add.js

@@ -0,0 +1,146 @@
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { relative } from 'path';
+import { hasBaseSkillDirectory, installSkillToBaseDir } from './base-dir.js';
+import { sanitizeName } from './filesystem.js';
+import { cloneRepo, cleanupTempDir } from './git.js';
+import { t } from './i18n.js';
+import { ensureBaseDir, getBaseDir } from './paths.js';
+import { getOwnerRepo, parseSource } from './source-parser.js';
+import { fetchSkillFolderHash, getGitHubToken } from './skill-lock.js';
+import { discoverSkills, filterSkills } from './skills.js';
+async function promptForDirectoryName(defaultName) {
+    return p.text({
+        message: t('directoryExistsPrompt', { defaultName }),
+        defaultValue: `${defaultName}-copy`,
+        validate(value) {
+            if (!value.trim()) {
+                return t('directoryNameRequired');
+            }
+        },
+    });
+}
+export async function resolveDirectoryName(skill, options, promptImpl = promptForDirectoryName, reservedDirectoryNames = new Set()) {
+    const defaultName = sanitizeName(skill.name);
+    const hasConflict = async (directoryName) => {
+        return reservedDirectoryNames.has(directoryName) || (await hasBaseSkillDirectory(directoryName));
+    };
+    if (!(await hasConflict(defaultName))) {
+        reservedDirectoryNames.add(defaultName);
+        return defaultName;
+    }
+    if (options.skill?.length) {
+        throw new Error(t('skillDirectoryConflict', { directoryName: defaultName }));
+    }
+    const renamed = await promptImpl(defaultName);
+    if (p.isCancel(renamed)) {
+        throw new Error(t('installationCancelled'));
+    }
+    const nextName = sanitizeName(renamed);
+    if (await hasConflict(nextName)) {
+        throw new Error(t('skillDirectoryConflict', { directoryName: nextName }));
+    }
+    reservedDirectoryNames.add(nextName);
+    return nextName;
+}
+export function parseAddOptions(args) {
+    const options = {};
+    let source;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === '-s' || arg === '--skill') {
+            options.skill = options.skill || [];
+            index += 1;
+            while (index < args.length && args[index] && !args[index].startsWith('-')) {
+                options.skill.push(args[index]);
+                index += 1;
+            }
+            index -= 1;
+            continue;
+        }
+        if (!arg?.startsWith('-') && !source) {
+            source = arg;
+        }
+    }
+    return { source, options };
+}
+export async function runAdd(sourceInput, options = {}) {
+    if (!sourceInput) {
+        p.log.error(t('missingSource'));
+        process.exit(1);
+    }
+    await ensureBaseDir();
+    const parsed = parseSource(sourceInput);
+    let tempDir = null;
+    try {
+        const sourceDir = parsed.type === 'local'
+            ? parsed.localPath
+            : ((tempDir = await cloneRepo(parsed.url, parsed.ref)), tempDir);
+        const discoveredSkills = await discoverSkills(sourceDir, parsed.subpath);
+        if (discoveredSkills.length === 0) {
+            p.log.error(t('noSkillsFoundInSource'));
+            process.exit(1);
+        }
+        let selectedSkills = discoveredSkills;
+        if (options.skill?.length) {
+            selectedSkills = filterSkills(discoveredSkills, options.skill);
+            if (selectedSkills.length === 0) {
+                p.log.error(t('noMatchingSkillsFound', { names: options.skill.join(', ') }));
+                process.exit(1);
+            }
+        }
+        else {
+            const picked = await p.multiselect({
+                message: `${t('selectSkillsToInstall')} ${pc.dim(t('multiselectPromptHelp'))}`,
+                options: discoveredSkills.map((skill) => ({
+                    value: skill.name,
+                    label: skill.name,
+                    hint: skill.description,
+                })),
+                initialValues: discoveredSkills.map((skill) => skill.name),
+                required: true,
+            });
+            if (p.isCancel(picked)) {
+                p.cancel(t('installationCancelled'));
+                process.exit(0);
+            }
+            selectedSkills = discoveredSkills.filter((skill) => picked.includes(skill.name));
+        }
+        const reservedDirectoryNames = new Set();
+        const resolvedInstalls = [];
+        for (const skill of selectedSkills) {
+            resolvedInstalls.push({
+                skill,
+                directoryName: await resolveDirectoryName(skill, options, promptForDirectoryName, reservedDirectoryNames),
+            });
+        }
+        const trackableSource = getOwnerRepo(parsed);
+        const normalizedSource = trackableSource ?? parsed.url;
+        const token = getGitHubToken();
+        for (const item of resolvedInstalls) {
+            const skillPath = relative(sourceDir, item.skill.path).split('\\').join('/');
+            const skillMdRelativePath = skillPath ? `${skillPath}/SKILL.md` : 'SKILL.md';
+            const skillFolderHash = trackableSource
+                ? ((await fetchSkillFolderHash(trackableSource, skillMdRelativePath, token)) ?? '')
+                : '';
+            await installSkillToBaseDir(item.skill.path, item.directoryName, {
+                displayName: item.skill.name,
+                source: normalizedSource,
+                sourceType: parsed.type,
+                sourceUrl: parsed.url,
+                skillPath: skillMdRelativePath,
+                skillFolderHash,
+            });
+        }
+        p.log.success(t('installedSkillsIntoBaseDir', { count: resolvedInstalls.length, baseDir: getBaseDir() }));
+    }
+    catch (error) {
+        p.log.error(error instanceof Error ? error.message : t('unknownError'));
+        process.exit(1);
+    }
+    finally {
+        if (tempDir) {
+            await cleanupTempDir(tempDir).catch(() => { });
+        }
+    }
+}

package/dist/base-dir.js

@@ -0,0 +1,60 @@
+import { readdir } from 'fs/promises';
+import { join } from 'path';
+import { ensureBaseDir, getBaseDir } from './paths.js';
+import { createDirectorySymlink, removeIfExists, sanitizeName } from './filesystem.js';
+import { addSkillToLock, readSkillLock, removeSkillFromLock } from './skill-lock.js';
+export async function listBaseSkills() {
+    const baseDir = await ensureBaseDir();
+    const lock = await readSkillLock();
+    try {
+        const entries = await readdir(baseDir, { encoding: 'utf8', withFileTypes: true });
+        return entries
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => ({
+            directoryName: entry.name,
+            managed: Boolean(lock.skills[entry.name]),
+            lockEntry: lock.skills[entry.name],
+            path: join(baseDir, entry.name),
+        }))
+            .sort((a, b) => a.directoryName.localeCompare(b.directoryName));
+    }
+    catch {
+        return [];
+    }
+}
+export async function hasBaseSkillDirectory(directoryName) {
+    const skills = await listBaseSkills();
+    return skills.some((skill) => skill.directoryName === sanitizeName(directoryName));
+}
+export async function installSkillToBaseDir(sourceDir, directoryName, lockEntry) {
+    const baseDir = await ensureBaseDir();
+    const sanitizedDirectoryName = sanitizeName(directoryName);
+    const targetDir = join(baseDir, sanitizedDirectoryName);
+    const { replaceDirectoryWithCopy } = await import('./filesystem.js');
+    await replaceDirectoryWithCopy(sourceDir, targetDir);
+    if (lockEntry) {
+        await addSkillToLock(sanitizedDirectoryName, lockEntry);
+    }
+    return targetDir;
+}
+export async function installBaseSkillToProject(directoryName, targetRootDir, mode) {
+    const sourceDir = join(getBaseDir(), directoryName);
+    const targetDir = join(targetRootDir, directoryName);
+    if (mode === 'copy') {
+        const { replaceDirectoryWithCopy } = await import('./filesystem.js');
+        await replaceDirectoryWithCopy(sourceDir, targetDir);
+        return { path: targetDir, linked: false };
+    }
+    await removeIfExists(targetDir);
+    const linked = await createDirectorySymlink(sourceDir, targetDir);
+    if (!linked) {
+        const { replaceDirectoryWithCopy } = await import('./filesystem.js');
+        await replaceDirectoryWithCopy(sourceDir, targetDir);
+    }
+    return { path: targetDir, linked };
+}
+export async function removeBaseSkill(directoryName) {
+    const skillPath = join(getBaseDir(), directoryName);
+    await removeIfExists(skillPath);
+    await removeSkillFromLock(directoryName);
+}

package/dist/cli.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { parseAddOptions, runAdd } from './add.js';
+import { t } from './i18n.js';
+import { parseInstallOptions, runInstall } from './install.js';
+import { runList } from './list.js';
+import { runRemove } from './remove.js';
+import { runUpdate } from './update.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+function getVersion() {
+    const pkgPath = join(__dirname, '..', 'package.json');
+    return JSON.parse(readFileSync(pkgPath, 'utf-8')).version;
+}
+function showHelp() {
+    console.log(t('helpText'));
+}
+async function main() {
+    const args = process.argv.slice(2);
+    const command = args[0];
+    const rest = args.slice(1);
+    if (!command) {
+        showHelp();
+        return;
+    }
+    switch (command) {
+        case 'add': {
+            const { source, options } = parseAddOptions(rest);
+            await runAdd(source, options);
+            return;
+        }
+        case 'list':
+            await runList();
+            return;
+        case 'install':
+            await runInstall(parseInstallOptions(rest));
+            return;
+        case 'remove':
+            await runRemove(rest);
+            return;
+        case 'update':
+            await runUpdate({ skillNames: rest });
+            return;
+        case '--help':
+        case '-h':
+            showHelp();
+            return;
+        case '--version':
+        case '-v':
+            console.log(getVersion());
+            return;
+        default:
+            console.log(t('unknownCommand', { command: command ?? '' }));
+            console.log(t('runHelpForUsage'));
+            process.exit(1);
+    }
+}
+main();

package/dist/constants.js

@@ -0,0 +1,2 @@
+export const LOCK_FILE_NAME = '.skls-mgr-lock.json';
+export const CURRENT_LOCK_VERSION = 1;

package/dist/filesystem.js

@@ -0,0 +1,109 @@
+import { cp, lstat, mkdir, readlink, readdir, rm } from 'fs/promises';
+import { join, relative, resolve, dirname } from 'path';
+async function pathExists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function replaceDirectoryWithCopy(sourceDir, targetDir) {
+    const parentDir = dirname(targetDir);
+    const targetName = targetDir.split(/[\\/]/).pop() ?? 'skill';
+    const uniqueSuffix = `${Date.now()}-${Math.random().toString(16).slice(2)}`;
+    const tempDir = join(parentDir, `${targetName}.tmp-${uniqueSuffix}`);
+    const backupDir = join(parentDir, `${targetName}.bak-${uniqueSuffix}`);
+    let hasBackup = false;
+    await mkdir(parentDir, { recursive: true });
+    try {
+        await copyDirectory(sourceDir, tempDir);
+        if (await pathExists(targetDir)) {
+            await import('fs/promises').then((fs) => fs.rename(targetDir, backupDir));
+            hasBackup = true;
+        }
+        await import('fs/promises').then((fs) => fs.rename(tempDir, targetDir));
+        if (hasBackup) {
+            await rm(backupDir, { recursive: true, force: true }).catch(() => { });
+        }
+    }
+    catch (error) {
+        await rm(tempDir, { recursive: true, force: true }).catch(() => { });
+        if (hasBackup) {
+            if (!(await pathExists(targetDir))) {
+                await import('fs/promises').then((fs) => fs.rename(backupDir, targetDir)).catch(() => { });
+            }
+            else {
+                await rm(backupDir, { recursive: true, force: true }).catch(() => { });
+            }
+        }
+        throw error;
+    }
+}
+export function sanitizeName(name) {
+    const sanitized = name
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, '-')
+        .replace(/^[.-]+|[.-]+$/g, '');
+    return sanitized || 'unnamed-skill';
+}
+export async function removeIfExists(path) {
+    await rm(path, { recursive: true, force: true }).catch(() => { });
+}
+export async function ensureDir(path) {
+    await mkdir(path, { recursive: true });
+}
+const EXCLUDE_FILES = new Set(['metadata.json']);
+const EXCLUDE_DIRS = new Set(['.git', '__pycache__', 'node_modules']);
+export async function copyDirectory(sourceDir, targetDir) {
+    await mkdir(targetDir, { recursive: true });
+    const entries = await readdir(sourceDir, { withFileTypes: true });
+    await Promise.all(entries
+        .filter((entry) => {
+        if (entry.isDirectory()) {
+            return !EXCLUDE_DIRS.has(entry.name);
+        }
+        return !EXCLUDE_FILES.has(entry.name) && !entry.name.startsWith('.');
+    })
+        .map(async (entry) => {
+        const sourcePath = join(sourceDir, entry.name);
+        const targetPath = join(targetDir, entry.name);
+        if (entry.isDirectory()) {
+            await copyDirectory(sourcePath, targetPath);
+            return;
+        }
+        await cp(sourcePath, targetPath, {
+            recursive: true,
+            dereference: true,
+        });
+    }));
+}
+export async function createDirectorySymlink(targetDir, linkPath) {
+    try {
+        const resolvedTarget = resolve(targetDir);
+        const resolvedLinkPath = resolve(linkPath);
+        try {
+            const existing = await lstat(linkPath);
+            if (existing.isSymbolicLink()) {
+                const currentTarget = await readlink(linkPath);
+                const absoluteTarget = resolve(dirname(linkPath), currentTarget);
+                if (absoluteTarget === resolvedTarget) {
+                    return true;
+                }
+            }
+            await rm(linkPath, { recursive: true, force: true });
+        }
+        catch {
+            // ignore
+        }
+        await mkdir(dirname(linkPath), { recursive: true });
+        const relativeTarget = relative(dirname(linkPath), resolvedTarget);
+        const symlinkType = process.platform === 'win32' ? 'junction' : 'dir';
+        await import('fs/promises').then((fs) => fs.symlink(relativeTarget, linkPath, symlinkType));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/git.js

@@ -0,0 +1,38 @@
+import { mkdtemp, rm } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join, normalize, resolve, sep } from 'path';
+import { simpleGit } from 'simple-git';
+import { t } from './i18n.js';
+const CLONE_TIMEOUT_MS = 60_000;
+export class GitCloneError extends Error {
+    url;
+    constructor(message, url) {
+        super(message);
+        this.name = 'GitCloneError';
+        this.url = url;
+    }
+}
+export async function cloneRepo(url, ref) {
+    const tempDir = await mkdtemp(join(tmpdir(), 'skls-mgr-'));
+    const git = simpleGit({
+        timeout: { block: CLONE_TIMEOUT_MS },
+    });
+    const cloneOptions = ref ? ['--depth', '1', '--branch', ref] : ['--depth', '1'];
+    try {
+        await git.clone(url, tempDir, cloneOptions);
+        return tempDir;
+    }
+    catch (error) {
+        await rm(tempDir, { recursive: true, force: true }).catch(() => { });
+        const message = error instanceof Error ? error.message : String(error);
+        throw new GitCloneError(t('failedToClone', { url, message }), url);
+    }
+}
+export async function cleanupTempDir(dir) {
+    const normalizedDir = normalize(resolve(dir));
+    const normalizedTmpDir = normalize(resolve(tmpdir()));
+    if (!normalizedDir.startsWith(normalizedTmpDir + sep) && normalizedDir !== normalizedTmpDir) {
+        throw new Error(t('attemptedTempDirCleanupOutsideTemp'));
+    }
+    await rm(dir, { recursive: true, force: true });
+}