opencode-dynamic-skills 1.0.2 → 1.2.0

package/README.md

@@ -1,29 +1,31 @@
 # OpenCode Dynamic Skills
 
+[![npm version](https://img.shields.io/npm/v/opencode-dynamic-skills?color=cb3837&logo=npm)](https://www.npmjs.com/package/opencode-dynamic-skills)
+[![license](https://img.shields.io/npm/l/opencode-dynamic-skills)](./LICENSE)
+[![bun](https://img.shields.io/badge/runtime-Bun-f9f1e1?logo=bun)](https://bun.sh/)
+[![OpenCode](https://img.shields.io/badge/plugin-OpenCode-111827)](https://opencode.ai/)
+
 [中文文档](./README.zh-CN.md)
 
 OpenCode plugin focused on three things:
 
 1. Dynamic skill loading
 2. Slash-style skill usage
-3. Skill-root-relative file references
-
-## Status
-
-This project is a reboot of the archived `opencode-skillful` codebase.
-
-- Package: `opencode-dynamic-skills`
-- Version: `1.0.0`
-- License: MIT
+3. Skill-root-relative file references and file manifests
 
 ## Attribution
 
 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 +39,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,10 +75,20 @@ 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
 
+When a skill is loaded, the plugin injects:
+
+- the `SKILL.md` body
+- the skill root path
+- a complete root-relative file manifest for the skill directory, excluding `SKILL.md`
+
+It does **not** inject every file's content by default.
+Actual file contents stay lazy and are read on demand through `skill_resource`.
+
 `skill_resource` now resolves paths from the skill root, for example:
 
 ```txt
@@ -101,18 +118,31 @@ Register the plugin in `opencode.json`:
 
 ## Configuration
 
+On startup the plugin ensures a complete commented JSONC config exists at:
+
+```text
+~/.config/opencode/opencode-dynamic-skills.config.jsonc
+```
+
 Example:
 
-```json
+```jsonc
 {
+  // Enable verbose plugin logs.
   "debug": false,
-  "promptRenderer": "xml",
-  "modelRenderers": {
-    "claude-3-5-sonnet": "xml",
-    "gpt-4": "json"
-  },
   "slashCommandName": "skill",
-  "enableSkillAliases": false
+  "enableSkillAliases": true,
+  "reservedSlashCommands": ["help", "model", "skills"],
+  "notifications": {
+    "enabled": false,
+    "success": true,
+    "errors": true,
+  },
+  "skillRecommend": {
+    "strategy": "heuristic",
+    "model": "openai/gpt-5.2",
+    "systemPrompt": "You are selecting the most relevant dynamic skills for a user request. Return strict JSON only with this shape: {\"recommendations\":[{\"name\":\"skill_tool_name\",\"reason\":\"why it matches\"}]}. Only recommend skills from the provided catalog. Prefer the smallest set of high-confidence matches.",
+  },
 }
 ```
 
@@ -120,10 +150,18 @@ Fields:
 
 - `debug`
 - `basePaths`
-- `promptRenderer`
-- `modelRenderers`
 - `slashCommandName`
 - `enableSkillAliases`
+- `reservedSlashCommands`
+- `notifications`
+- `skillRecommend`
+
+Injected skill content now always uses a single XML renderer. The previous custom renderer selection feature was removed.
+
+`skillRecommend.strategy` supports:
+
+- `heuristic` (default): use the built-in ranker
+- `model`: call an internal OpenCode session with the configured `provider/model` string
 
 ## Skill discovery
 
@@ -161,6 +199,7 @@ Rules:
 - `name` must match the directory name
 - `name` must satisfy OpenCode naming rules
 - `description` is required
+- non-`SKILL.md` files under the skill directory are indexed and exposed as an available file manifest
 
 ## Development
 

package/README.zh-CN.md

@@ -6,24 +6,21 @@
 
 1. 动态加载 skill
 2. 用 slash 方式使用 skill
-3. 让 skill 内文件引用统一基于 skill 根目录
-
-## 当前状态
-
-这是对已归档 `opencode-skillful` 仓库的重启版本。
-
-- 包名：`opencode-dynamic-skills`
-- 版本：`1.0.0`
-- 协议：MIT
+3. 让 skill 内文件引用与文件清单统一基于 skill 根目录
 
 ## 来源说明
 
 本项目来自并改造于：
 
 - 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 +34,16 @@
 
 插件提供：
 
+- `skill`
 - `skill_find`
 - `skill_recommend`
 - `skill_use`
 - `skill_resource`
 
+默认设计会尽量保持初始工具上下文很小。
+它**不会**在一开始把全部 skill 目录和每个 skill 的 description 都注入进去。
+真正的发现与装载会延后到运行时，通过 `skill_find`、`skill_recommend`、直接 slash 拦截或显式 `skill(name="...")` 调用完成。
+
 ### Slash 技能命令
 
 默认形式：
@@ -68,10 +70,20 @@
 /git-release 帮我起草 release checklist
 ```
 
-alias 默认关闭，避免与 OpenCode 内置命令或官方 commands 冲突。
+在纯 oh-my-openagent 风格下，alias 默认开启，因此提交 `/<skill-name>` 后插件会尝试接管。
+但这不代表 OpenCode 会在输入阶段为这些 alias 提供动态候选列表。
 
 ### Skill 根目录相对资源
 
+当一个 skill 被加载时，插件会注入：
+
+- `SKILL.md` 正文
+- skill 根目录路径
+- 一份完整的 skill 根目录相对文件清单（不包含 `SKILL.md`）
+
+它**不会**默认把所有文件内容都注入进上下文。
+真正的文件内容仍然通过 `skill_resource` 按需读取。
+
 `skill_resource` 现在按 skill 根目录解析路径，例如：
 
 ```txt
@@ -101,18 +113,31 @@ templates/pr.md
 
 ## 配置
 
+插件启动时会确保在下面位置存在一份带英文注释的完整 JSONC 配置：
+
+```text
+~/.config/opencode/opencode-dynamic-skills.config.jsonc
+```
+
 示例：
 
-```json
+```jsonc
 {
+  // Enable verbose plugin logs.
   "debug": false,
-  "promptRenderer": "xml",
-  "modelRenderers": {
-    "claude-3-5-sonnet": "xml",
-    "gpt-4": "json"
-  },
   "slashCommandName": "skill",
-  "enableSkillAliases": false
+  "enableSkillAliases": true,
+  "reservedSlashCommands": ["help", "model", "skills"],
+  "notifications": {
+    "enabled": false,
+    "success": true,
+    "errors": true,
+  },
+  "skillRecommend": {
+    "strategy": "heuristic",
+    "model": "openai/gpt-5.2",
+    "systemPrompt": "You are selecting the most relevant dynamic skills for a user request. Return strict JSON only with this shape: {\"recommendations\":[{\"name\":\"skill_tool_name\",\"reason\":\"why it matches\"}]}. Only recommend skills from the provided catalog. Prefer the smallest set of high-confidence matches.",
+  },
 }
 ```
 
@@ -120,10 +145,18 @@ templates/pr.md
 
 - `debug`
 - `basePaths`
-- `promptRenderer`
-- `modelRenderers`
 - `slashCommandName`
 - `enableSkillAliases`
+- `reservedSlashCommands`
+- `notifications`
+- `skillRecommend`
+
+当前注入的 skill 内容已固定使用单一 XML 渲染器，之前可自定义渲染格式的功能已移除。
+
+`skillRecommend.strategy` 支持：
+
+- `heuristic`（默认）：使用内置规则排序
+- `model`：使用配置的 `provider/model` 字符串发起一次内部 OpenCode session 调用
 
 ## Skill 发现路径
 
@@ -161,6 +194,7 @@ compatibility: opencode
 - `name` 必须和目录名一致
 - `name` 必须符合 OpenCode 命名规则
 - `description` 必填
+- skill 目录下除 `SKILL.md` 外的文件会被索引，并作为可用文件清单暴露给模型
 
 ## 开发
 

package/dist/api.d.ts

@@ -9,12 +9,12 @@
  * - Logger (for debug output)
  * - SkillRegistry (for discovery and parsing)
  * - Tool creators (functions that create skill_find, skill_use, skill_resource)
- * - PromptRenderer (for format selection and rendering)
+ * - Prompt rendering helpers
  *
  * INITIALIZATION TIMING (CRITICAL):
  * - createLogger(): synchronous, immediate
  * - createSkillRegistry(): synchronous factory call (returns a SkillRegistry object)
- * - createPromptRenderer(): synchronous, immediate (format selection at runtime)
+ * - XML prompt rendering is fixed and selected by the caller
  * - registry.initialise(): NOT called here, caller must do this separately
  *
  * WHY NOT CALL initialise(): The caller (index.ts) needs to await initialise()
@@ -23,7 +23,7 @@
  * RETURN VALUE: Object with:
  * - registry: SkillRegistry instance (must call .initialise() before use)
  * - logger: PluginLogger for debug output
- * - config: PluginConfig (needed for model-aware format selection)
+ * - config: PluginConfig
  * - findSkills: Tool creator function for skill search
  * - readResource: Tool creator function for resource reading
  * - loadSkill: Tool creator function for skill loading
@@ -34,63 +34,23 @@
  *   // Note: registry is created but NOT yet initialized
  *   // Must be done by caller: await registry.initialise()
  */
+import type { PluginInput } from '@opencode-ai/plugin';
+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, client?: PluginInput["client"]) => 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,8 +18,8 @@ export declare function rewriteRecommendSlashCommandText(text: string): Promise<
 export declare function rewriteSlashCommandText(args: {
     text: string;
     registry: SkillRegistry;
-    renderSkill: (skill: Skill) => string;
     slashCommandName: string;
     enableSkillAliases: boolean;
+    reservedSlashCommands?: string[];
 }): Promise<string | null>;
 export {};

package/dist/config.d.ts

@@ -1,5 +1,14 @@
 import type { PluginInput } from '@opencode-ai/plugin';
-import type { PluginConfig } from './types';
+import type { NotificationConfig, PluginConfig, SkillRecommendConfig } from './types';
+export declare const DEFAULT_RESERVED_SLASH_COMMANDS: readonly ["agent", "agents", "compact", "connect", "details", "editor", "exit", "export", "fork", "help", "init", "mcp", "model", "models", "new", "open", "redo", "sessions", "share", "skills", "terminal", "themes", "thinking", "undo", "unshare"];
+export declare const DEFAULT_SKILL_RECOMMEND_SYSTEM_PROMPT: string;
+export declare const MANAGED_PLUGIN_CONFIG_DIRECTORY: string;
+export declare const MANAGED_PLUGIN_JSONC_FILENAME = "opencode-dynamic-skills.config.jsonc";
+export declare const MANAGED_PLUGIN_JSON_FILENAME = "opencode-dynamic-skills.config.json";
+type PartialPluginConfig = Partial<Omit<PluginConfig, 'skillRecommend' | 'notifications'>> & {
+    skillRecommend?: Partial<SkillRecommendConfig>;
+    notifications?: Partial<NotificationConfig>;
+};
 /**
  * Gets OpenCode-compatible config paths for the current platform.
  *
@@ -44,4 +53,15 @@ export declare function resolveBasePath(basePath: string, projectDirectory: stri
  */
 export declare function normalizeBasePaths(basePaths: string[], projectDirectory: string): string[];
 export declare function getProjectSkillBasePaths(directory: string, worktree?: string): string[];
+export declare function createDefaultSkillRecommendConfig(): SkillRecommendConfig;
+export declare function createDefaultNotificationConfig(): NotificationConfig;
+export declare function createDefaultPluginConfig(): PluginConfig;
+export declare function stripJsonComments(input: string): string;
+export declare function removeTrailingJsonCommas(input: string): string;
+export declare function parseJsonc<T>(input: string): T;
+export declare function getManagedPluginConfigPaths(configDirectory?: string): string[];
+export declare function renderManagedPluginConfigJsonc(config?: PluginConfig): string;
+export declare function ensureManagedPluginConfigFile(configDirectory?: string): Promise<string>;
+export declare function loadManagedPluginConfig(configDirectory?: string): Promise<PartialPluginConfig>;
 export declare function getPluginConfig(ctx: PluginInput): Promise<PluginConfig>;
+export {};

package/dist/index.d.ts

@@ -11,7 +11,7 @@
  *   - find_skills(): Search for skills by free-text query
  * - Delivers skill content via silent message insertion (noReply pattern)
  * - Supports nested skills with proper naming
- * - Supports multiple prompt formats (XML, JSON, Markdown) with model-aware selection
+ * - Uses a single XML prompt format for injected skill content
  *
  * Design Decisions:
  * - Consolidates 50+ individual skill tools into 2 unified tools (cleaner namespace)
@@ -21,7 +21,7 @@
  * - Message insertion pattern ensures skill content persists (user messages not purged)
  * - Base directory context enables relative path resolution
  * - Skills require restart to reload (acceptable trade-off)
- * - Prompt format selection: model-aware via modelRenderers config, default XML
+ * - Prompt rendering is fixed to XML for simpler, stable behavior
  *
  * @see https://github.com/anthropics/skills
  */