skillmds 1.1.1 → 1.1.2

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to `skillmds` are documented here. Versions follow [semver](https://semver.org).
 
+## 1.1.2
+
+- **MCP tool metadata.** Every tool now declares a `title`, `annotations` (all read-only except `skillmd_install`, none destructive), an `outputSchema`, and a description on every parameter; list-returning tools respond with `structuredContent: { items }`, `skillmd_lint` and `skillmd_install` return structured results, and refusals are flagged `isError`.
+- **Server metadata.** `initialize` reports a title, description, website URL, icons and usage instructions.
+- No behavior changes to what the tools do.
+
 ## 1.1.1
 
 - Releases are now published through npm Trusted Publishing (OIDC from GitHub Actions) with provenance; no long-lived npm tokens exist for this package.

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://cdn.jsdelivr.net/npm/skillmds/assets/skillmd-banner.jpg" alt="SkillMD" width="560">
+  <img src="https://skillmd.com/brand/banner.png" alt="SkillMD" width="560">
 </p>
 
 # skillmds

package/bin/skillmd-mcp.mjs

@@ -46,7 +46,17 @@ async function api(path, init = {}) {
   if (!res.ok) throw new Error(`SkillMD API ${res.status} on ${path}: ${await res.text().catch(() => "")}`);
   return res.json();
 }
-const text = (obj) => ({ content: [{ type: "text", text: typeof obj === "string" ? obj : JSON.stringify(obj, null, 2) }] });
+// Tool results carry both a text rendering and structuredContent matching the
+// tool's outputSchema. Arrays are wrapped as { items } so the structured payload
+// is always an object, as the spec requires. Plain strings are messages only.
+const text = (obj) => {
+  if (typeof obj === "string") return { content: [{ type: "text", text: obj }] };
+  const structured = Array.isArray(obj) ? { items: obj } : obj;
+  return { content: [{ type: "text", text: JSON.stringify(structured, null, 2) }], structuredContent: structured };
+};
+// A human-readable refusal/notice: text only, flagged as an error so clients do
+// not expect structuredContent for it.
+const notice = (msg) => ({ isError: true, content: [{ type: "text", text: msg }] });
 
 // The public API returns site-oriented fields (ratings, counters, avatars,
 // ranker internals) that are noise for an agent picking a skill. Strip them
@@ -67,76 +77,756 @@ const trimItems = (items) => (items ?? []).map((s) => Object.fromEntries(Object.
 
 const TOOLS = [
   {
-    name: "skillmd_search",
-    description: "Search SkillMD for Agent Skills by name, description, or task. Returns matching skills with their owner/name slug and install snippets.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        query: { type: "string", description: "Natural-language query or keywords" },
-        category: { type: "string", description: "Filter by category slug (e.g. devops, data, security)" },
-        verified_only: { type: "boolean", description: "Only verified skills" },
-        type: { type: "string", enum: ["single", "pack"], description: "single file or pack" },
-        min_rating: { type: "number", description: "Minimum average rating 0-5" },
-        limit: { type: "number", description: "Max results (default 20)" },
+    "name": "skillmd_search",
+    "title": "Search skills",
+    "description": "Search the SkillMD registry of Agent Skills (SKILL.md files) by task, name or keywords. Returns matching skills with their owner/name slug, description, category, safety verdict and install snippet, best match first.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "query": {
+          "type": "string",
+          "description": "Natural-language query or keywords describing the task or skill"
+        },
+        "category": {
+          "type": "string",
+          "description": "Restrict to one category slug, e.g. coding, devops, data, security"
+        },
+        "verified_only": {
+          "type": "boolean",
+          "description": "Return only skills from verified publishers (default false)"
+        },
+        "type": {
+          "type": "string",
+          "enum": [
+            "single",
+            "pack"
+          ],
+          "description": "Restrict to single-file skills or multi-file packs"
+        },
+        "min_rating": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 5,
+          "description": "Minimum average rating, 0 to 5"
+        },
+        "limit": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 100,
+          "description": "Maximum number of results (default 20)"
+        }
       },
-      required: ["query"],
+      "required": [
+        "query"
+      ],
+      "additionalProperties": false
     },
+    "outputSchema": {
+      "type": "object",
+      "properties": {
+        "items": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "description": "A skill as listed in search and leaderboard results.",
+            "properties": {
+              "slug": {
+                "type": "string",
+                "description": "owner/name identifier, e.g. anthropic/pdf"
+              },
+              "title": {
+                "type": "string",
+                "description": "Human-readable skill title"
+              },
+              "description": {
+                "type": "string",
+                "description": "What the skill does and when an agent should use it"
+              },
+              "category": {
+                "type": "string",
+                "description": "Category name"
+              },
+              "owner_handle": {
+                "type": "string",
+                "description": "Publisher handle"
+              },
+              "owner_name": {
+                "type": "string",
+                "description": "Publisher display name"
+              },
+              "license": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "SPDX license id when declared"
+              },
+              "security_flags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Capability flags: docs_only, network_calls, executes_scripts, reads_secrets, untrusted_install"
+              },
+              "ai_audit_verdict": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "Safety review verdict: pass, caution, warning, fail or inconclusive"
+              },
+              "repo_stars": {
+                "type": [
+                  "number",
+                  "null"
+                ],
+                "description": "GitHub stars of the source repository"
+              },
+              "install_snippet": {
+                "type": "string",
+                "description": "One-line install command"
+              }
+            },
+            "required": [
+              "slug"
+            ],
+            "additionalProperties": true
+          },
+          "description": "Matching skills, best first"
+        }
+      },
+      "required": [
+        "items"
+      ]
+    },
+    "annotations": {
+      "title": "Search skills",
+      "readOnlyHint": true,
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": false
+    }
   },
   {
-    name: "skillmd_get",
-    description: "Fetch a single skill by slug (owner/name), including its SKILL.md body, provenance, license and security flags.",
-    inputSchema: { type: "object", properties: { slug: { type: "string", description: "owner/name, e.g. anthropic/pdf" } }, required: ["slug"] },
+    "name": "skillmd_get",
+    "title": "Get skill details",
+    "description": "Fetch one skill by owner/name slug, including its SKILL.md body, provenance (source repo and pinned commit), license, safety verdict and capability flags.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "slug": {
+          "type": "string",
+          "pattern": "^[^/]+/[^/]+$",
+          "description": "Skill identifier as owner/name, e.g. anthropic/pdf"
+        }
+      },
+      "required": [
+        "slug"
+      ],
+      "additionalProperties": false
+    },
+    "outputSchema": {
+      "type": "object",
+      "description": "Full skill record.",
+      "properties": {
+        "slug": {
+          "type": "string",
+          "description": "owner/name identifier, e.g. anthropic/pdf"
+        },
+        "title": {
+          "type": "string",
+          "description": "Human-readable skill title"
+        },
+        "description": {
+          "type": "string",
+          "description": "What the skill does and when an agent should use it"
+        },
+        "category": {
+          "type": "string",
+          "description": "Category name"
+        },
+        "owner_handle": {
+          "type": "string",
+          "description": "Publisher handle"
+        },
+        "owner_name": {
+          "type": "string",
+          "description": "Publisher display name"
+        },
+        "license": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "SPDX license id when declared"
+        },
+        "security_flags": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Capability flags: docs_only, network_calls, executes_scripts, reads_secrets, untrusted_install"
+        },
+        "ai_audit_verdict": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Safety review verdict: pass, caution, warning, fail or inconclusive"
+        },
+        "repo_stars": {
+          "type": [
+            "number",
+            "null"
+          ],
+          "description": "GitHub stars of the source repository"
+        },
+        "install_snippet": {
+          "type": "string",
+          "description": "One-line install command"
+        },
+        "type": {
+          "type": "string",
+          "enum": [
+            "single",
+            "pack"
+          ],
+          "description": "single SKILL.md or a multi-file pack"
+        },
+        "body_md": {
+          "type": "string",
+          "description": "Markdown body of SKILL.md"
+        },
+        "raw_md": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Verbatim SKILL.md including frontmatter when stored"
+        },
+        "verified": {
+          "type": "boolean",
+          "description": "Published by a verified publisher"
+        },
+        "source_repo": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Upstream repository"
+        },
+        "commit_sha": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Pinned upstream commit"
+        },
+        "files": {
+          "type": "array",
+          "description": "Companion files for packs",
+          "items": {
+            "type": "object",
+            "additionalProperties": true
+          }
+        },
+        "tags": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": true
+          }
+        },
+        "categories": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": true
+          }
+        }
+      },
+      "required": [
+        "slug",
+        "title",
+        "description"
+      ],
+      "additionalProperties": true
+    },
+    "annotations": {
+      "title": "Get skill details",
+      "readOnlyHint": true,
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": false
+    }
   },
   {
-    name: "skillmd_install",
-    description:
-      "Install a skill by slug: writes its SKILL.md into the agent's skills directory. Never executes any scripts. Any skill installs; the response reports its security flags (docs_only / network_calls / executes_scripts / reads_secrets) as information.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        slug: { type: "string", description: "owner/name, e.g. anthropic/pdf" },
-        dest: { type: "string", description: "Target skills dir. Default ~/.claude/skills" },
+    "name": "skillmd_install",
+    "title": "Install skill",
+    "description": "Install a skill by owner/name slug: validates it, then writes SKILL.md (and companion files for packs, integrity-checked) into the agent's skills directory. Never executes scripts. The response reports the skill's capability flags (docs_only, network_calls, executes_scripts, reads_secrets) as information.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "slug": {
+          "type": "string",
+          "pattern": "^[^/]+/[^/]+$",
+          "description": "Skill identifier as owner/name, e.g. anthropic/pdf"
+        },
+        "dest": {
+          "type": "string",
+          "description": "Skills directory to write into (default ~/.claude/skills)"
+        }
+      },
+      "required": [
+        "slug"
+      ],
+      "additionalProperties": false
+    },
+    "outputSchema": {
+      "type": "object",
+      "properties": {
+        "installed": {
+          "type": "boolean",
+          "description": "Whether files were written"
+        },
+        "slug": {
+          "type": "string",
+          "description": "owner/name of the skill"
+        },
+        "dir": {
+          "type": "string",
+          "description": "Absolute directory the skill was written to"
+        },
+        "files_written": {
+          "type": "integer",
+          "description": "Number of files written"
+        },
+        "security_flags": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Capability flags reported for the skill"
+        },
+        "note": {
+          "type": "string",
+          "description": "Caveats, e.g. when only SKILL.md could be written"
+        }
       },
