@nnnggel/skills-management 1.0.1 → 1.0.2

package/README.md

@@ -2,7 +2,7 @@
 
 [简体中文](./README.zh-CN.md) | English
 
-`skm` is a powerful CLI tool designed to manage and synchronize "skills" (prompt libraries, instruction sets, or capability modules) across various AI coding agents and projects. It serves as a central hub to download skills from GitHub and selectively link them into your local AI project configurations.
+`skm` is a powerful CLI tool designed to manage and synchronize "skills" (prompt libraries, instruction sets, or capability modules) across various AI coding agents and projects. It serves as a central hub to add skills from GitHub or local directories and selectively link them into your local AI project configurations.
 
 It supports multiple AI environments including **OpenCode**, **Cursor**, **Gemini**, **Antigravity**, **Claude**, and **GitHub** projects.
 
@@ -12,11 +12,14 @@ It supports multiple AI environments including **OpenCode**, **Cursor**, **Gemin
 
 - **Global Skill Repository**: Centralized management of your AI skills.
 - **GitHub Integration**: Add skills directly from GitHub repositories or specific subdirectories (sparse checkout).
+- **Local Skill Support**: Add skills from local directories for development and debugging.
 - **Version Control**: Check for updates and synchronize changes from remote repositories.
 - **Project Detection**: Automatically detects the AI project type in your current directory.
 - **Symbolic Linking**: Efficiently links skills to projects without duplication, keeping them in sync.
 - **Project Isolation**: Manage different sets of skills for different projects.
 
+![Screenshot](repo.png)
+
 ## 💡 Why skm?
 
 - **Centralized Efficiency**: Skills are cloned only once (`~/.skills-management/repo`) and shared across infinite projects via symbolic links. This saves significant disk space and ensures all your projects use the same curated version of a skill.
@@ -24,7 +27,7 @@ It supports multiple AI environments including **OpenCode**, **Cursor**, **Gemin
 - **Automatic Environment Awareness**: You don't need to know where Cursor, Claude, or OpenCode stores their skills. `skm` automatically detects your project environment and handles the directory structures for you.
 - **Clean & Non-Intrusive**: Since skills are symlinked, your project folder stays clean. No extra `.git` folders or heavy files are added to your project's version control.
 - **Self-healing**: Proactively detects and helps you clean up broken symbolic links if a global skill is deleted.
-- **Version Sync**: One-click check for updates across all your global skills to keep your local "AI brain" sharp.
+- **Version Sync**: Check for remote updates to keep your local "AI brain" sharp.
 
 ## 📦 Installation
 
@@ -57,10 +60,18 @@ skm
 
 Select **"1. repo"** from the main menu to manage your global collection of skills.
 
