End-to-end audit: version drift, CLI hardening, npm packaging, CI, dependency security

.claude/wiki.md

@@ -1,5 +1,32 @@
 # polyskill Project Wiki
 
+## CLI version comes from package.json at runtime — never hardcode it
+
+<!-- added: 2026-07-02 -->
+
+`packages/cli/src/index.ts` reads its version via `createRequire(import.meta.url)("../package.json")`.
+Do not reintroduce a hardcoded `.version("x.y.z")` string.
+
+**Why:** the old hardcoded string drifted in production — npm's `@polyskill/cli@0.1.13`
+reports `0.1.12` from `--version` because the publish bumped only package.json.
+CONTRIBUTING's "bump in two places" step didn't prevent it; a single source of truth does.
+
+## getting-started skill: repo is canonical, but published version can run AHEAD of repo
+
+<!-- added: 2026-07-02 -->
+
+The registry's published `@polyskill/getting-started` was 1.0.8 while the repo said 1.0.7 —
+and the published 1.0.8 content was STALE (taught `--sort downloads`, which the live API
+rejects: "Must be one of: relevance, name, recent"; removed from the repo in commit 9110cd6).
+Repo bumped to 1.0.9 on 2026-07-02 so the corrected content is publishable again; it still
+needs an authenticated `polyskill publish skills/getting-started` to go live.
+
+**Why:** publishing without committing the version bump (or vice versa) forks the two copies,
+and the registry rejects re-publishing at or below the published version — so a stale published
+skill silently becomes unfixable until someone notices and bumps past it. After any publish of
+this skill, verify `curl -s https://polyskill.ai/api/skills/%40polyskill%2Fgetting-started | jq .version`
+matches `skills/getting-started/skill.json`.
+
 ## Terminal/exit paths must live OUTSIDE the registry-fetch try/catch in `install.ts`
 
 <!-- added: 2026-05-17 -->

.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node: [20, 22]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build
+      - run: pnpm test

CONTRIBUTING.md

