opencode-plugin-preload-skills 1.2.0 → 1.3.0

package/dist/index.d.cts

@@ -3,18 +3,37 @@ import { Plugin } from '@opencode-ai/plugin';
 interface PreloadSkillsConfig {
     skills: string[];
     fileTypeSkills?: Record<string, string[]>;
+    agentSkills?: Record<string, string[]>;
+    pathPatterns?: Record<string, string[]>;
+    contentTriggers?: Record<string, string[]>;
+    groups?: Record<string, string[]>;
+    conditionalSkills?: ConditionalSkill[];
+    maxTokens?: number;
+    useSummaries?: boolean;
+    analytics?: boolean;
     persistAfterCompaction?: boolean;
     debug?: boolean;
 }
+interface ConditionalSkill {
+    skill: string;
+    if: ConditionCheck;
+}
+interface ConditionCheck {
+    fileExists?: string;
+    packageHasDependency?: string;
+    envVar?: string;
+}
 interface ParsedSkill {
     name: string;
     description: string;
+    summary?: string;
     content: string;
     filePath: string;
+    tokenCount: number;
 }
 
 declare function loadSkills(skillNames: string[], projectDir: string): ParsedSkill[];
-declare function formatSkillsForInjection(skills: ParsedSkill[]): string;
+declare function formatSkillsForInjection(skills: ParsedSkill[], useSummaries?: boolean): string;
 
 declare const PreloadSkillsPlugin: Plugin;
 

package/dist/index.d.ts

@@ -3,18 +3,37 @@ import { Plugin } from '@opencode-ai/plugin';
 interface PreloadSkillsConfig {
     skills: string[];
     fileTypeSkills?: Record<string, string[]>;
+    agentSkills?: Record<string, string[]>;
+    pathPatterns?: Record<string, string[]>;
+    contentTriggers?: Record<string, string[]>;
+    groups?: Record<string, string[]>;
+    conditionalSkills?: ConditionalSkill[];
+    maxTokens?: number;
+    useSummaries?: boolean;
+    analytics?: boolean;
     persistAfterCompaction?: boolean;
     debug?: boolean;
 }
+interface ConditionalSkill {
+    skill: string;
+    if: ConditionCheck;
+}
+interface ConditionCheck {
+    fileExists?: string;
+    packageHasDependency?: string;
+    envVar?: string;
+}
 interface ParsedSkill {
     name: string;
     description: string;
+    summary?: string;
     content: string;
     filePath: string;
+    tokenCount: number;
 }
 
 declare function loadSkills(skillNames: string[], projectDir: string): ParsedSkill[];
-declare function formatSkillsForInjection(skills: ParsedSkill[]): string;
+declare function formatSkillsForInjection(skills: ParsedSkill[], useSummaries?: boolean): string;
 
 declare const PreloadSkillsPlugin: Plugin;
 

package/dist/index.js

@@ -1,8 +1,49 @@
-import { readFileSync, existsSync } from 'fs';
-import { extname, join } from 'path';
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
+import { extname, join, dirname } from 'path';
 import { homedir } from 'os';
 
 // src/index.ts
