skill-linker 4.1.3 → 4.2.0

package/CHANGELOG.md

@@ -0,0 +1,106 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [4.2.0] - 2026-06-02
+
+### Added
+
+- `list --skills` flag: flat-lists every individual skill across the whole
+  library (supports `--json`).
+
+### Changed
+
+- Agent auto-detection (when `--agent` is omitted) now also detects agents by
+  their project skills directory in the current folder, not just the global
+  directory.
+
+## [4.1.4] - 2026-06-02
+
+### Fixed
+
+- `--skill` with a relative path (e.g. `./my-skill`) no longer creates a
+  broken, self-referential symlink; the source is resolved to an absolute
+  path before linking.
+- `--from` with a `/tree/<branch>/<path>` URL now actually clones that
+  branch instead of silently cloning the default branch.
+
+## [4.1.3] - 2026-06-02
+
+### Changed
+
+- Rewrote the README to be newcomer-friendly: explains what a Skill is,
+  adds a copy-paste "golden" example, documents `--agent` auto-detection,
+  multi-skill subpath installs, and manual uninstall.
+
+### Fixed
+
+- Corrected stale `install` usage docs that still marked `--skill` as
+  required and used the wrong `list --repo` name format.
+
+## [4.1.2] - 2026-06-02
+
+### Added
+
+- Unit tests (`node --test`) for GitHub URL parsing and file-system utils.
+
+### Changed
+
+- `--skill` is now optional: provide either `--skill <path>` or
+  `--from <url>` (at least one required).
+- `install` exits with a non-zero status when one or more links fail, so
+  automation can detect partial failures.
+
+### Fixed
+
+- `createSymlink` refuses to overwrite a real (non-symlink) file or
+  directory, preventing silent data loss on `--yes` overwrite.
+
+### Removed
+
+- Deleted the obsolete `legacy-link-skill.sh` and a stale duplicate
+  `SKILL.md` at the repo root.
+
+## [4.1.1] - 2026-02-26
+
+### Added
+
+- Agent skill definition so the tool can install itself.
+
+## [4.1.0] - 2026-02-26
+
+### Added
+
+- Release SOP document and `release.sh` helper script.
+
+## [4.0.4] - 2025
+
+### Fixed
+
+- Corrected the OpenCode global skills path to `~/.config/opencode/skills/`.
+
+## [4.0.0] - 2025
+
+### Changed
+
+- **Breaking:** removed interactive mode; the tool is now CLI-only.
+
+### Added
+
+- Agent alias support for common names (e.g. `claude`, `gh-copilot`).
+- Shallow clone and rebase for faster git operations.
+
+[Unreleased]: https://github.com/raybird/skill-linker/compare/v4.2.0...HEAD
+[4.2.0]: https://github.com/raybird/skill-linker/compare/v4.1.4...v4.2.0
+[4.1.4]: https://github.com/raybird/skill-linker/compare/v4.1.3...v4.1.4
+[4.1.3]: https://github.com/raybird/skill-linker/compare/v4.1.2...v4.1.3
+[4.1.2]: https://github.com/raybird/skill-linker/compare/v4.1.1...v4.1.2
+[4.1.1]: https://github.com/raybird/skill-linker/compare/v4.1.0...v4.1.1
+[4.1.0]: https://github.com/raybird/skill-linker/compare/v4.0.4...v4.1.0
+[4.0.4]: https://github.com/raybird/skill-linker/compare/v4.0.0...v4.0.4
+[4.0.0]: https://github.com/raybird/skill-linker/compare/v3.0.8...v4.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raybird
+
+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

@@ -82,7 +82,7 @@ Options:
 
 > `--skill` 與 `--from` 至少要提供一個（兩者皆可省略其一）。
 >
-> **`--agent` 省略時**：會自動安裝到所有「已偵測到」的 Agent —— 也就是那些全域目錄（如 `~/.claude`、`~/.cursor`）已存在於你系統上的工具。
+> **`--agent` 省略時**：會自動安裝到所有「已偵測到」的 Agent —— 也就是其**全域目錄**（如 `~/.claude/skills`）或**當前專案目錄**（如 `./.cursor/skills`）已存在的工具。
 
 範例：
 
@@ -107,6 +107,7 @@ Usage: skill-linker list [options]
 
 Options:
   -r, --repo <name>   指定 Repository 名稱（格式為 owner/repo）
