@kaddo/cli 3.20.0 → 3.21.0

package/README.md

@@ -505,6 +505,9 @@ create --from roadmap → owners → guard → explain`.
 | v3.16 | Knowledge Capsules: `kaddo capsule export/add`, External Knowledge in context/explain, new `capsule-agent` |
 | v3.17 | Knowledge Graph Export: `kaddo graph export` (`.kaddo/graph.json` + `.mmd`, `--scope`/`--format`); graph summary in context/explain |
 | v3.18 | Graph relationship quality & metadata hints: `graph-hints.md`/`.json`, quality levels, `graph-agent`; hints in context/explain/understand |
+| v3.19 | Read-only MCP server `@kaddo/mcp` (resources, tools, prompts over stdio) |
+| v3.20 | MCP derived tools: safe regeneration of context/explain/understand/graph/capsule-draft under `.kaddo/` |
+| v3.21 | Reusable Skills layer (`kaddo add skills`); skills in context/explain/understand, agent prompts and MCP |
 
 **Optional modules (installed with `kaddo add`):**
 

package/dist/index.js

@@ -1487,6 +1487,386 @@ var guardAdvancedModule = {
   ]
 };
 
+// src/skills/skills.ts
+function skill(id, title, group, appliesTo, body) {
+  const frontMatter2 = [
+    "---",
+    "type: skill",
+    `id: ${id}`,
+    `title: ${title}`,
+    "version: 1",
+    `group: ${group}`,
+    "applies_to:",
+    ...appliesTo.map((a) => `  - ${a}`),
+    "---",
+    ""
+  ].join("\n");
+  return { id, title, group, appliesTo, content: frontMatter2 + body.trimStart() };
+}
+var ADR_WRITING = skill(
+  "adr-writing",
+  "ADR Writing Skill",
+  "tech",
+  ["decision-agent", "architecture-agent", "implementation-agent"],
+  `
+# ADR Writing Skill
+
+## Purpose
+
+Standardize how Architecture Decision Records are written so every decision is captured the same
+way and stays auditable.
+
+## When to use
+
+When a real, consequential technical decision is being made or recognized \u2014 and only then.
+
+## Inputs
+
+The context pack, the relevant Work Item or architecture note, and the decision being made.
+
+## Output
+
+A single ADR containing: context, the decision, alternatives considered, consequences, the code
+paths it governs (\`code:\` globs when known) and the decision status (proposed / accepted /
+superseded).
+
+## Rules
+
+- One ADR = one decision. Never mix unrelated decisions.
+- Never invent decisions; never write an ADR without a clear reason.
+- Record alternatives honestly, including the one chosen and why.
+- Prefer narrow governed \`code:\` globs over broad ones.
+
+## Quality checklist
+
+- Context explains why the decision was needed.
+- The decision and its alternatives are explicit.
+- Consequences (positive and negative) are stated.
+- Status and governed paths are present.
+
+## Example output
+
+\`\`\`md
+# ADR-0007 \u2014 Use SQLite for local persistence
+Status: accepted
+## Context
+...
+## Decision
+...
+## Alternatives considered
+...
+## Consequences
+...
+\`\`\`
+`
+);
+var WORK_ITEM_REFINEMENT = skill(
+  "work-item-refinement",
+  "Work Item Refinement Skill",
+  "delivery",
+  ["work-item-agent", "backlog-agent", "roadmap-agent"],
+  `
+# Work Item Refinement Skill
+
+## Purpose
+
+Standardize how a Work Item is sharpened from a rough idea into a ready, implementable item.
+
+## When to use
+
+When improving a draft Work Item, or turning a backlog idea / roadmap candidate into a ready item.
+
+## Inputs
+
+The context pack and the Work Item (draft or candidate).
+
+## Output
+
+An improved Work Item with: problem, expected result, scope, out of scope, acceptance criteria,
+validation (how to test it), definition of done, open questions and dependencies.
+
+## Rules
+
+- Do not implement code.
+- Do not expand scope without explicit confirmation.
+- Do not create mega Work Items \u2014 split when it covers multiple outcomes.
+- Keep acceptance criteria testable.
+
+## Quality checklist
+
+- Problem and expected result are unambiguous.
+- Scope and out-of-scope are explicit.
+- Acceptance criteria and validation are present and testable.
+- Open questions and dependencies are surfaced, not hidden.
+
+## Example output
+
+A Work Item markdown with the sections above filled in, ready for the implementation-agent.
+`
+);
+var OWNERSHIP_SUGGESTION = skill(
+  "ownership-suggestion",
+  "Ownership Suggestion Skill",
+  "tech",
+  ["ownership-agent", "work-item-agent", "graph-agent", "implementation-agent"],
+  `
+# Ownership Suggestion Skill
+
+## Purpose
+
+Standardize how precise \`code:\` ownership globs are proposed so Guard can relate code changes to
+the right knowledge.
+
+## When to use
+
+When a Work Item or artifact is missing ownership, or its ownership is too broad/inaccurate.
+
+## Inputs
+
+The context pack, the Work Item, and the technical inventory / codebase notes.
+
+## Output
+
+A \`code:\` glob proposal, e.g.
+
+\`\`\`yaml
+code:
+  - src/database/**
+  - src/cli/**
+\`\`\`
+
+## Rules
+
+- Prefer small, specific globs; avoid \`src/**\`.
+- Use only real paths; validate intent against the Work Item.
+- Explain uncertainty instead of guessing.
+- Propose only \u2014 the human applies with \`kaddo owners suggest\`.
+
+## Quality checklist
+
+- Every glob maps to a real path relevant to the item.
+- No catch-all globs.
+- Uncertainty is marked.
+
+## Example output
+
+The YAML \`code:\` block above plus a one-line rationale per glob.
+`
+);
+var GRAPH_METADATA_REVIEW = skill(
+  "graph-metadata-review",
+  "Graph Metadata Review Skill",
+  "tech",
+  ["graph-agent", "ownership-agent", "work-item-agent"],
+  `
+# Graph Metadata Review Skill
+
+## Purpose
+
+Standardize how \`kaddo graph export\` hints become precise relationship front matter.
+
+## When to use
+
+When relationship quality is partial/sparse/empty, or when reviewing \`.kaddo/graph-hints.md\`.
+
+## Inputs
+
+The context pack, \`.kaddo/graph.json\` and \`.kaddo/graph-hints.md\`, plus the affected artifacts.
+
+## Output
+
+Front matter proposals, e.g.
+
+\`\`\`yaml
+capabilities:
+  - local-persistence
+decisions:
+  - ADR-0001
+code:
+  - src/database/**
+capsules:
+  - orders-service
+\`\`\`
+
+## Rules
+
+- Never invent relationships, paths or IDs.
+- Do not try to resolve every hint at once \u2014 propose what is justified.
+- Do not modify artifacts; the human applies and re-runs \`kaddo graph export\`.
+
+## Quality checklist
+
+- Each proposal maps to a real artifact/path/capability/ADR/capsule.
+- Globs are narrow; uncertainty is marked.
+
+## Example output
+
+The YAML proposal above, grouped per artifact, with a short reason each.
+`
+);
+var CAPSULE_WRITING = skill(
+  "capsule-writing",
+  "Capsule Writing Skill",
+  "integration",
+  ["capsule-agent", "architecture-agent", "product-agent"],
+  `
+# Capsule Writing Skill
+
+## Purpose
+
+Standardize how a Knowledge Capsule is written/reviewed so external consumers get safe, useful
+context.
+
+## When to use
+
+When creating or refining a Knowledge Capsule for sharing with another project.
+
+## Inputs
+
+The context pack, capabilities, current-state, decisions and any public contracts.
+
+## Output
+
+A capsule with: purpose, responsibilities, capabilities, contracts, dependencies, risks, owners,
+out of scope and usage notes.
+
+## Rules
+
+- Never include secrets, tokens, credentials, source code, PII or unnecessary internal detail.
+- Never invent contracts; mark unknowns.
+- Summarize boundaries; prefer "unknown" over guessing.
+
+## Quality checklist
+
+- Purpose and boundaries are clear.
+- Contracts are real, not invented.
+- No secrets/source/PII included.
+
+## Example output
+
+A \`*.capsule.md\` with the sections above.
+`
+);
+var LEARNING_CAPTURE = skill(
+  "learning-capture",
+  "Learning Capture Skill",
+  "delivery",
+  ["implementation-agent", "guard-agent", "architecture-agent", "work-item-agent"],
+  `
+# Learning Capture Skill
+
+## Purpose
+
+Standardize how a Work Item's learning is captured when it closes.
+
+## When to use
+
+When finishing a Work Item, after implementation and verification.
+
+## Inputs
+
+The Work Item, the diff/result, and any decisions or surprises that came up.
+
+## Output
+
+A learning record: what was implemented, what changed, what was learned, what decision emerged,
+which knowledge must be updated, and what remains pending.
+
+## Rules
+
+- Do not close a Work Item without validation.
+- Do not hide failures; record them honestly.
+- Do not assume everything is done if errors remain.
+
+## Quality checklist
+
+- Implemented vs changed vs learned are distinct.
+- Knowledge to update is named (ADR / capabilities / current-state).
+- Pending items are listed.
+
+## Example output
+
+A short learning section appended to the Work Item or a learning note.
+`
+);
+var IMPLEMENTATION_PLANNING = skill(
+  "implementation-planning",
+  "Implementation Planning Skill",
+  "delivery",
+  ["implementation-agent", "work-item-agent"],
+  `
+# Implementation Planning Skill
+
+## Purpose
+
+Standardize the plan produced before implementation starts.
+
+## When to use
+
+Before writing code for a ready Work Item.
+
+## Inputs
+
+The context pack and the ready Work Item.
+
+## Output
+
+A plan with: technical scope, expected files, risks, validations, out of scope, implementation
+steps, and stop criteria (when to pause and ask).
+
+## Rules
+
+- Do not start coding without confirmation.
+- Do not expand scope.
+- Never make commits or push \u2014 suggest only.
+
+## Quality checklist
+
+- Scope and expected files are explicit.
+- Risks and validations are listed.
+- Stop criteria are defined.
+
+## Example output
+
+A numbered plan covering the sections above, ending with a request to confirm before coding.
+`
+);
+var SKILLS = [
+  ADR_WRITING,
+  WORK_ITEM_REFINEMENT,
+  OWNERSHIP_SUGGESTION,
+  GRAPH_METADATA_REVIEW,
+  CAPSULE_WRITING,
+  LEARNING_CAPTURE,
+  IMPLEMENTATION_PLANNING
+];
+var SKILL_GROUPS = {
+  delivery: ["work-item-refinement", "implementation-planning", "learning-capture"],
+  tech: ["adr-writing", "ownership-suggestion", "graph-metadata-review"],
+  integration: ["capsule-writing"]
+};
+var SKILL_GROUP_NAMES = Object.keys(SKILL_GROUPS);
+var RECOMMENDED_SKILLS = [...SKILL_GROUPS.delivery, ...SKILL_GROUPS.tech];
+function skillInstallPath(id) {
+  return `knowledge/skills/${id}/skill.md`;
+}
+function selectSkills(opts) {
+  if (opts.all) {
+    return { ids: SKILLS.map((s) => s.id), label: "all skills" };
+  }
+  if (opts.group) {
+    const group = opts.group;
+    const ids = SKILL_GROUPS[group];
+    if (!ids) {
+      throw new Error(
+        `Unknown skill group "${opts.group}". Valid groups: ${SKILL_GROUP_NAMES.join(", ")}.`
+      );
+    }
+    return { ids, label: `group: ${group}` };
+  }
+  return { ids: RECOMMENDED_SKILLS, label: "recommended skills" };
+}
+
 // src/agents/responsibility.ts
 var RESPONSIBILITY_MATRIX = {
   "business-agent": {
@@ -1758,14 +2138,30 @@ function renderLanguageRule() {
     ""
   ].join("\n");
 }
+function renderSkillsSection(agent) {
+  const applicable = SKILLS.filter((s) => s.appliesTo.includes(agent));
+  if (applicable.length === 0) return "";
+  return [
+    "## Reusable Skills",
+    "",
+    "Apply these reusable skills when relevant (install with `kaddo add skills`; read them in",
+    "`knowledge/skills/` or via the Kaddo MCP server):",
+    "",
+    ...applicable.map((s) => `- **${s.id}** \u2014 ${s.title}.`),
+    ""
+  ].join("\n");
+}
 function withResponsibilityTrace(fileName, content) {
   const agent = fileName.replace(/\.md$/, "");
   if (!RESPONSIBILITY_MATRIX[agent]) return content;
+  const skills = renderSkillsSection(agent);
+  const skillsBlock = skills ? `${skills}
+` : "";
   return `${content.trimEnd()}
 
 ${renderLanguageRule()}
 ${renderAgentBoundaries(agent)}
-${renderAgentTrace(agent)}`;
+${skillsBlock}${renderAgentTrace(agent)}`;
 }
 
 // src/agents/prompts.ts
@@ -3532,74 +3928,40 @@ var agentsModule = {
 };
 
 // src/modules/skills.ts
+var skillsReadme = {
+  path: "knowledge/skills/README.md",
+  content: [
+    "# Skills",
+    "",
+    "Reusable **skill** definitions \u2014 capabilities shared across agents. A skill does not decide",
+    "WHAT to do (that is the agent); it defines HOW to do one thing well. Agents orchestrate;",
+    "skills standardize; knowledge grounds; MCP exposes.",
+    "",
+    "Skills never execute anything \u2014 they are reusable instructions, not tools. They never run",
+    "git, never call an LLM and never modify files.",
+    "",
+    "## Installed skills",
+    "",
+    ...SKILLS.map((s) => `- \`${s.id}\` (${s.group}) \u2014 ${s.title}. Applies to: ${s.appliesTo.join(", ")}.`),
+    "",
+    "## Groups",
+    "",
+    ...Object.entries(SKILL_GROUPS).map(([g, ids]) => `- **${g}**: ${ids.join(", ")}`),
+    "",
+    "Install: `kaddo add skills` (recommended), `--all`, or `--group <delivery|tech|integration>`."
+  ].join("\n")
+};
+var skillFiles = SKILLS.map((s) => ({
+  path: skillInstallPath(s.id),
+  content: s.content
+}));
 var skillsModule = {
   name: "skills",
-  description: "Reusable skills \u2014 capabilities shared across agents, teams, or projects",
+  description: "Reusable skills \u2014 capabilities shared across agents (adr-writing, work-item-refinement, \u2026)",
   configKey: "module_skills",
   dirs: ["knowledge/skills"],
-  files: [
-    {
-      path: "knowledge/skills/.gitkeep",
-      content: ""
-    },
-    {
-      path: "knowledge/skills/README.md",
-      content: [
-        "# Skills",
-        "",
-        "This directory contains skill definitions \u2014 reusable capabilities that agents",
-        "or team members can invoke.",
-        "",
-        "A skill is a well-defined, repeatable capability with:",
-        "- Clear inputs and outputs",
-        "- A defined trigger (when to use it)",
-        "- Known preconditions",
-        "",
-        "Skills differ from agents: a skill is a single capability,",
-        "an agent is an orchestrator that uses skills."
-      ].join("\n")
-    }
-  ],
-  workItemTypes: [
-    {
-      name: "skill",
-      knowledgeLevel: "K3",
-      description: "Skill \u2014 a reusable capability shared across agents, teams, or projects.",
-      questions: [
-        {
-          id: "what_it_does",
-          prompt: "What does this skill do?",
-          placeholder: "e.g. Reads the artifact front matters and returns ownership gaps",
-          frontMatterField: "what_it_does",
-          required: true
-        },
-        {
-          id: "trigger",
-          prompt: "When should this skill be invoked?",
-          placeholder: "e.g. When a guard FYI has no matching artifact with code globs",
-          frontMatterField: "trigger",
-          required: true
-        },
-        {
-          id: "inputs_outputs",
-          prompt: "What are the inputs and outputs?",
-          placeholder: "e.g. Input: list of touched files. Output: suggested artifact IDs to update",
-          frontMatterField: "inputs_outputs",
-          required: true
-        }
-      ],
-      qualityGate: [
-        "Skill is scoped to a single, reusable capability.",
-        "Trigger condition is explicit.",
-        "Inputs and outputs are defined."
-      ],
-      extraFrontMatter: {
-        skill_type: "analysis",
-        reusable_by: [],
-        code: []
-      }
-    }
-  ]
+  files: [skillsReadme, ...skillFiles],
+  workItemTypes: []
 };
 
 // src/modules/global-docs.ts