-      required: ["slug"],
+      "required": [
+        "installed",
+        "slug"
+      ]
     },
+    "annotations": {
+      "title": "Install skill",
+      "readOnlyHint": false,
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": false
+    }
   },
   {
-    name: "skillmd_trending",
-    description: "Top skills on the SkillMD leaderboard. range: '30d' or 'all'.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        range: { type: "string", enum: ["30d", "all"], description: "Time window (default all)" },
-        category: { type: "string", description: "Optional category slug" },
-        limit: { type: "number", description: "Max results (default 20)" },
+    "name": "skillmd_trending",
+    "title": "Trending skills",
+    "description": "Top skills on the SkillMD leaderboard, ranked by installs, saves and ratings, optionally within one category and time window.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "range": {
+          "type": "string",
+          "enum": [
+            "30d",
+            "all"
+          ],
+          "description": "Ranking window: last 30 days or all time (default all)"
+        },
+        "category": {
+          "type": "string",
+          "description": "Restrict to one category slug, e.g. coding, devops, data, security"
+        },
+        "limit": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 100,
+          "description": "Maximum number of results (default 20)"
+        }
+      },
+      "additionalProperties": false
+    },
+    "outputSchema": {
+      "type": "object",
+      "properties": {
+        "items": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "description": "A skill as listed in search and leaderboard results.",
+            "properties": {
+              "slug": {
+                "type": "string",
+                "description": "owner/name identifier, e.g. anthropic/pdf"
+              },
+              "title": {
+                "type": "string",
+                "description": "Human-readable skill title"
+              },
+              "description": {
+                "type": "string",
+                "description": "What the skill does and when an agent should use it"
+              },
+              "category": {
+                "type": "string",
+                "description": "Category name"
+              },
+              "owner_handle": {
+                "type": "string",
+                "description": "Publisher handle"
+              },
+              "owner_name": {
+                "type": "string",
+                "description": "Publisher display name"
+              },
+              "license": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "SPDX license id when declared"
+              },
+              "security_flags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Capability flags: docs_only, network_calls, executes_scripts, reads_secrets, untrusted_install"
+              },
+              "ai_audit_verdict": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "Safety review verdict: pass, caution, warning, fail or inconclusive"
+              },
+              "repo_stars": {
+                "type": [
+                  "number",
+                  "null"
+                ],
+                "description": "GitHub stars of the source repository"
+              },
+              "install_snippet": {
+                "type": "string",
+                "description": "One-line install command"
+              }
+            },
+            "required": [
+              "slug"
+            ],
+            "additionalProperties": true
+          },
+          "description": "Matching skills, best first"
+        }
       },
