skillmds 0.1.0 → 1.0.0

package/README.md

@@ -0,0 +1,128 @@
+<p align="center">
+  <img src="https://skillmd.com/skillmd-banner.jpg" alt="SkillMD" width="640">
+</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.
+
+This one package ships two tools:
+
+- **`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.*
+
+---
+
+## CLI quick start
+
+```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
+```
+
+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):
+
+```bash
+claude mcp add skillmds -- npx -y skillmds
+```
+
+**Claude Desktop / Cursor / any MCP client** — add to your MCP config:
+
+```jsonc
+{
+  "mcpServers": {
+    "skillmds": {
+      "command": "npx",
+      "args": ["-y", "skillmds"]
+    }
+  }
+}
+```
+
+That's it. Restart your client and the SkillMD tools are available.
+
+---
+
+## What you can do
+
+Once connected, just ask your agent in plain language:
+
+- *"Find a skill for optimizing Dockerfiles."*
+- *"Install the anthropic/pdf skill."*
+- *"What are the top-rated data skills right now?"*
+
+The agent picks the right tool, fetches the skill from SkillMD, and writes it into your skills directory.
+
+## Tools
+
+| 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`. |
+
+By default, `skillmd_install` writes to `~/.claude/skills/<name>/SKILL.md`. Pass a `dest` to target another directory.
+
+## Configuration
+
+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. |
+
+Example with a token:
+
+```jsonc
+{
+  "mcpServers": {
+    "skillmds": {
+      "command": "npx",
+      "args": ["-y", "skillmds"],
+      "env": { "SKILLMD_TOKEN": "skillmd_pat_…" }
+    }
+  }
+}
+```
+
+## 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.
+
+## Requirements
+
+- Node.js **18+**
+
+## Links
+
+- 🌐 Registry: **[skillmd.com](https://skillmd.com)**
+- 🧩 What is an Agent Skill? See the [FAQ](https://skillmd.com/#faq)
+
+## License
+
+MIT

package/bin/skillmd-mcp.mjs

@@ -14,6 +14,14 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprot
 import { mkdir, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
+// 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;
+try {
+  ({ lint } = await import("../vendor/index.js"));
+} catch {
+  /* skillmd_lint will report that validation is unavailable */
+}
 
 const API = process.env.SKILLMD_API || "https://skillmd-api.vinoor.workers.dev";
 const TOKEN = process.env.SKILLMD_TOKEN || "";
@@ -86,6 +94,18 @@ const TOOLS = [
     description: "List the signed-in user's saved skills. Requires SKILLMD_TOKEN to be set.",
     inputSchema: { type: "object", properties: {} },
   },
+  {
+    name: "skillmd_lint",
+    description:
+      "Validate a SKILL.md against the SkillMD spec and return diagnostics, security flags, and a quality score (0-100). Pass raw SKILL.md content, or a registry slug (owner/name) to fetch and lint.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        content: { type: "string", description: "Raw SKILL.md content to validate" },
+        slug: { type: "string", description: "Registry slug owner/name to fetch and validate" },
+      },
+    },
+  },
 ];
 
 function reconstructSkillMd(skill) {
@@ -134,6 +154,20 @@ async function handleCall(name, args) {
       const r = await api(`/api/favorites`);
       return text(r.items ?? []);
     }
+    case "skillmd_lint": {
+      if (!lint) return text("Validation engine unavailable — run `npm run build` in the skillmds package.");
+      let raw = args.content;
+      let slug;
+      if (!raw && args.slug) {
+        const [owner, slugName] = String(args.slug).split("/");
+        const skill = await api(`/api/skills/${owner}/${slugName}`);
+        raw = reconstructSkillMd(skill);
+        slug = slugName;
+      }
+      if (!raw) return text("Provide `content` (raw SKILL.md) or `slug` (owner/name).");
+      const result = lint(raw, slug ? { slug } : {});
+      return text({ ok: result.ok, score: result.score, diagnostics: result.diagnostics, security: result.security });
+    }
     case "skillmd_install": {
       const [owner, slugName] = String(args.slug).split("/");
       const skill = await api(`/api/skills/${owner}/${slugName}`);
@@ -153,7 +187,7 @@ async function handleCall(name, args) {
   }
 }
 
-const server = new Server({ name: "skillmd", version: "0.1.0" }, { capabilities: { tools: {} } });
+const server = new Server({ name: "skillmd", version: "1.0.0" }, { capabilities: { tools: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
 server.setRequestHandler(CallToolRequestSchema, async (req) => {
   try {

package/bin/skillmd.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// The `skillmd` CLI, shipped inside the `skillmds` package.
+import("../dist/cli.js");