skill-land 1.0.0 → 1.1.0

package/README.md

@@ -8,6 +8,8 @@ npx skill-land Magithar/SKILLmama --for codex,antigravity
 npx skill-land Magithar/SKILLmama --for codex --verify   # audit an existing install
 ```
 
+[![npm](https://img.shields.io/npm/v/skill-land)](https://www.npmjs.com/package/skill-land)
+
 ## Why this exists
 
 `npx skills add -a <agent> -g` reports success while writing to the wrong directory
@@ -110,6 +112,32 @@ directory an agent auto-loads. So it scans before writing, delegating to
 uv tool install git+https://github.com/NVIDIA/skillspector.git
 ```
 
+### What always runs: disclosure
+
+A skill is instructions an agent executes with full permissions, so before writing anything
+`skill-land` shows what is actually in the file. No dependencies, so it runs for everyone:
+
+```
+contains
+    3  shell commands        curl, rm, git
+    1  network hosts         attacker.example.com
+    5  credential refs       AWS_SECRET_ACCESS_KEY, ~/.ssh, id_rsa, ~/.aws
+    2  destructive commands  rm -rf, git push --force
+```
+
+A skill with nothing notable says so:
+
+```
+contains  no shell commands, network calls or credential references
+```
+
+**This is disclosure, not a verdict.** It counts and names; it never scores and never prints
+"safe". That distinction is deliberate. A built-in matcher that declared a skill safe would be
+worse than no check, and the numbers below show why. Counting stays honest at any false-positive
+rate because it makes no claim.
+
+### What runs when available: SkillSpector
+
 **It reports, it does not block.** That is a measured decision, not a shortcut.
 
 Scanning 18 known-good skills already installed on a dev machine (2026-08-08, SkillSpector
@@ -121,10 +149,16 @@ v2.8.1, `--no-llm`):
 | CAUTION | 9 |
 | **DO_NOT_INSTALL** | **8 (44%)** |
 