+      "required": [
+        "items"
+      ]
     },
+    "annotations": {
+      "title": "Trending skills",
+      "readOnlyHint": true,
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": false
+    }
   },
   {
-    name: "skillmd_recommend",
-    description: "Recommend skills. If based_on is given, suggests skills similar to it (same category); otherwise returns trending.",
-    inputSchema: {
-      type: "object",
-      properties: { based_on: { type: "string", description: "A slug to base recommendations on" }, limit: { type: "number" } },
+    "name": "skillmd_recommend",
+    "title": "Recommend skills",
+    "description": "Recommend skills. With based_on set to a skill's owner/name slug, returns the top skills in that skill's category (excluding itself); without it, returns what is trending over the last 30 days.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "based_on": {
+          "type": "string",
+          "pattern": "^[^/]+/[^/]+$",
+          "description": "Skill slug (owner/name) to base recommendations on"
+        },
+        "limit": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 100,
+          "description": "Maximum number of results (default 10)"
+        }
+      },
+      "additionalProperties": false
+    },
+    "outputSchema": {
+      "type": "object",
+      "properties": {
+        "items": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "description": "A skill as listed in search and leaderboard results.",
+            "properties": {
+              "slug": {
+                "type": "string",
+                "description": "owner/name identifier, e.g. anthropic/pdf"
+              },
+              "title": {
+                "type": "string",
+                "description": "Human-readable skill title"
+              },
+              "description": {
+                "type": "string",
+                "description": "What the skill does and when an agent should use it"
+              },
+              "category": {
+                "type": "string",
+                "description": "Category name"
+              },
+              "owner_handle": {
+                "type": "string",
+                "description": "Publisher handle"
+              },
+              "owner_name": {
+                "type": "string",
+                "description": "Publisher display name"
+              },
+              "license": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "SPDX license id when declared"
+              },
+              "security_flags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Capability flags: docs_only, network_calls, executes_scripts, reads_secrets, untrusted_install"
+              },
+              "ai_audit_verdict": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "Safety review verdict: pass, caution, warning, fail or inconclusive"
+              },
+              "repo_stars": {
+                "type": [
+                  "number",
+                  "null"
+                ],
+                "description": "GitHub stars of the source repository"
+              },
+              "install_snippet": {
+                "type": "string",
+                "description": "One-line install command"
+              }
+            },
+            "required": [
+              "slug"
+            ],
+            "additionalProperties": true
+          },
+          "description": "Matching skills, best first"
+        }
+      },
+      "required": [
+        "items"
+      ]
     },
+    "annotations": {
+      "title": "Recommend skills",
+      "readOnlyHint": true,
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": false
+    }
   },
   {
-    name: "skillmd_list_saved",
-    description: "List the signed-in user's saved skills. Requires SKILLMD_TOKEN to be set.",
-    inputSchema: { type: "object", properties: {} },
+    "name": "skillmd_list_saved",
+    "title": "List saved skills",
+    "description": "List the signed-in user's saved skills. Requires the SKILLMD_TOKEN environment variable (a SkillMD personal access token).",
+    "inputSchema": {
+      "type": "object",
+      "properties": {},
+      "additionalProperties": false
+    },
+    "outputSchema": {
+      "type": "object",
+      "properties": {
+        "items": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "description": "A skill as listed in search and leaderboard results.",
+            "properties": {
+              "slug": {
+                "type": "string",
+                "description": "owner/name identifier, e.g. anthropic/pdf"
+              },
+              "title": {
+                "type": "string",
+                "description": "Human-readable skill title"
+              },
+              "description": {
+                "type": "string",
+                "description": "What the skill does and when an agent should use it"
+              },
+              "category": {
+                "type": "string",
+                "description": "Category name"
+              },
+              "owner_handle": {
+                "type": "string",
+                "description": "Publisher handle"
+              },
+              "owner_name": {
+                "type": "string",
+                "description": "Publisher display name"
+              },
+              "license": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "SPDX license id when declared"
+              },
+              "security_flags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Capability flags: docs_only, network_calls, executes_scripts, reads_secrets, untrusted_install"
+              },
+              "ai_audit_verdict": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "Safety review verdict: pass, caution, warning, fail or inconclusive"
+              },
+              "repo_stars": {
+                "type": [
+                  "number",
+                  "null"
+                ],
+                "description": "GitHub stars of the source repository"
+              },
+              "install_snippet": {
+                "type": "string",
+                "description": "One-line install command"
+              }
+            },
+            "required": [
+              "slug"
+            ],
+            "additionalProperties": true
+          },
+          "description": "Matching skills, best first"
+        }
+      },
+      "required": [
+        "items"
+      ]
+    },
+    "annotations": {
+      "title": "List saved skills",
+      "readOnlyHint": true,
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": false
+    }
   },
   {
-    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" },
+    "name": "skillmd_lint",
+    "title": "Lint a SKILL.md",
+    "description": "Validate a SKILL.md against the SkillMD format and return diagnostics, capability flags and a 0-100 quality score. Pass raw SKILL.md content, or a registry slug (owner/name) to fetch and lint that skill.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "content": {
+          "type": "string",
+          "description": "Raw SKILL.md text to validate (frontmatter plus body)"
+        },
+        "slug": {
+          "type": "string",
+          "pattern": "^[^/]+/[^/]+$",
+          "description": "Registry skill (owner/name) to fetch and validate instead of content"
+        }
       },
