@tyvm/knowhow 0.0.129 → 0.0.130

package/src/commands/behaviors.ts

@@ -0,0 +1,47 @@
+import { Command } from "commander";
+import { BehaviorsService } from "../services/BehaviorsService";
+
+export function addBehaviorsCommand(program: Command): void {
+  const behaviors = program
+    .command("behaviors")
+    .description("Manage org behaviors from the CLI");
+
+  behaviors
+    .command("list")
+    .description("List behaviors from backend")
+    .option("--skills-only", "Only show skill behaviors")
+    .option("--include-internal", "Include platform skills")
+    .action(async (opts) => {
+      const svc = new BehaviorsService();
+      await svc.list({
+        skillsOnly: opts.skillsOnly,
+        includeInternal: opts.includeInternal,
+      });
+    });
+
+  behaviors
+    .command("download")
+    .description("Download behaviors from backend to .knowhow/behaviors/")
+    .option("--skills-only", "Only download skill behaviors")
+    .option("--include-internal", "Include platform skills")
+    .option(
+      "--md",
+      "Save as Markdown files with YAML frontmatter instead of JSON"
+    )
+    .action(async (opts) => {
+      const svc = new BehaviorsService();
+      await svc.download({
+        skillsOnly: opts.skillsOnly,
+        includeInternal: opts.includeInternal,
+        md: opts.md,
+      });
+    });
+
+  behaviors
+    .command("upload")
+    .description("Upload behaviors from .knowhow/behaviors/ to backend")
+    .action(async () => {
+      const svc = new BehaviorsService();
+      await svc.upload();
+    });
+}

package/src/commands/services.ts

@@ -3,6 +3,7 @@ import * as allTools from "../agents/tools";
 import { LazyToolsService, services, MinimalToolsService } from "../services";
 import { agents } from "../agents";
 import { ModulesService } from "../services/modules";
+import { getConfig } from "../config";
 
 /**
  * Shared service setup used by commands that need full services (chat, agent, worker, etc.)
@@ -17,12 +18,14 @@ export async function setupServices() {
     Plugins,
     Events,
     MediaProcessor,
+    Behaviors,
   } = services();
 
-
   // cli uses LazyTools to keep context slim
   const Tools = new LazyToolsService();
+  await Behaviors.initFromConfig();
 
+  // Give LazyToolsService the same context that ToolService had
   Tools.setContext({
     ...AllTools.getContext(),
   });
@@ -70,7 +73,8 @@ export async function setupServices() {
     Clients,
     Tools,
     MediaProcessor,
-    Events
+    Behaviors,
+    Events,
   });
 
   return { Tools, Clients };

package/src/commands/skills.ts

@@ -0,0 +1,71 @@
+import { Command } from "commander";
+import { SkillsService } from "../services/SkillsService";
+
+export function addSkillsCommand(program: Command): void {
+  const skills = program
+    .command("skills")
+    .description("Manage agent skills from the skills.sh ecosystem");
+
+  skills
+    .command("add <package>")
+    .description(
+      "Add a skill. Accepts:\n" +
+        "  owner/repo@skill-name\n" +
+        "  https://github.com/owner/repo  (with --skill <name>)\n" +
+        "  https://github.com/owner/repo@skill-name"
+    )
+    .option("--skill <name>", "Skill name when using a GitHub URL as the package argument")
+    .option("--global", "Install skill globally to ~/.knowhow/skills/")
+    .option(
+      "--install-dir <dir>",
+      "Custom install directory (overrides default and --global)"
+    )
+    .action(async (pkg: string, opts: { skill?: string; global?: boolean; installDir?: string }) => {
+      const svc = new SkillsService({
+        global: opts.global,
+        installDir: opts.installDir,
+      });
+      await svc.add(pkg, opts.skill);
+    });
+
+  skills
+    .command("remove <skill>")
+    .alias("rm")
+    .description("Remove an installed skill by name")
+    .option("--global", "Remove from global ~/.knowhow/skills/")
+    .action((skillName: string, opts: { global?: boolean }) => {
+      const svc = new SkillsService({ global: opts.global });
+      svc.remove(skillName);
+    });
+
+  skills
+    .command("list")
+    .alias("ls")
+    .description("List installed skills from the lock file")
+    .option("--global", "List skills from global ~/.knowhow/skills/")
+    .action((opts: { global?: boolean }) => {
+      const svc = new SkillsService({ global: opts.global });
+      svc.list();
+    });
+
+  skills
+    .command("install")
+    .description(
+      "Install all skills from skills-lock.json (restores from lock file)"
+    )
+    .option("--global", "Install from global ~/.knowhow/skills/skills-lock.json")
+    .action(async (opts: { global?: boolean }) => {
+      const svc = new SkillsService({ global: opts.global });
+      await svc.install();
+    });
+
+  skills
+    .command("update [skills...]")
+    .alias("upgrade")
+    .description("Update installed skills to their latest versions")
+    .option("--global", "Update skills in global ~/.knowhow/skills/")
+    .action(async (skillNames: string[], opts: { global?: boolean }) => {
+      const svc = new SkillsService({ global: opts.global });
+      await svc.update(skillNames);
+    });
+}

package/src/index.ts

@@ -60,6 +60,8 @@ export { ConversionService } from "./services/conversion/ConversionService";
 // Export plugin types for external plugins
 export { PluginBase } from "./plugins/PluginBase";
 export { PluginMeta, Plugin, PluginContext } from "./plugins/types";
+export { PluginService } from "./plugins/plugins";
+export { SkillsPlugin } from "./plugins/SkillsPlugin";
 // Export embedding types
 export { MinimalEmbedding, Embeddable } from "./types";
 

package/src/plugins/PluginBase.ts

@@ -1,4 +1,3 @@
-import { MinimalEmbedding } from "../types";
 import { Plugin, PluginContext, PluginMeta } from "./types";
 
 export abstract class PluginBase implements Plugin {
@@ -66,7 +65,6 @@ export abstract class PluginBase implements Plugin {
   /** Mandatory plugin actions ---------------------------------------- */
   /* ------------------------------------------------------------------ */
   abstract call(input?: string): Promise<string>;
