proskills-cli 0.1.0 → 0.2.0

package/README.md

@@ -1,83 +1,99 @@
-# proskills-cli
-
-Install [ProSkills](https://proskills.dev) agent skills in one command, and scan any `SKILL.md` folder in CI.
-
-Node 18 or newer. One dependency (`jszip`).
-
-## Use it
-
-No install needed:
-
-```sh
-npx proskills-cli list                      # every skill, price and scan score
-npx proskills-cli add humanizer             # install a free skill into this project
-npx proskills-cli add grill-me hook-lab     # several at once
-npx proskills-cli scan                      # score the skills already in this repo
-```
-
-Or install it: `npm i -g proskills`.
-
-### `proskills list [--collection <slug>]`
-
-Prints a table of skills with price (or `Free`) and scan score.
-
-### `proskills add <skill-id...>`
-
-| Flag | Meaning |
-|---|---|
-| `--agent claude\|cursor\|codex\|gemini\|all` | Which agent to install for. Default: `.claude/` found, then Claude Code; else `.agents/` found, then `.agents/skills`; else Claude Code. |
-| `--global` | Install for every project (your home folder) instead of this one. |
-| `--order <id>` | Order id from your receipt (`cs_live_...`). Also read from env `PROSKILLS_ORDER`. Required for paid skills. |
-| `--dir <path>` | Use this folder instead of the current one (instead of your home folder with `--global`). |
-| `--force` | Replace a skill folder that already exists. Without it, nothing is overwritten. |
-| `--answers file.json` | Send your saved answers so `profile.md` is filled in. Optional. |
-
-Paid skill without an order id: the command stops and prints the link to buy it (`https://proskills.dev/library/<collection>`).
-
-### `proskills scan [paths...] [--min 80] [--json]`
-
-Scores skill folders against the Agent Skills spec, token budget, clarity and security. A path is a skill folder (has `SKILL.md`) or a folder of skill folders. Default: `.claude/skills` and `.agents/skills`. Exits `1` when any skill is grade F (any critical finding) or scores under `--min`, `2` on usage errors. Scanning runs locally; nothing is uploaded.
-
-### Everywhere
-
-`--base <url>` (or env `PROSKILLS_URL`) points at another host. Default `https://proskills.dev`. `--help`, `--version`.
-
-## CI
-
-Block a pull request that adds a weak or unsafe skill:
-
-```yaml
-name: skills
-on: [pull_request]
-jobs:
-  scan:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with: { node-version: 20 }
-      - run: npx proskills-cli scan --min 80
-```
-
-Add paths to scan something else: `npx proskills-cli scan ./skills --min 90 --json`.
-
-## What it writes, and where
-
-Each skill becomes one folder, with `SKILL.md`, `profile.md` and any files the skill reads:
-
-| Agent | This project | With `--global` |
-|---|---|---|
-| Claude Code | `.claude/skills/<id>/` | `~/.claude/skills/<id>/` |
-| Cursor | `.agents/skills/<id>/` | `~/.cursor/skills/<id>/` |
-| Codex | `.agents/skills/<id>/` | `~/.agents/skills/<id>/` |
-| Gemini CLI | `.agents/skills/<id>/` | `~/.gemini/skills/<id>/` |
-
-It writes only inside that skills folder. Archive entries with `..`, absolute paths or drive letters are rejected before anything is written. Restart your agent afterwards.
-
-## Privacy
-
-`list` and `add` send only the skill ids you ask for, plus the order id if you give one. Your saved answers are not sent unless you pass `--answers file.json`. No telemetry, no accounts, no other network calls. `scan` makes none at all.
-
-## License
-
-MIT
+# proskills-cli
+
+Install [ProSkills](https://proskills.dev) agent skills in one command, and scan any `SKILL.md` folder in CI.
+
+Node 18 or newer. One dependency (`jszip`).
+
+## Use it
+
+No install needed:
+
+```sh
+npx proskills-cli list                      # every skill, price and scan score
+npx proskills-cli add humanizer             # install a free skill into this project
+npx proskills-cli add grill-me hook-lab     # several at once
+npx proskills-cli scan                      # score the skills already in this repo
+```
+
+Or install it: `npm i -g proskills`.
+
+### `proskills list [--collection <slug>]`
+
+Prints a table of skills with price (or `Free`) and scan score.
+
+### `proskills add <skill-id...>`
+
+| Flag | Meaning |
+|---|---|
+| `--agent claude\|cursor\|codex\|gemini\|all` | Which agent to install for. Default: `.claude/` found, then Claude Code; else `.agents/` found, then `.agents/skills`; else Claude Code. |
+| `--global` | Install for every project (your home folder) instead of this one. |
+| `--order <id>` | Order id from your receipt (`cs_live_...`). Also read from env `PROSKILLS_ORDER`. Required for paid skills. |
+| `--dir <path>` | Use this folder instead of the current one (instead of your home folder with `--global`). |
+| `--force` | Replace a skill folder that already exists. Without it, nothing is overwritten. |
+| `--answers file.json` | Send your saved answers so `profile.md` is filled in. Optional. |
+
+Paid skill without an order id: the command stops and prints the link to buy it (`https://proskills.dev/library/<collection>`).
+
+### `proskills scan [paths...] [--min 80] [--json] [--badge]`
+
+Scores skill folders against the Agent Skills spec, token budget, clarity and security. A path is a skill folder (has `SKILL.md`) or a folder of skill folders. Default: `.claude/skills` and `.agents/skills`. Exits `1` when any skill is grade F (any critical finding) or scores under `--min`, `2` on usage errors. `--badge` prints a README badge snippet after the scan, using the lowest score across the scanned skills (with `--json` it is a `badge` field instead). Scanning runs locally; nothing is uploaded.
+
+### Everywhere
+
+`--base <url>` (or env `PROSKILLS_URL`) points at another host. Default `https://proskills.dev`. `--help`, `--version`.
+
+## CI
+
+Block a pull request that adds a weak or unsafe skill:
+
+```yaml
+name: skills
+on: [pull_request]
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20 }
+      - run: npx proskills-cli scan --min 80
+```
+
+Add paths to scan something else: `npx proskills-cli scan ./skills --min 90 --json`.
+
+Or use the GitHub Action from the [public repo](https://github.com/yungprimer/proskills), which also prints the badge in the job summary:
+
+```yaml
+      - uses: yungprimer/proskills@v1
+        with:
+          min: 80
+```
+
+## Badge
+
+`npx proskills-cli scan --badge` prints this for your README (the number is your lowest skill score):
+
+```md
+[![Scanned by ProSkills](https://proskills.dev/badge?score=92)](https://proskills.dev/scan)
+```
+
+## What it writes, and where
+
+Each skill becomes one folder, with `SKILL.md`, `profile.md` and any files the skill reads:
+
+| Agent | This project | With `--global` |
+|---|---|---|
+| Claude Code | `.claude/skills/<id>/` | `~/.claude/skills/<id>/` |
+| Cursor | `.agents/skills/<id>/` | `~/.cursor/skills/<id>/` |
+| Codex | `.agents/skills/<id>/` | `~/.agents/skills/<id>/` |
+| Gemini CLI | `.agents/skills/<id>/` | `~/.gemini/skills/<id>/` |
+
+It writes only inside that skills folder. Archive entries with `..`, absolute paths or drive letters are rejected before anything is written. Restart your agent afterwards.
+
+## Privacy
+
+`list` and `add` send only the skill ids you ask for, plus the order id if you give one. Your saved answers are not sent unless you pass `--answers file.json`. No telemetry, no accounts, no other network calls. `scan` makes none at all.
+
+## License
+
+MIT

package/dist/cli.js

@@ -5,27 +5,29 @@ import { parseArgs } from "node:util";
 import { CliError, fetchCatalog } from "./api.js";
 import { install } from "./install.js";
 import { pickAgents, resolveTargets } from "./paths.js";
-import { DEFAULT_SCAN_DIRS, isFailing, scanDirs } from "./scancmd.js";
+import { DEFAULT_SCAN_DIRS, badgeMarkdown, isFailing, scanDirs } from "./scancmd.js";
 export const DEFAULT_BASE = "https://proskills.dev";
-export const HELP = `proskills - install ProSkills agent skills and scan any skill folder
-
-Usage
-  proskills list [--collection <slug>]
-  proskills add <skill-id...> [--agent claude|cursor|codex|gemini|all] [--global]
-                [--order <id>] [--dir <path>] [--force] [--answers file.json]
-  proskills scan [paths...] [--min 80] [--json]
-
-Options
-  --base <url>   Another host (default ${DEFAULT_BASE}, or env PROSKILLS_URL)
-  --order <id>   Order id from your receipt (or env PROSKILLS_ORDER)
-  --dir <path>   Base folder instead of the current one (home folder with --global)
-  --help         Show this help
-  --version      Show the version
-
-Examples
-  npx proskills-cli add humanizer
-  npx proskills-cli add grill-me --agent all --global
-  npx proskills-cli scan --min 80
+export const HELP = `proskills - install ProSkills agent skills and scan any skill folder
+
+Usage
+  proskills list [--collection <slug>]
+  proskills add <skill-id...> [--agent claude|cursor|codex|gemini|all] [--global]
+                [--order <id>] [--dir <path>] [--force] [--answers file.json]
+  proskills scan [paths...] [--min 80] [--json] [--badge]
+
+Options
+  --base <url>   Another host (default ${DEFAULT_BASE}, or env PROSKILLS_URL)
+  --order <id>   Order id from your receipt (or env PROSKILLS_ORDER)
+  --dir <path>   Base folder instead of the current one (home folder with --global)
+  --badge        After a scan, print a README badge snippet using the lowest score
+                 across the scanned skills (with --json: a "badge" field)
+  --help         Show this help
+  --version      Show the version
+
+Examples
+  npx proskills-cli add humanizer
+  npx proskills-cli add grill-me --agent all --global
+  npx proskills-cli scan --min 80
 `;
 const OPTIONS = {
     help: { type: "boolean", short: "h" },
@@ -40,6 +42,7 @@ const OPTIONS = {
     collection: { type: "string" },
     min: { type: "string" },
     json: { type: "boolean" },
+    badge: { type: "boolean" },
 };
 export function parseCli(argv) {
     const { values, positionals } = parseArgs({ args: argv, options: OPTIONS, allowPositionals: true, strict: true });
@@ -138,7 +141,7 @@ export async function run(argv, io) {
                 throw new CliError(explicit ? "No skill folders (containing SKILL.md) found in the given paths." : `No skills found in ${DEFAULT_SCAN_DIRS.join(" or ")}. Pass a path: proskills scan ./my-skill`, 2);
             const failed = results.filter((r) => isFailing(r, min));
             if (values.json) {
-                io.out(JSON.stringify({ min, ok: failed.length === 0, skills: results.map((r) => ({ dir: r.dir.replace(/\\/g, "/"), failed: isFailing(r, min), ...r.report })) }, null, 2));
+                io.out(JSON.stringify({ min, ok: failed.length === 0, ...(values.badge ? { badge: badgeMarkdown(results.map((r) => r.report.score)) } : {}), skills: results.map((r) => ({ dir: r.dir.replace(/\\/g, "/"), failed: isFailing(r, min), ...r.report })) }, null, 2));
             }
             else {
                 for (const { dir, report: r } of results) {
@@ -147,6 +150,8 @@ export async function run(argv, io) {
                         io.out(`     ${f.severity.padEnd(8)} ${f.rule.padEnd(24)} ${f.file ?? ""}${f.line ? ":" + f.line : ""}  ${f.message}`);
                 }
                 io.out(`\n${results.length} skills scanned, ${failed.length} below the gate (min ${min}, grade F always fails).`);
+                if (values.badge)
+                    io.out(`\nREADME badge (lowest score: ${Math.min(...results.map((r) => r.report.score))}):\n${badgeMarkdown(results.map((r) => r.report.score))}`);
             }
             return failed.length ? 1 : 0;
         }

package/dist/scancmd.js

@@ -48,3 +48,8 @@ export function scanDirs(roots, cwd) {
 export function isFailing(r, min) {
     return r.report.grade === "F" || r.report.score < min;
 }
+/** README badge for a scan. Uses the lowest score, so one weak skill cannot hide behind a strong one. */
+export function badgeMarkdown(scores) {
+    const score = Math.max(0, Math.min(100, Math.round(Math.min(...scores))));
+    return `[![Scanned by ProSkills](https://proskills.dev/badge?score=${score})](https://proskills.dev/scan)`;
+}

package/package.json

@@ -1,49 +1,49 @@
-{
-  "name": "proskills-cli",
-  "version": "0.1.0",
-  "description": "Install ProSkills agent skills in one command and scan any SKILL.md folder in CI.",
-  "keywords": [
-    "agent-skills",
-    "skill.md",
-    "claude-code",
-    "cursor",
-    "codex",
-    "gemini-cli",
-    "cli"
-  ],
-  "homepage": "https://proskills.dev",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/yungprimer/proskills.git",
-    "directory": "cli"
-  },
-  "bugs": {
-    "url": "https://github.com/yungprimer/proskills/issues"
-  },
-  "author": "ProSkills (https://proskills.dev)",
-  "license": "MIT",
-  "type": "module",
-  "bin": {
-    "proskills": "dist/index.js"
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "scripts": {
-    "prebuild": "node scripts/copy-scan.mjs",
-    "build": "tsc -p tsconfig.json",
-    "test": "node --test test/cli.test.mjs",
-    "prepublishOnly": "npm run build && npm test"
-  },
-  "dependencies": {
-    "jszip": "^3.10.1"
-  },
-  "devDependencies": {
-    "@types/node": "^20",
-    "typescript": "^5"
-  }
-}
+{
+  "name": "proskills-cli",
+  "version": "0.2.0",
+  "description": "Install ProSkills agent skills in one command and scan any SKILL.md folder in CI.",
+  "keywords": [
+    "agent-skills",
+    "skill.md",
+    "claude-code",
+    "cursor",
+    "codex",
+    "gemini-cli",
+    "cli"
+  ],
+  "homepage": "https://proskills.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yungprimer/proskills.git",
+    "directory": "cli"
+  },
+  "bugs": {
+    "url": "https://github.com/yungprimer/proskills/issues"
+  },
+  "author": "ProSkills (https://proskills.dev)",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "proskills": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "prebuild": "node scripts/copy-scan.mjs",
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test test/cli.test.mjs",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "jszip": "^3.10.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5"
+  }
+}