@xelandernt/skilly 0.0.22 → 0.0.25

package/README.md

@@ -1,20 +1,219 @@
-# @xelandernt/skilly
+# skilly
 
-Run the native `skilly` CLI through `npx` without a separate TypeScript or
-JavaScript CLI implementation.
+Manage [Agent Skills](https://agentskills.io/specification) from the command line
+or Python.
 
-## Usage
+`skilly` creates specification-compliant skills, installs skills from GitHub or
+Python dependencies, and keeps managed skills up to date.
+
+## Installation
+
+Run the CLI without installing it:
 
 ```shell
+uvx skilly --help
 npx @xelandernt/skilly --help
 ```
 
-The package preserves the native CLI's stdio behavior so interactive TUI flows
-and non-interactive automation keep using the same Rust implementation.
+Or install the CLI and Python package:
+
+```shell
+pip install skilly
+```
+
+The npm package ships the same native Rust CLI behind the executable name
+`skilly`. The current npm support matrix is macOS arm64/x64, Linux x64
+(glibc), and Windows x64.
+
+## Quick Start
+
+Scan the current Python project for skills shipped by its dependencies:
+
+```shell
+uvx skilly scan
+```
+
+Download a skill from GitHub:
+
+```shell
+uvx skilly download https://github.com/example/project/tree/main/skills/code-review
+```
+
+Inspect installed skills:
+
+```shell
+uvx skilly list
+```
+
+## CLI Commands
+
+| Command | Purpose |
+| --- | --- |
+| `uvx skilly scan` | Find skills provided by the project's Python dependencies. |
+| `uvx skilly download <github-url>` | Install one or more skills from GitHub. |
+| `uvx skilly list` | Browse, update, or remove installed skills. |
+| `uvx skilly update` | Preview available updates; add `--yes` to apply all updates. |
+| `uvx skilly remove <name>` | Remove an installed skill by directory name. |
+| `uvx skilly skillsmp search <query>` | Search SkillsMP and install a selected result. |
+| `uvx skilly create` | Create a valid skill through a terminal wizard or explicit options. |
+
+Use `uvx skilly <command> --help` for all options.
+
+### Create Skills
+
+Interactive terminals open a full-screen editor for the required and optional
+Agent Skills fields. `Ctrl+S` creates the skill, `Ctrl+X` cancels, and `Enter`
+in the multi-line editors inserts real line breaks.
+
+For scripts and automation, provide the required name and description:
+
+```shell
+uvx skilly create deployment-checks \
+  --description "Validate deployment readiness before a production release." \
+  --instructions "# Instructions
+
+Run the deployment checklist and report blockers." \
+  --metadata owner=platform \
+  --with-scripts \
+  --yes
+```
+
+Existing skills are rejected by default. Use `--overwrite` to replace one
+atomically. See `uvx skilly create --help` for the complete contract.
+
+### Install Dependency Skills
+
+`uvx skilly scan` reads `pyproject.toml` and the project's `.venv`, then offers
+skills shipped by direct, development, and optional dependencies:
+
+```shell
+uvx skilly scan
+```
+
+Exclude dependency categories when needed:
+
+```shell
+uvx skilly scan --no-dependency-groups --no-optional-dependencies
+```
+
+### Install GitHub Skills
+
+```shell
+uvx skilly download https://github.com/example/project
+```
+
+When a repository contains multiple skills, select one or install all:
+
+```shell
+uvx skilly download https://github.com/example/project --skill-name code-review
+uvx skilly download https://github.com/example/project --all
+```
+
+### Destinations
+
+Management commands accept the same destination options:
+
+| Option | Destination |
+| --- | --- |
+| `--local` | Project-local skills directory. |
+| `--global` | User-global skills directory. |
+| `--claude` | Claude skills directory. |
+| `--codex` | Codex skills directory. |
+| `--copilot` | GitHub Copilot skills directory. |
+| `--directory <path>` | Explicit directory; overrides all other destination options. |
+
+Without destination options, `skilly` uses `.agents/skills`.
+
+```shell
+uvx skilly download https://github.com/example/project --global --codex
+uvx skilly list --local --claude
+```
+
+### GitHub Authentication
+
+Authenticated requests have higher GitHub API rate limits. Use the first
+available token:
+
+```shell
+export SKILLY_GITHUB_TOKEN=ghp_your_token
+# or GITHUB_TOKEN / GH_TOKEN
+```
+
+GitHub-fetching commands also accept `--github-token`.
+
+## Python API
+
+`SkillRepository` is the stateful management interface. Bind a destination,
+project settings, or custom filesystem once and reuse it:
+
+```python
+from pathlib import Path
+
+from skilly import ProjectSettings, Skill, SkillRepository
+
+repository = SkillRepository(
+    directory=Path(".agents/skills"),
+    project=ProjectSettings(include_dependency_groups=True),
+)
+
+created = repository.install(
+    Skill(
+        name="code-review",
+        description="Review code for correctness and maintainability.",
+        content="# Instructions\n\nReview the proposed change.",
+    )
+)
+
+for match in repository.scan_project():
+    print(match.available.name, match.status)
+```
+
+Use focused discovery functions when no repository state is needed:
+
+```python
+from skilly import discover_installed_skills, discover_venv_skills
+
+installed = discover_installed_skills()
+dependency_skills = discover_venv_skills()
+```
+
+The SkillsMP client returns typed results directly. Async methods expose the
+same result types without blocking the event loop:
+
+```python
+from skilly.skillsmp import ClientSettings, SkillsMp, SkillsMpSearchQuery
+
+client = SkillsMp(settings=ClientSettings(base_url="https://skillsmp.com/api/v1"))
+result = client.search(SkillsMpSearchQuery(text="python", limit=5))
+print(result.data.skills[0].github_url)
+```
+
+## Development
+
+Install development dependencies and the editable extension:
+
+```shell
+just install
+```
+
+Run the required quality gates:
+
+```shell
+just lint
+just test
+just typecheck
+```
+
+The TypeScript launcher package also has dedicated helpers:
+
+```shell
+just ts::build
+just ts::test
+just ts::typecheck
+just ts::smoke
+just ts::publish-dry-run
+```
 
-## Supported targets
+## License
 
-- macOS arm64
-- macOS x64
-- Linux x64 (glibc)
-- Windows x64
+[MIT](LICENSE)

package/dist/src/bin/skilly.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const launcher_1 = require("../lib/launcher");
+(0, launcher_1.run)(process.argv.slice(2));

package/dist/src/lib/launcher.js

@@ -0,0 +1,62 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveBinaryPath = resolveBinaryPath;
+exports.ensureBinaryExists = ensureBinaryExists;
+exports.launch = launch;
+exports.run = run;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const targets_1 = require("./targets");
+function resolveBinaryPath(options = {}) {
+    const rootDir = options.rootDir ?? node_path_1.default.resolve(__dirname, "..", "..", "..");
+    const processLike = options.processLike ?? process;
+    const target = (0, targets_1.resolveTarget)(processLike);
+    return node_path_1.default.join(rootDir, (0, targets_1.vendorRelativePath)(target));
+}
+function ensureBinaryExists(binaryPath) {
+    if (node_fs_1.default.existsSync(binaryPath)) {
+        return;
+    }
+    const error = new Error(`No packaged skilly binary was found at ${binaryPath}. Reinstall ${targets_1.PACKAGE_NAME} or rebuild the npm package with staged native binaries.`);
+    error.code = "ERR_MISSING_BINARY";
+    throw error;
+}
+function launch(argv, options = {}) {
+    const processLike = options.processLike ?? process;
+    const spawnImpl = options.spawnImpl ?? node_child_process_1.spawn;
+    const binaryPath = resolveBinaryPath(options);
+    ensureBinaryExists(binaryPath);
+    const child = spawnImpl(binaryPath, argv, {
+        env: processLike.env,
+        stdio: "inherit",
+        windowsHide: false
+    });
+    return { child, binaryPath };
+}
+function writeError(processLike, message) {
+    if (processLike.stderr && typeof processLike.stderr.write === "function") {
+        processLike.stderr.write(`${message}\n`);
+        return;
+    }
+    console.error(message);
+}
+function run(argv, options = {}) {
+    const processLike = options.processLike ?? process;
+    const { child, binaryPath } = launch(argv, options);
+    child.once("error", (error) => {
+        writeError(processLike, `Failed to launch skilly from ${binaryPath}: ${error.message}`);
+        processLike.exit(1);
+    });
+    child.once("close", (code, signal) => {
+        if (signal) {
+            processLike.kill(processLike.pid, signal);
+            return;
+        }
+        processLike.exit(code ?? 1);
+    });
+    return child;
+}

package/dist/src/lib/targets.js

@@ -0,0 +1,90 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TARGETS = exports.PACKAGE_NAME = void 0;
+exports.supportedTargetLabels = supportedTargetLabels;
+exports.detectLinuxLibc = detectLinuxLibc;
+exports.executableName = executableName;
+exports.vendorRelativePath = vendorRelativePath;
+exports.unsupportedPlatformError = unsupportedPlatformError;
+exports.resolveTarget = resolveTarget;
+const node_path_1 = __importDefault(require("node:path"));
+exports.PACKAGE_NAME = "@xelandernt/skilly";
+exports.TARGETS = [
+    {
+        platform: "darwin",
+        arch: "arm64",
+        triple: "aarch64-apple-darwin",
+        label: "macOS arm64"
+    },
+    {
+        platform: "darwin",
+        arch: "x64",
+        triple: "x86_64-apple-darwin",
+        label: "macOS x64"
+    },
+    {
+        platform: "linux",
+        arch: "x64",
+        libc: "glibc",
+        triple: "x86_64-unknown-linux-gnu",
+        label: "Linux x64 (glibc)"
+    },
+    {
+        platform: "win32",
+        arch: "x64",
+        triple: "x86_64-pc-windows-msvc",
+        label: "Windows x64"
+    }
+];
+function supportedTargetLabels() {
+    return exports.TARGETS.map((target) => target.label);
+}
+function detectLinuxLibc(processLike = process) {
+    if (processLike.platform !== "linux") {
+        return null;
+    }
+    const report = processLike.report;
+    if (!report || typeof report.getReport !== "function") {
+        return "unknown";
+    }
+    const glibcVersionRuntime = report.getReport()?.header?.glibcVersionRuntime;
+    return glibcVersionRuntime ? "glibc" : "musl";
+}
+function executableName(target) {
+    return target.platform === "win32" ? "skilly.exe" : "skilly";
+}
+function vendorRelativePath(target) {
+    return node_path_1.default.posix.join("vendor", target.triple, executableName(target));
+}
+function unsupportedPlatformError(processLike = process) {
+    const libc = detectLinuxLibc(processLike);
+    const details = libc
+        ? `${processLike.platform} ${processLike.arch} (${libc})`
+        : `${processLike.platform} ${processLike.arch}`;
+    const supported = supportedTargetLabels().join(", ");
+    const hint = processLike.platform === "linux" && libc !== "glibc"
+        ? "Linux builds currently require glibc."
+        : "No packaged binary matches this platform.";
+    const error = new Error(`Unsupported platform for ${exports.PACKAGE_NAME}: ${details}. Supported targets: ${supported}. ${hint}`);
+    error.code = "ERR_UNSUPPORTED_PLATFORM";
+    return error;
+}
+function resolveTarget(processLike = process) {
+    const libc = detectLinuxLibc(processLike);
+    const target = exports.TARGETS.find((candidate) => {
+        if (candidate.platform !== processLike.platform || candidate.arch !== processLike.arch) {
+            return false;
+        }
+        if (candidate.platform !== "linux") {
+            return true;
+        }
+        return candidate.libc === libc;
+    });
+    if (!target) {
+        throw unsupportedPlatformError(processLike);
+    }
+    return target;
+}

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@xelandernt/skilly",
-  "version": "0.0.22",
+  "version": "0.0.25",
   "description": "Native npm launcher for the skilly CLI.",
   "license": "MIT",
   "bin": {
-    "skilly": "dist/bin/skilly.js"
+    "skilly": "dist/src/bin/skilly.js"
   },
   "type": "commonjs",
   "files": [
     "README.md",
-    "dist/bin",
-    "dist/lib",
+    "dist/src/bin",
+    "dist/src/lib",
     "vendor"
   ],
   "engines": {
@@ -22,9 +22,10 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "stage-local-binary": "npm run build && node ./dist/scripts/stage-local-binary.js",
+    "sync-readme": "node ./dist/scripts/sync-readme.js",
     "test": "npm run build && node --test ./dist/test/targets.test.js ./dist/test/launcher.test.js",
     "typecheck": "tsc --noEmit -p tsconfig.json",
-    "prepack": "npm run build"
+    "prepack": "npm run build && npm run sync-readme"
   },
   "devDependencies": {
     "@types/node": "^22.16.5",