+  --skills            平鋪列出整個 Library 中的每一個 skill
   --json              JSON 輸出格式
 ```
 
@@ -116,6 +117,9 @@ Options:
 # 列出 Library 中所有 Repos
 npx skill-linker list
 
+# 平鋪列出所有 repo 底下的每一個 skill（owner/repo/skill）
+npx skill-linker list --skills
+
 # 列出特定 Repo 的 Skills（名稱為 owner/repo）
 npx skill-linker list --repo anthropics/skills
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skill-linker",
-  "version": "4.1.3",
+  "version": "4.2.0",
   "description": "CLI to link AI Agent Skills to various agents (Claude, Copilot, Antigravity, Cursor, etc.)",
   "main": "bin/cli.js",
   "bin": {
@@ -41,6 +41,8 @@
     "bin/",
     "src/",
     "skills/",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
   ]
 }

package/src/cli.js

@@ -42,10 +42,12 @@ program
   .command("list")
   .description("List available skills in library")
   .option("-r, --repo <name>", "Repository name to list skills from")
+  .option("--skills", "List every individual skill across the whole library")
   .option("--json", "Output as JSON")
   .action(async (options) => {
     await list({
       repo: options.repo,
+      skills: options.skills || false,
       json: options.json || false,
     });
   });

package/src/commands/list.js

@@ -2,6 +2,7 @@ const chalk = require("chalk");
 const path = require("path");
 const {
   findRepos,
+  findSkills,
   listDirectories,
   dirExists,
 } = require("../utils/file-system");
@@ -11,16 +12,19 @@ const { DEFAULT_LIB_PATH } = require("../utils/git");
  * List command - shows repos and skills (CLI mode only)
  * @param {Object} options - Command options
  * @param {string} [options.repo] - Repository name to list
+ * @param {boolean} [options.skills] - List individual skills across the library
  * @param {boolean} [options.json] - Output as JSON
+ * @param {string} [options.libPath] - Library root (defaults to DEFAULT_LIB_PATH)
  */
 async function list(options = {}) {
   const repoName = options.repo;
   const outputJson = options.json || false;
+  const libPath = options.libPath || DEFAULT_LIB_PATH;
 
-  if (!dirExists(DEFAULT_LIB_PATH)) {
+  if (!dirExists(libPath)) {
     console.error(
       chalk.red("[ERROR]"),
-      `Skill library not found: ${DEFAULT_LIB_PATH}`,
+      `Skill library not found: ${libPath}`,
     );
     console.log(
       chalk.blue("[INFO]"),
@@ -29,12 +33,12 @@ async function list(options = {}) {
     process.exit(1);
   }
 
-  const repos = findRepos(DEFAULT_LIB_PATH);
+  const repos = findRepos(libPath);
 
   if (repos.length === 0) {
     console.log(
       chalk.yellow("[WARNING]"),
-      `No repos found in ${DEFAULT_LIB_PATH}`,
+      `No repos found in ${libPath}`,
     );
     console.log(
       chalk.blue("[INFO]"),
@@ -43,6 +47,36 @@ async function list(options = {}) {
     return;
   }
 
+  // Flat listing: every individual skill across the whole library.
+  // Only applies when no specific --repo was requested.
+  if (options.skills && !repoName) {
+    const skills = findSkills(libPath);
+
+    if (outputJson) {
+      console.log(
+        JSON.stringify(
+          skills.map((s) => ({ name: s.name, path: s.path })),
+          null,
+          2,
+        ),
+      );
+      return;
+    }
+
+    console.log("");
+    console.log(
+      chalk.blue("[INFO]"),
+      `Skills in library (${libPath}):`,
+    );
+    console.log("");
+    skills.forEach((skill, index) => {
+      console.log(`  ${index + 1}. ${chalk.cyan(skill.name)}`);
+      console.log(`     ${chalk.dim(skill.path)}`);
+    });
+    console.log("");
+    return;
+  }
+
   // CLI mode: use provided repo name
   if (repoName) {
     const selectedRepo = repos.find(
@@ -134,7 +168,7 @@ async function list(options = {}) {
     console.log("");
     console.log(
       chalk.blue("[INFO]"),
-      `Repositories in library (${DEFAULT_LIB_PATH}):`,
+      `Repositories in library (${libPath}):`,
     );
     console.log("");
 

package/src/utils/agents.js

@@ -74,15 +74,22 @@ function findAgentIndex(nameOrAlias) {
 }
 
 /**
- * Detect which agents are installed on the system
+ * Detect which agents are installed / in use.
+ *
+ * An agent counts as detected if EITHER its global skills directory exists,
+ * OR its project skills directory exists under the given working directory.
+ * The latter lets project-only setups be auto-detected when --agent is omitted.
+ *
+ * @param {string} [cwd] - Working directory to check project dirs against
  * @returns {Array} List of detected agent indices
  */
-function detectInstalledAgents() {
+function detectInstalledAgents(cwd = process.cwd()) {
   const installed = [];
 
   AGENTS.forEach((agent, index) => {
-    // Check if global directory exists
-    if (fs.existsSync(agent.globalDir)) {
+    const globalExists = fs.existsSync(agent.globalDir);
+    const projectExists = fs.existsSync(path.join(cwd, agent.projectDir));
+    if (globalExists || projectExists) {
       installed.push(index);
     }
   });

package/src/utils/file-system.js

@@ -32,6 +32,11 @@ function ensureDir(dirPath) {
  */
 function createSymlink(source, target) {
     try {
+        // Resolve the source to an absolute path. A relative source (e.g.
+        // "./my-skill") would otherwise be stored verbatim and resolved
+        // relative to the link's own directory, producing a broken link.
+        const resolvedSource = path.resolve(source);
+
         // Ensure parent directory exists
         ensureDir(path.dirname(target));
 
@@ -57,7 +62,7 @@ function createSymlink(source, target) {
             }
         }
 
-        fs.symlinkSync(source, target, 'dir');
+        fs.symlinkSync(resolvedSource, target, 'dir');
         return true;
     } catch (error) {
         console.error(`Failed to create symlink: ${error.message}`);

package/src/utils/git.js

@@ -13,7 +13,8 @@ const DEFAULT_LIB_PATH = path.join(os.homedir(), "Documents/AgentSkills");
 function parseGitHubUrl(url) {
   let cleanUrl = url;
   let subpath = "";
-  let branch = "main";
+  // null means "no explicit branch" — let git use the remote default.
+  let branch = null;
 
   // Check for /tree/branch/path format
   const treeMatch = url.match(/(.+)\/tree\/([^/]+)\/(.+)$/);
@@ -39,19 +40,38 @@ function parseGitHubUrl(url) {
   };
 }
 
+/**
+ * Build the argument list for `git clone`.
+ * @param {string} url - GitHub URL
+ * @param {string} targetPath - Target directory
+ * @param {Object} [opts]
+ * @param {boolean} [opts.shallow] - Use shallow clone (default true)
+ * @param {string|null} [opts.branch] - Branch to check out, or null for default
+ * @returns {string[]} git arguments
+ */
+function buildCloneArgs(url, targetPath, { shallow = true, branch = null } = {}) {
+  const args = ["clone"];
+  if (shallow) {
+    args.push("--depth", "1");
+  }
+  if (branch) {
+    args.push("--branch", branch);
+  }
+  args.push(url, targetPath);
+  return args;
+}
+
 /**
  * Clone a GitHub repository
  * @param {string} url - GitHub URL
  * @param {string} targetPath - Target directory
  * @param {boolean} shallow - Use shallow clone (default true)
+ * @param {string|null} branch - Branch to check out, or null for default
  * @returns {Promise<void>}
  */
-async function cloneRepo(url, targetPath, shallow = true) {
+async function cloneRepo(url, targetPath, shallow = true, branch = null) {
   try {
-    const args = shallow
-      ? ["clone", "--depth", "1", url, targetPath]
-      : ["clone", url, targetPath];
-    await execa("git", args);
+    await execa("git", buildCloneArgs(url, targetPath, { shallow, branch }));
   } catch (error) {
     throw new Error(`Failed to clone repository: ${error.message}`);
   }
@@ -85,8 +105,8 @@ async function cloneOrUpdateRepo(url) {
     // Repo exists, ask if user wants to update
     needsUpdate = true;
   } else {
-    // Clone new repo
-    await cloneRepo(parsed.cleanUrl, targetPath);
+    // Clone new repo (honour an explicit branch from /tree/<branch>/ URLs)
+    await cloneRepo(parsed.cleanUrl, targetPath, true, parsed.branch);
   }
 
   // Determine final skill path
@@ -106,6 +126,7 @@ async function cloneOrUpdateRepo(url) {
 module.exports = {
   DEFAULT_LIB_PATH,
   parseGitHubUrl,
+  buildCloneArgs,
   cloneRepo,
   pullRepo,
   cloneOrUpdateRepo,