@gobing-ai/superskill 0.2.9 → 0.2.10

package/README.md

@@ -25,8 +25,8 @@ Requires [Bun](https://bun.sh/) ≥ 1.3.14. See [Installation guide](docs/help/i
 ## Quick start
 
 ```bash
-# Distribute a plugin to every supported target
-superskill install my-plugin --targets all
+# Distribute a plugin cc in current repo to every supported target
+superskill install cc --targets all
 
 # Author a skill: scaffold → validate → evaluate → refine
 superskill skill scaffold my-skill --description "Deploy a Cloudflare Worker"

package/dist/index.js

@@ -14269,6 +14269,25 @@ function mergeFrontmatterList(content, key, items) {
   }
   return content.slice(0, fmStart) + newFmBody + content.slice(closePos);
 }
+function mergeFrontmatterScalar(content, key, value) {
+  const fenceRe = /^---$/gm;
+  const matches = [...content.matchAll(fenceRe)];
+  if (matches.length < 2)
+    return content;
+  const openPos = matches[0]?.index ?? 0;
+  const closePos = matches[1]?.index ?? 0;
+  const fmStart = openPos + 3;
+  const fmBody = content.slice(fmStart, closePos);
+  const pattern = new RegExp(`^${key}:.*$`, "m");
+  let newFmBody;
+  if (pattern.test(fmBody)) {
+    newFmBody = fmBody.replace(pattern, `${key}: ${value}`);
+  } else {
+    newFmBody = `${fmBody}${key}: ${value}
+`;
+  }
+  return content.slice(0, fmStart) + newFmBody + content.slice(closePos);
+}
 function resolveTemplate(type, tier) {
   const homeDir = process.env.HOME ?? homedir3();
   const tierName = tier?.trim();
@@ -14315,6 +14334,14 @@ async function scaffold(type, name, opts = {}) {
   });
   const toolField = type === "agent" ? "tools" : "allowed-tools";
   content = mergeFrontmatterList(content, toolField, parseList(opts.tools));
+  if (type === "skill" && opts.invocationMode === "user") {
+    content = mergeFrontmatterScalar(content, "disable-model-invocation", "true");
+    if (!opts.description) {
+      content = content.replace(/^description: *$/m, "description: # One-line, human-facing: what this does, no trigger phrasing (user picks this skill directly)");
+    }
+  } else if (type === "skill" && !opts.description) {
+    content = content.replace(/^description: *$/m, 'description: # Trigger-rich: front-load the identity phrase, one branch per genuine "use when" case');
+  }
   const outDir = opts.output ?? cwd4();
   mkdirSync4(outDir, { recursive: true });
   const filePath = type === "skill" ? join6(outDir, name, "SKILL.md") : join6(outDir, `${name}.md`);
@@ -14434,6 +14461,89 @@ function hasPattern(text, patterns) {
   }
   return clamp(matched / patterns.length);
 }
+function scoreDescriptionBudget(description, min = 20, max = 500) {
+  return scoreLength(description, min, max);
+}
+function noOpDensity(text) {
+  const lower = text.toLowerCase();
+  const noOpHits = NO_OP_PHRASES.filter((p) => lower.includes(p)).length;
+  const imperativeHits = IMPERATIVE_KEYWORDS.filter((k) => lower.includes(k)).length;
+  const denominator = noOpHits + imperativeHits;
+  if (denominator === 0)
+    return 0;
+  return clamp(noOpHits / denominator);
+}
+function shingles(text, size) {
+  const words = text.toLowerCase().replace(/[^a-z0-9\s]/g, " ").split(/\s+/).filter(Boolean);
+  if (words.length < size)
+    return [];
+  const result = [];
+  for (let i = 0;i <= words.length - size; i++) {
+    result.push(words.slice(i, i + size).join(" "));
+  }
+  return result;
+}
+function duplicationRatio(text, other, size = 8) {
+  const own = shingles(text, size);
+  if (own.length === 0)
+    return 0;
+  if (other !== undefined) {
+    const otherSet = new Set(shingles(other, size));
+    if (otherSet.size === 0)
+      return 0;
+    const dup = own.filter((s) => otherSet.has(s)).length;
+    return clamp(dup / own.length);
+  }
+  const counts = new Map;
+  for (const s of own)
+    counts.set(s, (counts.get(s) ?? 0) + 1);
+  const repeated = own.filter((s) => (counts.get(s) ?? 0) > 1).length;
+  return clamp(repeated / own.length);
+}
+function countTriggerBranches(phrases) {
+  const wordSets = phrases.map((p) => new Set(p.toLowerCase().split(/\s+/).filter(Boolean)));
+  const branchOf = new Array(phrases.length).fill(-1);
+  let nextBranch = 0;
+  for (let i = 0;i < wordSets.length; i++) {
+    if (branchOf[i] !== -1)
+      continue;
+    branchOf[i] = nextBranch;
+    for (let j = i + 1;j < wordSets.length; j++) {
+      if (branchOf[j] !== -1)
+        continue;
+      if (jaccard(wordSets[i] ?? new Set, wordSets[j] ?? new Set) >= 0.5) {
+        branchOf[j] = branchOf[i] ?? nextBranch;
+      }
+    }
+    nextBranch++;
+  }
+  return nextBranch;
+}
+function jaccard(a, b) {
+  if (a.size === 0 && b.size === 0)
+    return 1;
+  let intersection = 0;
+  for (const w of a)
+    if (b.has(w))
+      intersection++;
+  const union = a.size + b.size - intersection;
+  return union === 0 ? 0 : intersection / union;
+}
+function completionCheckability(body) {
+  const stepLines = body.split(`
+`).filter((l) => /^\s*\d+[.)]\s/.test(l) || /^\s*-\s*\[[ x]\]/i.test(l));
+  if (stepLines.length === 0)
+    return 1;
+  const lower = body.toLowerCase();
+  const vagueHits = VAGUE_COMPLETION_BOUNDS.filter((v) => lower.includes(v)).length;
+  const penalty = clamp(vagueHits / Math.max(3, VAGUE_COMPLETION_BOUNDS.length));
+  return clamp(1 - penalty);
+}
+function progressiveDisclosureShape(body, budget = 8000) {
+  if (body.length <= budget)
+    return true;
+  return /references\//i.test(body) || /##\s*(see also|additional resources)/i.test(body);
+}
 function extractBody(content) {
   if (!content.startsWith(`---
 `))
@@ -14443,15 +14553,52 @@ function extractBody(content) {
     return content.slice(4);
   return content.slice(closerMatch.index + 4 + 4);
 }
+function descriptionTriggerRichness(description) {
+  if (!description)
+    return 0;
+  const branchDelimiters = (description.match(/[,;]|\bor\b/gi) ?? []).length;
+  const dispatchCues = (description.match(/\b(use (?:this|it) when|whenever|triggers? on|use when)\b/gi) ?? []).length;
+  const lengthSignal = clamp(description.length / 300);
+  const branchSignal = clamp(branchDelimiters / 3);
+  const cueSignal = clamp(dispatchCues);
+  return clamp(branchSignal * 0.5 + cueSignal * 0.3 + lengthSignal * 0.2);
+}
 function clamp(n) {
   return Math.max(0, Math.min(1, n));
 }
 function escapeRegex(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+var NO_OP_PHRASES, VAGUE_COMPLETION_BOUNDS;
 var init_heuristics = __esm(() => {
   init_frontmatter();
   init_types2();
+  NO_OP_PHRASES = [
+    "be helpful",
+    "be concise",
+    "be accurate",
+    "do your best",
+    "think carefully",
+    "think step by step",
+    "try your best",
+    "work hard",
+    "pay attention",
+    "be thorough",
+    "take your time",
+    "be careful",
+    "stay focused",
+    "use good judgment"
+  ];
+  VAGUE_COMPLETION_BOUNDS = [
+    "understanding reached",
+    "as needed",
+    "as appropriate",
+    "when ready",
+    "until satisfied",
+    "good enough",
+    "as necessary",
+    "when done"
+  ];
 });
 
 // ../../packages/core/src/quality/hook.ts
@@ -14776,6 +14923,9 @@ function _validateContent(type, content, opts) {
   findings.push(...checkLinkValidity(type, data, opts?.referenceChecker));
   if (opts?.strict) {
     findings.push(...strictChecks(type, data, body));
+    if (type === "skill") {
+      findings.push(...checkInvocationModeMismatch(data));
+    }
   }
   const valid = !findings.some((f) => f.severity === "error");
   return { valid, findings };
@@ -14894,6 +15044,28 @@ function checkLinkValidity(type, data, referenceChecker) {
   }
   return findings;
 }
+function checkInvocationModeMismatch(data) {
+  const findings = [];
+  const description = typeof data.description === "string" ? data.description : "";
+  if (!description)
+    return findings;
+  const userInvoked = data["disable-model-invocation"] === true;
+  const richness = descriptionTriggerRichness(description);
+  if (userInvoked && richness >= TRIGGER_RICH_THRESHOLD) {
+    findings.push({
+      severity: "warning",
+      field: "invocation-mode",
+      message: "disable-model-invocation is true (user-invoked) but the description reads " + "trigger-rich (branch/dispatch phrasing). A user-invoked skill cannot be fired " + "by other skills or commands \u2014 rewrite the description as a one-line, " + "human-facing summary instead."
+    });
+  } else if (!userInvoked && richness <= ONE_LINE_THRESHOLD) {
+    findings.push({
+      severity: "warning",
+      field: "invocation-mode",
+      message: "This skill is model-invoked (disable-model-invocation is absent/false) but the " + "description reads like a bare one-liner with no trigger phrasing. The dispatching " + 'orchestrator needs distinct "use when" branches to select this skill reliably.'
+    });
+  }
+  return findings;
+}
 function strictChecks(type, data, body) {
   const findings = [];
   const desc = data.description;
@@ -14959,10 +15131,11 @@ function sentinelResult(message) {
     findings: [{ severity: "error", field: "_file", message }]
   };
 }
-var MODEL_ALIASES, FIELD_TYPES, DEPRECATED_FIELDS, KNOWN_OPTIONAL;
+var MODEL_ALIASES, FIELD_TYPES, DEPRECATED_FIELDS, KNOWN_OPTIONAL, TRIGGER_RICH_THRESHOLD = 0.4, ONE_LINE_THRESHOLD = 0.15;
 var init_validate = __esm(() => {
   init_frontmatter();
   init_identity();
+  init_heuristics();
   init_hook();
   init_types2();
   MODEL_ALIASES = ["inherit", "sonnet", "opus", "haiku"];
@@ -14970,7 +15143,8 @@ var init_validate = __esm(() => {
     skill: {
       name: { type: "string" },
       description: { type: "string" },
-      "allowed-tools": { type: "array" }
+      "allowed-tools": { type: "array" },
+      "disable-model-invocation": { type: "boolean" }
     },
     command: {
       name: { type: "string" },
@@ -40886,18 +41060,39 @@ var init_slash_command2 = __esm(() => {
 });
 
 // ../../packages/core/src/quality/agent.ts
-function scoreCompleteness(data) {
+function scoreCompleteness(data, body) {
   const fieldsPresent = Object.keys(data);
   const required2 = REQUIRED_FIELDS.agent;
-  const score = scorePresence(fieldsPresent, required2);
+  const presence = scorePresence(fieldsPresent, required2);
   const missing = required2.filter((f) => !fieldsPresent.includes(f));
-  const findings = missing.length > 0 ? [`Missing required fields: ${missing.join(", ")}`] : undefined;
-  const recs = missing.length > 0 ? ["Add the missing frontmatter fields"] : undefined;
+  const description = typeof data.description === "string" ? data.description : "";
+  const budgetScore = description ? scoreDescriptionBudget(description, 20, 2000) : 1;
+  const noOp = noOpDensity(description);
+  const descDup = description ? duplicationRatio(description, body, 12) : 0;
+  const score = clamp(presence * budgetScore * (1 - noOp) * (1 - descDup));
+  const findings = [];
+  const recs = [];
+  if (missing.length > 0) {
+    findings.push(`Missing required fields: ${missing.join(", ")}`);
+    recs.push("Add the missing frontmatter fields");
+  }
+  if (budgetScore < 1) {
+    findings.push(`Description is ${description.length} chars, outside the 20\u20132000 char budget.`);
+    recs.push("Tighten the description to the agent\u2019s role and dispatch trigger.");
+  }
+  if (noOp > 0.2) {
+    findings.push("Description contains default-behavior phrases that add no signal (no-op candidates).");
+    recs.push("Delete no-op phrasing from the description rather than trimming it.");
+  }
+  if (descDup > 0.3) {
+    findings.push("Description restates body text near-verbatim (duplication).");
+    recs.push("State the agent\u2019s role once in the description; do not repeat it in the body.");
+  }
   return {
-    score: clamp(score),
+    score,
     note: missing.length > 0 ? `Missing: ${missing.join(", ")}` : "All required fields present",
-    findings,
-    recommendations: recs
+    findings: findings.length > 0 ? findings : undefined,
+    recommendations: recs.length > 0 ? recs : undefined
   };
 }
 function scoreRoleClarity(body) {
@@ -41006,7 +41201,7 @@ function evaluateAgent(content, target) {
   const data = parseFrontmatterSafe(content) ?? {};
   const body = extractBody(content);
   const dimensions = {
-    completeness: scoreCompleteness(data),
+    completeness: scoreCompleteness(data, body),
     "role-clarity": scoreRoleClarity(body),
     "tool-selection": scoreToolSelection(data),
     "skill-linkage": scoreSkillLinkage(body),
@@ -41043,8 +41238,27 @@ function scoreCompleteness2(data) {
   const recs = missing.includes("description") ? ["Add a description field to the command frontmatter"] : undefined;
   return { score, note, findings, recommendations: recs };
 }
-function scoreClarity(body) {
-  return scoreClarityFromDensities(body);
+function scoreClarity(body, description) {
+  const base2 = scoreClarityFromDensities(body);
+  const budgetScore = description ? scoreDescriptionBudget(description) : 1;
+  const noOp = noOpDensity(description);
+  const descDup = description ? duplicationRatio(description, body, 12) : 0;
+  const score = clamp(base2.score * budgetScore * (1 - noOp) * (1 - descDup));
+  const findings = [...base2.findings ?? []];
+  const recommendations = [...base2.recommendations ?? []];
+  if (budgetScore < 1) {
+    findings.push(`Description is ${description.length} chars, outside the 20\u2013500 char budget.`);
+    recommendations.push("Tighten the description to what the command does and when to use it.");
+  }
+  if (noOp > 0.2) {
+    findings.push("Description contains default-behavior phrases that add no signal (no-op candidates).");
+    recommendations.push("Delete no-op phrasing from the description rather than trimming it.");
+  }
+  if (descDup > 0.3) {
+    findings.push("Description restates body text near-verbatim (duplication).");
+    recommendations.push("State the command purpose once in the description; do not repeat it in the body.");
+  }
+  return { score, note: base2.note, findings, recommendations };
 }
 function scoreArgumentHints(data) {
   const hasKey = "argument-hint" in data;
@@ -41146,7 +41360,7 @@ function evaluateCommand(content, target) {
   const body = extractBody(content);
   const dimensions = {
     completeness: scoreCompleteness2(data),
-    clarity: scoreClarity(body),
+    clarity: scoreClarity(body, typeof data.description === "string" ? data.description : ""),
     "argument-hints": scoreArgumentHints(data),
     "tool-references": scoreToolReferences(body, data),
     "slash-syntax": scoreSlashSyntax(body, target)
@@ -41335,9 +41549,25 @@ function scorePlatformCoverage(data, body) {
   return { score, note: `${platforms.length} platforms covered`, findings, recommendations: recs };
 }
 function scoreConciseness(body) {
+  const lengthScore = scoreLength(body, 1000, 8000);
+  const noOp = noOpDensity(body);
+  const bodyDup = duplicationRatio(body, undefined, 12);
+  const score = clamp(lengthScore * (1 - noOp) * (1 - bodyDup * 0.3));
+  const findings = [];
+  const recs = [];
+  if (noOp > 0.2) {
+    findings.push("Body contains default-behavior phrases that do not change model behavior (no-op candidates).");
+    recs.push("Delete no-op instructions rather than trimming them \u2014 they add no signal.");
+  }
+  if (bodyDup > 0.15) {
+    findings.push("Body repeats the same phrasing (n-gram duplication) in multiple places.");
+    recs.push("Collapse duplicated phrasing into one authoritative section; cite it elsewhere.");
+  }
   return {
-    score: scoreLength(body, 1000, 8000),
-    note: `Body length: ${body.length} chars`
+    score,
+    note: `Body length: ${body.length} chars`,
+    findings: findings.length > 0 ? findings : undefined,
+    recommendations: recs.length > 0 ? recs : undefined
   };
 }
 function scoreToneConsistency(body) {
@@ -41411,12 +41641,13 @@ var init_magent = __esm(() => {
 function evaluateSkill(content, target) {
   const data = parseFrontmatterSafe(content);
   const body = extractBody(content);
+  const description = typeof data?.description === "string" ? data.description : "";
   const dimensions = {
     completeness: scoreCompleteness4(content, data, body),
     clarity: scoreClarity2(body),
-    "trigger-accuracy": scoreTriggerAccuracy(body),
+    "trigger-accuracy": scoreTriggerAccuracy(body, description, data),
     "anti-hallucination": scoreAntiHallucination(body),
-    conciseness: scoreConciseness2(body)
+    conciseness: scoreConciseness2(body, description)
   };
   return {
     type: "skill",
@@ -41435,7 +41666,8 @@ function scoreCompleteness4(content, data, body) {
   const required2 = REQUIRED_FIELDS.skill;
   const presence = scorePresence(presentKeys, required2);
   const structure = hasPattern(body, [/^# /m, /^## /m, /^### /m]);
-  const score = clamp(presence * structure);
+  const disclosed = progressiveDisclosureShape(body) ? 1 : 0.7;
+  const score = clamp(presence * structure * disclosed);
   const keySet = new Set(presentKeys);
   const missing = required2.filter((f) => !keySet.has(f));
   const note = missing.length > 0 ? `Missing fields: ${missing.join(", ")}` : "All required fields present";
@@ -41449,13 +41681,31 @@ function scoreCompleteness4(content, data, body) {
     findings.push("Body lacks section headings (# / ## / ###). Structure aids navigation.");
     recommendations.push("Organize content with markdown headings for progressive disclosure");
   }
+  if (disclosed < 1) {
+    findings.push("Body is over the disclosure budget with no references/ (or See Also) link.");
+    recommendations.push("Move supporting detail into references/*.md and link it, rather than growing the body.");
+  }
   return { score, note, findings, recommendations };
 }
 function scoreClarity2(body) {
-  return scoreClarityFromDensities(body);
-}
-function scoreTriggerAccuracy(body) {
-  const count2 = countTriggerPhrases(body);
+  const base2 = scoreClarityFromDensities(body);
+  const checkability = completionCheckability(body);
+  const score = clamp(base2.score * checkability);
+  const findings = [...base2.findings ?? []];
+  const recommendations = [...base2.recommendations ?? []];
+  if (checkability < 1) {
+    findings.push('Step-shaped content uses vague completion bounds (e.g. "as needed", "when ready").');
+    recommendations.push("Replace vague bounds with a decidable done-condition per step.");
+  }
+  return { score, note: base2.note, findings, recommendations };
+}
+function scoreTriggerAccuracy(body, description, data) {
+  const userInvoked = data?.["disable-model-invocation"] === true;
+  if (userInvoked) {
+    return scoreUserInvokedDescription(description);
+  }
+  const phrases = collectTriggerPhrases(body, description);
+  const count2 = countTriggerBranches(phrases);
   let score;
   if (count2 >= 3 && count2 <= 10) {
     score = 1;
@@ -41467,13 +41717,38 @@ function scoreTriggerAccuracy(body) {
   const findings = [];
   const recommendations = [];
   if (count2 < 3) {
-    findings.push(`Only ${count2} trigger phrase(s) found; aim for 3\u201310 for reliable skill activation.`);
-    recommendations.push("Add 1\u20132 more When-to-Use scenarios or trigger phrase patterns to the description.");
+    findings.push(`Only ${count2} distinct trigger branch(es) found; aim for 3\u201310 for reliable skill activation.`);
+    recommendations.push("Add 1\u20132 more When-to-Use scenarios covering genuinely distinct branches.");
   } else if (count2 > 10) {
-    findings.push(`${count2} trigger phrases may cause overlap with adjacent skills.`);
+    findings.push(`${count2} distinct trigger branches may cause overlap with adjacent skills.`);
     recommendations.push("Consolidate overlapping triggers or narrow the activation scope.");
   }
-  return { score, note: `${count2} trigger phrases found`, findings, recommendations };
+  if (phrases.length > count2) {
+    findings.push(`${phrases.length} trigger phrase(s) collapse to ${count2} distinct branch(es) \u2014 some are synonym clusters.`);
+    recommendations.push("Collapse synonym-cluster triggers into one phrase per genuine branch.");
+  }
+  return {
+    score,
+    note: `${count2} distinct trigger branch(es) (${phrases.length} phrases)`,
+    findings,
+    recommendations
+  };
+}
+function scoreUserInvokedDescription(description) {
+  const richness = descriptionTriggerRichness(description);
+  const score = clamp(1 - richness);
+  const findings = [];
+  const recommendations = [];
+  if (richness > 0.4) {
+    findings.push("This skill is user-invoked (disable-model-invocation: true) but the description reads " + "trigger-rich. A user-invoked skill cannot be fired by other skills or commands.");
+    recommendations.push("Rewrite the description as a one-line, human-facing summary \u2014 no branch list.");
+  }
+  return {
+    score,
+    note: `User-invoked: description trigger-richness ${richness.toFixed(2)} (lower is better)`,
+    findings,
+    recommendations
+  };
 }
 function scoreAntiHallucination(body) {
   const density = keywordDensity(body, [
@@ -41495,16 +41770,45 @@ function scoreAntiHallucination(body) {
   }
   return { score: density, note, findings, recommendations };
 }
-function scoreConciseness2(body) {
-  const score = scoreLength(body, 500, 15000);
-  return { score, note: `Body length: ${body.length} chars` };
+function scoreConciseness2(body, description) {
+  const lengthScore = scoreLength(body, 500, 15000);
+  const budgetScore = description ? scoreDescriptionBudget(description) : 1;
+  const noOp = noOpDensity(body);
+  const descDup = description ? duplicationRatio(description, body, 12) : 0;
+  const bodyDup = duplicationRatio(body, undefined, 12);
+  const score = clamp(lengthScore * budgetScore * (1 - noOp) * (1 - descDup) * (1 - bodyDup * 0.3));
+  const findings = [];
+  const recommendations = [];
+  if (budgetScore < 1) {
+    findings.push(`Description is ${description.length} chars, outside the 20\u2013500 char budget.`);
+    recommendations.push("Tighten the description to the identity phrase plus distinct trigger branches.");
+  }
+  if (noOp > 0.2) {
+    findings.push("Body contains default-behavior phrases that do not change model behavior (no-op candidates).");
+    recommendations.push("Delete no-op instructions rather than trimming them \u2014 they add no signal.");
+  }
+  if (descDup > 0.3) {
+    findings.push("Body restates the description near-verbatim (duplication).");
+    recommendations.push("State identity once in the description; do not repeat it in the body.");
+  }
+  if (bodyDup > 0.15) {
+    findings.push("Body repeats the same phrasing (n-gram duplication) in multiple places.");
+    recommendations.push("Collapse duplicated phrasing into one authoritative section; cite it elsewhere.");
+  }
+  return { score, note: `Body length: ${body.length} chars`, findings, recommendations };
+}
+function collectTriggerPhrases(body, description) {
+  const fromSection = triggerSectionPhrases(body);
+  if (fromSection.length > 0)
+    return fromSection;
+  return descriptionTriggerPhrases(description);
 }
-function countTriggerPhrases(body) {
+function triggerSectionPhrases(body) {
   const lines = body.split(`
 `);
   let inTriggerSection = false;
   let sectionDepth = 0;
-  let count2 = 0;
+  const phrases = [];
   for (const line of lines) {
     const headingMatch = line.match(/^(#{1,6})\s+(.+)/);
     if (headingMatch) {
@@ -41519,19 +41823,18 @@ function countTriggerPhrases(body) {
       continue;
     }
     if (inTriggerSection) {
-      if (/^\s*[-*+]\s/.test(line) || /^\s*\d+[.)]\s/.test(line)) {
-        count2++;
+      const listMatch = line.match(/^\s*(?:[-*+]|\d+[.)])\s+(.+)/);
+      if (listMatch?.[1]) {
+        phrases.push(listMatch[1].replace(/^["']|["']$/g, "").trim());
       }
     }
   }
-  if (count2 === 0) {
-    for (const line of lines) {
-      if (/^\s*[-*+]\s/.test(line) || /^\s*\d+[.)]\s/.test(line)) {
-        count2++;
-      }
-    }
-  }
-  return count2;
+  return phrases;
+}
+function descriptionTriggerPhrases(description) {
+  if (!description)
+    return [];
+  return description.split(/[,;]|(?:\bor\b)/i).map((s) => s.trim()).filter((s) => s.length > 3);
 }
 var init_skill = __esm(() => {
   init_heuristics();
@@ -95937,6 +96240,7 @@ async function replaySplit(backend, skill2, cases, split, toolsCalled) {
 init_src();
 
 // src/operations/evolve.ts
+var FAILURE_MODES = ["sprawl", "sediment", "duplication", "no-op", "premature-completion"];
 function isHookApplyCapableOpt(opts) {
   if (!opts)
     return false;
@@ -96306,6 +96610,9 @@ async function ingestProposal(db2, type, name, resolvedPath, ingestPath, opts, b
     if (!change.dimension || !change.location || !change.proposed || !change.reason) {
       throw Object.assign(new Error(`Invalid ProposedChange: missing required field (dimension, location, proposed, reason)`), { code: 1 });
     }
+    if (change.failure_mode !== undefined && !FAILURE_MODES.includes(change.failure_mode)) {
+      throw Object.assign(new Error(`Invalid failure_mode "${change.failure_mode}". Expected one of: ${FAILURE_MODES.join(", ")}`), { code: 1 });
+    }
   }
   const proposalDao = new ProposalDao(db2);
   const existingProposals = await proposalDao.getProposals(type, name);
@@ -96872,7 +97179,7 @@ function classifyFix(finding) {
   if (finding.severity === "error") {
     return "auto-apply";
   }
-  if (["description", "trigger-accuracy", "clarity", "conciseness"].includes(finding.field)) {
+  if (["description", "trigger-accuracy", "clarity", "conciseness", "invocation-mode"].includes(finding.field)) {
     return "suggest";
   }
   if (["skill-linkage", "tool-selection", "model-fit", "platform-coverage"].includes(finding.field)) {
@@ -97261,7 +97568,7 @@ function addTargetOption(cmd) {
   return cmd.option("-t, --target <agent>", "Target agent platform", "claude");
 }
 function addScaffoldOptions(cmd) {
-  return cmd.option("-d, --description <text>", "Content description").option("-t, --target <agent>", "Target agent platform", "claude").option("-o, --output <dir>", "Output directory (default: cwd)").option("--template <tier>", "Template tier (e.g. minimal / standard / specialist)").option("--tools <list>", "Comma-separated tool names to pre-populate frontmatter").option("--force", "Overwrite existing file if present");
+  return cmd.option("-d, --description <text>", "Content description").option("-t, --target <agent>", "Target agent platform", "claude").option("-o, --output <dir>", "Output directory (default: cwd)").option("--template <tier>", "Template tier (e.g. minimal / standard / specialist)").option("--tools <list>", "Comma-separated tool names to pre-populate frontmatter").option("--invocation-mode <mode>", "Skill invocation axis: 'user' (disable-model-invocation + one-line description) " + "or 'model' (trigger-rich description, default)").option("--force", "Overwrite existing file if present");
 }
 function addEvolveOptions(cmd) {
   return cmd.option("-t, --target <agent>", "Target agent platform", "claude").option("--from <date>", "Analyze evaluations since date (ISO 8601)").option("--propose-only", "Generate proposal without applying").option("--accept <id>", "Accept a specific proposal by ID").option("--reject <id>", "Reject a specific proposal").option("--json", "Output machine-readable JSON (envelope-out with --propose-only)").option("--ingest <file>", "Agent-authored proposal JSON (ingest-in mode)").option("--margin <n>", "\u0394-margin gate threshold for accept (default 0.05)", Number.parseFloat, 0.05).option("--eval-gate", "Enable empirical behavior gate (requires skills/<name>/eval/cases.yaml)").option("--analyze", "Print analysis summary (trends, score, data sources) without writing a proposal").option("--history", "List applied proposal versions from the store").option("--rollback <id>", "Rollback to a prior version by proposal_id (requires --confirm)").option("--confirm", "Confirm a destructive operation (required for --rollback)");
@@ -98451,6 +98758,13 @@ async function migrateSkills(sources, dest, opts) {
 init_src();
 
 // src/commands/skill.ts
+function parseInvocationMode(value) {
+  if (value === undefined)
+    return;
+  if (value === "user" || value === "model")
+    return value;
+  throw new Error(`Invalid --invocation-mode "${value}". Expected 'user' or 'model'.`);
+}
 async function skillScaffold(opts) {
   const target = resolveTarget(opts);
   const createdPath = await scaffold("skill", opts.name, {
@@ -98459,7 +98773,8 @@ async function skillScaffold(opts) {
     output: opts.output,
     force: opts.force,
     template: opts.template,
-    tools: opts.tools
+    tools: opts.tools,
+    invocationMode: parseInvocationMode(opts.invocationMode)
   });
   echo(`Created: ${createdPath}`);
   return;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/superskill",
-    "version": "0.2.9",
+    "version": "0.2.10",
     "description": "A manager for multi-agent skill, slash command, subagent, hook, MCP and etc.",
     "keywords": [
         "cli",

package/rubrics/agent.yaml

@@ -1,4 +1,4 @@
-version: 1
+version: 2
 type: agent
 dimensions:
   - name: completeness
@@ -6,10 +6,21 @@ dimensions:
     criterion: >
       Does the agent cover its stated scope end-to-end? Penalize missing workflow
       phases, undocumented edge cases, and gaps between the stated trigger and
-      the actual execution path.
+      the actual execution path. Measurable proxies (folded in, not a new
+      dimension): the frontmatter description — the dispatch-time signal a
+      Task-tool orchestrator reads to pick this agent — sits within a 20-2000
+      char context-load budget (wider than skill’s 20-500: Claude Code's own
+      convention embeds few-shot <example> blocks directly in an agent's
+      description, unlike a skill's single-sentence trigger), is free of curated
+      no-op phrases, and does not restate the body near-verbatim. Progressive
+      disclosure (references/*.md) does NOT apply here — agents in this repo
+      are flat single-file documents with no companion references/ directory
+      convention, unlike skills. Whether the description's wording will actually
+      read well to a dispatching orchestrator is genuinely subjective — judge
+      that here, in the two-call seam, not via a deterministic proxy.
     anchors:
-      excellent: "Full workflow from intake to delivery; every phase has explicit steps and exit conditions."
-      poor: "Scope claims coverage but execution path skips phases or leaves edge cases unhandled."
+      excellent: "Full workflow from intake to delivery; every phase has explicit steps and exit conditions; description is tight, within budget, and not duplicated from the body."
+      poor: "Scope claims coverage but execution path skips phases, leaves edge cases unhandled, or the description is vague, no-op-heavy, or duplicated from the body."
 
   - name: role-clarity
     weight: 0.25

package/rubrics/command.yaml

@@ -1,4 +1,4 @@
-version: 1
+version: 2
 type: command
 dimensions:
   - name: completeness
@@ -16,10 +16,17 @@ dimensions:
     criterion: >
       Is the command's purpose and usage unambiguous? The description should
       tell the user what it does and when to use it. Penalize descriptions
-      that restate the command name without adding information.
+      that restate the command name without adding information. Measurable
+      proxies (folded in, not a new dimension): description sits within a
+      20-500 char context-load budget; description is free of curated no-op
+      phrases ("be helpful", "think carefully") that add no signal; description
+      does not restate the command body near-verbatim (n-gram duplication).
+      Whether the description's actual WORDING is well-chosen for the intended
+      audience is genuinely subjective — judge that here, in the two-call seam,
+      not via a deterministic proxy.
     anchors:
-      excellent: "Description states what the command does, when to use it, and what the output means."
-      poor: "Description restates the command name; user cannot tell when to use it."
+      excellent: "Description states what the command does, when to use it, and what the output means, within budget, with no no-op or duplicated phrasing."
+      poor: "Description restates the command name, exceeds the context-load budget, or duplicates the body verbatim; user cannot tell when to use it."
 
   - name: argument-hints
     weight: 0.20

package/rubrics/hook.yaml

@@ -1,5 +1,10 @@
 version: 1
 type: hook
+# R2 scoping note (task 0070): description-budget / no-op-density / duplication proxies
+# do NOT transfer to hooks. A hook definition is a JSON matcher/command table with no
+# frontmatter description field and no markdown prose body — there is nothing for those
+# proxies to measure. The trigger-equivalent concept here is the JSON `matcher` field,
+# already scored by pattern-match-quality. This is a deliberate N/A, not a gap.
 dimensions:
   - name: correctness
     weight: 0.25

package/rubrics/magent.yaml

@@ -1,4 +1,4 @@
-version: 1
+version: 2
 type: magent
 dimensions:
   - name: completeness
@@ -27,10 +27,17 @@ dimensions:
     criterion: >
       Is the config as short as possible while remaining complete? Penalize
       redundant rule restating, boilerplate that adds no information, and
-      rules that could be merged without loss.
+      rules that could be merged without loss. Measurable proxies (folded in,
+      not a new dimension): body is free of curated no-op phrases ("be
+      helpful", "think carefully") that restate default model behavior without
+      changing it; body has low within-body n-gram duplication. A magent
+      config (AGENTS.md/CLAUDE.md) has no separate frontmatter description
+      field — it is read wholesale rather than dispatch-selected — so the
+      description-budget check that applies to skill/command/agent does not
+      apply here.
     anchors:
-      excellent: "Minimal length with no redundancy; every rule carries unique information."
-      poor: "Redundant rules and boilerplate; rules could be merged without loss."
+      excellent: "Minimal length with no redundancy; every rule carries unique information; no no-op phrasing."
+      poor: "Redundant rules, boilerplate, or no-op phrasing that adds no signal; rules could be merged without loss."
 
   - name: tone-consistency
     weight: 0.20

package/rubrics/skill.yaml

@@ -1,4 +1,4 @@
-version: 1
+version: 2
 type: skill
 dimensions:
   - name: completeness
@@ -6,31 +6,45 @@ dimensions:
     criterion: >
       Does the skill cover its stated purpose end-to-end? Penalize missing
       steps, undocumented preconditions, and gaps between the trigger and the
-      delivered outcome. A complete skill leaves no implicit step.
+      delivered outcome. A complete skill leaves no implicit step. Also check
+      progressive-disclosure shape: a body that has grown past a reasonable
+      length budget without moving supporting detail into references/*.md (or
+      linking a "See Also"/"Additional Resources" section) is incomplete in a
+      structural sense — coverage exists but isn't disclosed in a navigable way.
     anchors:
-      excellent: "Every phase from trigger to outcome is explicit; preconditions and exit conditions stated."
-      poor: "Purpose claims coverage but steps are implicit or preconditions unstated."
+      excellent: "Every phase from trigger to outcome is explicit; preconditions and exit conditions stated; a body over the length budget discloses detail via references/."
+      poor: "Purpose claims coverage but steps are implicit or preconditions unstated; a long body with no references/ link buries detail instead of disclosing it."
 
   - name: clarity
     weight: 0.25
     criterion: >
       Is the skill's instruction unambiguous to a fresh agent? Penalize
       vague verbs ('handle', 'process'), undefined terms, and instructions
-      that require external context the skill does not provide.
+      that require external context the skill does not provide. For
+      step/workflow-shaped content, also check completion-criteria
+      checkability: each step should read as a decidable done-condition.
+      Penalize vague bounds ("understanding reached", "as needed", "as
+      appropriate") that leave a reader unable to tell when a step is done.
     anchors:
-      excellent: "Concrete verbs, defined terms, self-contained instructions an agent can execute without guessing."
-      poor: "Vague verbs and undefined terms; agent must guess the intended behavior."
+      excellent: "Concrete verbs, defined terms, self-contained instructions an agent can execute without guessing; every step has a decidable done-condition."
+      poor: "Vague verbs and undefined terms; agent must guess the intended behavior; steps end on vague bounds like 'as needed' with no checkable condition."
 
   - name: trigger-accuracy
     weight: 0.20
     criterion: >
       Does the skill fire on the right inputs and not on adjacent ones? The
-      description must precisely scope when the skill activates. Penalize
-      triggers that are too broad (fires on unrelated requests) or too narrow
-      (misses the intended case).
+      description must precisely scope when the skill activates. Score by
+      DISTINCT trigger branches, not raw phrase count — a description with 8
+      near-synonymous phrasings of the same branch ("review this code" /
+      "review the code" / "review code") is still one branch, not eight.
+      Reward description phrasing that covers 3-10 genuinely distinct
+      branches (one phrase per branch); penalize triggers that are too broad
+      (fires on unrelated requests), too narrow (misses the intended case),
+      or padded with synonym clusters that inflate the apparent count without
+      adding coverage.
     anchors:
-      excellent: "Trigger description scopes activation precisely; no overlap with adjacent skills."
-      poor: "Trigger is broad enough to fire on unrelated requests or narrow enough to miss the intended case."
+      excellent: "Trigger description scopes activation precisely across 3-10 genuinely distinct branches; no synonym-cluster padding; no overlap with adjacent skills."
+      poor: "Trigger is broad enough to fire on unrelated requests, narrow enough to miss the intended case, or pads the same branch with several near-identical phrasings."
 
   - name: anti-hallucination
     weight: 0.15
@@ -47,7 +61,17 @@ dimensions:
     criterion: >
       Is the skill as short as possible while remaining complete? Penalize
       redundant restating, boilerplate that adds no information, and steps
-      that could be merged without loss.
+      that could be merged without loss. Specifically check: (1) description
+      char budget — a model-invoked description sits in context every turn it
+      is a candidate, so it should be no longer than the identity phrase plus
+      its distinct trigger branches require; (2) no-op density — instructions
+      that restate default model behavior ("be helpful", "think carefully")
+      change nothing and should be deleted, not trimmed; (3) duplication —
+      the body should not restate the description near-verbatim, and should
+      not repeat the same phrasing in multiple places within itself. Leading-
+      word quality (is this the RIGHT tight/imperative word for the described
+      action, for this specific model) is genuinely subjective — judge it
+      here, in the two-call seam, not via a deterministic proxy.
     anchors:
-      excellent: "Minimal length with no redundancy; every line carries unique information."
-      poor: "Redundant restating and boilerplate; steps could be merged without loss."
+      excellent: "Minimal length with no redundancy; description stays within its context-load budget; no no-op instructions; no restated or duplicated phrasing; leading words are precise and model-appropriate."
+      poor: "Redundant restating and boilerplate; steps could be merged without loss; description is bloated; body pads out no-op instructions or duplicates the description verbatim."

package/templates/skill/default.md

@@ -1,5 +1,7 @@
 ---
 name: <!-- NAME -->
+# Description rules: front-load the leading identity phrase; one trigger per genuine
+# branch (collapse synonym triggers into one); never restate the body's identity line.
 description: <!-- DESCRIPTION -->
 ---
 

package/templates/skill/pattern.md

@@ -1,5 +1,7 @@
 ---
 name: <!-- NAME -->
+# Description rules: front-load the leading identity phrase; one trigger per genuine
+# branch (collapse synonym triggers into one); never restate the body's identity line.
 description: <!-- DESCRIPTION -->
 license: Apache-2.0
 metadata:

package/templates/skill/reference.md

@@ -1,5 +1,7 @@
 ---
 name: <!-- NAME -->
+# Description rules: front-load the leading identity phrase; one trigger per genuine
+# branch (collapse synonym triggers into one); never restate the body's identity line.
 description: <!-- DESCRIPTION -->
 license: Apache-2.0
 metadata:

package/templates/skill/technique.md

@@ -1,5 +1,7 @@
 ---
 name: <!-- NAME -->
+# Description rules: front-load the leading identity phrase; one trigger per genuine
+# branch (collapse synonym triggers into one); never restate the body's identity line.
 description: <!-- DESCRIPTION -->
 license: Apache-2.0
 metadata: