@polygraphso/litmus 0.8.1 → 0.9.1

package/README.md

@@ -151,6 +151,58 @@ machine.
 - **`verify_attestation` says `lookup_failed`:** the grade index or RPC was
   unreachable — that's *unknown*, not *no grade*. Retry; check `POLYGRAPH_API_URL`.
 
+## Grade a skill
+
+Claude Code / Agent **Skills** (a `SKILL.md` plus an optional bundle) are graded by a
+separate static litmus (`litmus-skill-v1`). It scans the skill's bytes — **S-01**
+prompt injection in the body, **S-03** data-exfiltration instructions, **S-04**
+dangerous commands in bundled executable scripts — and content-hashes the whole
+directory. The letter is **A/B/D/F**.
+
+This is a **static** scan: it does not execute the skill or its scripts, so an `A`
+means the static checks were clean, not that the skill is behaviorally safe. A
+command the skill builds or fetches at runtime is not visible to it.
+
+### CLI
+
+```bash
+polygraphso-litmus-skill <path-to-skill-dir>          # grade a local skill folder (must contain SKILL.md)
+polygraphso-litmus-skill --json <path-to-skill-dir>   # machine-readable safety + quality bundles
+```
+
+It also prints a separate, advisory **quality** signal (`well-formed` / `issues` /
+`malformed`) — never an A–F letter, never minted. Its deterministic checks
+(frontmatter + bundled-link resolution) always run; the optional LLM-judged axes
+(honesty, coherence) run only when a judge is available:
+
+- **Inside an agent** (the MCP tool below): the host agent's own model judges via MCP
+  sampling — no key, any provider.
+- **Standalone:** bring your own key for any OpenAI-compatible endpoint:
+
+  ```bash
+  export LITMUS_LLM_API_KEY=…                            # your key (any OpenAI-compatible endpoint)
+  export LITMUS_LLM_MODEL=gpt-4o                         # a model the endpoint serves
+  export LITMUS_LLM_BASE_URL=https://api.openai.com/v1   # optional; defaults to OpenAI
+  # Other providers via their OpenAI-compatible endpoint, e.g.:
+  #   Claude:  LITMUS_LLM_BASE_URL=https://api.anthropic.com/v1                       LITMUS_LLM_MODEL=claude-sonnet-4-6
+  #   Gemini:  LITMUS_LLM_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai  LITMUS_LLM_MODEL=gemini-2.5-flash
+  ```
+
+- With neither, the judged axes are skipped — the grade and deterministic quality
+  still run. The core never needs a key.
+
+### From an AI agent (MCP)
+
+The same `polygraphso-litmus-mcp` server exposes two skill tools (plus `grade-skill` /
+`check-skill` prompts):
+
+- **`run_skill_litmus`** — grade a local skill directory now (static; uses the host
+  model via sampling for the quality axes, no key).
+- **`verify_skill_attestation`** — read a skill's *already-published* grade by its
+  `skill_ref` (`source/owner/repo#path`, e.g. `github/anthropics/skills#skills/pdf`). It
+  returns the attested `contentHash`; recompute the skill's hash and require equality
+  before installing — the content hash, not the version, is the trust anchor.
+
 ## Library
 
 ```ts
@@ -158,6 +210,12 @@ import { runLitmus, gateDecision, liveFingerprint, readAttestation } from "@poly
 
 const bundle = await runLitmus("npm/@modelcontextprotocol/server-filesystem");
 console.log(bundle.grade, bundle.gradeRationale);
+
+// Skills: static safety grade + a separate advisory quality bundle.
+import { runSkillLitmus, runSkillQuality } from "@polygraphso/litmus";
+
+const skill = runSkillLitmus("./skills/my-skill");
+console.log(skill.grade, skill.contentHash);
 ```
 
 ## License

package/dist/{chunk-ZR6XRGMQ.js → chunk-44R4ZYOE.js}

@@ -82,6 +82,69 @@ function serverKey(parts) {
   return parts.owner ? `${parts.registry}/${parts.owner}/${parts.name}` : `${parts.registry}/${parts.name}`;
 }
 
+// ../core/src/skill-identity.ts
+var SOURCES = /* @__PURE__ */ new Set(["github", "marketplace", "npm"]);
+var OWNER_RE2 = /^@?[A-Za-z0-9][A-Za-z0-9._-]*$/;
+var NAME_RE2 = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+var REF_RE = /^[A-Za-z0-9][A-Za-z0-9.+_-]*$/;
+var PATH_SEG_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+var SkillRefParseError = class extends Error {
+  constructor(ref, reason) {
+    super(`Invalid skill ref "${ref}": ${reason}`);
+    this.name = "SkillRefParseError";
+  }
+};
+function parseSkillRef(ref) {
+  const firstSlash = ref.indexOf("/");
+  if (firstSlash === -1) throw new SkillRefParseError(ref, "expected `{source}/...`");
+  const source = ref.slice(0, firstSlash);
+  if (!SOURCES.has(source)) {
+    throw new SkillRefParseError(ref, `unknown source "${source}" (expected one of: ${[...SOURCES].join(", ")})`);
+  }
+  let rest = ref.slice(firstSlash + 1);
+  let pin = null;
+  const at = rest.lastIndexOf("@");
+  if (at > 0) {
+    pin = rest.slice(at + 1);
+    rest = rest.slice(0, at);
+    if (!pin) throw new SkillRefParseError(ref, "empty ref after `@`");
+    if (!REF_RE.test(pin)) throw new SkillRefParseError(ref, "ref contains disallowed characters");
+  }
+  let path = null;
+  const hash = rest.indexOf("#");
+  if (hash >= 0) {
+    path = rest.slice(hash + 1);
+    rest = rest.slice(0, hash);
+    if (!path) throw new SkillRefParseError(ref, "empty path after `#`");
+    for (const seg of path.split("/")) {
+      if (!PATH_SEG_RE.test(seg)) throw new SkillRefParseError(ref, "path contains disallowed characters");
+    }
+  }
+  const lastSlash = rest.lastIndexOf("/");
+  let owner;
+  let name;
+  if (lastSlash === -1) {
+    owner = null;
+    name = rest;
+  } else {
+    owner = rest.slice(0, lastSlash);
+    name = rest.slice(lastSlash + 1);
+  }
+  if (!name) throw new SkillRefParseError(ref, "empty name segment");
+  if (owner !== null && !OWNER_RE2.test(owner)) throw new SkillRefParseError(ref, "owner contains disallowed characters");
+  if (!NAME_RE2.test(name)) throw new SkillRefParseError(ref, "name contains disallowed characters");
+  return { source, owner, name, path, ref: pin };
+}
+function formatSkillRef(p) {
+  let base = p.owner ? `${p.source}/${p.owner}/${p.name}` : `${p.source}/${p.name}`;
+  if (p.path) base += `#${p.path}`;
+  return p.ref ? `${base}@${p.ref}` : base;
+}
+function skillKey(p) {
+  const base = p.owner ? `${p.source}/${p.owner}/${p.name}` : `${p.source}/${p.name}`;
+  return p.path ? `${base}#${p.path}` : base;
+}
+
 // ../core/src/canonical.ts
 function canonicalStringify(value) {
   return JSON.stringify(sortDeep(value));
@@ -116,5 +179,9 @@ export {
   parseServerRef,
   formatServerRef,
   serverKey,
+  SkillRefParseError,
+  parseSkillRef,
+  formatSkillRef,
+  skillKey,
   canonicalStringify
 };

package/dist/{chunk-VOPISHBU.js → chunk-BUKDFSDO.js}

@@ -1,6 +1,6 @@
 import {
   canonicalStringify
-} from "./chunk-ZR6XRGMQ.js";
+} from "./chunk-44R4ZYOE.js";
 
 // ../cli/src/litmus.ts
 import { existsSync } from "fs";
@@ -44,7 +44,7 @@ async function runLitmusCli(args) {
     );
     return 2;
   }
-  const { runLitmus } = await import("./src-RSTPCEYU.js");
+  const { runLitmus } = await import("./src-TMJOIVGB.js");
   const input = resolveTarget(target);
   try {
     const bundle = await runLitmus(input, { headers, allowStateChanging });