-  abstract embed(input: string): Promise<MinimalEmbedding[]>;
 }
 
 export { PluginMeta, Plugin } from "./types";

package/src/plugins/SkillsPlugin.ts

@@ -1,33 +1,11 @@
-import { promises as fs, Dirent } from "fs";
-import * as path from "path";
 import { PluginBase, PluginMeta } from "./PluginBase";
 import { Plugin, PluginContext } from "./types";
-import { MinimalEmbedding } from "../types";
-import { getConfig } from "../config";
-
-interface SkillMeta {
-  name: string;
-  description: string;
-  filePath: string;
-}
-
-function parseFrontmatter(content: string): Record<string, string> {
-  const match = content.match(/^---\n([\s\S]*?)\n---/);
-  if (!match) return {};
-  const result: Record<string, string> = {};
-  for (const line of match[1].split("\n")) {
-    const [key, ...rest] = line.split(":");
-    if (key && rest.length) result[key.trim()] = rest.join(":").trim();
-  }
-  return result;
-}
 
 export class SkillsPlugin extends PluginBase implements Plugin {
   static readonly meta: PluginMeta = {
     key: "skills",
     name: "Skills Plugin",
-    description:
-      "Scans configured skills directories for SKILL.md files and provides skill content to agents",
+    description: "Lists available skills",
     requires: [],
   };
 
@@ -37,114 +15,23 @@ export class SkillsPlugin extends PluginBase implements Plugin {
     super(context);
   }
 
-  async call(input?: string): Promise<string> {
-    const result = await this.embed(input || "");
-    return result.map((e) => e.text).join("\n\n");
-  }
-
-  async embed(userPrompt: string): Promise<MinimalEmbedding[]> {
-    const config = await getConfig();
-    const skillDirs: string[] = (config as any).skills || [];
-
-    if (skillDirs.length === 0) {
-      return [];
-    }
-
-    const skills = await this.scanSkills(skillDirs);
+  /**
+   * Returns a summary list of in-memory skills (name + description).
+   * This is called by the plugin system to inject context into agent prompts.
+   * Skills must be loaded into memory first via Behaviors.initFromDisk() at startup.
+   */
+  async call(_input?: string): Promise<string> {
+    const { Behaviors } = this.context;
+    const skills = Behaviors.listSkills();
 
     if (skills.length === 0) {
-      return [];
-    }
-
-    // Check if any skill name appears in the prompt
-    const matchedSkills = skills.filter((skill) =>
-      userPrompt.toLowerCase().includes(skill.name.toLowerCase())
-    );
-
-    if (matchedSkills.length > 0) {
-      // Return full skill content for matched skills
-      const results: MinimalEmbedding[] = [];
-      for (const skill of matchedSkills) {
-        try {
-          const content = await fs.readFile(skill.filePath, "utf-8");
-          results.push({
-            id: skill.filePath,
-            text: `## Skill: ${skill.name}\nFile: ${skill.filePath}\n\n${content}`,
-            metadata: { filePath: skill.filePath },
-          });
-        } catch {
-          // Skip unreadable files
-        }
-      }
-      return results;
-    }
-
-    // Return skill discovery summary
-    const summary = this.buildSkillSummary(skills);
-    return [
-      {
-        id: "skills:summary",
-        text: summary,
-        metadata: {},
-      },
-    ];
-  }
-
-  private async scanSkills(dirs: string[]): Promise<SkillMeta[]> {
-    const skills: SkillMeta[] = [];
-    for (const dir of dirs) {
-      const resolvedDir = dir.replace(/^~/, process.env.HOME || "");
-      try {
-        const found = await this.findSkillFiles(resolvedDir);
-        skills.push(...found);
-      } catch {
-        // Skip directories that don't exist or can't be read
-      }
-    }
-    return skills;
-  }
-
-  private async findSkillFiles(dir: string): Promise<SkillMeta[]> {
-    const skills: SkillMeta[] = [];
-    let entries: Dirent[];
-    try {
-      entries = await fs.readdir(dir, { withFileTypes: true });
-    } catch {
-      return skills;
-    }
-
-    for (const entry of entries) {
-      const fullPath = path.join(dir, entry.name);
-      if (entry.isDirectory()) {
-        const nested = await this.findSkillFiles(fullPath);
-        skills.push(...nested);
-      } else if (entry.isFile() && entry.name === "SKILL.md") {
-        try {
-          const content = await fs.readFile(fullPath, "utf-8");
-          const frontmatter = parseFrontmatter(content);
-          const name = frontmatter.name;
-          const description = frontmatter.description || "";
-          if (name) {
-            skills.push({ name, description, filePath: fullPath });
-          }
-        } catch {
-          // Skip unreadable files
-        }
-      }
+      return "No skills available";
     }
 
-    return skills;
-  }
-
-  private buildSkillSummary(skills: SkillMeta[]): string {
     const lines = ["Available skills:"];
     for (const skill of skills) {
-      lines.push(`- ${skill.name} (${skill.filePath}): ${skill.description}`);
+      lines.push(`- ${skill.name}: ${skill.description}`);
     }
-    lines.push("");
-    lines.push(
-      "To use a skill, reference its name in your request and I will load the full instructions."
-    );
     return lines.join("\n");
   }
 }

package/src/plugins/language.ts

@@ -6,7 +6,6 @@ import { getConfig, getLanguageConfig } from "../config";
 import { getEnabledPlugins } from "../types";
 import { PluginBase, PluginMeta } from "./PluginBase";
 import { Plugin, PluginContext } from "./types";
-import { PluginService } from "./plugins";
 
 /**
  * Language Plugin with event-driven context loading

package/src/plugins/plugins.ts

@@ -14,24 +14,12 @@ import { SkillsPlugin } from "./SkillsPlugin";
 import { EventService } from "../services/EventService";
 
 export class PluginService {
-  private pluginMap = new Map<string, Plugin>();
+  protected pluginMap = new Map<string, Plugin>();
   private events?: EventService;
 
   constructor(context: PluginContext) {
     this.events = context.Events;
     context.Plugins = this;
-
-    // Register migrated PluginBase plugins
-    this.pluginMap.set("embeddings", new EmbeddingPlugin(context));
-    this.pluginMap.set("vim", new VimPlugin(context));
-    this.pluginMap.set("linter", new LinterPlugin(context));
-    this.pluginMap.set("language", new LanguagePlugin(context));
-    this.pluginMap.set("url", new UrlPlugin(context));
-    this.pluginMap.set("git", new GitPlugin(context));
-    this.pluginMap.set("tmux", new TmuxPlugin(context));
-    this.pluginMap.set("agents-md", new AgentsMdPlugin(context));
-    this.pluginMap.set("exec", new ExecPlugin(context));
-    this.pluginMap.set("skills", new SkillsPlugin(context));
   }
 
   /* -------- lifecycle helpers ------------------------------------ */
@@ -146,3 +134,26 @@ export class PluginService {
     return newPlugin.embed ? newPlugin.embed(userInput) : [];
   }
 }
