@modelbound/skill-trust

Local-first trust, safety and clarity scoring for Agent Skills (SKILL.md).

The same scanner that powers the ModelBound web app and the Cursor / VS Code extension. Pure TypeScript, zero runtime dependencies, byte-identical scoring across web, Deno edge functions, Node and the browser.

Install

npm install @modelbound/skill-trust

Usage

import { scoreSkillTrust, trustTier } from "@modelbound/skill-trust";

const result = scoreSkillTrust({
  name: "pr-contributor",
  description: "Triggered when reviewing pull requests; produces structured review comments.",
  body_md: fs.readFileSync("SKILL.md", "utf8"),
  allowed_tools: ["Read", "Write"],
});

console.log(result.total);        // 0–100 overall score
console.log(result.clarity);      // sub-score
console.log(result.safety);
console.log(result.fit);
console.log(result.findings);     // [{ class, severity, message, hint? }]
console.log(trustTier(result.total)); // "green" | "amber" | "red"

What it checks

• Clarity — empty/short/vague descriptions, "Use this skill when…" anti-patterns, overlong frontmatter.
• Safety — prompt-injection patterns (ignore previous instructions, hidden Unicode, embedded <system> tags), exfiltration vectors (markdown-image data leaks, interpolated network calls), privilege escalation (sudo, sensitive paths, unscoped package installs), and risky allowed_tools combinations (Bash + Network).
• Fit — Jaccard overlap between description and body to flag skills that don't deliver what they promise.

Versioning

SCANNER_VERSION is bumped whenever heuristics change so consumers can re-score in bulk. Pin a major version in package.json if you store scores.

License

MIT — © ModelBound