@@ -5346,7 +5708,7 @@ function runIgnoreRemove(artifactId) {
 }
 
 // src/commands/explain.ts
-import matter3 from "gray-matter";
+import matter4 from "gray-matter";
 import { parse as parseYaml9 } from "yaml";
 
 // src/core/delivery-phase.ts
@@ -6084,6 +6446,42 @@ function loadGraphHints(dir) {
   }
 }
 
+// src/services/installed-skills.ts
+import matter3 from "gray-matter";
+var SKILLS_DIR = join("knowledge", "skills");
+function discoverInstalledSkills(dir) {
+  const base = join(dir, SKILLS_DIR);
+  if (!exists(base) || !isDir(base)) return [];
+  const out = [];
+  for (const entry of readDir(base)) {
+    const skillFile = join(base, entry, "skill.md");
+    if (!isFile(skillFile)) continue;
+    try {
+      const { data } = matter3(readFile(skillFile));
+      if (data.type && String(data.type) !== "skill") continue;
+      const id = String(data.id ?? entry);
+      out.push({
+        id,
+        title: String(data.title ?? id),
+        group: String(data.group ?? "unknown"),
+        appliesTo: Array.isArray(data.applies_to) ? data.applies_to.map(String).filter(Boolean) : [],
+        relPath: `${SKILLS_DIR.replace(/\\/g, "/")}/${entry}/skill.md`
+      });
+    } catch {
+    }
+  }
+  return out.sort((a, b) => a.id.localeCompare(b.id));
+}
+function skillGroupCounts(skills) {
+  const counts = {};
+  for (const s of skills) counts[s.group] = (counts[s.group] ?? 0) + 1;
+  return counts;
+}
+function skillsForAgents(skills, agents) {
+  const set = new Set(agents.map((a) => a.replace(/\.md$/, "")));
+  return skills.filter((s) => s.appliesTo.some((a) => set.has(a))).map((s) => s.id);
+}
+
 // src/core/knowledge-discovery.ts
 var KNOWLEDGE4 = "knowledge";
 var CONSOLIDATED_TYPE = {
@@ -6416,6 +6814,10 @@ function buildProjectExplanation(dir) {
     externalCapsules: loadExternalCapsules(dir),
     graph: loadGraphSummary(dir),
     graphHints: loadGraphHints(dir),
+    skills: (() => {
+      const installed = discoverInstalledSkills(dir);
+      return { total: installed.length, byGroup: skillGroupCounts(installed) };
+    })(),
     layers,
     roadmap,
     mappedModules,
@@ -6566,6 +6968,15 @@ function renderExplanationHuman(exp) {
     if (exp.graph.generatedAt) lines.push(`- Last exported: ${exp.graph.generatedAt}`);
     lines.push("");
   }
+  if (exp.skills.total > 0) {
+    lines.push(`## Skills installed: ${exp.skills.total}`);
+    const groups = Object.entries(exp.skills.byGroup).sort((a, b) => a[0].localeCompare(b[0]));
+    if (groups.length > 0) {
+      lines.push("Groups:");
+      for (const [g, n] of groups) lines.push(`- ${g}: ${n}`);
+    }
+    lines.push("");
+  }
   if (exp.missingKnowledge.length > 0) {
     lines.push("## Missing Knowledge");
     for (const m of exp.missingKnowledge) lines.push(`- ${m}`);
@@ -6609,7 +7020,7 @@ function readKnowledge(dir) {
   if (!exists(knowledgePath)) return null;
   try {
     const raw = readFile(knowledgePath);
-    const { data, content } = matter3(raw);
+    const { data, content } = matter4(raw);
     return { content, data };
   } catch {
     return null;
@@ -6620,7 +7031,7 @@ function readRoadmap(dir) {
   if (!exists(roadmapPath)) return null;
   try {
     const raw = readFile(roadmapPath);
-    const { content } = matter3(raw);
+    const { content } = matter4(raw);
     return content.trim();
   } catch {
     return null;
@@ -6789,7 +7200,7 @@ function runExplain(opts) {
 }
 
 // src/core/context-pack.ts
-import matter4 from "gray-matter";
+import matter5 from "gray-matter";
 var CONTEXT_PACK_VERSION = "1";
 var ARCH_DIR6 = "knowledge";
 function readScanJson(dir) {
@@ -6802,7 +7213,7 @@ function readScanJson(dir) {
   }
 }
 function firstParagraph2(markdown) {
-  const body = matter4(markdown).content.trim();
+  const body = matter5(markdown).content.trim();
   const para = body.split("\n\n").map((p2) => p2.trim()).find((p2) => p2 && !p2.startsWith("#"));
   return para ?? "";
 }
@@ -6975,6 +7386,7 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     external: loadExternalCapsules(dir),
     graph: loadGraphSummary(dir),
     graphHints: loadGraphHints(dir),
+    skills: discoverInstalledSkills(dir).map((s) => s.id),
     mappedModules,
     missing,
     // VS-052: the handoff is driven by the REAL phase, not project.state, so the pack never
@@ -7168,6 +7580,12 @@ function renderContextPack(pack) {
 `);
     }
   }
+  if (pack.skills.length > 0) {
+    parts.push("## Skills\n");
+    parts.push("Available reusable skills (agents apply these; content is not inlined):\n");
+    parts.push(pack.skills.map((s) => `- ${s}`).join("\n") + "\n");
+    parts.push("Read full skill definitions in `knowledge/skills/` or via the Kaddo MCP server (`kaddo://skills`).\n");
+  }
   parts.push("## Missing Context\n");
   if (missing.length > 0) {
     parts.push(missing.map((m) => `- ${m}`).join("\n") + "\n");
@@ -7489,6 +7907,14 @@ function runUnderstand() {
   if (assessment.nextStep) {
     console.log(`Next step: ${assessment.nextStep}`);
   }
+  const installedSkills = discoverInstalledSkills(dir);
+  if (installedSkills.length > 0 && assessment.recommendedAgents.length > 0) {
+    const recSkills = skillsForAgents(installedSkills, assessment.recommendedAgents);
+    if (recSkills.length > 0) {
+      console.log("Recommended skills:");
+      for (const s of recSkills) console.log(`  - ${s}`);
+    }
+  }
   if (exp.externalCapsules.length > 0) {
     console.log("");
     console.log("External knowledge:");
@@ -7803,7 +8229,7 @@ function runStatus() {
 }
 
 // src/commands/learn.ts
-import matter5 from "gray-matter";
+import matter6 from "gray-matter";
 var ARCH_DIR9 = "knowledge";
 var WORK_ITEMS_DIR2 = "knowledge/delivery/work-items";
 function findWorkItemFile(dir, id) {
@@ -7815,7 +8241,7 @@ function findWorkItemFile(dir, id) {
 }
 function updateWorkItemFile(filePath, learning) {
   const raw = readFile(filePath);
-  const { data, content } = matter5(raw);
+  const { data, content } = matter6(raw);
   data.status = "done";
   data.completed_at = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
   let updatedContent = content;
@@ -7840,7 +8266,7 @@ ${learning.trim()}
 ${learning.trim()}
 `;
   }
-  const newRaw = matter5.stringify(updatedContent, data);
+  const newRaw = matter6.stringify(updatedContent, data);
   writeFile(filePath, newRaw);
 }
 async function runLearn(artifactId) {
@@ -7968,6 +8394,12 @@ function selectAgentModuleFiles(files, opts, state) {
   );
   return { files: selected, label };
 }
+function selectSkillModuleFiles(files, opts) {
+  const { ids, label } = selectSkills({ all: opts.all, group: opts.group });
+  const wanted = new Set(ids.map((id) => skillInstallPath(id)));
+  const selected = files.filter((f) => f.path.endsWith("README.md") || wanted.has(f.path));
+  return { files: selected, label };
+}
 function markModuleInstalled(dir, configKey, moduleName) {
   const configPath = join(dir, CONFIG_PATH5);
   if (!exists(configPath)) return;
@@ -8028,6 +8460,15 @@ function runAdd(moduleName, opts = {}, dir = cwd()) {
       console.error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
+  } else if (mod.name === "skills") {
+    try {
+      const sel = selectSkillModuleFiles(mod.files, opts);
+      filesToInstall = sel.files;
+      log2.info(`Installing skills (${sel.label}).`);
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
   }
   const written = [];
   const skipped = [];
@@ -8058,6 +8499,13 @@ function runAdd(moduleName, opts = {}, dir = cwd()) {
     outro2("Agents installed. Kaddo prepares context \u2014 your LLM does the interpretation.");
     return;
   }
+  if (mod.name === "skills") {
+    log2.info("Skills are reusable capabilities agents apply \u2014 they never run anything.");
+    log2.info("More skills: `kaddo add skills --all` or `--group <delivery|tech|integration>`.");
+    log2.info("Read them in `knowledge/skills/` or via the Kaddo MCP server (`kaddo://skills`).");
+    outro2("Skills installed. Agents orchestrate; skills standardize.");
+    return;
+  }
   if (mod.workItemTypes.length > 0) {
     log2.info(`New work item types available:`);
     for (const t of mod.workItemTypes) {
@@ -8068,7 +8516,7 @@ function runAdd(moduleName, opts = {}, dir = cwd()) {
 }
 
 // src/core/ownership-suggest.ts
-import matter6 from "gray-matter";
+import matter7 from "gray-matter";
 var SCAN_PATH = ".kaddo/scan.json";
 function normalizeGlob(input) {
   let g = input.trim().replace(/\\/g, "/");
@@ -8190,11 +8638,11 @@ function suggestGlobs(artifact, signals) {
   return [...new Set(out)];
 }
 function applyOwnership(raw, globs, mode = "replace") {
-  const parsed = matter6(raw);
+  const parsed = matter7(raw);
   const existing = toStringArray3(parsed.data.code);
   const next = mode === "append" ? [.../* @__PURE__ */ new Set([...existing, ...globs])] : [...new Set(globs)];
   const data = { ...parsed.data, code: next };
-  return matter6.stringify(parsed.content, data);
+  return matter7.stringify(parsed.content, data);
 }
 
 // src/commands/owners.ts
@@ -10444,7 +10892,7 @@ modulesCmd.command("map").description("Register a secondary repository as a modu
 modulesCmd.command("list").description("List mapped modules").action(() => {
   runModulesList();
 });
-program.command("add [module]").description("Install an optional Kaddo module (adr, incident, rfc, migration, legacy, agents, standards, security, stack, git-strategy)").option("--all", "For `add agents`: install every agent (not just the recommended set)").option("--group <name>", "For `add agents`: install one layer group (business, product, tech, delivery, utilities)").action((moduleName, opts) => {
+program.command("add [module]").description("Install an optional Kaddo module (adr, incident, rfc, migration, legacy, agents, skills, standards, security, stack, git-strategy)").option("--all", "For `add agents` / `add skills`: install every item (not just the recommended set)").option("--group <name>", "For `add agents`: business|product|tech|delivery|utilities. For `add skills`: delivery|tech|integration").action((moduleName, opts) => {
   runAdd(moduleName ?? "", { all: opts.all, group: opts.group });
 });
 program.parseAsync(process.argv).catch((err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaddo/cli",
-  "version": "3.20.0",
+  "version": "3.21.0",
   "description": "Knowledge Driven Development toolkit",
   "license": "MIT",
   "repository": {