-SKILLmama's own `SKILL.md` scores **100 / CRITICAL / DO_NOT_INSTALL**, because its Phase 3.7
-DISCARD rules contain the literal phrase *"instructions to bypass safety checks"* and the pattern
-matcher reads that as an anti-refusal attack. A security checklist gets flagged for describing
-the attacks it checks for.
+The failure mode is worth understanding, because it is not random. A skill that *documents* attack
+patterns gets flagged for *containing* them: the static matcher has no negation handling, so a rule
+saying "reject skills that bypass safety checks" reads identically to a skill saying "bypass safety
+checks".
+
+[SKILLmama](https://github.com/Magithar/SKILLmama) was a worked example. Its security checklist
+scored `CRITICAL` until four DISCARD criteria were reworded to say the same thing in different
+words; it now scores `7 / LOW / SAFE`. Its behaviour never changed, only its vocabulary. Adding an
+explicit user-consent section was also tested and made the score **worse**, because describing a
+safeguard trips the same patterns as describing the danger.
 
 A gate that blocks 44% of legitimate skills does not make anyone safer; it teaches people to pass
 the override flag reflexively. So findings are surfaced with file and line, and the decision stays
@@ -176,6 +210,22 @@ $ skill-land product-on-purpose/pm-skills --for codex
            ...
 ```
 
+## Releasing
+
+Published from CI by [trusted publishing](https://docs.npmjs.com/trusted-publishers), so there is
+no `NPM_TOKEN` in this repo and the npm account keeps 2FA on write actions. npm mints a
+short-lived token from the GitHub identity of `.github/workflows/publish-skill-land.yml`.
+
+```bash
+# bump version in package.json, commit, then:
+git tag skill-land-v1.0.2
+git push origin skill-land-v1.0.2
+```
+
+CI runs the tests, refuses to publish a version that already exists, checks the tag matches
+`package.json`, and publishes. The tag is package-scoped so other tools in this repo can release
+independently.
+
 ## Adding an agent
 
 Edit `agents.json`. `broken: true` marks agents where the upstream CLI misroutes a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skill-land",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Install an agent skill to the directory the agent actually reads, then verify it landed. Exits non-zero if it didn't.",
   "keywords": [
     "agent-skills",
@@ -27,6 +27,9 @@
   "bin": {
     "skill-land": "skill-land.mjs"
   },
+  "scripts": {
+    "test": "node test.mjs"
+  },
   "files": [
     "skill-land.mjs",
     "agents.json",

package/skill-land.mjs

@@ -141,6 +141,57 @@ function parseFrontmatter(text) {
 
 // ---------------------------------------------------------------- security
 
+// A skill is instructions an agent executes with full permissions, so the one
+// check worth always running is showing what is actually in the file.
+//
+// This is disclosure, not a verdict: it counts and quotes, it never scores.
+// That distinction is the point. A built-in pattern-matcher that printed
+// "SAFE" would be worse than nothing, and we measured why: SkillSpector's
+// static mode calls 44% of known-good skills DO_NOT_INSTALL. Counting is
+// honest at any false-positive rate because it makes no claim.
+//
+// SkillSpector, when installed, does the judging. This does the showing, and
+// it has no dependencies so it runs for everyone.
+// Each entry reduces its matches to a short, stable label (the binary, the
+// host) rather than quoting raw text, so the output stays readable and does
+// not leak half-sentences from prose that happens to contain a keyword.
+const DISCLOSE = [
+  {
+    label: "shell commands",
+    re: /\b(sudo|rm|mv|cp|chmod|chown|curl|wget|git|npm|npx|pip|uv|docker|kubectl|ssh|scp|eval|bash|sh)\s+(?:-{1,2}[\w-]+|[\w./~$@-]+)/g,
+    key: (m) => m[1],
+  },
+  {
+    label: "network hosts",
+    re: /https?:\/\/([^\s/"'`)>\]]+)/g,
+    key: (m) => m[1],
+  },
+  {
+    label: "credential refs",
+    re: /(~\/\.ssh|~\/\.aws|\.env(?:\.[a-z]+)?|id_rsa|[A-Z][A-Z_]*(?:API_KEY|SECRET|TOKEN|PASSWORD)[A-Z_]*)/g,
+    key: (m) => m[1],
+  },
+  {
+    label: "destructive commands",
+    re: /(rm\s+-[rf]{1,2}|git\s+push\s+--force|push\s+-f\b|DROP\s+(?:TABLE|DATABASE)|TRUNCATE)/gi,
+    key: (m) => m[1].replace(/\s+/g, " ").toLowerCase(),
+  },
+];
+
+function disclose(text) {
+  const out = [];
+  for (const { label, re, key } of DISCLOSE) {
+    const keys = [...text.matchAll(re)].map(key).filter(Boolean);
+    if (!keys.length) continue;
+    // Rank by frequency so the most-used thing is what you see first.
+    const freq = new Map();
+    for (const k of keys) freq.set(k, (freq.get(k) || 0) + 1);
+    const top = [...freq.entries()].sort((a, b) => b[1] - a[1]).map(([k]) => k);
+    out.push({ label, count: keys.length, distinct: top.length, sample: top.slice(0, 4) });
+  }
+  return out;
+}
+
 // Skills run with full agent permissions, and this tool writes a file fetched
 // from a URL into a directory an agent auto-loads. So scan before writing.
 //
@@ -304,6 +355,7 @@ try {
 
   // Scan before any write. A blocked skill must never reach disk.
   const scan = skipSecurity ? { status: "skipped" } : securityScan(skillPath);
+  const contents = disclose(rawBody.toString("utf-8"));
   const findings = (scan.top || []).length
     ? "\n" + scan.top.map((t) => `           ${t}`).join("\n") : "";
   // Reported, never applied. See securityScan().
@@ -323,7 +375,19 @@ try {
   console.log(`\n  source   ${src.label}`);
   console.log(`  skill    ${fm.name || "(no frontmatter name)"}  [${rawBody.length} bytes, sha ${expected.hash.slice(0,12)}]`);
   console.log(`  from     ${skillPath.replace(root, ".")}`);
-  if (!verifyOnly) console.log(SCAN_LINE[scan.status]());
+  if (!verifyOnly) {
+    // Always shown, with or without a scanner. Counts and quotes only.
+    if (contents.length) {
+      console.log("  contains");
+      for (const c of contents) {
+        const more = c.distinct > c.sample.length ? `, +${c.distinct - c.sample.length} more` : "";
+        console.log(`    ${String(c.count).padStart(3)}  ${c.label.padEnd(21)} ${c.sample.join(", ")}${more}`.slice(0, 100));
+      }
+    } else {
+      console.log("  contains  no shell commands, network calls or credential references");
+    }
+    console.log(SCAN_LINE[scan.status]());
+  }
   console.log("");
 
   // Refuse to write a skill the scanner flagged. --force is an explicit,