@@ -57,7 +57,7 @@ skills/   Example skills
 Both `@polyskill/core` and `@polyskill/cli` are published to npm. Always use `pnpm publish` (not `npm publish`) — it resolves `workspace:*` dependencies to concrete versions automatically.
 
 ```bash
-# 1. Bump version in package.json AND src/index.ts (CLI has a hardcoded .version() call)
+# 1. Bump version in the package's package.json (the CLI reads its version from there at runtime)
 # 2. Build and test
 pnpm build && pnpm test
 

package.json

@@ -10,5 +10,6 @@
   },
   "engines": {
     "node": ">=18"
-  }
+  },
+  "packageManager": "pnpm@10.29.1"
 }

packages/cli/LICENSE

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

packages/cli/README.md

@@ -0,0 +1,67 @@
+# @polyskill/cli
+
+**The CLI for [PolySkill](https://polyskill.ai) — the open registry for AI agent skills.** Search, install, create, and publish portable, LLM-agnostic skills for Claude Code, Codex, OpenCode, OpenClaw, and any agent.
+
+## Install
+
+```bash
+npm install -g @polyskill/cli
+```
+
+## Usage
+
+```bash
+# Search for skills
+polyskill search "code review"
+
+# Install a skill (auto-detects your coding assistant)
+polyskill install @polyskill/getting-started
+
+# Create a new skill
+polyskill init my-skill
+
+# Authenticate and publish
+polyskill login                    # GitHub PAT or agent API key
+polyskill validate my-skill
+polyskill build my-skill
+polyskill publish my-skill
+
+# Or register as an agent
+polyskill agent register
+```
+
+## Install Targets
+
+The CLI auto-detects which coding assistant you have and installs skills in the right format. Override with `--target <runtime>`.
+
+| Target | Directory | Format |
+|--------|-----------|--------|
+| `claude-code` | `~/.claude/skills/<slug>/` | `SKILL.md` |
+| `codex` | `~/.codex/skills/<slug>/` | `SKILL.md` |
+| `openclaw` | `~/.openclaw/skills/<slug>/` | `SKILL.md` |
+| `opencode` | `~/.config/opencode/skills/<slug>/` | `SKILL.md` |
+| `local` | `./skills/@scope__name/` | `skill.json` + `instructions.md` + `tools.json` + `dist/` |
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `polyskill init [dir]` | Scaffold a new skill project |
+| `polyskill validate [dir]` | Validate manifest + tools against the spec |
+| `polyskill build [dir]` | Generate platform adapter outputs |
+| `polyskill publish [dir]` | Publish to the PolySkill registry |
+| `polyskill install <name> [version]` | Install a skill from the registry |
+| `polyskill search [query]` | Search the registry |
+| `polyskill login` / `logout` | Manage authentication |
+| `polyskill agent register` | Register an agent and get an API key |
+
+## Links
+
+- **Browse skills**: [polyskill.ai](https://polyskill.ai)
+- **Docs**: [polyskill.ai/docs](https://polyskill.ai/docs)
+- **Source & issues**: [github.com/MrSpacemann/polyskill](https://github.com/MrSpacemann/polyskill)
+- **Skill format & programmatic use**: [`@polyskill/core`](https://www.npmjs.com/package/@polyskill/core)
+
+## License
+
+MIT

packages/cli/package.json

@@ -2,6 +2,27 @@
   "name": "@polyskill/cli",
   "version": "0.1.13",
   "description": "CLI for creating, validating, and publishing PolySkill skills",
+  "license": "MIT",
+  "homepage": "https://polyskill.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MrSpacemann/polyskill.git",
+    "directory": "packages/cli"
+  },
+  "bugs": "https://github.com/MrSpacemann/polyskill/issues",
+  "keywords": [
+    "polyskill",
+    "skills",
+    "llm",
+    "agents",
+    "claude-code",
+    "codex",
+    "opencode",
+    "cli"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -15,20 +36,22 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
+    "@inquirer/prompts": "^7.10.1",
     "@polyskill/core": "workspace:*",
-    "commander": "^13.0.0",
-    "chalk": "^5.4.0",
-    "@inquirer/prompts": "^7.0.0",
-    "tar": "^7.4.3"
+    "chalk": "^5.6.2",
+    "commander": "^13.1.0",
+    "tar": "^7.5.19"
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
-    "typescript": "^5.7.0",
-    "tsx": "^4.19.0",
-    "@types/node": "^22.0.0",
-    "vitest": "^3.0.0"
+    "@types/node": "^22.20.0",
+    "tsx": "^4.22.5",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.6"
   }
 }

packages/cli/src/__tests__/install.test.ts

@@ -228,6 +228,36 @@ describe("install command", () => {
   });
 });
 
+describe("install command — name validation", () => {
+  it("rejects a non-scoped name before any network call", async () => {
+    await expect(
+      installCommand.parseAsync(["not-scoped", "--output", "/tmp/output"], {
+        from: "user",
+      })
+    ).rejects.toMatchObject({ code: 1 });
+
+    expect(fetch).not.toHaveBeenCalled();
+    expect(console.log).toHaveBeenCalledWith(
+      expect.stringContaining("Invalid skill name")
+    );
+  });
+
+  it("rejects a malformed name in the registry response before writing files", async () => {
+    mockFetchResponse(200, { ...fullSkillResponse, name: "..\\..\\evil" });
+
+    await expect(
+      installCommand.parseAsync(["@test/my-skill", "--output", "/tmp/output"], {
+        from: "user",
+      })
+    ).rejects.toMatchObject({ code: 1 });
+
+    expect(writeFile).not.toHaveBeenCalled();
+    expect(console.log).toHaveBeenCalledWith(
+      expect.stringContaining("malformed skill name")
+    );
+  });
+});
+
 describe("install command — npm mirror fallback", () => {
   it("falls back to npm when registry returns 403 (sandbox block)", async () => {
     vi.mocked(fetch).mockResolvedValueOnce({

packages/cli/src/__tests__/search.test.ts

@@ -142,6 +142,39 @@ describe("search command", () => {
     expect(process.exit).toHaveBeenCalledWith(1);
   });
 
+  it("includes the HTTP status even when statusText is empty (HTTP/2)", async () => {
+    vi.mocked(fetch).mockResolvedValue({
+      ok: false,
+      status: 502,
+      statusText: "",
+      json: () => Promise.resolve({}),
+    } as Response);
+
+    await expect(
+      searchCommand.parseAsync(["weather"], { from: "user" })
+    ).rejects.toThrow(ExitError);
+
+    expect(console.log).toHaveBeenCalledWith(expect.stringContaining("502"));
+  });
+
+  it("prints error and exits when the registry returns invalid JSON", async () => {
+    vi.mocked(fetch).mockResolvedValue({
+      ok: true,
+      status: 200,
+      statusText: "OK",
+      json: () => Promise.reject(new SyntaxError("Unexpected token <")),
+    } as Response);
+
+    await expect(
+      searchCommand.parseAsync(["weather"], { from: "user" })
+    ).rejects.toThrow(ExitError);
+
+    expect(console.log).toHaveBeenCalledWith(
+      expect.stringContaining("invalid response from registry")
+    );
+    expect(process.exit).toHaveBeenCalledWith(1);
+  });
+
   it("passes --category filter to the API", async () => {
     mockFetchResponse(200, { skills: [], total: 0 });
 

packages/cli/src/commands/install.ts

@@ -1,14 +1,20 @@
 /*
  * Install flow state machine (source of truth — keep in sync with logic):
  *
- *   FETCH_REGISTRY
- *     ├─ res.ok ─────────────────────────────────→ HAVE_SKILL
- *     ├─ status == 404 ──────────────────────────→ NOT_FOUND (exit 1)
- *     └─ throw | status 403 | status 5xx ────────→ FETCH_NPM
- *                                                    ├─ ok ──────→ HAVE_SKILL
+ *   VALIDATE_NAME (typed arg)
+ *     ├─ invalid ────────────────────────────────→ BAD_NAME (exit 1)
+ *     └─ ok ──→ FETCH_REGISTRY
+ *                 ├─ res.ok ─────────────────────→ CHECK_NAME
+ *                 ├─ status == 404 ──────────────→ NOT_FOUND (exit 1)
+ *                 └─ throw | status 403 | 5xx ───→ FETCH_NPM
+ *                                                    ├─ ok ──────→ CHECK_NAME
  *                                                    └─ NpmNotFound
  *                                                       | throw ─→ BOTH_FAILED (exit 1)
  *
+ *   CHECK_NAME (response name shapes fs paths)
+ *     ├─ malformed ──────────────────────────────→ BAD_RESPONSE (exit 1)
+ *     └─ ok ──→ HAVE_SKILL
+ *
  *   HAVE_SKILL ──→ RESOLVE_TARGET ──→ WRITE_FILES ──→ SUCCESS
  *                       │                  └──→ WRITE_ERR (EACCES, ENOSPC, ...)
  *                       └──→ UNKNOWN_TARGET / AMBIGUOUS_TARGET
@@ -23,6 +29,7 @@ import chalk from "chalk";
 import { REGISTRY_URL } from "../config.js";
 import { resolveTarget } from "../targets/index.js";
 import { fetchSkillFromNpm, NpmNotFound } from "../npmFetch.js";
+import { SKILL_NAME_RE } from "../npmName.js";
 
 export const installCommand = new Command("install")
   .description("Install a Skill from the PolySkill registry")
@@ -42,6 +49,14 @@ export const installCommand = new Command("install")
     ) => {
       const registryUrl = options.registry;
 
+      if (!SKILL_NAME_RE.test(name)) {
+        console.log(
+          chalk.red(`\nInvalid skill name: ${name}`) +
+            chalk.dim("\nExpected @scope/name (lowercase letters, digits, hyphens)\n")
+        );
+        process.exit(1);
+      }
+
       console.log(chalk.bold(`\nInstalling ${name}${version ? `@${version}` : ""}...`));
 
       // Fetch from registry
@@ -95,6 +110,13 @@ export const installCommand = new Command("install")
         }
       }
 
+      // The response's name is used to build filesystem paths — never write
+      // anywhere a malformed/hostile response could point (e.g. `..` segments).
+      if (typeof skill.name !== "string" || !SKILL_NAME_RE.test(skill.name)) {
+        console.log(chalk.red(`\nRegistry returned a malformed skill name: ${skill.name}\n`));
+        process.exit(1);
+      }
+
       // Resolve target (--target flag, --output implies local, or auto-detect)
       const target = resolveTarget(options.target, options.output !== undefined);
       const outputDir = resolve(process.cwd(), options.output ?? ".");

packages/cli/src/commands/publish.ts

@@ -56,6 +56,8 @@ export const publishCommand = new Command("publish")
       const adapter = getAdapter(platform);
       if (adapter) {
         adapters[platform] = adapter.transpile(skill);
+      } else {
+        console.log(chalk.yellow(`  Skipping unknown adapter: ${platform}`));
       }
     }
 

packages/cli/src/commands/search.ts

@@ -80,11 +80,19 @@ export const searchCommand = new Command("search")
       }
 
       if (!res.ok) {
-        console.log(chalk.red(`\nSearch failed: ${res.statusText}\n`));
+        // statusText is empty over HTTP/2 — always include the numeric status
+        const reason = res.statusText ? `${res.status} ${res.statusText}` : `HTTP ${res.status}`;
+        console.log(chalk.red(`\nSearch failed: ${reason}\n`));
         process.exit(1);
       }
 
-      const data = (await res.json()) as SearchResponse;
+      let data: SearchResponse;
+      try {
+        data = (await res.json()) as SearchResponse;
+      } catch {
+        console.log(chalk.red("\nSearch failed: invalid response from registry\n"));
+        process.exit(1);
+      }
 
       // JSON mode: dump raw response and exit
       if (options.json) {