@xelandernt/skilly 0.0.28 → 0.0.29

package/README.md

@@ -1,90 +1,90 @@
-[![npm](https://img.shields.io/npm/v/%40xelandernt%2Fskilly
-)](https://www.npmjs.com/package/@xelandernt/skilly)
+[![npm](https://img.shields.io/npm/v/%40xelandernt%2Fskilly)](https://www.npmjs.com/package/@xelandernt/skilly)
+[![pypi](https://img.shields.io/pypi/v/skilly)](https://pypi.org/project/skilly/)
 [![pyrefly](https://img.shields.io/endpoint?url=https://pyrefly.org/badge.json)](https://github.com/facebook/pyrefly)
 [![GitHub stars](https://img.shields.io/github/stars/xelandernt/skilly)](https://github.com/xelandernt/skilly/stargazers)
+[![npm Downloads](https://img.shields.io/npm/dm/%40xelandernt%2Fskilly)](https://www.npmjs.com/package/@xelandernt/skilly)
 [![PyPI Downloads](https://static.pepy.tech/badge/skilly/month)](https://pepy.tech/projects/skilly)
-[![License](https://img.shields.io/github/license/xelandernt/skilly
-)](https://github.com/xelandernt/skilly/blob/main/LICENSE)
+[![License](https://img.shields.io/github/license/xelandernt/skilly)](https://github.com/xelandernt/skilly/blob/main/LICENSE)
+
 # skilly
 
-Manage [Agent Skills](https://agentskills.io/specification) from the command line
-or Python.
+Manage [Agent Skills](https://agentskills.io/specification) from the command line or Python.
+
+`skilly` creates specification-compliant skills, installs skills from GitHub or Python dependencies, and keeps managed skills up to date.
+
+## Table of Contents
 
-`skilly` creates specification-compliant skills, installs skills from GitHub or
-Python dependencies, and keeps managed skills up to date.
+- [Installation](#installation)
+  - [Python](#python)
+  - [Node](#node)
+  - [Homebrew](#homebrew)
+  - [Info](#info)
+- [Quick Start](#quick-start)
+- [CLI Commands](#cli-commands)
+  - [Create Skills](#create-skills)
+  - [Install Dependency Skills](#install-dependency-skills)
+  - [Install GitHub Skills](#install-github-skills)
+  - [Destinations](#destinations)
+  - [GitHub Authentication](#github-authentication)
+- [Python API](#python-api)
+- [Development](#development)
+- [License](#license)
 
 ## Installation
 
-Run with `uvx`:
-```shell
-uvx skilly --help
 
+### Python
+```shell
+uvx skilly --help           # run on-the-fly
+pip install skilly          # or install persistently
 ```
 
-Run with `npx`:
+### Node
 ```shell
 npx @xelandernt/skilly --help
 ```
 
-Install the native CLI with Homebrew from this repository's tap:
 
+### Homebrew
 ```shell
 brew tap xelandernt/skilly https://github.com/xelandernt/skilly
 brew install xelandernt/skilly/skilly
 ```
 
-Homebrew installs the CLI only. Install the Python package when you need the
-import surface as well:
+### Info
 
-```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.
+| Method        | Ships                                                                                                |
+|---------------|------------------------------------------------------------------------------------------------------|
+| `uvx` / `pip` | Python package with import surface + CLI (pre-built wheels: Linux x64, macOS arm64/x64, Windows x64) |
+| `npx`         | Native Rust CLI (macOS arm64/x64, Linux x64 glibc, Windows x64)                                      |
+| `brew`        | Native Rust CLI (macOS arm64/x64, Linux 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
+uvx skilly scan                       # Find skills from Python dependencies
+uvx skilly download <github-url>      # Install skills from GitHub
+uvx skilly list                       # Browse installed skills
+uvx skilly update                     # Preview available updates
 ```
 
 ## 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. |
+|---------|---------|
+| `scan` | Find skills provided by the project's Python dependencies |
+| `download <github-url>` | Install one or more skills from GitHub |
+| `list` | Browse, update, or remove installed skills |
+| `update` | Preview available updates; `--yes` applies all |
+| `remove <name>` | Remove an installed skill by directory name |
+| `skillsmp search <query>` | Search SkillsMP and install a selected result |
+| `create` | Create a valid skill through a terminal wizard or explicit options |
 
-Use `uvx skilly <command> --help` for all options.
+Run `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:
+Interactive terminals open a full-screen editor. `Ctrl+S` creates the skill, `Ctrl+X` cancels.
 
 ```shell
 uvx skilly create deployment-checks \
@@ -97,22 +97,20 @@ Run the deployment checklist and report blockers." \
   --yes
 ```
 
-Existing skills are rejected by default. Use `--overwrite` to replace one
-atomically. See `uvx skilly create --help` for the complete contract.
+Existing skills are rejected unless `--overwrite` is passed.
 
 ### Install Dependency Skills
 
-`uvx skilly scan` reads `pyproject.toml` and the project's `.venv`, then offers
-skills shipped by direct, development, and optional dependencies:
+`skilly scan` reads `pyproject.toml` and the project's `.venv`, then surfaces skills shipped by dependencies:
 
 ```shell
 uvx skilly scan
 ```
 
-Filter named groups and extras when needed:
+Include or exclude specific extras and dependency groups (flags are repeatable):
 
 ```shell
-uvx skilly scan --group dev --exclude-extra docs
+uvx skilly scan --group dev --group test --exclude-extra docs
 ```
 
 ### Install GitHub Skills
@@ -121,86 +119,63 @@ uvx skilly scan --group dev --exclude-extra docs
 uvx skilly download https://github.com/example/project
 ```
 
-When a repository contains multiple skills, select one or install all:
+When a repository contains multiple skills:
 
 ```shell
-uvx skilly download https://github.com/example/project --skill-name code-review
 uvx skilly download https://github.com/example/project --all
+uvx skilly download https://github.com/example/project --skill-name code-review
 ```
 
 ### 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`.
-
-Set `SKILLY_DIRECTORY` to change that default without passing `--directory`
-every time:
+All management commands accept the same destination options:
 
 ```shell
-export SKILLY_DIRECTORY="$HOME/.config/skilly/skills"
-skilly list
+uvx skilly list --local        # .agents/skills
+uvx skilly list --global       # ~/.agents/skills
+uvx skilly list --claude       # .claude/skills
+uvx skilly list --codex        # .codex/skills
+uvx skilly list --copilot      # .github/skills (local), ~/.copilot/skills (global)
+uvx skilly list --directory ~/custom     # Explicit directory
 ```
 
-`--directory`, `--local`, `--global`, `--claude`, `--codex`, and `--copilot`
-override `SKILLY_DIRECTORY` when provided explicitly.
+| Flags                | Resolved destination                                  |
+|----------------------|-------------------------------------------------------|
+| _none_               | `SKILLY_DIRECTORY` if set, otherwise `.agents/skills` |
+| `--local`            | `.agents/skills`                                      |
+| `--global`           | `~/.agents/skills`                                    |
+| `--claude`           | `.claude/skills`                                      |
+| `--claude --global`  | `~/.claude/skills`                                    |
+| `--codex`            | `.codex/skills`                                       |
+| `--codex --global`   | `~/.codex/skills`                                     |
+| `--copilot`          | `.github/skills`                                      |
+| `--copilot --global` | `~/.copilot/skills`                                   |
+| `--directory <path>` | That directory (after `~` expansion)                  |
+
+Set a default destination:
 
 ```shell
-uvx skilly download https://github.com/example/project --global --codex
-uvx skilly list --local --claude
+export SKILLY_DIRECTORY="$HOME/.config/skilly/skills"
 ```
 
-#### Destination Mapping
-
-`skilly` resolves destination paths before use. Relative paths become absolute
-from the current working directory, and `--directory "~/.copilot"` expands `~`
-to your home directory.
-
-| Flags                | Resolved destination                                                      |
-|----------------------|---------------------------------------------------------------------------|
-| _none_               | `SKILLY_DIRECTORY` when set, otherwise `.agents/skills`                   |
-| `--local`            | `.agents/skills`                                                          |
-| `--global`           | `~/.agents/skills`                                                        |
-| `--claude`           | `.claude/skills`                                                          |
-| `--claude --global`  | `~/.claude/skills`                                                        |
-| `--codex`            | `.codex/skills`                                                           |
-| `--codex --global`   | `~/.codex/skills`                                                         |
-| `--copilot`          | `.github/skills`                                                          |
-| `--copilot --global` | `~/.copilot/skills`                                                       |
-| `--directory <path>` | Exactly that directory, after `~` expansion and absolute-path resolution. |
-
-`--directory` overrides `--local`, `--global`, `--claude`, `--codex`, and
-`--copilot`.
+`--directory` overrides all other destination options and `SKILLY_DIRECTORY`.
 
 ### GitHub Authentication
 
-Authenticated requests have higher GitHub API rate limits. Use the first
-available token:
+Set a token for higher API rate limits (first available wins: `SKILLY_GITHUB_TOKEN`, `GITHUB_TOKEN`, `GH_TOKEN`):
 
 ```shell
 export SKILLY_GITHUB_TOKEN=ghp_your_token
-# or GITHUB_TOKEN / GH_TOKEN
 ```
 
-GitHub-fetching commands also accept `--github-token`.
+All 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:
+`SkillRepository` bundles a directory and project settings for stateful workflows:
 
 ```python
 from pathlib import Path
-
 from skilly import ProjectSettings, Skill, SkillRepository
 
 repository = SkillRepository(
@@ -211,7 +186,7 @@ repository = SkillRepository(
     ),
 )
 
-created = repository.install(
+repository.install(
     Skill(
         name="code-review",
         description="Review code for correctness and maintainability.",
@@ -223,7 +198,7 @@ for match in repository.scan_project():
     print(match.available.name, match.status)
 ```
 
-Use focused discovery functions when no repository state is needed:
+Stateless discovery functions for one-shot reads:
 
 ```python
 from skilly import discover_installed_skills, discover_venv_skills
@@ -232,8 +207,7 @@ 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:
+SkillsMP client with typed results:
 
 ```python
 from skilly.skillsmp import ClientSettings, SkillsMp, SkillsMpSearchQuery
@@ -245,28 +219,11 @@ 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
+just install      # Install dev dependencies + editable extension
+just lint         # Run linters
+just test         # Run tests
+just typecheck    # Run type checkers
 ```
 
 ## License

package/dist/src/lib/launcher.js

@@ -7,9 +7,9 @@ exports.resolveBinaryPath = resolveBinaryPath;
 exports.ensureBinaryExists = ensureBinaryExists;
 exports.launch = launch;
 exports.run = run;
+const node_child_process_1 = require("node:child_process");
 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, "..", "..", "..");
@@ -33,7 +33,7 @@ function launch(argv, options = {}) {
     const child = spawnImpl(binaryPath, argv, {
         env: processLike.env,
         stdio: "inherit",
-        windowsHide: false
+        windowsHide: false,
     });
     return { child, binaryPath };
 }

package/dist/src/lib/targets.js

@@ -17,27 +17,27 @@ exports.TARGETS = [
         platform: "darwin",
         arch: "arm64",
         triple: "aarch64-apple-darwin",
-        label: "macOS arm64"
+        label: "macOS arm64",
     },
     {
         platform: "darwin",
         arch: "x64",
         triple: "x86_64-apple-darwin",
-        label: "macOS x64"
+        label: "macOS x64",
     },
     {
         platform: "linux",
         arch: "x64",
         libc: "glibc",
         triple: "x86_64-unknown-linux-gnu",
-        label: "Linux x64 (glibc)"
+        label: "Linux x64 (glibc)",
     },
     {
         platform: "win32",
         arch: "x64",
         triple: "x86_64-pc-windows-msvc",
-        label: "Windows x64"
-    }
+        label: "Windows x64",
+    },
 ];
 function supportedTargetLabels() {
     return exports.TARGETS.map((target) => target.label);
@@ -75,7 +75,8 @@ function unsupportedPlatformError(processLike = process) {
 function resolveTarget(processLike = process) {
     const libc = detectLinuxLibc(processLike);
     const target = exports.TARGETS.find((candidate) => {
-        if (candidate.platform !== processLike.platform || candidate.arch !== processLike.arch) {
+        if (candidate.platform !== processLike.platform ||
+            candidate.arch !== processLike.arch) {
             return false;
         }
         if (candidate.platform !== "linux") {

package/package.json

@@ -1,34 +1,35 @@
 {
-  "name": "@xelandernt/skilly",
-  "version": "0.0.28",
-  "description": "Native npm launcher for the skilly CLI.",
-  "license": "MIT",
-  "bin": {
-    "skilly": "dist/src/bin/skilly.js"
-  },
-  "type": "commonjs",
-  "files": [
-    "README.md",
-    "dist/src/bin",
-    "dist/src/lib",
-    "vendor"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "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 && npm run sync-readme"
-  },
-  "devDependencies": {
-    "@types/node": "^22.16.5",
-    "typescript": "^5.8.3"
-  }
+	"name": "@xelandernt/skilly",
+	"version": "0.0.29",
+	"description": "Native npm launcher for the skilly CLI.",
+	"license": "MIT",
+	"bin": {
+		"skilly": "dist/src/bin/skilly.js"
+	},
+	"type": "commonjs",
+	"files": [
+		"README.md",
+		"dist/src/bin",
+		"dist/src/lib",
+		"vendor"
+	],
+	"engines": {
+		"node": ">=18"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"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 && npm run sync-readme"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.4.16",
+		"@types/node": "^22.16.5",
+		"typescript": "^5.8.3"
+	}
 }