-- **Add Skill**: Enter a GitHub URL to download a skill.
-  - Supports full repositories: `https://github.com/user/repo`
-  - Supports specific subfolders: `https://github.com/user/repo/tree/main/path/to/skill`
-- **Update Skills**: Checks for newer commits on the remote GitHub repository and updates your local copy.
+#### Add Skill
+
+**GitHub Type**:
+- Full repositories: `https://github.com/user/repo` (example: https://github.com/blader/humanizer)
+- Specific subfolders: `https://github.com/user/repo/tree/main/path/to/skill` (example: https://github.com/anthropics/skills/tree/main/skills/pdf)
+
+**Local Type**:
+- Local directories: `/local/path/to/skill` (example: `~/Desktop/myskill`)
+
+#### Other Operations
+
+- **Update Skills**: Checks for newer commits on the remote GitHub repository and updates your local copy (GitHub type only).
 - **Delete Skills**: Remove skills from your global repository.
 
 ### 2. Project Skill Management (`list`)
@@ -96,8 +107,8 @@ Select **"2. list(type)"** to manage skills for the current project.
 
 - **`config.json`**: Global configuration file. It stores system-level settings and metadata.
 - **`repo/`**: The heart of the management system.
-    - **`versions.json`**: The skill registry. It tracks all added skills, their unique IDs, current commit hashes (for version control), and original paths.
-    - **`github__[user]__[repo]__[subpath]/`**: Local Git repositories. `skm` flattens the ID (replacing `/` with `__`) to create safe directory names.
+    - **`skills.json`**: The skill registry. It tracks all added skills, their unique IDs, current commit hashes (for version control), and original paths.
+    - **`[type]__[name]/`**: Local skill repository storage. `skm` flattens the ID (replacing `/` with `__`) to create safe directory names. For example, `github:user/repo/path` becomes `github__user__repo__path`, and `local:myskill` becomes `local__myskill`.
     - **Note**: `skm` handles complex paths like `github:user/repo/path/to/skill` by creating a unique folder like `github__user__repo__path__to__skill`.
 
 ### Cross-Platform Compatibility (Windows)
@@ -105,7 +116,13 @@ Select **"2. list(type)"** to manage skills for the current project.
 - On **macOS/Linux**, it uses standard symbolic links.
 - On **Windows**, it automatically uses **Directory Junctions** (a type of symbolic link for folders) to ensure capability without requiring Administrator privileges or Developer Mode.
 
+---
+
+## 📝 Changelog
 
+### v1.0.2
+- Local Skill Support: Add skills directly from local directories
+- Menu Navigation Optimization: Unified numeric menu style, added return options, improved terminal compatibility
 
 ## 📄 License
 

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 简体中文 | [English](./README.md)
 
-`skm` 是一个强大的命令行工具，用于在各种 AI 编程代理和项目中管理与同步“技能”（Skills，即提示词库、指令集或能力模块）。它作为一个中心枢纽，帮助你从 GitHub 下载技能，并将其选择性地链接到本地 AI 项目配置中。
+`skm` 是一个强大的命令行工具，用于在各种 AI 编程代理和项目中管理与同步“技能”（Skills，即提示词库、指令集或能力模块）。它作为一个中心枢纽，帮助你从 GitHub 或本地目录添加技能，并将其选择性地链接到本地 AI 项目配置中。
 
 支持多种 AI 环境，包括 **OpenCode**、**Cursor**、**Gemini**、**Antigravity**、**Claude** 和 **GitHub** 项目。
 
@@ -12,11 +12,14 @@
 
 - **全局技能仓库**：集中管理所有的 AI 技能。
 - **GitHub 集成**：直接从 GitHub 仓库或指定子目录添加技能（支持稀疏检出）。
+- **本地技能支持**：支持从本地目录添加技能，方便开发和调试。
 - **版本控制**：检查远程更新并同步技能版本。
 - **项目检测**：自动检测当前目录下的 AI 项目类型。
 - **软链接管理**：通过符号链接将技能高效注入项目，避免文件复制，保持同步。
 - **项目隔离**：为不同项目配置不同的技能组合。
 
+![示意图](repo.png)
+
 ## 💡 为什么选择 skm?
 
 - **核心效率**：技能仅克隆一次（存储在 `~/.skills-management/repo`），通过符号链接在无限个项目间共享。这不仅极大地节省了磁盘空间，还确保了所有项目使用的技能版本高度统一。
@@ -24,7 +27,7 @@
 - **自动化环境感知**：你不需要记住 Cursor、Claude 或 OpenCode 把技能存在哪里。`skm` 会自动识别你的项目环境并处理对应的目录结构。
 - **整洁且无侵入**：由于使用的是软链接，你的项目文件夹保持纯净。不会有额外的 `.git` 文件夹或庞大的二进制文件进入你的项目版本控制。
 - **自我维护**：主动检测并帮助你清理失效的软链接（例如当全局技能被删除时）。
-- **版本同步**：一键检查所有全局技能的远程更新，确保你的“AI 大脑”始终处于最新状态。
+- **版本同步**：检查技能的远程更新，确保你的“AI 大脑”始终处于最新状态。
 
 ## 📦 安装指南
 
@@ -59,10 +62,18 @@ skm
 
 在主菜单选择 **"1. repo"** 来管理你的全局技能库。
 
-- **添加技能 (Add skill)**：输入 GitHub URL 下载技能。
-  - 支持完整仓库：`https://github.com/user/repo`
-  - 支持特定子目录：`https://github.com/user/repo/tree/main/path/to/skill`
-- **更新技能 (Update)**：自动检查远程仓库是否有新提交，并更新本地副本。
+#### 添加技能 (Add skill)
+
+**GitHub 类型**：
+- 支持完整仓库：`https://github.com/user/repo` (例子：https://github.com/blader/humanizer)
+- 支持特定子目录：`https://github.com/user/repo/tree/main/path/to/skill` (例子：https://github.com/anthropics/skills/tree/main/skills/pdf)
+
+**Local 类型**：
+- 支持本地目录：`/local/path/to/skill` (例子：`~/Desktop/myskill`)
+
+#### 其他操作
+
+- **更新技能 (Update)**：自动检查远程仓库是否有新提交，并更新本地副本（仅支持 GitHub 类型）。
 - **删除技能 (Delete)**：从全局仓库中移除技能。
 
 ### 2. 项目技能管理 (`list`)
@@ -98,8 +109,8 @@ skm
 
 - **`config.json`**: 全局配置文件，存储系统级设置和元数据。
 - **`repo/`**: 管理系统的核心目录。
-    - **`versions.json`**: 技能注册表（数据库）。记录了所有已添加技能的 ID、当前 Commit Hash（用于版本追踪）、检出类型和路径信息。
-    - **`github__[user]__[repo]__[subpath]/`**: 本地 Git 仓库存储中心。`skm` 会将 ID 扁平化（将 `/` 替换为 `__`）以创建安全的文件目录名。例如 `github:user/repo/path` 会被存储为 `github__user__repo__path`。
+    - **`skills.json`**: 技能注册表（数据库）。记录了所有已添加技能的 ID、当前 Commit Hash（用于版本追踪）、检出类型和路径信息。
+    - **`[type]__[name]/`**: 本地 Skill 仓库存储中心。`skm` 会将 ID 扁平化（将 `/` 替换为 `__`）以创建安全的文件目录名。例如 `github:user/repo/path` 会被存储为 `github__user__repo__path`，`local:myskill` 会被存储为 `local__myskill`。
 
 ### Windows 兼容性说明
 `skm` 完全兼容 Windows 系统。
@@ -107,6 +118,14 @@ skm
 - 在 **Windows** 上，工具会自动使用 **Directory Junctions** (目录联接点)。这是 Windows NTFS 文件系统的一种特性，类似于目录的软链接，但通常**不需要管理员权限**即可创建，确保了最佳的开箱即用体验。
 
 
+---
+
+## 📝 更新日志
+
+### v1.0.2
+- 支持本地技能 (Local Skill)：可以直接从本地目录添加技能
+- 菜单引导优化：统一使用数字菜单，添加返回选项，提升终端兼容性
+
 ## 📄 License
 
 ISC

package/dist/index.js

@@ -129,6 +129,7 @@ var ProjectDetector = class _ProjectDetector {
 var import_inquirer = __toESM(require("inquirer"));
 var import_fs_extra5 = __toESM(require("fs-extra"));
 var import_path4 = __toESM(require("path"));
+var import_os2 = __toESM(require("os"));
 
 // src/core/skills.ts
 var import_fs_extra3 = __toESM(require("fs-extra"));
@@ -136,7 +137,7 @@ var import_path3 = __toESM(require("path"));
 var SkillRegistry = class {
   versionsFile;
   constructor(configManager) {
-    this.versionsFile = import_path3.default.join(configManager.getRepoDir(), "versions.json");
+    this.versionsFile = import_path3.default.join(configManager.getRepoDir(), "skills.json");
   }
   getStoredSkills() {
     if (!import_fs_extra3.default.existsSync(this.versionsFile)) {
@@ -147,9 +148,12 @@ var SkillRegistry = class {
   saveSkills(skills) {
     import_fs_extra3.default.writeJsonSync(this.versionsFile, skills, { spaces: 2 });
   }
-  addSkill(id, commitId, type, skillPath) {
+  addSkill(id, type, commitId, skillPath) {
     const skills = this.getStoredSkills();
-    skills[id] = { commitId, type, path: skillPath };
+    const skillData = { type };
+    if (commitId) skillData.commitId = commitId;
+    if (skillPath) skillData.path = skillPath;
+    skills[id] = skillData;
     this.saveSkills(skills);
   }
   removeSkill(id) {
@@ -349,7 +353,11 @@ async function repoMenu() {
     } else {
       skills.forEach((s, index) => {
         const num = (index + 1).toString();
-        console.log(`${num}. ${s.id}:${s.commitId.substring(0, 7)}`);
+        if (s.type === "local") {
+          console.log(`${num}. ${s.id}`);
+        } else {
+          console.log(`${num}. ${s.id}:${s.commitId?.substring(0, 7) || "N/A"}`);
+        }
         menuMap[num] = { action: "manage", skill: s };
       });
     }
@@ -416,18 +424,23 @@ async function checkSingleSkillUpdate(skill) {
 async function manageSkill(skill) {
   console.log(`
 === Manage: ${skill.id} ===`);
-  const update = await checkSingleSkillUpdate(skill);
-  const hasUpdate = update !== null;
   const menuMap = {
     "0": "back"
   };
   let optionNum = 1;
-  if (hasUpdate && update) {
-    console.log(`${optionNum}. Update (${skill.commitId.substring(0, 7)} -> ${update.remoteHead.substring(0, 7)})`);
-    menuMap[optionNum.toString()] = "update";
-    optionNum++;
+  let update = null;
+  if (skill.type === "github") {
+    update = await checkSingleSkillUpdate(skill);
+    const hasUpdate = update !== null;
+    if (hasUpdate && update) {
+      console.log(`${optionNum}. Update (${skill.commitId?.substring(0, 7)} -> ${update.remoteHead.substring(0, 7)})`);
+      menuMap[optionNum.toString()] = "update";
+      optionNum++;
+    } else {
+      console.log("(No updates available)");
+    }
   } else {
-    console.log("(No updates available)");
+    console.log("(Local skill - updates not supported)");
   }
   console.log(`${optionNum}. Delete`);
   menuMap[optionNum.toString()] = "delete";
@@ -462,22 +475,120 @@ async function updateSingleSkill(skill, update) {
   }
 }
 async function addSkillInteractive(url) {
+  if (url) {
+    await addGitHubSkillInteractive(url);
+    return;
+  }
+  console.log("\\n=== Select Skill Type ===");
+  console.log("1. GitHub Repository");
+  console.log("2. Local Directory");
+  console.log("0. Return");
+  const typeAnswer = await import_inquirer.default.prompt([
+    {
+      type: "input",
+      name: "type",
+      message: "Select option:",
+      validate: (input) => ["0", "1", "2"].includes(input) || "Please enter 0, 1 or 2"
+    }
+  ]);
+  if (typeAnswer.type === "0") {
+    return;
+  } else if (typeAnswer.type === "2") {
+    await addLocalSkillInteractive();
+  } else {
+    await addGitHubSkillInteractive();
+  }
+}
+async function addLocalSkillInteractive() {
+  const configManager = new ConfigManager();
+  const skillRegistry = new SkillRegistry(configManager);
+  console.log("(Enter empty to return)");
+  const answer = await import_inquirer.default.prompt([
+    {
+      type: "input",
+      name: "path",
+      message: "Enter local skill path:"
+    }
+  ]);
+  if (!answer.path || answer.path.trim() === "") {
+    return;
+  }
+  const localPath = import_path4.default.resolve(answer.path);
+  if (!import_fs_extra5.default.existsSync(localPath)) {
+    console.error("Error: Path does not exist.");
+    return;
+  }
+  if (!import_fs_extra5.default.statSync(localPath).isDirectory()) {
+    console.error("Error: Path is not a directory.");
+    return;
+  }
+  const skillMdPath = import_path4.default.join(localPath, "SKILL.md");
+  if (!import_fs_extra5.default.existsSync(skillMdPath)) {
+    console.error("Error: SKILL.md not found in the specified directory.");
+    return;
+  }
+  const skillName = import_path4.default.basename(localPath);
+  const id = `local:${skillName}`;
+  const existingSkill = skillRegistry.getSkill(id);
+  if (existingSkill) {
+    const confirm = await import_inquirer.default.prompt([
+      {
+        type: "confirm",
+        name: "overwrite",
+        message: `Skill ${id} already exists. Overwrite?`,
+        default: false
+      }
+    ]);
+    if (!confirm.overwrite) {
+      console.log("Operation cancelled.");
+      return;
+    }
+    await import_fs_extra5.default.remove(configManager.getRepoPath(id));
+  }
+  const destPath = configManager.getRepoPath(id);
+  console.log(`Copying ${skillName} to repository...`);
+  await import_fs_extra5.default.copy(localPath, destPath);
+  skillRegistry.addSkill(id, "local");
+  console.log(`Skill ${id} added successfully.`);
+  console.log("\\nHow to handle the original directory?");
+  console.log("1. Keep (do nothing)");
+  console.log("2. Link (replace with symlink to repo)");
+  console.log("3. Delete");
+  const handleAnswer = await import_inquirer.default.prompt([
+    {
+      type: "input",
+      name: "action",
+      message: "Select option:",
+      validate: (input) => ["1", "2", "3"].includes(input) || "Please enter 1, 2 or 3"
+    }
+  ]);
+  if (handleAnswer.action === "3") {
+    await import_fs_extra5.default.remove(localPath);
+    console.log("Original directory deleted.");
+  } else if (handleAnswer.action === "2") {
+    await import_fs_extra5.default.remove(localPath);
+    const symlinkType = import_os2.default.platform() === "win32" ? "junction" : "dir";
+    await import_fs_extra5.default.ensureSymlink(destPath, localPath, symlinkType);
+    console.log("Original directory replaced with symlink.");
+  }
+}
+async function addGitHubSkillInteractive(url) {
   const configManager = new ConfigManager();
   const skillRegistry = new SkillRegistry(configManager);
   const gitManager = new GitManager();
   let repoUrl = url;
   if (!repoUrl) {
+    console.log("(Enter empty to return)");
     const answer = await import_inquirer.default.prompt([
       {
         type: "input",
         name: "url",
-        message: "Enter GitHub URL:",
-        validate: (input) => input.length > 0 || "URL is required"
+        message: "Enter GitHub URL:"
       }
     ]);
     repoUrl = answer.url;
   }
-  if (!repoUrl) return;
+  if (!repoUrl || repoUrl.trim() === "") return;
   try {
     await gitManager.checkGitVersion();
     const gitInfo = gitManager.normalizeUrl(repoUrl);
@@ -528,7 +639,7 @@ async function addSkillInteractive(url) {
     } else {
       commitId = await gitManager.getLocalPathCommitId(destPath, ".");
     }
-    skillRegistry.addSkill(id, commitId, "github", gitInfo.path);
+    skillRegistry.addSkill(id, "github", commitId, gitInfo.path);
     console.log(`Skill ${id} added successfully.`);
   } catch (error) {
     console.error(`Failed to add skill: ${error.message}`);
@@ -577,7 +688,7 @@ async function deleteSkill(id) {
 var import_inquirer2 = __toESM(require("inquirer"));
 var import_fs_extra6 = __toESM(require("fs-extra"));
 var import_path5 = __toESM(require("path"));
-var import_os2 = __toESM(require("os"));
+var import_os3 = __toESM(require("os"));
 async function linkSkillToProject(skillId, projectInfo) {
   const configManager = new ConfigManager();
   const skillRegistry = new SkillRegistry(configManager);
@@ -603,7 +714,7 @@ async function linkSkillToProject(skillId, projectInfo) {
     return;
   }
   try {
-    const type = import_os2.default.platform() === "win32" ? "junction" : "dir";
+    const type = import_os3.default.platform() === "win32" ? "junction" : "dir";
     await import_fs_extra6.default.ensureSymlink(targetPath, linkPath, type);
     console.log(`Linked ${skill.id}`);
   } catch (error) {
@@ -780,19 +891,14 @@ async function mainMenu() {
 }
 async function main() {
   const args = process.argv.slice(2);
-  if (args.includes("--config")) {
-    await showConfig();
-    return;
-  }
-  if (args.includes("--help") || args.includes("-h")) {
-    console.log(`
-Skills Management CLI (skm)
-
-Usage:
-  skm           Enter interactive mode
-  skm --config  View configuration
-`);
-    return;
+  if (args.length > 0) {
+    if (args.includes("--config")) {
+      await showConfig();
+      return;
+    }
+    console.error(`Error: Unknown argument(s): ${args.join(" ")}`);
+    console.error("Usage: skm [--config]");
+    process.exit(1);
   }
   await mainMenu();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nnnggel/skills-management",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "main": "index.js",
   "description": "A CLI tool to manage and synchronize AI coding agent skills",
   "bin": {