skillmds 1.0.1 → 1.0.3

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to `skillmds` are documented here. Versions follow [semver](https://semver.org).
+
+## 1.0.3
+
+- CLI (`skillmd`) and MCP server (`skillmds`) now report their version from `package.json` instead of a hardcoded string.
+- READMEs rewritten; added this changelog.
+
+## 1.0.2
+
+- `skillmd lint`: skip directories that cannot be read (e.g. `EPERM` on protected system folders) instead of aborting the scan.
+
+## 1.0.1
+
+- Fix `skillmd_lint` in the MCP server: keep `yaml` external in the bundled engine so it loads at runtime (bundling a CommonJS module into ESM raised `Dynamic require of "process"`).
+
+## 1.0.0
+
+- Add the `skillmd` CLI, shipped alongside the MCP server in this package. Commands: `lint`/`check`, `scan`, `rules`, `init`, `search`, `add`, `list`, `remove`, `update`, `publish`/`submit`, `login`, `logout`.
+- Validation engine shared with the SkillMD registry: `SKILL.md` parser, lint rules `SK001`–`SK040`, security scan, quality score, and `text`/`json`/`sarif`/`github` output.
+- Add the `skillmd_lint` MCP tool.
+- MCP server and CLI authenticate with `Authorization: Bearer` tokens.
+
+## 0.1.1
+
+- Initial MCP server: `skillmd_search`, `skillmd_get`, `skillmd_install`, `skillmd_trending`, `skillmd_recommend`, `skillmd_list_saved`.

package/README.md

@@ -1,127 +1,111 @@
 <p align="center">
-  <img src="https://skillmd.com/skillmd-banner.jpg" alt="SkillMD" width="640">
+  <img src="https://skillmd.com/skillmd-banner.jpg" alt="SkillMD" width="560">
 </p>
 
 # skillmds
 
 [![npm version](https://img.shields.io/npm/v/skillmds.svg)](https://www.npmjs.com/package/skillmds)
-[![npm downloads](https://img.shields.io/npm/dm/skillmds.svg)](https://www.npmjs.com/package/skillmds)
 [![license](https://img.shields.io/npm/l/skillmds.svg)](#license)
 
-> SkillMD for agents — the official **MCP server** *and* the **`skillmd` CLI** for **[SkillMD](https://skillmd.com)**, the open, verified registry of Agent Skills.
+Tools for working with [Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills) (`SKILL.md`) from the [SkillMD](https://skillmd.com) registry. One package, two binaries:
 
-This one package ships two tools:
+- **`skillmd`** — a CLI to lint, scan, search, install, and publish skills.
+- **`skillmds`** — an MCP server exposing the registry to MCP clients (Claude Code, Claude Desktop, Cursor, …).
 
-- **`skillmds`** — an MCP server so any MCP-capable agent (Claude Code, Claude Desktop, Cursor, …) can search, fetch, validate, and install `SKILL.md` skills with no copy-paste.
-- **`skillmd`** — a CLI that lints and security-scans skills before installing or publishing them. *The registry that lints.*
+Both validate `SKILL.md` with the same engine, so the CLI and the registry apply identical rules.
 
----
-
-## CLI quick start
+## Install
 
 ```bash
-npm i -g skillmds        # installs the `skillmd` command (and `skillmds`)
-
-skillmd lint ./my-skill            # validate against the spec + quality score
-skillmd lint . --format sarif      # SARIF for GitHub Code Scanning
-skillmd scan . --deny executes_scripts
-skillmd search pdf --verified
-skillmd add anthropic/pdf -a claude-code -g   # lints before installing
-skillmd init my-skill
-skillmd login && skillmd publish ./my-skill   # refuses to publish on lint errors
+npm i -g skillmds
 ```
 
-Without a global install, run a one-off with `npx -p skillmds skillmd lint .`.
-Commands: `lint`/`check`, `scan`, `rules`, `init`, `search`, `add`, `list`, `remove`, `update`, `publish`, `login`. All support `--json`.
-
----
-
-## MCP server
-
-## Install
-
-**Claude Code** (one line):
+This installs both the `skillmd` and `skillmds` commands. To run the CLI without installing:
 
 ```bash
-claude mcp add skillmds -- npx -y skillmds
+npx -p skillmds skillmd lint .
 ```
 
-**Claude Desktop / Cursor / any MCP client** — add to your MCP config:
+## CLI: `skillmd`
 
-```jsonc
-{
-  "mcpServers": {
-    "skillmds": {
-      "command": "npx",
-      "args": ["-y", "skillmds"]
-    }
-  }
-}
-```
+| Command | Description |
+|---|---|
+| `skillmd lint [path]` (`check`) | Validate `SKILL.md` files; print diagnostics and a quality score. |
+| `skillmd scan [path]` | Report scripts, network calls, and secret access. |
+| `skillmd rules [id]` | List lint rules, or show one. |
+| `skillmd init [name]` | Create a `SKILL.md` from a template. |
+| `skillmd search <query>` | Search the registry. |
+| `skillmd add <source>` | Install a skill (registry slug, GitHub repo, or local path). Lints before writing. |
+| `skillmd list` (`ls`) | List installed skills. |
+| `skillmd remove <names...>` (`rm`) | Remove installed skills. |
+| `skillmd update [names...]` | Update installed skills from the registry. |
+| `skillmd publish [path]` (`submit`) | Publish to the registry. Exits non-zero on lint errors. |
+| `skillmd login` / `logout` | Store or remove a token. |
 
-That's it. Restart your client and the SkillMD tools are available.
+All commands accept `--json`.
 
----
+### lint
 
-## What you can do
+```bash
+skillmd lint ./my-skill
+skillmd lint . --format sarif > skillmd.sarif
+skillmd lint . --strict
+skillmd lint . --fix
+```
 
-Once connected, just ask your agent in plain language:
+Formats: `text` (default), `json`, `sarif` (GitHub Code Scanning), `github` (Actions annotations).
+Exit codes: `0` clean, `1` errors (or warnings with `--strict` / `--fail-on-warning`), `2` usage error.
 
-- *"Find a skill for optimizing Dockerfiles."*
-- *"Install the anthropic/pdf skill."*
-- *"What are the top-rated data skills right now?"*
+### add
 
-The agent picks the right tool, fetches the skill from SkillMD, and writes it into your skills directory.
+```bash
+skillmd add anthropic/pdf                 # registry slug (verified-only by default)
+skillmd add owner/repo                     # GitHub repo
+skillmd add ./path                         # local
+skillmd add anthropic/pdf -a claude-code -g
+skillmd add some/skill --deny executes_scripts
+skillmd add some/skill --skip-lint
+```
 
-## Tools
+### publish
 
-| Tool | Auth | What it does |
-| --- | --- | --- |
-| `skillmd_search` | – | Search skills by name, description, or task (filter by category, type, rating, verified). |
-| `skillmd_get` | – | Fetch one skill by `owner/name`, with its `SKILL.md`, provenance, license, and security flags. |
-| `skillmd_install` | – | Write a skill's `SKILL.md` into your agent's skills dir. **Never executes scripts.** |
-| `skillmd_trending` | – | Top skills on the leaderboard (`30d` or `all`, optional category). |
-| `skillmd_recommend` | – | Skills similar to one you give, or trending if none. |
-| `skillmd_list_saved` | token | Your saved skills (requires `SKILLMD_TOKEN`). |
-| `skillmd_lint` | – | Validate a SKILL.md against the spec; returns diagnostics, security flags, and a quality score (0-100). Pass `content` or a `slug`. |
+```bash
+skillmd login                # store a token from your skillmd.com account
+skillmd publish ./my-skill   # blocked on lint errors
+skillmd publish ./my-skill --dry-run
+skillmd publish ./my-skill --force   # publish despite warnings; never bypasses errors
+```
 
-By default, `skillmd_install` writes to `~/.claude/skills/<name>/SKILL.md`. Pass a `dest` to target another directory.
+## MCP server: `skillmds`
 
-## Configuration
+Claude Code:
 
-Both are optional environment variables:
-
-| Variable | Default | Purpose |
-| --- | --- | --- |
-| `SKILLMD_API` | `https://skillmd-api.vinoor.workers.dev` | Override the API base URL. |
-| `SKILLMD_TOKEN` | – | SkillMD personal access token; enables `skillmd_list_saved` and personalized recommendations. |
+```bash
+claude mcp add skillmds -- npx -y skillmds
+```
 
-Example with a token:
+Other MCP clients:
 
 ```jsonc
 {
   "mcpServers": {
-    "skillmds": {
-      "command": "npx",
-      "args": ["-y", "skillmds"],
-      "env": { "SKILLMD_TOKEN": "skillmd_pat_…" }
-    }
+    "skillmds": { "command": "npx", "args": ["-y", "skillmds"] }
   }
 }
 ```
 
-## Safety
-
-SkillMD shows security flags (executes scripts, network calls, reads secrets, or docs-only) parsed from every skill's files, and **this server never runs a skill's scripts** — `skillmd_install` only writes the `SKILL.md` to disk. Review a skill before relying on it, especially from unverified authors.
+Tools: `skillmd_search`, `skillmd_get`, `skillmd_install`, `skillmd_trending`, `skillmd_recommend`, `skillmd_list_saved`, `skillmd_lint`. `skillmd_install` writes a skill's `SKILL.md` and never executes scripts.
 
-## Requirements
+## Configuration
 
-- Node.js **18+**
+Resolution order, highest first:
 
-## Links
+| Setting | Sources |
+|---|---|
+| Token | `--token` → `SKILLMD_TOKEN` → `~/.skillmd/config.json` |
+| API base | `--api` → `SKILLMD_API` → default registry |
 
-- 🌐 Registry: **[skillmd.com](https://skillmd.com)**
-- 🧩 What is an Agent Skill? See the [FAQ](https://skillmd.com/#faq)
+`SKILLMD_TOKEN` enables `skillmd_list_saved`, personalized recommendations, and publishing.
 
 ## License
 

package/bin/skillmd-mcp.mjs

@@ -12,8 +12,17 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { mkdir, writeFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
+
+const VERSION = (() => {
+  try {
+    return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+  } catch {
+    return "0.0.0";
+  }
+})();
 // Shared validation engine, bundled into ./vendor at publish time (npm run build).
 // Falls back gracefully if the vendor build is absent (e.g. running from source).
 let lint = null;
@@ -187,7 +196,7 @@ async function handleCall(name, args) {
   }
 }
 
-const server = new Server({ name: "skillmd", version: "1.0.1" }, { capabilities: { tools: {} } });
+const server = new Server({ name: "skillmd", version: VERSION }, { capabilities: { tools: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
 server.setRequestHandler(CallToolRequestSchema, async (req) => {
   try {

package/dist/cli.js

@@ -1,5 +1,6 @@
 // ../cli/src/index.ts
 import { Command as Command12 } from "commander";
+import { readFileSync as readFileSync4 } from "fs";
 
 // ../cli/src/commands/lint.ts
 import { Command } from "commander";
@@ -275,7 +276,13 @@ import { join, basename, dirname } from "path";
 var IGNORE_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", ".wrangler"]);
 function findSkillFiles(dir) {
   const out = [];
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
     if (entry.isDirectory()) {
       if (IGNORE_DIRS.has(entry.name)) continue;
       out.push(...findSkillFiles(join(dir, entry.name)));
@@ -914,7 +921,12 @@ function logoutCommand() {
 }
 
 // ../cli/src/index.ts
-var program = new Command12("skillmd").version("1.0.0").description("The registry that lints. Discover, validate, and install verified Agent Skills.").option("--json", "machine-readable output").option("--token <token>", "SkillMD personal access token").option("--api <url>", "override the registry API base URL");
+var version = "0.0.0";
+try {
+  version = JSON.parse(readFileSync4(new URL("../package.json", import.meta.url), "utf8")).version;
+} catch {
+}
+var program = new Command12("skillmd").version(version).description("Lint, validate, and install Agent Skills from the SkillMD registry.").option("--json", "machine-readable output").option("--token <token>", "SkillMD personal access token").option("--api <url>", "override the registry API base URL");
 program.addCommand(lintCommand());
 program.addCommand(scanCommand());
 program.addCommand(rulesCommand());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillmds",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "SkillMD for agents: the `skillmds` MCP server + the `skillmd` CLI (lint, scan, search, install, publish Agent Skills) from skillmd.com.",
   "type": "module",
   "bin": {
@@ -27,7 +27,7 @@
   "bugs": { "url": "https://skillmd.com/contact" },
   "author": "SkillMD",
   "license": "MIT",
-  "files": ["bin", "dist", "vendor", "README.md"],
+  "files": ["bin", "dist", "vendor", "README.md", "CHANGELOG.md"],
   "engines": { "node": ">=18" },
   "dependencies": {
     "@clack/prompts": "^0.8.0",