karajan-code 1.40.0 → 1.41.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "1.40.0",
+  "version": "1.41.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/commands/architect.js

@@ -63,7 +63,7 @@ export async function architectCommand({ task, config, logger, context, json })
   logger.info(`Architect (${architectRole.provider}) starting...`);
 
   const agent = createAgent(architectRole.provider, config, logger);
-  const prompt = buildArchitectPrompt({ task, researchContext: context });
+  const prompt = await buildArchitectPrompt({ task, researchContext: context });
   const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
   const result = await agent.runTask({ prompt, onOutput, role: "architect" });
 

package/src/commands/code.js

@@ -17,7 +17,7 @@ export async function codeCommand({ task, config, logger }) {
       try { coderRules = await fs.readFile("coder-rules.md", "utf8"); } catch { /* no coder rules file */ }
     }
   }
-  const prompt = buildCoderPrompt({ task, coderRules, methodology: config.development?.methodology || "tdd" });
+  const prompt = await buildCoderPrompt({ task, coderRules, methodology: config.development?.methodology || "tdd" });
   const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
   const result = await coder.runTask({ prompt, onOutput, role: "coder" });
   if (!result.ok) {

package/src/commands/review.js

@@ -32,7 +32,7 @@ export async function reviewCommand({ task, config, logger, baseRef }) {
 
   const { rules } = await resolveReviewProfile({ mode: config.review_mode, projectDir: process.cwd() });
 
-  const prompt = buildReviewerPrompt({ task, diff, reviewRules: rules, mode: config.review_mode });
+  const prompt = await buildReviewerPrompt({ task, diff, reviewRules: rules, mode: config.review_mode });
   const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
   const result = await reviewer.reviewTask({ prompt, onOutput, role: "reviewer" });
   if (!result.ok) {

package/src/mcp/server-handlers.js

@@ -488,7 +488,7 @@ export async function handleCodeDirect(a, server, extra) {
       try { coderRules = await fs.readFile("coder-rules.md", "utf8"); } catch { /* no coder rules file */ }
     }
   }
-  const prompt = buildCoderPrompt({ task: a.task, coderRules, methodology: config.development?.methodology || "tdd" });
+  const prompt = await buildCoderPrompt({ task: a.task, coderRules, methodology: config.development?.methodology || "tdd" });
   sendTrackerLog(server, "coder", "running", coderRole.provider);
   runLog.logText(`[coder] agent launched, waiting for response...`);
   let result;
@@ -535,7 +535,7 @@ export async function handleReviewDirect(a, server, extra) {
   const diff = await generateDiff({ baseRef: resolvedBase });
   const { rules } = await resolveReviewProfile({ mode: config.review_mode, projectDir: process.cwd() });
 
-  const prompt = buildReviewerPrompt({ task: a.task, diff, reviewRules: rules, mode: config.review_mode });
+  const prompt = await buildReviewerPrompt({ task: a.task, diff, reviewRules: rules, mode: config.review_mode });
   sendTrackerLog(server, "reviewer", "running", reviewerRole.provider);
   runLog.logText(`[reviewer] agent launched, waiting for response...`);
   let result;
@@ -989,6 +989,40 @@ async function handleSuggest(a) {
   });
 }
 
+async function handleSkills(a) {
+  const action = a.action;
+  if (!action) return failPayload("Missing required field: action");
+
+  const { isOpenSkillsAvailable, installSkill, removeSkill, listSkills, readSkill } =
+    await import("../skills/openskills-client.js");
+
+  const opts = { projectDir: a.projectDir || null };
+
+  switch (action) {
+    case "install": {
+      if (!a.source) return failPayload("Missing required field: source (required for install)");
+      const available = await isOpenSkillsAvailable();
+      if (!available) {
+        return failPayload("OpenSkills CLI is not available. Install it with: npm install -g openskills");
+      }
+      return installSkill(a.source, { ...opts, global: a.global || false });
+    }
+    case "remove": {
+      if (!a.name) return failPayload("Missing required field: name (required for remove)");
+      return removeSkill(a.name, opts);
+    }
+    case "list": {
+      return listSkills(opts);
+    }
+    case "read": {
+      if (!a.name) return failPayload("Missing required field: name (required for read)");
+      return readSkill(a.name, opts);
+    }
+    default:
+      return failPayload(`Unknown skills action: ${action}`);
+  }
+}
+
 /* ── Handler dispatch map ─────────────────────────────────────────── */
 
 const toolHandlers = {
@@ -1013,7 +1047,8 @@ const toolHandlers = {
   kj_audit:       (a, server, extra) => handleAudit(a, server, extra),
   kj_board:       (a) => handleBoard(a),
   kj_hu:          (a, server) => handleHu(a, server),
-  kj_suggest:     (a) => handleSuggest(a)
+  kj_suggest:     (a) => handleSuggest(a),
+  kj_skills:      (a) => handleSkills(a)
 };
 
 export async function handleToolCall(name, args, server, extra) {

package/src/mcp/tools.js

@@ -347,5 +347,20 @@ export const tools = [
         projectDir: { type: "string", description: "Project directory" }
       }
     }
+  },
+  {
+    name: "kj_skills",
+    description: "Manage OpenSkills for domain-specific agent knowledge. Install skills from the marketplace or GitHub repos to give coders domain expertise.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: ["install", "remove", "list", "read"], description: "Action to perform" },
+        source: { type: "string", description: "Skill source: marketplace name, GitHub URL, or local path (for install)" },
+        name: { type: "string", description: "Skill name (for remove/read)" },
+        global: { type: "boolean", description: "Install globally (~/.agent/skills/) instead of project-local" },
+        projectDir: { type: "string", description: "Project directory" }
+      },
+      required: ["action"]
+    }
   }
 ];