+
+/**
+ * CliPluginService extends PluginService with the full set of default plugins
+ * used by the Knowhow CLI. Use this class when setting up agents for CLI usage.
+ * Use the base PluginService when you want a clean slate to register your own plugins.
+ */
+export class CliPluginService extends PluginService {
+  constructor(context: PluginContext) {
+    super(context);
+
+    // Register CLI default plugins
+    this.pluginMap.set("embeddings", new EmbeddingPlugin(context));
+    this.pluginMap.set("vim", new VimPlugin(context));
+    this.pluginMap.set("linter", new LinterPlugin(context));
+    this.pluginMap.set("language", new LanguagePlugin(context));
+    this.pluginMap.set("url", new UrlPlugin(context));
+    this.pluginMap.set("git", new GitPlugin(context));
+    this.pluginMap.set("tmux", new TmuxPlugin(context));
+    this.pluginMap.set("agents-md", new AgentsMdPlugin(context));
+    this.pluginMap.set("exec", new ExecPlugin(context));
+    this.pluginMap.set("skills", new SkillsPlugin(context));
+  }
+}

package/src/plugins/types.ts

@@ -1,5 +1,10 @@
 import { Embeddable, MinimalEmbedding } from "../types";
-import { AgentService, EventService, ToolsService } from "../services";
+import {
+  AgentService,
+  BehaviorsService,
+  EventService,
+  ToolsService,
+} from "../services";
 import { AIClient } from "../clients";
 import { PluginService } from "./plugins";
 
@@ -13,7 +18,7 @@ export interface PluginMeta {
 export interface Plugin {
   callMany(userInput?: string): Promise<string>;
   call(userInput?: string): Promise<string>;
-  embed(userInput?: string): Promise<MinimalEmbedding[]>;
+  embed?(userInput?: string): Promise<MinimalEmbedding[]>;
   enable(): void;
   disable(): void;
   isEnabled(): boolean;
@@ -27,4 +32,5 @@ export interface PluginContext {
   Clients?: AIClient;
   Tools?: ToolsService;
   Plugins?: PluginService;
+  Behaviors?: BehaviorsService;
 }