+      "additionalProperties": false
     },
-  },
+    "outputSchema": {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "type": "boolean",
+          "description": "True when there are no error-level diagnostics"
+        },
+        "score": {
+          "type": "number",
+          "description": "Quality score 0-100"
+        },
+        "diagnostics": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "description": "Rule id, e.g. SK011"
+              },
+              "severity": {
+                "type": "string",
+                "enum": [
+                  "error",
+                  "warning",
+                  "info"
+                ]
+              },
+              "message": {
+                "type": "string"
+              },
+              "line": {
+                "type": [
+                  "integer",
+                  "null"
+                ]
+              }
+            },
+            "required": [
+              "id",
+              "severity",
+              "message"
+            ],
+            "additionalProperties": true
+          }
+        },
+        "security": {
+          "type": "object",
+          "description": "Scanner findings and capability flags",
+          "additionalProperties": true
+        }
+      },
+      "required": [
+        "ok",
+        "score",
+        "diagnostics"
+      ]
+    },
+    "annotations": {
+      "title": "Lint a SKILL.md",
+      "readOnlyHint": true,
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": false
+    }
+  }
 ];
 
 async function handleCall(name, args) {
@@ -174,12 +864,12 @@ async function handleCall(name, args) {
       return text(trimItems(r.items));
     }
     case "skillmd_list_saved": {
-      if (!TOKEN) return text("Set SKILLMD_TOKEN (a SkillMD personal access token) to list your saved skills.");
+      if (!TOKEN) return notice("Set SKILLMD_TOKEN (a SkillMD personal access token) to list your saved skills.");
       const r = await api(`/api/favorites`);
       return text(r.items ?? []);
     }
     case "skillmd_lint": {
-      if (!lint) return text("Validation engine unavailable — reinstall the skillmds package (npm i -g skillmds), or run `npm ci && npm run build` in a source checkout.");
+      if (!lint) return notice("Validation engine unavailable — reinstall the skillmds package (npm i -g skillmds), or run `npm ci && npm run build` in a source checkout.");
       let raw = args.content;
       let slug;
       let verified = false;
@@ -190,18 +880,18 @@ async function handleCall(name, args) {
         slug = slugName;
         verified = !!skill.verified;
       }
-      if (!raw) return text("Provide `content` (raw SKILL.md) or `slug` (owner/name).");
+      if (!raw) return notice("Provide `content` (raw SKILL.md) or `slug` (owner/name).");
       const result = lint(raw, { ...(slug ? { slug } : {}), verified });
       return text({ ok: result.ok, score: result.score, diagnostics: result.diagnostics, security: result.security });
     }
     case "skillmd_install": {
-      if (!skillMdFor) return text("skillmds is not fully installed — reinstall it (npm i -g skillmds) and try again.");
+      if (!skillMdFor) return notice("skillmds is not fully installed — reinstall it (npm i -g skillmds) and try again.");
       const [owner, slugName] = String(args.slug).split("/");
       // Defense in depth: slugName becomes a directory name below — refuse
       // anything outside the registry's slugify alphabet (path separators,
       // "..", etc.) before touching the network or filesystem.
       if (!/^[a-z0-9][a-z0-9-]*$/.test(slugName ?? "")) {
-        return text(`Refused: invalid skill name "${slugName}" — expected a lowercase slug.`);
+        return notice(`Refused: invalid skill name "${slugName}" — expected a lowercase slug.`);
       }
       const skill = await api(`/api/skills/${owner}/${slugName}`);
       const flags = skill.security_flags ?? [];
@@ -212,7 +902,7 @@ async function handleCall(name, args) {
         const result = lint(raw, { slug: slugName });
         if (!result.ok) {
           const errors = result.diagnostics.filter((d) => d.severity === "error");
-          return text(`Refused: ${args.slug} failed validation (${errors.map((d) => `${d.id}: ${d.message}`).join("; ")}). Not installed.`);
+          return notice(`Refused: ${args.slug} failed validation (${errors.map((d) => `${d.id}: ${d.message}`).join("; ")}). Not installed.`);
         }
       }
       const baseDir = args.dest ? resolve(args.dest) : join(homedir(), ".claude", "skills");
@@ -265,7 +955,7 @@ async function handleCall(name, args) {
           written = resolved.length || 1;
           if (!resolved.some((f) => f.path === "SKILL.md")) await writeSafe("SKILL.md", raw);
         } catch (e) {
-          if (e && e.integrity) return text(`Refused: ${args.slug} failed integrity verification — ${e.message}. Not installed.`);
+          if (e && e.integrity) return notice(`Refused: ${args.slug} failed integrity verification — ${e.message}. Not installed.`);
           await writeSafe("SKILL.md", raw);
           note = ` NOTE: pack assets could not be fetched — only SKILL.md was written. For the full pack run: npx skillmds add ${args.slug}`;
         }
@@ -273,7 +963,11 @@ async function handleCall(name, args) {
         await writeSafe("SKILL.md", raw);
       }
       api(`/api/skills/${owner}/${slugName}/install`, { method: "POST", body: JSON.stringify({ via: "mcp" }) }).catch(() => {});
-      return text(`Installed ${args.slug} → ${dir} (${written} file${written === 1 ? "" : "s"}; security: ${flags.join(", ") || "unscanned"})${note}`);
+      const summary = { installed: true, slug: args.slug, dir, files_written: written, security_flags: flags, ...(note ? { note: note.trim() } : {}) };
+      return {
+        content: [{ type: "text", text: `Installed ${args.slug} → ${dir} (${written} file${written === 1 ? "" : "s"}; security: ${flags.join(", ") || "unscanned"})${note}` }],
+        structuredContent: summary,
+      };
     }
     default:
       throw new Error(`Unknown tool: ${name}`);
@@ -281,7 +975,25 @@ async function handleCall(name, args) {
 }
 
 async function startMcpServer() {
-  const server = new Server({ name: "skillmd", version: VERSION }, { capabilities: { tools: {} } });
+  const server = new Server(
+    {
+      name: "skillmd",
+      version: VERSION,
+      title: "SkillMD",
+      description:
+        "The open registry of Agent Skills: search, inspect, lint and install 25,000+ linted, security-reviewed SKILL.md files for Claude Code, Cursor, Codex and 60+ other agents.",
+      websiteUrl: "https://skillmd.com",
+      icons: [
+        { src: "https://skillmd.com/favicon.png", mimeType: "image/png", sizes: ["512x512"] },
+        { src: "https://skillmd.com/favicon.svg", mimeType: "image/svg+xml", sizes: ["any"] },
+      ],
+    },
+    {
+      capabilities: { tools: {} },
+      instructions:
+        "SkillMD is a registry of Agent Skills (SKILL.md files). Use skillmd_search to find skills for a task, skillmd_get to inspect one (safety verdict, capability flags, provenance), skillmd_install to write it into the agent's skills directory, and skillmd_lint to validate your own SKILL.md. skillmd_trending and skillmd_recommend surface popular and related skills. Only skillmd_install writes files; it never executes scripts.",
+    },
+  );
   server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
   server.setRequestHandler(CallToolRequestSchema, async (req) => {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillmds",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "SkillMD for agents: the `skillmds` MCP server + the `skillmd` CLI (lint, scan, search, install, publish Agent Skills) from skillmd.com.",
   "license": "MIT",
   "author": "SkillMD",