+function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+function matchGlobPattern(filePath, pattern) {
+  let regexPattern = pattern.replace(/\*\*\//g, "\0DOUBLESTARSLASH\0").replace(/\*\*/g, "\0DOUBLESTAR\0").replace(/\*/g, "\0SINGLESTAR\0").replace(/\?/g, "\0QUESTION\0");
+  regexPattern = regexPattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  regexPattern = regexPattern.replace(/\x00DOUBLESTARSLASH\x00/g, "(?:[^/]+/)*").replace(/\x00DOUBLESTAR\x00/g, ".*").replace(/\x00SINGLESTAR\x00/g, "[^/]*").replace(/\x00QUESTION\x00/g, "[^/]");
+  const regex = new RegExp(`^${regexPattern}$`);
+  return regex.test(filePath);
+}
+function checkCondition(condition, projectDir) {
+  if (condition.fileExists) {
+    const fullPath = join(projectDir, condition.fileExists);
+    if (!existsSync(fullPath)) return false;
+  }
+  if (condition.packageHasDependency) {
+    const packageJsonPath = join(projectDir, "package.json");
+    if (!existsSync(packageJsonPath)) return false;
+    try {
+      const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+      const deps = {
+        ...packageJson.dependencies,
+        ...packageJson.devDependencies,
+        ...packageJson.peerDependencies
+      };
+      if (!deps[condition.packageHasDependency]) return false;
+    } catch {
+      return false;
+    }
+  }
+  if (condition.envVar) {
+    if (!process.env[condition.envVar]) return false;
+  }
+  return true;
+}
+function textContainsKeyword(text, keywords) {
+  const lowerText = text.toLowerCase();
+  return keywords.some((kw) => lowerText.includes(kw.toLowerCase()));
+}
+
+// src/skill-loader.ts
 var SKILL_FILENAME = "SKILL.md";
 var SKILL_SEARCH_PATHS = [
   (dir) => join(dir, ".opencode", "skills"),
@@ -35,8 +76,19 @@ function parseFrontmatter(content) {
   if (descMatch?.[1]) {
     result.description = descMatch[1].trim();
   }
+  const summaryMatch = frontmatter.match(/^summary:\s*(.+)$/m);
+  if (summaryMatch?.[1]) {
+    result.summary = summaryMatch[1].trim();
+  }
   return result;
 }
+function extractAutoSummary(content, maxLength = 500) {
+  const withoutFrontmatter = content.replace(/^---\s*\n[\s\S]*?\n---\s*\n?/, "");
+  const firstSection = withoutFrontmatter.split(/\n##\s/)[0] ?? "";
+  const cleaned = firstSection.replace(/^#\s+.+\n?/, "").replace(/\n+/g, " ").trim();
+  if (cleaned.length <= maxLength) return cleaned;
+  return cleaned.slice(0, maxLength).replace(/\s+\S*$/, "") + "...";
+}
 function loadSkill(skillName, projectDir) {
   const filePath = findSkillFile(skillName, projectDir);
   if (!filePath) {
@@ -44,12 +96,14 @@ function loadSkill(skillName, projectDir) {
   }
   try {
     const content = readFileSync(filePath, "utf-8");
-    const { name, description } = parseFrontmatter(content);
+    const { name, description, summary } = parseFrontmatter(content);
     return {
       name: name ?? skillName,
       description: description ?? "",
+      summary: summary ?? extractAutoSummary(content),
       content,
-      filePath
+      filePath,
+      tokenCount: estimateTokens(content)
     };
   } catch {
     return null;
@@ -68,28 +122,52 @@ function loadSkills(skillNames, projectDir) {
   }
   return skills;
 }
-function formatSkillsForInjection(skills) {
+function formatSkillsForInjection(skills, useSummaries = false) {
   if (!Array.isArray(skills) || skills.length === 0) {
     return "";
   }
-  const parts = skills.map(
-    (skill) => `<preloaded-skill name="${skill.name}">
-${skill.content}
-</preloaded-skill>`
-  );
+  const parts = skills.map((skill) => {
+    const content = useSummaries && skill.summary ? skill.summary : skill.content;
+    return `<preloaded-skill name="${skill.name}">
+${content}
+</preloaded-skill>`;
+  });
   return `<preloaded-skills>
 The following skills have been automatically loaded for this session:
 
 ${parts.join("\n\n")}
 </preloaded-skills>`;
 }
+function calculateTotalTokens(skills) {
+  return skills.reduce((sum, skill) => sum + skill.tokenCount, 0);
+}
+function filterSkillsByTokenBudget(skills, maxTokens) {
+  const result = [];
+  let totalTokens = 0;
+  for (const skill of skills) {
+    if (totalTokens + skill.tokenCount <= maxTokens) {
+      result.push(skill);
+      totalTokens += skill.tokenCount;
+    }
+  }
+  return result;
+}
 
 // src/index.ts
 var CONFIG_FILENAME = "preload-skills.json";
+var ANALYTICS_FILENAME = "preload-skills-analytics.json";
 var FILE_TOOLS = ["read", "edit", "write", "glob", "grep"];
 var DEFAULT_CONFIG = {
   skills: [],
   fileTypeSkills: {},
+  agentSkills: {},
+  pathPatterns: {},
+  contentTriggers: {},
+  groups: {},
+  conditionalSkills: [],
+  maxTokens: void 0,
+  useSummaries: false,
+  analytics: false,
   persistAfterCompaction: true,
   debug: false
 };
@@ -106,7 +184,7 @@ function findConfigFile(projectDir) {
   }
   return null;
 }
-function parseFileTypeSkills(raw) {
+function parseStringArrayRecord(raw) {
   if (!raw || typeof raw !== "object") return {};
   const result = {};
   for (const [key, value] of Object.entries(raw)) {
@@ -116,6 +194,12 @@ function parseFileTypeSkills(raw) {
   }
   return result;
 }
+function parseConditionalSkills(raw) {
+  if (!Array.isArray(raw)) return [];
+  return raw.filter(
+    (item) => typeof item === "object" && item !== null && typeof item.skill === "string" && typeof item.if === "object"
+  );
+}
 function loadConfigFile(projectDir) {
   const configPath = findConfigFile(projectDir);
   if (!configPath) {
@@ -126,7 +210,15 @@ function loadConfigFile(projectDir) {
     const parsed = JSON.parse(content);
     return {
       skills: Array.isArray(parsed.skills) ? parsed.skills : [],
-      fileTypeSkills: parseFileTypeSkills(parsed.fileTypeSkills),
+      fileTypeSkills: parseStringArrayRecord(parsed.fileTypeSkills),
+      agentSkills: parseStringArrayRecord(parsed.agentSkills),
+      pathPatterns: parseStringArrayRecord(parsed.pathPatterns),
+      contentTriggers: parseStringArrayRecord(parsed.contentTriggers),
+      groups: parseStringArrayRecord(parsed.groups),
+      conditionalSkills: parseConditionalSkills(parsed.conditionalSkills),
+      maxTokens: typeof parsed.maxTokens === "number" ? parsed.maxTokens : void 0,
+      useSummaries: typeof parsed.useSummaries === "boolean" ? parsed.useSummaries : void 0,
+      analytics: typeof parsed.analytics === "boolean" ? parsed.analytics : void 0,
       persistAfterCompaction: typeof parsed.persistAfterCompaction === "boolean" ? parsed.persistAfterCompaction : void 0,
       debug: typeof parsed.debug === "boolean" ? parsed.debug : void 0
     };
@@ -150,8 +242,29 @@ function getSkillsForExtension(ext, fileTypeSkills) {
   }
   return [...new Set(skills)];
 }
+function getSkillsForPath(filePath, pathPatterns) {
+  const skills = [];
+  for (const [pattern, skillNames] of Object.entries(pathPatterns)) {
+    if (matchGlobPattern(filePath, pattern)) {
+      skills.push(...skillNames);
+    }
+  }
+  return [...new Set(skills)];
+}
+function resolveSkillGroups(skillNames, groups) {
+  const resolved = [];
+  for (const name of skillNames) {
+    if (name.startsWith("@") && groups[name.slice(1)]) {
+      resolved.push(...groups[name.slice(1)]);
+    } else {
+      resolved.push(name);
+    }
+  }
+  return [...new Set(resolved)];
+}
 var PreloadSkillsPlugin = async (ctx) => {
   const sessionStates = /* @__PURE__ */ new Map();
+  const analyticsData = /* @__PURE__ */ new Map();
   const fileConfig = loadConfigFile(ctx.directory);
   const config = {
     ...DEFAULT_CONFIG,
@@ -168,57 +281,176 @@ var PreloadSkillsPlugin = async (ctx) => {
       }
     });
   };
+  const trackSkillUsage = (sessionID, skillName, triggerType) => {
+    if (!config.analytics) return;
+    if (!analyticsData.has(sessionID)) {
+      analyticsData.set(sessionID, {
+        sessionId: sessionID,
+        skillUsage: /* @__PURE__ */ new Map()
+      });
+    }
+    const data = analyticsData.get(sessionID);
+    const now = Date.now();
+    if (data.skillUsage.has(skillName)) {
+      const stats = data.skillUsage.get(skillName);
+      stats.loadCount++;
+      stats.lastLoaded = now;
+    } else {
+      data.skillUsage.set(skillName, {
+        skillName,
+        loadCount: 1,
+        triggerType,
+        firstLoaded: now,
+        lastLoaded: now
+      });
+    }
+  };
+  const saveAnalytics = () => {
+    if (!config.analytics) return;
+    try {
+      const analyticsPath = join(ctx.directory, ".opencode", ANALYTICS_FILENAME);
+      const dir = dirname(analyticsPath);
+      if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+      }
+      const serializable = {};
+      for (const [sessionId, data] of analyticsData) {
+        serializable[sessionId] = {
+          sessionId: data.sessionId,
+          skillUsage: Object.fromEntries(data.skillUsage)
+        };
+      }
+      writeFileSync(analyticsPath, JSON.stringify(serializable, null, 2));
+    } catch {
+      log("warn", "Failed to save analytics");
+    }
+  };
   const skillCache = /* @__PURE__ */ new Map();
-  const getOrLoadSkill = (skillName) => {
-    if (skillCache.has(skillName)) {
-      return skillCache.get(skillName) ?? null;
+  const loadSkillsWithBudget = (skillNames, currentTokens, triggerType, sessionID) => {
+    const resolved = resolveSkillGroups(skillNames, config.groups ?? {});
+    let skills = loadSkills(resolved, ctx.directory);
+    for (const skill of skills) {
+      skillCache.set(skill.name, skill);
     }
-    const skill = loadSkill(skillName, ctx.directory);
-    if (skill) {
-      skillCache.set(skillName, skill);
+    if (config.maxTokens) {
+      const remainingBudget = config.maxTokens - currentTokens;
+      skills = filterSkillsByTokenBudget(skills, remainingBudget);
+    }
+    for (const skill of skills) {
+      trackSkillUsage(sessionID, skill.name, triggerType);
+    }
+    return {
+      skills,
+      tokensUsed: calculateTotalTokens(skills)
+    };
+  };
+  const resolveConditionalSkills = () => {
+    if (!config.conditionalSkills?.length) return [];
+    const resolved = [];
+    for (const { skill, if: condition } of config.conditionalSkills) {
+      if (checkCondition(condition, ctx.directory)) {
+        resolved.push(skill);
+      }
     }
-    return skill;
+    return resolved;
   };
   let initialSkills = [];
   let initialFormattedContent = "";
-  if (config.skills.length > 0) {
-    initialSkills = loadSkills(config.skills, ctx.directory);
-    initialFormattedContent = formatSkillsForInjection(initialSkills);
-    for (const skill of initialSkills) {
-      skillCache.set(skill.name, skill);
-    }
+  let initialTokensUsed = 0;
+  const allInitialSkillNames = [
+    ...config.skills,
+    ...resolveConditionalSkills()
+  ];
+  if (allInitialSkillNames.length > 0) {
+    const result = loadSkillsWithBudget(
+      allInitialSkillNames,
+      0,
+      "initial",
+      "__init__"
+    );
+    initialSkills = result.skills;
+    initialTokensUsed = result.tokensUsed;
+    initialFormattedContent = formatSkillsForInjection(
+      initialSkills,
+      config.useSummaries
+    );
     const loadedNames = initialSkills.map((s) => s.name);
-    const missingNames = config.skills.filter((s) => !loadedNames.includes(s));
-    log("info", `Loaded ${initialSkills.length} skills for preloading`, {
+    const missingNames = allInitialSkillNames.filter(
+      (s) => !loadedNames.includes(s) && !s.startsWith("@")
+    );
+    log("info", `Loaded ${initialSkills.length} initial skills`, {
       loaded: loadedNames,
+      tokens: initialTokensUsed,
       missing: missingNames.length > 0 ? missingNames : void 0
     });
-    if (missingNames.length > 0) {
-      log("warn", "Some configured skills were not found", {
-        missing: missingNames
-      });
-    }
   }
-  const hasFileTypeSkills = Object.keys(config.fileTypeSkills ?? {}).length > 0;
-  if (config.skills.length === 0 && !hasFileTypeSkills) {
+  const hasTriggeredSkills = Object.keys(config.fileTypeSkills ?? {}).length > 0 || Object.keys(config.agentSkills ?? {}).length > 0 || Object.keys(config.pathPatterns ?? {}).length > 0 || Object.keys(config.contentTriggers ?? {}).length > 0;
+  if (allInitialSkillNames.length === 0 && !hasTriggeredSkills) {
     log("warn", "No skills configured. Create .opencode/preload-skills.json");
   }
   const getSessionState = (sessionID) => {
     if (!sessionStates.has(sessionID)) {
       sessionStates.set(sessionID, {
         initialSkillsInjected: false,
-        loadedSkills: new Set(initialSkills.map((s) => s.name))
+        loadedSkills: new Set(initialSkills.map((s) => s.name)),
+        totalTokensUsed: initialTokensUsed
       });
     }
     return sessionStates.get(sessionID);
   };
   const pendingSkillInjections = /* @__PURE__ */ new Map();
+  const queueSkillsForInjection = (sessionID, skillNames, triggerType, state) => {
+    const newSkillNames = skillNames.filter((name) => !state.loadedSkills.has(name));
+    if (newSkillNames.length === 0) return;
+    const result = loadSkillsWithBudget(
+      newSkillNames,
+      state.totalTokensUsed,
+      triggerType,
+      sessionID
+    );
+    if (result.skills.length > 0) {
+      for (const skill of result.skills) {
+        state.loadedSkills.add(skill.name);
+      }
+      state.totalTokensUsed += result.tokensUsed;
+      const existing = pendingSkillInjections.get(sessionID) ?? [];
+      pendingSkillInjections.set(sessionID, [...existing, ...result.skills]);
+      log("debug", `Queued ${triggerType} skills for injection`, {
+        sessionID,
+        skills: result.skills.map((s) => s.name),
+        tokens: result.tokensUsed
+      });
+    }
+  };
   return {
     "chat.message": async (input, output) => {
       if (!input.sessionID) return;
       const state = getSessionState(input.sessionID);
       const firstTextPart = output.parts.find((p) => p.type === "text");
       if (!firstTextPart || !("text" in firstTextPart)) return;
+      const messageText = firstTextPart.text;
+      if (input.agent && config.agentSkills?.[input.agent]) {
+        queueSkillsForInjection(
+          input.sessionID,
+          config.agentSkills[input.agent],
+          "agent",
+          state
+        );
+      }
+      if (config.contentTriggers) {
+        for (const [keyword, skillNames] of Object.entries(
+          config.contentTriggers
+        )) {
+          if (textContainsKeyword(messageText, [keyword])) {
+            queueSkillsForInjection(
+              input.sessionID,
+              skillNames,
+              "content",
+              state
+            );
+          }
+        }
+      }
       const contentToInject = [];
       if (!state.initialSkillsInjected && initialFormattedContent) {
         contentToInject.push(initialFormattedContent);
@@ -230,10 +462,10 @@ var PreloadSkillsPlugin = async (ctx) => {
       }
       const pending = pendingSkillInjections.get(input.sessionID);
       if (pending && pending.length > 0) {
-        const formatted = formatSkillsForInjection(pending);
+        const formatted = formatSkillsForInjection(pending, config.useSummaries);
         if (formatted) {
           contentToInject.push(formatted);
-          log("info", "Injected file-type triggered skills", {
+          log("info", "Injected triggered skills", {
             sessionID: input.sessionID,
             skills: pending.map((s) => s.name)
           });
@@ -249,7 +481,6 @@ ${firstTextPart.text}`;
       }
     },
     "tool.execute.after": async (input, _output) => {
-      if (!hasFileTypeSkills) return;
       if (!FILE_TOOLS.includes(input.tool)) return;
       if (!input.sessionID) return;
       const state = getSessionState(input.sessionID);
@@ -258,27 +489,17 @@ ${firstTextPart.text}`;
       const filePath = getFilePathFromArgs(toolArgs);
       if (!filePath) return;
       const ext = extname(filePath);
-      if (!ext) return;
-      const skillNames = getSkillsForExtension(ext, config.fileTypeSkills ?? {});
-      if (skillNames.length === 0) return;
-      const newSkills = [];
-      for (const name of skillNames) {
-        if (state.loadedSkills.has(name)) continue;
-        const skill = getOrLoadSkill(name);
-        if (skill) {
-          newSkills.push(skill);
-          state.loadedSkills.add(name);
+      if (ext && config.fileTypeSkills) {
+        const extSkills = getSkillsForExtension(ext, config.fileTypeSkills);
+        if (extSkills.length > 0) {
+          queueSkillsForInjection(input.sessionID, extSkills, "fileType", state);
         }
       }
-      if (newSkills.length > 0) {
-        const existing = pendingSkillInjections.get(input.sessionID) ?? [];
-        pendingSkillInjections.set(input.sessionID, [...existing, ...newSkills]);
-        log("debug", "Queued file-type skills for injection", {
-          sessionID: input.sessionID,
-          filePath,
-          extension: ext,
-          skills: newSkills.map((s) => s.name)
-        });
+      if (config.pathPatterns) {
+        const pathSkills = getSkillsForPath(filePath, config.pathPatterns);
+        if (pathSkills.length > 0) {
+          queueSkillsForInjection(input.sessionID, pathSkills, "path", state);
+        }
       }
     },
     "experimental.session.compacting": async (input, output) => {
@@ -291,7 +512,10 @@ ${firstTextPart.text}`;
         if (skill) allLoadedSkills.push(skill);
       }
       if (allLoadedSkills.length === 0) return;
-      const formatted = formatSkillsForInjection(allLoadedSkills);
+      const formatted = formatSkillsForInjection(
+        allLoadedSkills,
+        config.useSummaries
+      );
       output.context.push(
         `## Preloaded Skills
 
@@ -304,13 +528,16 @@ ${formatted}`
         sessionID: input.sessionID,
         skillCount: allLoadedSkills.length
       });
+      saveAnalytics();
     },
     event: async ({ event }) => {
       if (event.type === "session.deleted" && "sessionID" in event.properties) {
         const sessionID = event.properties.sessionID;
         sessionStates.delete(sessionID);
         pendingSkillInjections.delete(sessionID);
+        analyticsData.delete(sessionID);
         log("debug", "Cleaned up session state", { sessionID });
+        saveAnalytics();
       }
     }
   };