opencode-dynamic-skills 1.0.1 → 1.1.0

package/README.md

@@ -21,9 +21,14 @@ This project is a reboot of the archived `opencode-skillful` codebase.
 This project is derived from and adapted from:
 
 - https://github.com/zenobi-us/opencode-skillful
+- https://github.com/code-yeongyu/oh-my-openagent
+- Anthropic Agent Skills specification and skills ecosystem: https://github.com/anthropics/skills
 
 The current codebase restructures and extends that work for a fresh restart.
 
+This project also references the slash-command and skill-loading ideas explored by oh-my-openagent.
+Thanks to the maintainers and contributors of these projects for the public implementation ideas and prior art.
+
 ## Goals
 
 - Keep skills **lazy-loaded**, instead of injecting all skills into every session
@@ -37,11 +42,16 @@ The current codebase restructures and extends that work for a fresh restart.
 
 The plugin provides:
 
+- `skill`
 - `skill_find`
 - `skill_recommend`
 - `skill_use`
 - `skill_resource`
 
+The default design keeps the initial tool context small.
+It does **not** inject the full skill catalog or every skill description up front.
+Discovery is deferred to runtime through `skill_find`, `skill_recommend`, direct slash interception, or explicit `skill(name="...")` calls.
+
 ### Slash skill command
 
 Default form:
@@ -68,7 +78,8 @@ Optional aliases are also supported:
 /git-release draft a release checklist
 ```
 
-Aliases are disabled by default to avoid collisions with native or official OpenCode commands.
+Aliases are enabled by default in the pure oh-my-openagent-style flow, so `/<skill-name>` can be intercepted after submit.
+This does not mean OpenCode will show dynamic picker suggestions for those aliases.
 
 ### Skill-root-relative resources
 
@@ -112,7 +123,7 @@ Example:
     "gpt-4": "json"
   },
   "slashCommandName": "skill",
-  "enableSkillAliases": false
+  "enableSkillAliases": true
 }
 ```
 

package/README.zh-CN.md

@@ -21,9 +21,14 @@
 本项目来自并改造于：
 
 - https://github.com/zenobi-us/opencode-skillful
+- https://github.com/code-yeongyu/oh-my-openagent
+- Anthropic Agent Skills 规范与 skills 生态：https://github.com/anthropics/skills
 
 当前版本在此基础上做了重新组织和重启开发。
 
+其中 slash 风格 skill 调用与 skill 装载思路，明确参考了 oh-my-openagent 的公开实现。
+感谢这些项目的维护者与贡献者。
+
 ## 目标
 
 - 保持 **按需加载**，不把所有 skill 预注入到每个会话
@@ -37,11 +42,16 @@
 
 插件提供：
 
+- `skill`
 - `skill_find`
 - `skill_recommend`
 - `skill_use`
 - `skill_resource`
 
+默认设计会尽量保持初始工具上下文很小。
+它**不会**在一开始把全部 skill 目录和每个 skill 的 description 都注入进去。
+真正的发现与装载会延后到运行时，通过 `skill_find`、`skill_recommend`、直接 slash 拦截或显式 `skill(name="...")` 调用完成。
+
 ### Slash 技能命令
 
 默认形式：
@@ -68,7 +78,8 @@
 /git-release 帮我起草 release checklist
 ```
 
-alias 默认关闭，避免与 OpenCode 内置命令或官方 commands 冲突。
+在纯 oh-my-openagent 风格下，alias 默认开启，因此提交 `/<skill-name>` 后插件会尝试接管。
+但这不代表 OpenCode 会在输入阶段为这些 alias 提供动态候选列表。
 
 ### Skill 根目录相对资源
 
@@ -112,7 +123,7 @@ templates/pr.md
     "gpt-4": "json"
   },
   "slashCommandName": "skill",
-  "enableSkillAliases": false
+  "enableSkillAliases": true
 }
 ```
 

package/dist/api.d.ts

@@ -34,63 +34,22 @@
  *   // Note: registry is created but NOT yet initialized
  *   // Must be done by caller: await registry.initialise()
  */
+import { createLogger } from './services/logger';
+import { createSkillRegistry } from './services/SkillRegistry';
+import { createSkillFinder } from './tools/SkillFinder';
+import { createSkillRecommender } from './tools/SkillRecommender';
+import { createSkillResourceReader } from './tools/SkillResourceReader';
+import { createSkillTool } from './tools/Skill';
+import { createSkillLoader } from './tools/SkillUser';
 import type { PluginConfig } from './types';
