skillmds 1.0.2 → 1.0.4

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to `skillmds` are documented here. Versions follow [semver](https://semver.org).
+
+## 1.0.4
+
+- `skillmd lint`/`scan` print a progress line to stderr and warn when scanning a home directory, so a directory scan never looks like a frozen blank screen.
+- Directory scans skip large build/OS directories (`AppData`, `node_modules`, `target`, …) and cap recursion depth, so `lint .` in a big tree terminates quickly.
+- Clearer message when no `SKILL.md` is found.
+- Bare `skillmd` (no command) prints help.
+
+## 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,9 +1,12 @@
 // ../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";
 import { writeFileSync } from "fs";
+import { homedir } from "os";
+import { resolve } from "path";
 
 // ../../packages/core/src/parse.ts
 import { parse as parseYaml } from "yaml";
@@ -272,9 +275,35 @@ function toGithub(results) {
 import { existsSync, statSync, readFileSync, readdirSync, mkdtempSync } from "fs";
 import { tmpdir } from "os";
 import { join, basename, dirname } from "path";
-var IGNORE_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", ".wrangler"]);
-function findSkillFiles(dir) {
+var IGNORE_DIRS = /* @__PURE__ */ new Set([
+  // build/dependency dirs
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  "out",
+  ".next",
+  ".wrangler",
+  ".cache",
+  ".npm",
+  ".pnpm-store",
+  ".venv",
+  "venv",
+  "__pycache__",
+  "target",
+  "vendor",
+  // large OS / user dirs (mostly relevant when run from a home directory)
+  "AppData",
+  "Library",
+  "$Recycle.Bin",
+  "System Volume Information",
+  "Windows",
+  "Program Files"
+]);
+var MAX_DEPTH = 12;
+function findSkillFiles(dir, depth = 0) {
   const out = [];
+  if (depth > MAX_DEPTH) return out;
   let entries;
   try {
     entries = readdirSync(dir, { withFileTypes: true });
@@ -284,7 +313,7 @@ function findSkillFiles(dir) {
   for (const entry of entries) {
     if (entry.isDirectory()) {
       if (IGNORE_DIRS.has(entry.name)) continue;
-      out.push(...findSkillFiles(join(dir, entry.name)));
+      out.push(...findSkillFiles(join(dir, entry.name), depth + 1));
     } else if (entry.name === "SKILL.md") {
       out.push(join(dir, entry.name));
     }
@@ -303,7 +332,9 @@ async function resolveSource(arg) {
     const st = statSync(arg);
     if (st.isFile()) return [loadLocal(arg)];
     const files2 = findSkillFiles(arg);
-    if (files2.length === 0) throw new Error(`No SKILL.md found under ${arg}`);
+    if (files2.length === 0) {
+      throw new Error(`No SKILL.md found under ${arg}. Point at a skill directory, e.g. "skillmd lint ./my-skill", or run "skillmd init" to create one.`);
+    }
     return files2.map(loadLocal);
   }
   const { downloadTemplate } = await import("giget");
@@ -388,6 +419,11 @@ async function runLint(target, flags) {
 }
 function lintCommand() {
   return new Command("lint").alias("check").description("Validate SKILL.md file(s) against the spec and report a quality score").argument("[target]", "local path or GitHub source", ".").option("--format <fmt>", "text | json | sarif | github", "text").option("--strict", "treat warnings as errors").option("--fail-on-warning", "exit non-zero when warnings exist").option("--fix", "apply safe automatic fixes (e.g. add missing license)").action(async (target, opts) => {
+    if (resolve(target) === homedir()) {
+      process.stderr.write("Warning: scanning your entire home directory. Pass a narrower path, e.g. skillmd lint ./my-skill\n");
+    }
+    process.stderr.write(`Looking for SKILL.md under ${target} \u2026
+`);
     const run = await runLint(target, opts);
     console.log(run.output);
     process.exitCode = run.exitCode;
@@ -521,11 +557,11 @@ import pc4 from "picocolors";
 
 // ../cli/src/config.ts
 import { readFileSync as readFileSync2, writeFileSync as writeFileSync3, mkdirSync as mkdirSync2 } from "fs";
-import { homedir } from "os";
+import { homedir as homedir2 } from "os";
 import { join as join3 } from "path";
 var DEFAULT_API = "https://skillmd-api.vinoor.workers.dev";
 function configPath() {
-  return join3(homedir(), ".skillmd", "config.json");
+  return join3(homedir2(), ".skillmd", "config.json");
 }
 function readConfig() {
   try {
@@ -535,7 +571,7 @@ function readConfig() {
   }
 }
 function writeConfig(cfg) {
-  const dir = join3(homedir(), ".skillmd");
+  const dir = join3(homedir2(), ".skillmd");
   mkdirSync2(dir, { recursive: true });
   writeFileSync3(configPath(), JSON.stringify(cfg, null, 2), { encoding: "utf8", mode: 384 });
 }
@@ -604,8 +640,8 @@ import pc5 from "picocolors";
 
 // ../cli/src/agents.ts
 import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync4, rmSync, symlinkSync, existsSync as existsSync3, readdirSync as readdirSync2, statSync as statSync2, readFileSync as readFileSync3 } from "fs";
-import { homedir as homedir2 } from "os";
-import { join as join4, resolve, dirname as dirname2 } from "path";
+import { homedir as homedir3 } from "os";
+import { join as join4, resolve as resolve2, dirname as dirname2 } from "path";
 var AGENTS = [
   { id: "claude-code", segments: [".claude", "skills"] },
   { id: "cursor", segments: [".cursor", "skills"] },
@@ -616,7 +652,7 @@ var AGENTS = [
 function agentDir(agentId, opts = {}) {
   const agent = AGENTS.find((a) => a.id === agentId);
   if (!agent) throw new Error(`Unknown agent: ${agentId}. Known: ${AGENTS.map((a) => a.id).join(", ")}`);
-  const root = opts.global ? homedir2() : opts.cwd ?? process.cwd();
+  const root = opts.global ? homedir3() : opts.cwd ?? process.cwd();
   return join4(root, ...agent.segments);
 }
 function detectAgents(opts = {}) {
@@ -627,7 +663,7 @@ function writeSkill(skillName, files, targetDir, opts = {}) {
   if (opts.mode === "symlink" && opts.canonicalDir) {
     mkdirSync3(dirname2(dest), { recursive: true });
     rmSync(dest, { recursive: true, force: true });
-    symlinkSync(resolve(opts.canonicalDir), dest, "dir");
+    symlinkSync(resolve2(opts.canonicalDir), dest, "dir");
     return dest;
   }
   mkdirSync3(dest, { recursive: true });
@@ -920,7 +956,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());
@@ -933,6 +974,10 @@ program.addCommand(updateCommand());
 program.addCommand(publishCommand());
 program.addCommand(loginCommand());
 program.addCommand(logoutCommand());
+if (process.argv.slice(2).length === 0) {
+  program.outputHelp();
+  process.exit(0);
+}
 program.parseAsync(process.argv).catch((err) => {
   console.error(err instanceof Error ? err.message : String(err));
   process.exitCode = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillmds",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "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",