package/src/orchestrator.js

@@ -40,6 +40,8 @@ import { waitForCooldown, MAX_STANDBY_RETRIES } from "./orchestrator/standby.js"
 import { detectTestFramework } from "./utils/project-detect.js";
 import { runPreflightChecks } from "./orchestrator/preflight-checks.js";
 import { detectRtk } from "./utils/rtk-detect.js";
+import { detectNeededSkills, autoInstallSkills, cleanupAutoInstalledSkills } from "./skills/skill-detector.js";
+import { isOpenSkillsAvailable } from "./skills/openskills-client.js";
 
 
 // --- Product Context loader ---
@@ -97,8 +99,8 @@ async function handleDryRun({ task, config, flags, emitter, pipelineFlags }) {
   const projectDir = config.projectDir || process.cwd();
   const { rules: reviewRules } = await resolveReviewProfile({ mode: config.review_mode, projectDir });
   const coderRules = await loadFirstExisting(resolveRoleMdPath("coder", projectDir));
-  const coderPrompt = buildCoderPrompt({ task, coderRules, methodology: config.development?.methodology, serenaEnabled: Boolean(config.serena?.enabled), rtkAvailable: Boolean(config.rtk?.available), productContext: config.productContext || null });
-  const reviewerPrompt = buildReviewerPrompt({ task, diff: "(dry-run: no diff)", reviewRules, mode: config.review_mode, serenaEnabled: Boolean(config.serena?.enabled), rtkAvailable: Boolean(config.rtk?.available), productContext: config.productContext || null });
+  const coderPrompt = await buildCoderPrompt({ task, coderRules, methodology: config.development?.methodology, serenaEnabled: Boolean(config.serena?.enabled), rtkAvailable: Boolean(config.rtk?.available), productContext: config.productContext || null });
+  const reviewerPrompt = await buildReviewerPrompt({ task, diff: "(dry-run: no diff)", reviewRules, mode: config.review_mode, serenaEnabled: Boolean(config.serena?.enabled), rtkAvailable: Boolean(config.rtk?.available), productContext: config.productContext || null });
 
   const summary = {
     dry_run: true,
@@ -845,6 +847,29 @@ async function runPreLoopStages({ config, logger, emitter, eventBase, session, f
   applyTriageOverrides(pipelineFlags, triageResult.roleOverrides);
   stageResults.triage = triageResult.stageResult;
 
+  // --- Auto-install skills based on task + project detection ---
+  const projectDir = config.projectDir || process.cwd();
+  try {
+    const osAvailable = await isOpenSkillsAvailable();
+    if (osAvailable) {
+      const neededSkills = await detectNeededSkills(task, projectDir);
+      if (neededSkills.length > 0) {
+        const skillResult = await autoInstallSkills(neededSkills, projectDir);
+        if (skillResult.installed.length > 0) {
+          session.autoInstalledSkills = skillResult.installed;
+        }
+        emitProgress(emitter, makeEvent("skills:auto-install", { ...eventBase, stage: "triage" }, {
+          message: skillResult.installed.length > 0
+            ? `Auto-installed ${skillResult.installed.length} skill(s): ${skillResult.installed.join(", ")}`
+            : `Skills detected (${neededSkills.join(", ")}) — all already installed or unavailable`,
+          detail: skillResult
+        }));
+      }
+    }
+  } catch (err) {
+    logger.warn(`Skill auto-install failed (non-blocking): ${err.message}`);
+  }
+
   // --- HU Reviewer auto-activation from triage (post-triage, no huFile needed) ---
   const triageRoles = new Set(triageResult.stageResult?.roles || []);
   if (triageRoles.has("hu-reviewer") && !stageResults.huReviewer) {
@@ -1387,44 +1412,60 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
 
   const ctx = await initFlowContext({ task, config, logger, emitter, askQuestion, pgTaskId, pgProject, flags });
 
-  // --- HU Sub-Pipeline: run each certified HU as an independent iteration loop ---
-  if (needsSubPipeline(ctx.stageResults.huReviewer)) {
-    logger.info(`HU sub-pipeline: ${ctx.stageResults.huReviewer.certified} certified stories — running each as a sub-pipeline`);
-    emitProgress(emitter, makeEvent("hu:sub-pipeline:start", { ...ctx.eventBase, stage: "hu-sub-pipeline" }, {
-      message: `Running ${ctx.stageResults.huReviewer.certified} HUs as sub-pipelines`,
-      detail: { total: ctx.stageResults.huReviewer.total, certified: ctx.stageResults.huReviewer.certified }
-    }));
+  try {
+    // --- HU Sub-Pipeline: run each certified HU as an independent iteration loop ---
+    if (needsSubPipeline(ctx.stageResults.huReviewer)) {
+      logger.info(`HU sub-pipeline: ${ctx.stageResults.huReviewer.certified} certified stories — running each as a sub-pipeline`);
+      emitProgress(emitter, makeEvent("hu:sub-pipeline:start", { ...ctx.eventBase, stage: "hu-sub-pipeline" }, {
+        message: `Running ${ctx.stageResults.huReviewer.certified} HUs as sub-pipelines`,
+        detail: { total: ctx.stageResults.huReviewer.total, certified: ctx.stageResults.huReviewer.certified }
+      }));
 
-    const subPipelineResult = await runHuSubPipeline({
-      huReviewerResult: ctx.stageResults.huReviewer,
-      runIterationFn: async (huTask) => runIterationLoop(ctx, { task: huTask, askQuestion, emitter, logger }),
-      emitter,
-      eventBase: ctx.eventBase,
-      logger
-    });
+      const subPipelineResult = await runHuSubPipeline({
+        huReviewerResult: ctx.stageResults.huReviewer,
+        runIterationFn: async (huTask) => runIterationLoop(ctx, { task: huTask, askQuestion, emitter, logger }),
+        emitter,
+        eventBase: ctx.eventBase,
+        logger
+      });
 
-    emitProgress(emitter, makeEvent("hu:sub-pipeline:end", { ...ctx.eventBase, stage: "hu-sub-pipeline" }, {
-      status: subPipelineResult.approved ? "ok" : "fail",
-      message: subPipelineResult.approved
-        ? "All HUs completed successfully"
-        : `Sub-pipeline finished with failures (${subPipelineResult.blockedIds.length} blocked)`,
-      detail: { results: subPipelineResult.results, blockedIds: subPipelineResult.blockedIds }
-    }));
+      emitProgress(emitter, makeEvent("hu:sub-pipeline:end", { ...ctx.eventBase, stage: "hu-sub-pipeline" }, {
+        status: subPipelineResult.approved ? "ok" : "fail",
+        message: subPipelineResult.approved
+          ? "All HUs completed successfully"
+          : `Sub-pipeline finished with failures (${subPipelineResult.blockedIds.length} blocked)`,
+        detail: { results: subPipelineResult.results, blockedIds: subPipelineResult.blockedIds }
+      }));
 
-    const finalResult = {
-      approved: subPipelineResult.approved,
-      sessionId: ctx.session.id,
-      huResults: subPipelineResult.results,
-      blockedIds: subPipelineResult.blockedIds
-    };
-    await writeHistoryRecord({ sessionId: ctx.session.id, task, result: finalResult, logger });
-    return finalResult;
-  }
+      const finalResult = {
+        approved: subPipelineResult.approved,
+        sessionId: ctx.session.id,
+        huResults: subPipelineResult.results,
+        blockedIds: subPipelineResult.blockedIds
+      };
+      await writeHistoryRecord({ sessionId: ctx.session.id, task, result: finalResult, logger });
+      return finalResult;
+    }
 
-  // --- Standard single-task pipeline (1 HU or no HU reviewer) ---
-  const result = await runIterationLoop(ctx, { task: ctx.plannedTask, askQuestion, emitter, logger });
-  await writeHistoryRecord({ sessionId: ctx.session.id, task, result, logger });
-  return result;
+    // --- Standard single-task pipeline (1 HU or no HU reviewer) ---
+    const result = await runIterationLoop(ctx, { task: ctx.plannedTask, askQuestion, emitter, logger });
+    await writeHistoryRecord({ sessionId: ctx.session.id, task, result, logger });
+    return result;
+  } finally {
+    // --- Cleanup auto-installed skills ---
+    const autoSkills = ctx.session?.autoInstalledSkills;
+    if (autoSkills && autoSkills.length > 0) {
+      const cleanProjectDir = ctx.config?.projectDir || process.cwd();
+      try {
+        const cleanupResult = await cleanupAutoInstalledSkills(autoSkills, cleanProjectDir);
+        if (cleanupResult.removed.length > 0) {
+          logger.info(`Cleaned up ${cleanupResult.removed.length} auto-installed skill(s): ${cleanupResult.removed.join(", ")}`);
+        }
+      } catch (err) {
+        logger.warn(`Skill cleanup failed (non-blocking): ${err.message}`);
+      }
+    }
+  }
 }
 
 export async function resumeFlow({ sessionId, answer, config, logger, flags = {}, emitter = null, askQuestion = null }) {

package/src/prompts/architect.js

@@ -1,3 +1,5 @@
+import { loadAvailableSkills, buildSkillSection } from "../skills/skill-loader.js";
+
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
   "Do NOT ask about using Karajan, do NOT mention Karajan, do NOT suggest orchestration.",
@@ -6,7 +8,7 @@ const SUBAGENT_PREAMBLE = [
 
 export const VALID_VERDICTS = new Set(["ready", "needs_clarification"]);
 
-export function buildArchitectPrompt({ task, instructions, researchContext = null, productContext = null }) {
+export async function buildArchitectPrompt({ task, instructions, researchContext = null, productContext = null, projectDir = null }) {
   const sections = [SUBAGENT_PREAMBLE];
 
   if (instructions) {
@@ -41,6 +43,14 @@ export function buildArchitectPrompt({ task, instructions, researchContext = nul
 
   sections.push(`## Task\n${task}`);
 
+  if (projectDir) {
+    const skills = await loadAvailableSkills(projectDir);
+    const skillSection = buildSkillSection(skills);
+    if (skillSection) {
+      sections.push(skillSection);
+    }
+  }
+
   return sections.join("\n\n");
 }
 

package/src/prompts/coder.js

@@ -1,4 +1,5 @@
 import { RTK_INSTRUCTIONS } from "./rtk-snippet.js";
+import { loadAvailableSkills, buildSkillSection } from "../skills/skill-loader.js";
 
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
@@ -31,7 +32,7 @@ const SERENA_INSTRUCTIONS = [
   "Fall back to reading files only when Serena tools are not sufficient."
 ].join("\n");
 
-export function buildCoderPrompt({ task, reviewerFeedback = null, sonarSummary = null, coderRules = null, methodology = "tdd", serenaEnabled = false, rtkAvailable = false, deferredContext = null, productContext = null, plan = null }) {
+export async function buildCoderPrompt({ task, reviewerFeedback = null, sonarSummary = null, coderRules = null, methodology = "tdd", serenaEnabled = false, rtkAvailable = false, deferredContext = null, productContext = null, plan = null, projectDir = null }) {
   const sections = [
     serenaEnabled ? SUBAGENT_PREAMBLE_SERENA : SUBAGENT_PREAMBLE,
     `Task:\n${task}`,
@@ -83,5 +84,13 @@ export function buildCoderPrompt({ task, reviewerFeedback = null, sonarSummary =
     sections.push(deferredContext);
   }
 
+  if (projectDir) {
+    const skills = await loadAvailableSkills(projectDir);
+    const skillSection = buildSkillSection(skills);
+    if (skillSection) {
+      sections.push(skillSection);
+    }
+  }
+
   return sections.join("\n\n");
 }

package/src/prompts/reviewer.js

@@ -1,4 +1,5 @@
 import { RTK_INSTRUCTIONS } from "./rtk-snippet.js";
+import { loadAvailableSkills, buildSkillSection } from "../skills/skill-loader.js";
 
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
@@ -22,7 +23,7 @@ const SERENA_INSTRUCTIONS = [
   "Fall back to reading files only when Serena tools are not sufficient."
 ].join("\n");
 
-export function buildReviewerPrompt({ task, diff, reviewRules, mode, serenaEnabled = false, rtkAvailable = false, productContext = null }) {
+export async function buildReviewerPrompt({ task, diff, reviewRules, mode, serenaEnabled = false, rtkAvailable = false, productContext = null, projectDir = null }) {
   const truncatedDiff = diff.length > 12000 ? `${diff.slice(0, 12000)}\n\n[TRUNCATED]` : diff;
 
   const sections = [
@@ -53,5 +54,13 @@ export function buildReviewerPrompt({ task, diff, reviewRules, mode, serenaEnabl
     `Git diff:\n${truncatedDiff}`
   );
 
+  if (projectDir) {
+    const skills = await loadAvailableSkills(projectDir);
+    const skillSection = buildSkillSection(skills);
+    if (skillSection) {
+      sections.push(skillSection);
+    }
+  }
+
   return sections.join("\n\n");
 }

package/src/roles/architect-role.js

@@ -59,7 +59,7 @@ export class ArchitectRole extends BaseRole {
     const provider = resolveProvider(this.config);
     const agent = this._createAgent(provider, this.config, this.logger);
 
-    const prompt = buildArchitectPrompt({ task, instructions: this.instructions, researchContext, productContext: this.config?.productContext || null });
+    const prompt = await buildArchitectPrompt({ task, instructions: this.instructions, researchContext, productContext: this.config?.productContext || null });
     const runArgs = { prompt, role: "architect" };
     if (onOutput) runArgs.onOutput = onOutput;
     const result = await agent.runTask(runArgs);

package/src/roles/coder-role.js

@@ -34,7 +34,7 @@ export class CoderRole extends BaseRole {
       this.logger.info(`Host-as-coder: delegating to host AI (skipping ${provider} subprocess)`);
     }
 
-    const prompt = buildCoderPrompt({
+    const prompt = await buildCoderPrompt({
       task: task || this.context?.task || "",
       reviewerFeedback: reviewerFeedback || null,
       sonarSummary: sonarSummary || null,

package/src/skills/openskills-client.js

@@ -0,0 +1,157 @@
+/**
+ * OpenSkills CLI client.
+ * Wraps `npx openskills` commands for installing, removing, listing, and reading skills.
+ */
+
+import { runCommand } from "../utils/process.js";
+
+const NPX = "npx";
+const PKG = "openskills";
+
+function buildCwd(projectDir) {
+  return projectDir || process.cwd();
+}
+
+/**
+ * Check whether the openskills CLI is available.
+ * @returns {Promise<boolean>}
+ */
+export async function isOpenSkillsAvailable() {
+  try {
+    const result = await runCommand(NPX, [PKG, "--version"], {
+      timeout: 15_000
+    });
+    return result.exitCode === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Install a skill from a marketplace name, GitHub URL, or local path.
+ * @param {string} source - Skill source identifier.
+ * @param {object} opts
+ * @param {string} [opts.projectDir] - Working directory.
+ * @param {boolean} [opts.global] - Install globally (~/.agent/skills/).
+ * @returns {Promise<{ok: boolean, name?: string, error?: string}>}
+ */
+export async function installSkill(source, { projectDir, global: isGlobal } = {}) {
+  if (!source) {
+    return { ok: false, error: "source is required for install" };
+  }
+
+  const args = [PKG, "install", source];
+  if (isGlobal) args.push("--global");
+
+  const result = await runCommand(NPX, args, {
+    cwd: buildCwd(projectDir),
+    timeout: 60_000
+  });
+
+  if (result.exitCode !== 0) {
+    const stderr = (result.stderr || "").trim();
+    return { ok: false, error: stderr || `install failed (exit ${result.exitCode})` };
+  }
+
+  // Try to extract the skill name from stdout
+  const output = (result.stdout || "").trim();
+  const nameMatch = output.match(/installed\s+(?:skill\s+)?["']?([^\s"']+)["']?/i)
+    || output.match(/([^\s/]+)\s*$/);
+  const name = nameMatch ? nameMatch[1] : source;
+
+  return { ok: true, name };
+}
+
+/**
+ * Remove an installed skill by name.
+ * @param {string} name - Skill name.
+ * @param {object} opts
+ * @param {string} [opts.projectDir] - Working directory.
+ * @returns {Promise<{ok: boolean, error?: string}>}
+ */
+export async function removeSkill(name, { projectDir } = {}) {
+  if (!name) {
+    return { ok: false, error: "name is required for remove" };
+  }
+
+  const result = await runCommand(NPX, [PKG, "remove", name], {
+    cwd: buildCwd(projectDir),
+    timeout: 30_000
+  });
+
+  if (result.exitCode !== 0) {
+    const stderr = (result.stderr || "").trim();
+    return { ok: false, error: stderr || `remove failed (exit ${result.exitCode})` };
+  }
+
+  return { ok: true };
+}
+
+/**
+ * List installed skills.
+ * @param {object} opts
+ * @param {string} [opts.projectDir] - Working directory.
+ * @returns {Promise<{ok: boolean, skills?: Array<{name: string, source?: string, scope?: string}>, error?: string}>}
+ */
+export async function listSkills({ projectDir } = {}) {
+  const result = await runCommand(NPX, [PKG, "list", "--json"], {
+    cwd: buildCwd(projectDir),
+    timeout: 30_000
+  });
+
+  if (result.exitCode !== 0) {
+    // Fallback: try without --json
+    const fallback = await runCommand(NPX, [PKG, "list"], {
+      cwd: buildCwd(projectDir),
+      timeout: 30_000
+    });
+
+    if (fallback.exitCode !== 0) {
+      const stderr = (fallback.stderr || "").trim();
+      return { ok: false, error: stderr || `list failed (exit ${fallback.exitCode})` };
+    }
+
+    // Parse text output: each line is a skill name
+    const lines = (fallback.stdout || "").split("\n").map(l => l.trim()).filter(Boolean);
+    const skills = lines.map(line => ({ name: line }));
+    return { ok: true, skills };
+  }
+
+  // Parse JSON output
+  const stdout = (result.stdout || "").trim();
+  try {
+    const parsed = JSON.parse(stdout);
+    const skills = Array.isArray(parsed) ? parsed : (parsed.skills || []);
+    return { ok: true, skills };
+  } catch {
+    // If JSON parse fails, treat as text
+    const lines = stdout.split("\n").map(l => l.trim()).filter(Boolean);
+    const skills = lines.map(line => ({ name: line }));
+    return { ok: true, skills };
+  }
+}
+
+/**
+ * Read a skill's content by name.
+ * @param {string} name - Skill name.
+ * @param {object} opts
+ * @param {string} [opts.projectDir] - Working directory.
+ * @returns {Promise<{ok: boolean, content?: string, error?: string}>}
+ */
+export async function readSkill(name, { projectDir } = {}) {
+  if (!name) {
+    return { ok: false, error: "name is required for read" };
+  }
+
+  const result = await runCommand(NPX, [PKG, "read", name], {
+    cwd: buildCwd(projectDir),
+    timeout: 30_000
+  });
+
+  if (result.exitCode !== 0) {
+    const stderr = (result.stderr || "").trim();
+    return { ok: false, error: stderr || `read failed (exit ${result.exitCode})` };
+  }
+
+  return { ok: true, content: (result.stdout || "").trim() };
+}

package/src/skills/skill-detector.js

@@ -0,0 +1,187 @@
+/**
+ * Detects needed skills from task description and project files,
+ * then auto-installs them via OpenSkills if available.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { loadAvailableSkills } from "./skill-loader.js";
+import { isOpenSkillsAvailable, installSkill, removeSkill } from "./openskills-client.js";
+
+/**
+ * Known frameworks detectable from package.json dependencies.
+ * Maps dependency name to the skill name to search for.
+ */
+const PKG_JSON_FRAMEWORKS = {
+  astro: "astro",
+  next: "nextjs",
+  react: "react",
+  "react-dom": "react",
+  vue: "vue",
+  svelte: "svelte",
+  "@angular/core": "angular",
+  express: "express",
+  fastify: "fastify",
+  "@nestjs/core": "nestjs",
+};
+
+/**
+ * Language markers: file presence maps to a skill name.
+ * Reuses the same concept as src/utils/project-detect.js LANGUAGE_MARKERS.
+ */
+const LANGUAGE_FILE_MARKERS = [
+  { file: "pom.xml", skill: "java" },
+  { file: "build.gradle", skill: "java" },
+  { file: "build.gradle.kts", skill: "kotlin" },
+  { file: "go.mod", skill: "go" },
+  { file: "Cargo.toml", skill: "rust" },
+  { file: "pyproject.toml", skill: "python" },
+  { file: "setup.py", skill: "python" },
+  { file: "Gemfile", skill: "ruby" },
+  { file: "pubspec.yaml", skill: "flutter" },
+  { file: "Package.swift", skill: "swift" },
+  { file: "phpunit.xml", skill: "php" },
+  { file: "composer.json", skill: "php" },
+];
+
+/**
+ * Patterns to detect framework/skill mentions in the task text.
+ * Each entry: regex pattern (case-insensitive) -> skill name.
+ */
+const TASK_TEXT_PATTERNS = [
+  { pattern: /\bastro\b/i, skill: "astro" },
+  { pattern: /\bnext\.?js\b/i, skill: "nextjs" },
+  { pattern: /\breact\b/i, skill: "react" },
+  { pattern: /\bvue\b/i, skill: "vue" },
+  { pattern: /\bsvelte\b/i, skill: "svelte" },
+  { pattern: /\bangular\b/i, skill: "angular" },
+  { pattern: /\bexpress\b/i, skill: "express" },
+  { pattern: /\bfastify\b/i, skill: "fastify" },
+  { pattern: /\bnest\.?js\b/i, skill: "nestjs" },
+  { pattern: /\bjava\b/i, skill: "java" },
+  { pattern: /\bkotlin\b/i, skill: "kotlin" },
+  { pattern: /\bgo(?:lang)?\b/i, skill: "go" },
+  { pattern: /\brust\b/i, skill: "rust" },
+  { pattern: /\bpython\b/i, skill: "python" },
+  { pattern: /\bruby\b/i, skill: "ruby" },
+  { pattern: /\bflutter\b/i, skill: "flutter" },
+  { pattern: /\bswift\b/i, skill: "swift" },
+  { pattern: /\bphp\b/i, skill: "php" },
+];
+
+/**
+ * Analyze the task and project to determine what skills might be needed.
+ * @param {string} task - The task description text.
+ * @param {string} projectDir - Absolute path to project root.
+ * @returns {Promise<string[]>} Array of unique skill names to search for.
+ */
+export async function detectNeededSkills(task, projectDir) {
+  const needed = new Set();
+
+  // 1. Scan package.json for known frameworks
+  if (projectDir) {
+    try {
+      const pkgRaw = await fs.readFile(path.join(projectDir, "package.json"), "utf8");
+      const pkg = JSON.parse(pkgRaw);
+      const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+      for (const [dep, skill] of Object.entries(PKG_JSON_FRAMEWORKS)) {
+        if (allDeps[dep]) {
+          needed.add(skill);
+        }
+      }
+    } catch { /* no package.json or parse error — skip */ }
+
+    // 2. Check for language markers
+    for (const marker of LANGUAGE_FILE_MARKERS) {
+      try {
+        await fs.access(path.join(projectDir, marker.file));
+        needed.add(marker.skill);
+      } catch { /* file not found — skip */ }
+    }
+  }
+
+  // 3. Check task text for framework mentions
+  if (task) {
+    for (const { pattern, skill } of TASK_TEXT_PATTERNS) {
+      if (pattern.test(task)) {
+        needed.add(skill);
+      }
+    }
+  }
+
+  return Array.from(needed);
+}
+
+/**
+ * Auto-install needed skills that are not yet installed.
+ * @param {string[]} neededSkills - Skill names to ensure are installed.
+ * @param {string} projectDir - Absolute path to project root.
+ * @returns {Promise<{installed: string[], failed: string[], alreadyInstalled: string[]}>}
+ */
+export async function autoInstallSkills(neededSkills, projectDir) {
+  const result = { installed: [], failed: [], alreadyInstalled: [] };
+
+  if (!neededSkills || neededSkills.length === 0) {
+    return result;
+  }
+
+  // Check which skills are already installed locally
+  const existingSkills = await loadAvailableSkills(projectDir);
+  const existingNames = new Set(existingSkills.map(s => s.name.toLowerCase()));
+
+  // Check if OpenSkills is available
+  const osAvailable = await isOpenSkillsAvailable();
+  if (!osAvailable) {
+    // All skills count as "failed" silently — caller should check osAvailable separately
+    return result;
+  }
+
+  for (const skillName of neededSkills) {
+    if (existingNames.has(skillName.toLowerCase())) {
+      result.alreadyInstalled.push(skillName);
+      continue;
+    }
+
+    try {
+      const installResult = await installSkill(skillName, { projectDir });
+      if (installResult.ok) {
+        result.installed.push(installResult.name || skillName);
+      } else {
+        result.failed.push(skillName);
+      }
+    } catch {
+      result.failed.push(skillName);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Remove skills that were auto-installed during this session.
+ * @param {string[]} skillNames - Skill names to remove.
+ * @param {string} projectDir - Absolute path to project root.
+ * @returns {Promise<{removed: string[], failed: string[]}>}
+ */
+export async function cleanupAutoInstalledSkills(skillNames, projectDir) {
+  const result = { removed: [], failed: [] };
+
+  if (!skillNames || skillNames.length === 0) {
+    return result;
+  }
+
+  for (const name of skillNames) {
+    try {
+      const removeResult = await removeSkill(name, { projectDir });
+      if (removeResult.ok) {
+        result.removed.push(name);
+      } else {
+        result.failed.push(name);
+      }
+    } catch {
+      result.failed.push(name);
+    }
+  }
+
+  return result;
+}

package/src/skills/skill-loader.js

@@ -0,0 +1,58 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const SKILL_DIRS = [".agent/skills", ".claude/skills"];
+const SKILL_FILE = "SKILL.md";
+
+/**
+ * Scans known skill directories for SKILL.md files.
+ * @param {string} projectDir — absolute path to the project root
+ * @returns {Promise<Array<{name: string, content: string}>>}
+ */
+export async function loadAvailableSkills(projectDir) {
+  const skills = [];
+
+  for (const rel of SKILL_DIRS) {
+    const dir = join(projectDir, rel);
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      continue; // directory does not exist — skip
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const skillPath = join(dir, entry.name, SKILL_FILE);
+      try {
+        const content = await readFile(skillPath, "utf-8");
+        skills.push({ name: entry.name, content });
+      } catch {
+        // no SKILL.md in this subdirectory — skip
+      }
+    }
+  }
+
+  return skills;
+}
+
+/**
+ * Builds a prompt section from loaded skills.
+ * @param {Array<{name: string, content: string}>} skills
+ * @returns {string} prompt section or empty string
+ */
+export function buildSkillSection(skills) {
+  if (!skills || skills.length === 0) return "";
+
+  const header = [
+    "## Domain Skills",
+    "",
+    "The following domain-specific knowledge is available for this task:"
+  ].join("\n");
+
+  const blocks = skills.map(
+    (s) => `### ${s.name}\n${s.content}`
+  );
+
+  return [header, ...blocks].join("\n\n");
+}