-export declare const createApi: (config: PluginConfig) => Promise<{
-    registry: import("./types").SkillRegistry;
-    logger: import("./types").PluginLogger;
+export type SkillsApi = {
+    registry: Awaited<ReturnType<typeof createSkillRegistry>>;
+    logger: ReturnType<typeof createLogger>;
     config: PluginConfig;
-    findSkills: (args: {
-        query: string | string[];
-    }) => Promise<{
-        query: string | string[];
-        skills: {
-            name: string;
-            description: string;
-        }[];
-        summary: {
-            total: number;
-            matches: number;
-            feedback: string;
-        };
-        debug: import("./types").SkillRegistryDebugInfo | undefined;
-    }>;
-    recommendSkills: (args: {
-        task: string;
-        limit?: number;
-    }) => Promise<{
-        mode: "recommend";
-        query: string;
-        skills: {
-            name: string;
-            description: string;
-        }[];
-        recommendations: {
-            name: string;
-            description: string;
-            score: number;
-            reason: string;
-        }[];
-        guidance: string;
-        summary: {
-            total: number;
-            matches: number;
-            feedback: string;
-        };
-        debug: import("./types").SkillRegistryDebugInfo | undefined;
-    }>;
-    readResource: (args: {
-        skill_name: string;
-        relative_path: string;
-    }) => Promise<{
-        injection: {
-            skill_name: string;
-            resource_path: string;
-            resource_mimetype: string;
-            content: string;
-        };
-    }>;
-    loadSkill: (skillNames: string[]) => Promise<{
-        loaded: import("./types").Skill[];
-        notFound: string[];
-    }>;
-}>;
+    findSkills: ReturnType<typeof createSkillFinder>;
+    recommendSkills: ReturnType<typeof createSkillRecommender>;
+    readResource: ReturnType<typeof createSkillResourceReader>;
+    loadSkill: ReturnType<typeof createSkillLoader>;
+    skillTool: ReturnType<typeof createSkillTool>;
+};
+export declare const createApi: (config: PluginConfig) => Promise<SkillsApi>;

package/dist/commands/SlashCommand.d.ts

@@ -10,7 +10,6 @@ export declare function parseSlashCommand(text: string, slashCommandName: string
 export declare function findSkillBySelector(registry: SkillRegistry, selector: string): Skill | null;
 export declare function renderSlashSkillPrompt(args: {
     invocationName: string;
-    renderedSkill: string;
     skill: Skill;
     userPrompt: string;
 }): string;
@@ -19,7 +18,6 @@ export declare function rewriteRecommendSlashCommandText(text: string): Promise<
 export declare function rewriteSlashCommandText(args: {
     text: string;
     registry: SkillRegistry;
-    renderSkill: (skill: Skill) => string;
     slashCommandName: string;
     enableSkillAliases: boolean;
 }): Promise<string | null>;

package/dist/index.js

@@ -17839,6 +17839,18 @@ function createResourceCandidates(type, relativePath) {
 function normalizeSkillIdentifier(identifier) {
   return identifier.trim().toLowerCase().replace(/[/-]/g, "_");
 }
+function resolveFileWithinSkillRoot(skill, relativePath) {
+  const normalizedPath = normalizeSkillResourcePath(relativePath);
+  const absolutePath = path.resolve(skill.fullPath, normalizedPath);
+  const relativeFromSkillRoot = path.relative(skill.fullPath, absolutePath);
+  if (relativeFromSkillRoot.startsWith("..") || path.isAbsolute(relativeFromSkillRoot) || !doesPathExist(absolutePath)) {
+    return null;
+  }
+  return {
+    absolutePath,
+    mimeType: detectMimeType(absolutePath)
+  };
+}
 function createSkillResourceResolver(provider) {
   return async (args) => {
     const skillIdentifier = normalizeSkillIdentifier(args.skill_name);
@@ -17849,18 +17861,19 @@ function createSkillResourceResolver(provider) {
     const resourceMap = getSkillResources(skill);
     const candidatePaths = createResourceCandidates(args.type, args.relative_path);
     const resourceEntry = candidatePaths.map((candidatePath) => resourceMap.get(candidatePath)).find((candidate) => candidate !== undefined);
-    if (!resourceEntry) {
+    const resolvedResource = resourceEntry ?? candidatePaths.map((candidatePath) => resolveFileWithinSkillRoot(skill, candidatePath)).find((candidate) => candidate !== null);
+    if (!resolvedResource) {
       throw new Error(`Resource not found: Skill "${args.skill_name}" does not have a resource at path "${args.relative_path}"`);
     }
     try {
-      const content = await readSkillFile(resourceEntry.absolutePath);
+      const content = await readSkillFile(resolvedResource.absolutePath);
       return {
-        absolute_path: resourceEntry.absolutePath,
+        absolute_path: resolvedResource.absolutePath,
         content,
-        mimeType: resourceEntry.mimeType
+        mimeType: resolvedResource.mimeType
       };
     } catch (error45) {
-      throw new Error(`Failed to read resource at ${resourceEntry.absolutePath}: ${error45 instanceof Error ? error45.message : String(error45)}`);
+      throw new Error(`Failed to read resource at ${resolvedResource.absolutePath}: ${error45 instanceof Error ? error45.message : String(error45)}`);
     }
   };
 }
@@ -17886,7 +17899,130 @@ function createSkillResourceReader(provider) {
   };
 }
 
+// src/lib/SkillLinks.ts
+import path2 from "path";
+var SCHEME_PATTERN = /^[a-z][a-z0-9+.-]*:/i;
+function normalizeLinkedSkillPath(target) {
+  const trimmedTarget = target.trim();
+  if (trimmedTarget.length === 0 || trimmedTarget.startsWith("#") || trimmedTarget.startsWith("/") || SCHEME_PATTERN.test(trimmedTarget)) {
+    return null;
+  }
+  const [pathWithoutFragment] = trimmedTarget.split("#", 1);
+  const [pathWithoutQuery] = pathWithoutFragment.split("?", 1);
+  const normalizedPath = path2.posix.normalize(pathWithoutQuery.replace(/\\/g, "/")).replace(/^\.\//, "");
+  if (normalizedPath.length === 0 || normalizedPath === "." || normalizedPath.startsWith("../") || normalizedPath.includes("/../")) {
+    return null;
+  }
+  return normalizedPath;
+}
+function extractSkillLinks(content) {
+  const links = new Map;
+  for (const match of content.matchAll(/\[([^\]]+)\]\(([^)]+)\)/g)) {
+    const label = match[1]?.trim();
+    const originalPath = match[2]?.trim();
+    if (!label || !originalPath) {
+      continue;
+    }
+    const resourcePath = normalizeLinkedSkillPath(originalPath);
+    if (!resourcePath) {
+      continue;
+    }
+    links.set(`${label}:${resourcePath}`, {
+      label,
+      originalPath,
+      resourcePath
+    });
+  }
+  for (const match of content.matchAll(/(^|[^a-zA-Z0-9])@([a-zA-Z0-9_.\-/]+(?:\/[a-zA-Z0-9_.\-/]+)*)/g)) {
+    const originalPath = match[2]?.trim();
+    if (!originalPath) {
+      continue;
+    }
+    const resourcePath = normalizeLinkedSkillPath(originalPath);
+    if (!resourcePath) {
+      continue;
+    }
+    links.set(`@:${resourcePath}`, {
+      label: `@${resourcePath}`,
+      originalPath: `@${originalPath}`,
+      resourcePath
+    });
+  }
+  return Array.from(links.values());
+}
+
+// src/lib/formatLoadedSkill.ts
+function formatLoadedSkill(args) {
+  const linkedResources = extractSkillLinks(args.skill.content);
+  const output = [
+    `## Skill: ${args.skill.name}`,
+    "",
+    `**Skill identifier**: ${args.skill.toolName}`,
+    `**Base directory**: ${args.skill.fullPath}`
+  ];
+  if (args.invocationName) {
+    output.push(`**Invocation**: /${args.invocationName}`);
+  }
+  if (args.userMessage?.trim()) {
+    output.push(`**User request**: ${args.userMessage.trim()}`);
+  }
+  output.push("", "Relative file references in this skill resolve from the skill root directory.");
+  output.push("Use skill_resource with the exact root-relative path when you need a linked file.");
+  if (linkedResources.length > 0) {
+    output.push("", "### Linked files", "");
+    for (const link of linkedResources) {
+      output.push(`- ${link.originalPath} -> ${link.resourcePath}`);
+    }
+  }
+  output.push("", args.skill.content);
+  return output.join(`
+`);
+}
+
+// src/tools/Skill.ts
+function normalizeSkillSelector(selector) {
+  return selector.trim().toLowerCase().replace(/[/-]/g, "_");
+}
+function findSkill(registry2, selector) {
+  const directMatch = registry2.controller.get(selector);
+  if (directMatch) {
+    return directMatch;
+  }
+  const normalizedSelector = normalizeSkillSelector(selector);
+  for (const skill of registry2.controller.skills) {
+    if (normalizeSkillSelector(skill.name) === normalizedSelector || normalizeSkillSelector(skill.toolName) === normalizedSelector) {
+      return skill;
+    }
+  }
+  return null;
+}
+function createSkillTool(registry2) {
+  return tool({
+    description: "Load a dynamic skill by exact name or slash alias without preloading the entire skill catalog. Use skill_find or skill_recommend first if you do not know the skill name.",
+    args: {
+      name: tool.schema.string().describe("The skill name. Use without the leading slash, for example bmad-help."),
+      user_message: tool.schema.string().optional().describe("Optional user request or arguments to apply with the skill.")
+    },
+    async execute(args) {
+      await registry2.controller.ready.whenReady();
+      const skill = findSkill(registry2, args.name.replace(/^\//, ""));
+      if (!skill) {
+        const available = registry2.controller.skills.map((entry) => entry.name).join(", ");
+        throw new Error(`Skill "${args.name}" not found. Available: ${available || "none"}`);
+      }
+      return formatLoadedSkill({
+        skill,
+        invocationName: args.name.replace(/^\//, ""),
+        userMessage: args.user_message
+      });
+    }
+  });
+}
+
 // src/tools/SkillUser.ts
+function normalizeSkillSelector2(selector) {
+  return selector.trim().toLowerCase().replace(/[/-]/g, "_");
+}
 function createSkillLoader(provider) {
   const registry2 = provider.controller;
   async function loadSkills(skillNames) {
@@ -17894,7 +18030,8 @@ function createSkillLoader(provider) {
     const loaded = [];
     const notFound = [];
     for (const name of skillNames) {
-      const skill = registry2.get(name);
+      const normalizedName = normalizeSkillSelector2(name);
+      const skill = registry2.get(name) ?? registry2.skills.find((candidate) => normalizeSkillSelector2(candidate.name) === normalizedName || normalizeSkillSelector2(candidate.toolName) === normalizedName);
       if (skill) {
         loaded.push(skill);
       } else {
@@ -17920,7 +18057,8 @@ var createApi = async (config2) => {
     findSkills: createSkillFinder(registry2),
     recommendSkills: createSkillRecommender(registry2),
     readResource: createSkillResourceReader(registry2),
-    loadSkill: createSkillLoader(registry2)
+    loadSkill: createSkillLoader(registry2),
+    skillTool: createSkillTool(registry2)
   };
 };
 
@@ -18386,10 +18524,10 @@ async function loadConfig({
 var defaultConfigDir = resolve(process3.cwd(), "config");
 var defaultGeneratedDir = resolve(process3.cwd(), "src/generated");
 function getProjectRoot(filePath, options2 = {}) {
-  let path2 = process2.cwd();
-  while (path2.includes("storage"))
-    path2 = resolve2(path2, "..");
-  const finalPath = resolve2(path2, filePath || "");
+  let path3 = process2.cwd();
+  while (path3.includes("storage"))
+    path3 = resolve2(path3, "..");
+  const finalPath = resolve2(path3, filePath || "");
   if (options2?.relative)
     return relative3(process2.cwd(), finalPath);
   return finalPath;
@@ -19836,10 +19974,10 @@ function applyEnvVarsToConfig(name, config3, verbose = false) {
     return config3;
   const envPrefix = name.toUpperCase().replace(/-/g, "_");
   const result = { ...config3 };
-  function processObject(obj, path2 = []) {
+  function processObject(obj, path3 = []) {
     const result2 = { ...obj };
     for (const [key, value] of Object.entries(obj)) {
-      const envPath = [...path2, key];
+      const envPath = [...path3, key];
       const formatKey = (k) => k.replace(/([A-Z])/g, "_$1").toUpperCase();
       const envKey = `${envPrefix}_${envPath.map(formatKey).join("_")}`;
       const oldEnvKey = `${envPrefix}_${envPath.map((p) => p.toUpperCase()).join("_")}`;
@@ -20021,10 +20159,10 @@ async function loadConfig3({
 var defaultConfigDir2 = resolve3(process6.cwd(), "config");
 var defaultGeneratedDir2 = resolve3(process6.cwd(), "src/generated");
 function getProjectRoot2(filePath, options2 = {}) {
-  let path2 = process7.cwd();
-  while (path2.includes("storage"))
-    path2 = resolve4(path2, "..");
-  const finalPath = resolve4(path2, filePath || "");
+  let path3 = process7.cwd();
+  while (path3.includes("storage"))
+    path3 = resolve4(path3, "..");
+  const finalPath = resolve4(path3, filePath || "");
   if (options2?.relative)
     return relative2(process7.cwd(), finalPath);
   return finalPath;
@@ -21461,10 +21599,10 @@ class EnvVarError extends BunfigError {
 
 class FileSystemError extends BunfigError {
   code = "FILE_SYSTEM_ERROR";
-  constructor(operation, path2, cause) {
-    super(`File system ${operation} failed for "${path2}": ${cause.message}`, {
+  constructor(operation, path3, cause) {
+    super(`File system ${operation} failed for "${path3}": ${cause.message}`, {
       operation,
-      path: path2,
+      path: path3,
       originalError: cause.name,
       originalMessage: cause.message
     });
@@ -21537,8 +21675,8 @@ var ErrorFactory = {
   envVar(envKey, envValue, expectedType, configName) {
     return new EnvVarError(envKey, envValue, expectedType, configName);
   },
-  fileSystem(operation, path2, cause) {
-    return new FileSystemError(operation, path2, cause);
+  fileSystem(operation, path3, cause) {
+    return new FileSystemError(operation, path3, cause);
   },
   typeGeneration(configDir, outputPath, cause) {
     return new TypeGenerationError(configDir, outputPath, cause);
@@ -21674,9 +21812,9 @@ class EnvProcessor {
     }
     return key.replace(/([A-Z])/g, "_$1").toUpperCase();
   }
-  processObject(obj, path2, envPrefix, options2) {
+  processObject(obj, path3, envPrefix, options2) {
     for (const [key, value] of Object.entries(obj)) {
-      const envPath = [...path2, key];
+      const envPath = [...path3, key];
       const formattedKeys = envPath.map((k) => this.formatEnvKey(k, options2.useCamelCase));
       const envKey = `${envPrefix}_${formattedKeys.join("_")}`;
       const oldEnvKey = options2.useBackwardCompatibility ? `${envPrefix}_${envPath.map((p) => p.toUpperCase()).join("_")}` : null;
@@ -21761,9 +21899,9 @@ class EnvProcessor {
         return this.formatAsText(envVars, configName);
     }
   }
-  extractEnvVarInfo(obj, path2, prefix, envVars) {
+  extractEnvVarInfo(obj, path3, prefix, envVars) {
     for (const [key, value] of Object.entries(obj)) {
-      const envPath = [...path2, key];
+      const envPath = [...path3, key];
       const envKey = `${prefix}_${envPath.map((k) => this.formatEnvKey(k, true)).join("_")}`;
       if (typeof value === "object" && value !== null && !Array.isArray(value)) {
         this.extractEnvVarInfo(value, envPath, prefix, envVars);
@@ -22178,15 +22316,15 @@ class ConfigFileLoader {
   }
   async preloadConfigurations(configPaths, options2 = {}) {
     const preloaded = new Map;
-    await Promise.allSettled(configPaths.map(async (path2) => {
+    await Promise.allSettled(configPaths.map(async (path3) => {
       try {
-        const result = await this.loadFromPath(path2, {}, options2);
+        const result = await this.loadFromPath(path3, {}, options2);
         if (result) {
-          preloaded.set(path2, result.config);
+          preloaded.set(path3, result.config);
         }
       } catch (error45) {
         if (options2.verbose) {
-          console.warn(`Failed to preload ${path2}:`, error45);
+          console.warn(`Failed to preload ${path3}:`, error45);
         }
       }
     }));
@@ -22265,13 +22403,13 @@ class ConfigValidator {
       warnings
     };
   }
-  validateObjectAgainstSchema(value, schema, path2, errors3, warnings, options2) {
+  validateObjectAgainstSchema(value, schema, path3, errors3, warnings, options2) {
     if (options2.validateTypes && schema.type) {
       const actualType = Array.isArray(value) ? "array" : typeof value;
       const expectedTypes = Array.isArray(schema.type) ? schema.type : [schema.type];
       if (!expectedTypes.includes(actualType)) {
         errors3.push({
-          path: path2,
+          path: path3,
           message: `Expected type ${expectedTypes.join(" or ")}, got ${actualType}`,
           expected: expectedTypes.join(" or "),
           actual: actualType,
@@ -22283,7 +22421,7 @@ class ConfigValidator {
     }
     if (schema.enum && !schema.enum.includes(value)) {
       errors3.push({
-        path: path2,
+        path: path3,
         message: `Value must be one of: ${schema.enum.join(", ")}`,
         expected: schema.enum.join(", "),
         actual: value,
@@ -22295,7 +22433,7 @@ class ConfigValidator {
     if (typeof value === "string") {
       if (schema.minLength !== undefined && value.length < schema.minLength) {
         errors3.push({
-          path: path2,
+          path: path3,
           message: `String length must be at least ${schema.minLength}`,
           expected: `>= ${schema.minLength}`,
           actual: value.length,
@@ -22304,7 +22442,7 @@ class ConfigValidator {
       }
       if (schema.maxLength !== undefined && value.length > schema.maxLength) {
         errors3.push({
-          path: path2,
+          path: path3,
           message: `String length must not exceed ${schema.maxLength}`,
           expected: `<= ${schema.maxLength}`,
           actual: value.length,
@@ -22315,7 +22453,7 @@ class ConfigValidator {
         const regex = new RegExp(schema.pattern);
         if (!regex.test(value)) {
           errors3.push({
-            path: path2,
+            path: path3,
             message: `String does not match pattern ${schema.pattern}`,
             expected: schema.pattern,
             actual: value,
@@ -22327,7 +22465,7 @@ class ConfigValidator {
     if (typeof value === "number") {
       if (schema.minimum !== undefined && value < schema.minimum) {
         errors3.push({
-          path: path2,
+          path: path3,
           message: `Value must be at least ${schema.minimum}`,
           expected: `>= ${schema.minimum}`,
           actual: value,
@@ -22336,7 +22474,7 @@ class ConfigValidator {
       }
       if (schema.maximum !== undefined && value > schema.maximum) {
         errors3.push({
-          path: path2,
+          path: path3,
           message: `Value must not exceed ${schema.maximum}`,
           expected: `<= ${schema.maximum}`,
           actual: value,
@@ -22346,7 +22484,7 @@ class ConfigValidator {
     }
     if (Array.isArray(value) && schema.items) {
       for (let i = 0;i < value.length; i++) {
-        const itemPath = path2 ? `${path2}[${i}]` : `[${i}]`;
+        const itemPath = path3 ? `${path3}[${i}]` : `[${i}]`;
         this.validateObjectAgainstSchema(value[i], schema.items, itemPath, errors3, warnings, options2);
         if (options2.stopOnFirstError && errors3.length > 0)
           return;
@@ -22358,7 +22496,7 @@ class ConfigValidator {
         for (const requiredProp of schema.required) {
           if (!(requiredProp in obj)) {
             errors3.push({
-              path: path2 ? `${path2}.${requiredProp}` : requiredProp,
+              path: path3 ? `${path3}.${requiredProp}` : requiredProp,
               message: `Missing required property '${requiredProp}'`,
               expected: "required",
               rule: "required"
@@ -22371,7 +22509,7 @@ class ConfigValidator {
       if (schema.properties) {
         for (const [propName, propSchema] of Object.entries(schema.properties)) {
           if (propName in obj) {
-            const propPath = path2 ? `${path2}.${propName}` : propName;
+            const propPath = path3 ? `${path3}.${propName}` : propName;
             this.validateObjectAgainstSchema(obj[propName], propSchema, propPath, errors3, warnings, options2);
             if (options2.stopOnFirstError && errors3.length > 0)
               return;
@@ -22383,7 +22521,7 @@ class ConfigValidator {
         for (const propName of Object.keys(obj)) {
           if (!allowedProps.has(propName)) {
             warnings.push({
-              path: path2 ? `${path2}.${propName}` : propName,
+              path: path3 ? `${path3}.${propName}` : propName,
               message: `Additional property '${propName}' is not allowed`,
               rule: "additionalProperties"
             });
@@ -22417,12 +22555,12 @@ class ConfigValidator {
       warnings
     };
   }
-  validateWithRule(value, rule, path2) {
+  validateWithRule(value, rule, path3) {
     const errors3 = [];
     if (rule.required && (value === undefined || value === null)) {
       errors3.push({
-        path: path2,
-        message: rule.message || `Property '${path2}' is required`,
+        path: path3,
+        message: rule.message || `Property '${path3}' is required`,
         expected: "required",
         rule: "required"
       });
@@ -22435,7 +22573,7 @@ class ConfigValidator {
       const actualType = Array.isArray(value) ? "array" : typeof value;
       if (actualType !== rule.type) {
         errors3.push({
-          path: path2,
+          path: path3,
           message: rule.message || `Expected type ${rule.type}, got ${actualType}`,
           expected: rule.type,
           actual: actualType,
@@ -22447,7 +22585,7 @@ class ConfigValidator {
       const length = Array.isArray(value) ? value.length : typeof value === "string" ? value.length : typeof value === "number" ? value : 0;
       if (length < rule.min) {
         errors3.push({
-          path: path2,
+          path: path3,
           message: rule.message || `Value must be at least ${rule.min}`,
           expected: `>= ${rule.min}`,
           actual: length,
@@ -22459,7 +22597,7 @@ class ConfigValidator {
       const length = Array.isArray(value) ? value.length : typeof value === "string" ? value.length : typeof value === "number" ? value : 0;
       if (length > rule.max) {
         errors3.push({
-          path: path2,
+          path: path3,
           message: rule.message || `Value must not exceed ${rule.max}`,
           expected: `<= ${rule.max}`,
           actual: length,
@@ -22470,7 +22608,7 @@ class ConfigValidator {
     if (rule.pattern && typeof value === "string") {
       if (!rule.pattern.test(value)) {
         errors3.push({
-          path: path2,
+          path: path3,
           message: rule.message || `Value does not match pattern ${rule.pattern}`,
           expected: rule.pattern.toString(),
           actual: value,
@@ -22480,7 +22618,7 @@ class ConfigValidator {
     }
     if (rule.enum && !rule.enum.includes(value)) {
       errors3.push({
-        path: path2,
+        path: path3,
         message: rule.message || `Value must be one of: ${rule.enum.join(", ")}`,
         expected: rule.enum.join(", "),
         actual: value,
@@ -22491,7 +22629,7 @@ class ConfigValidator {
       const customError = rule.validator(value);
       if (customError) {
         errors3.push({
-          path: path2,
+          path: path3,
           message: rule.message || customError,
           rule: "custom"
         });
@@ -22499,10 +22637,10 @@ class ConfigValidator {
     }
     return errors3;
   }
-  getValueByPath(obj, path2) {
-    if (!path2)
+  getValueByPath(obj, path3) {
+    if (!path3)
       return obj;
-    const keys = path2.split(".");
+    const keys = path3.split(".");
     let current = obj;
     for (const key of keys) {
       if (current && typeof current === "object" && key in current) {
@@ -22928,10 +23066,10 @@ async function loadConfig5(options2) {
 function applyEnvVarsToConfig2(name, config4, verbose = false) {
   const _envProcessor = new EnvProcessor;
   const envPrefix = name.toUpperCase().replace(/[^A-Z0-9]/g, "_");
-  function processConfigLevel(obj, path2 = []) {
+  function processConfigLevel(obj, path3 = []) {
     const result = { ...obj };
     for (const [key, value] of Object.entries(obj)) {
-      const currentPath = [...path2, key];
+      const currentPath = [...path3, key];
       const envKeys = [
         `${envPrefix}_${currentPath.join("_").toUpperCase()}`,
         `${envPrefix}_${currentPath.map((k) => k.toUpperCase()).join("")}`,
@@ -22997,14 +23135,14 @@ function getOpenCodeConfigPaths() {
   paths.push(join4(home, ".opencode"));
   return paths;
 }
-function expandTildePath(path2) {
-  if (path2 === "~") {
+function expandTildePath(path3) {
+  if (path3 === "~") {
     return homedir3();
   }
-  if (path2.startsWith("~/")) {
-    return join4(homedir3(), path2.slice(2));
+  if (path3.startsWith("~/")) {
+    return join4(homedir3(), path3.slice(2));
   }
-  return path2;
+  return path3;
 }
 var createPathKey = (absolutePath) => {
   const normalizedPath = normalize(absolutePath);
@@ -23077,7 +23215,7 @@ var options2 = {
     promptRenderer: "xml",
     modelRenderers: {},
     slashCommandName: "skill",
-    enableSkillAliases: false
+    enableSkillAliases: true
   }
 };
 async function getPluginConfig(ctx) {
@@ -23093,7 +23231,7 @@ async function getPluginConfig(ctx) {
 // src/commands/SlashCommand.ts
 var SLASH_COMMAND_SENTINEL = "<!-- opencode-dynamic-skills:slash-expanded -->";
 var RECOMMEND_COMMAND_SENTINEL = "<!-- opencode-dynamic-skills:skill-recommend-expanded -->";
-function normalizeSkillSelector(selector) {
+function normalizeSkillSelector3(selector) {
   return selector.trim().toLowerCase().replace(/[/-]/g, "_");
 }
 function parseSlashCommand(text, slashCommandName) {
@@ -23130,30 +23268,26 @@ function findSkillBySelector(registry2, selector) {
   if (directMatch) {
     return directMatch;
   }
-  const normalizedSelector = normalizeSkillSelector(selector);
+  const normalizedSelector = normalizeSkillSelector3(selector);
   for (const skill of registry2.controller.skills) {
-    if (normalizeSkillSelector(skill.toolName) === normalizedSelector) {
+    if (normalizeSkillSelector3(skill.toolName) === normalizedSelector) {
       return skill;
     }
-    if (normalizeSkillSelector(skill.name) === normalizedSelector) {
+    if (normalizeSkillSelector3(skill.name) === normalizedSelector) {
       return skill;
     }
   }
   return null;
 }
 function renderSlashSkillPrompt(args) {
-  const userPrompt = args.userPrompt || "Apply this skill to the current request.";
   return [
     SLASH_COMMAND_SENTINEL,
-    `Slash command: /${args.invocationName}`,
-    `Load the following dynamic skill and use it for this request.`,
-    `Skill identifier: ${args.skill.toolName}`,
-    `Skill root directory: ${args.skill.fullPath}`,
-    `Resolve every file reference inside the skill relative to the skill root directory.`,
-    `If you need a supporting file, use skill_resource with the exact root-relative path.`,
-    `User request: ${userPrompt}`,
-    "",
-    args.renderedSkill
+    formatLoadedSkill({
+      invocationName: args.invocationName,
+      skill: args.skill,
+      userMessage: args.userPrompt || "Apply this skill to the current request."
+    }),
+    ""
   ].join(`
 `);
 }
@@ -23201,7 +23335,6 @@ async function rewriteSlashCommandText(args) {
   }
   return renderSlashSkillPrompt({
     invocationName: parsedCommand.invocationName,
-    renderedSkill: args.renderSkill(skill),
     skill,
     userPrompt: parsedCommand.userPrompt
   });
@@ -23212,6 +23345,15 @@ var createJsonPromptRenderer = () => {
   const renderer = {
     format: "json",
     render(args) {
+      if (args.type === "Skill") {
+        return JSON.stringify({
+          Skill: {
+            ...args.data,
+            linkedResources: extractSkillLinks(args.data.content),
+            skillRootInstruction: "Resolve linked files relative to the skill root and use skill_resource with the exact root-relative path."
+          }
+        }, null, 2);
+      }
       return JSON.stringify({ [args.type]: args.data }, null, 2);
     }
   };
@@ -23269,6 +23411,8 @@ var createXmlPromptRenderer = () => {
   const prepareSkill = (skill) => {
     return {
       ...skill,
+      linkedResources: extractSkillLinks(skill.content),
+      skillRootInstruction: "Resolve linked files relative to the skill root and use skill_resource with the exact root-relative path.",
       references: resourceMapToArray(skill.references),
       scripts: resourceMapToArray(skill.scripts),
       assets: resourceMapToArray(skill.assets)
@@ -23490,6 +23634,7 @@ var createMdPromptRenderer = () => {
     return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
   };
   const renderSkill = (skill) => {
+    const linkedResources = extractSkillLinks(skill.content);
     return dedent_default`
       # ${skill.name}
 
@@ -23497,6 +23642,14 @@ var createMdPromptRenderer = () => {
       > ${skill.fullPath}
 
       Relative file references in this skill resolve from the skill root directory.
+      Always use skill_resource with the exact root-relative path for linked files.
+
+      ${linkedResources.length > 0 ? dedent_default`
+            ## Linked files detected in skill content
+
+            ${linkedResources.map((link) => `- [${link.label}](${link.originalPath}) \u2192 use skill_resource with ${link.resourcePath}`).join(`
+`)}
+          ` : ""}
 
       ${skill.content}
 
@@ -23645,7 +23798,7 @@ var SkillsPlugin = async (ctx) => {
         providerId: input.model?.providerID,
         config: config3
       });
-      const renderSkill = promptRenderer.getFormatter(format);
+      promptRenderer.getFormatter(format);
       for (const part of output.parts) {
         if (part.type !== "text") {
           continue;
@@ -23658,7 +23811,6 @@ var SkillsPlugin = async (ctx) => {
         const rewrittenText = await rewriteSlashCommandText({
           text: part.text,
           registry: api2.registry,
-          renderSkill: (skill) => renderSkill({ data: skill, type: "Skill" }),
           slashCommandName: config3.slashCommandName,
           enableSkillAliases: config3.enableSkillAliases
         });
@@ -23680,6 +23832,7 @@ var SkillsPlugin = async (ctx) => {
       }
     },
     tool: {
+      skill: api2.skillTool,
       skill_use: tool({
         description: "Load one or more skills into the chat. Provide an array of skill names to load them as user messages.",
         args: {

package/dist/lib/SkillLinks.d.ts

@@ -0,0 +1,7 @@
+export type SkillLink = {
+    label: string;
+    originalPath: string;
+    resourcePath: string;
+};
+export declare function normalizeLinkedSkillPath(target: string): string | null;
+export declare function extractSkillLinks(content: string): SkillLink[];

package/dist/lib/formatLoadedSkill.d.ts

@@ -0,0 +1,6 @@
+import type { Skill } from '../types';
+export declare function formatLoadedSkill(args: {
+    skill: Skill;
+    invocationName?: string;
+    userMessage?: string;
+}): string;

package/dist/tools/Skill.d.ts

@@ -0,0 +1,3 @@
+import { type ToolDefinition } from '@opencode-ai/plugin';
+import type { SkillRegistry } from '../types';
+export declare function createSkillTool(registry: SkillRegistry): ToolDefinition;

package/dist/tools/Skill.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-dynamic-skills",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "OpenCode plugin for dynamic skill loading, slash skill commands, and skill-root-relative resources",
   "homepage": "https://github.com/Wu-H-Y/opencode-dynamic-skills#readme",
   "bugs": {