opencode-dynamic-skills 1.1.0 → 1.3.0

package/README.md

@@ -1,20 +1,17 @@
 # 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
 
@@ -83,6 +80,15 @@ This does not mean OpenCode will show dynamic picker suggestions for those alias
 
 ### 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
@@ -112,18 +118,35 @@ 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": true
+  "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.",
+  },
+  "tuiCommandMirror": {
+    "enabled": true,
+    "directory": "~/.config/opencode/commands",
+  },
 }
 ```
 
@@ -131,10 +154,21 @@ Fields:
 
 - `debug`
 - `basePaths`
-- `promptRenderer`
-- `modelRenderers`
 - `slashCommandName`
 - `enableSkillAliases`
+- `reservedSlashCommands`
+- `notifications`
+- `skillRecommend`
+- `tuiCommandMirror`
+
+`tuiCommandMirror` is enabled by default. The plugin mirrors dynamic skills into proxy command files so TUI slash autocomplete can surface `/<skill-name>` after an OpenCode restart.
+
+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
 
@@ -172,6 +206,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,15 +6,7 @@
 
 1. 动态加载 skill
 2. 用 slash 方式使用 skill
-3. 让 skill 内文件引用统一基于 skill 根目录
-
-## 当前状态
-
-这是对已归档 `opencode-skillful` 仓库的重启版本。
-
-- 包名：`opencode-dynamic-skills`
-- 版本：`1.0.0`
-- 协议：MIT
+3. 让 skill 内文件引用与文件清单统一基于 skill 根目录
 
 ## 来源说明
 
@@ -83,6 +75,15 @@
 
 ### Skill 根目录相对资源
 
+当一个 skill 被加载时，插件会注入：
+
+- `SKILL.md` 正文
+- skill 根目录路径
+- 一份完整的 skill 根目录相对文件清单（不包含 `SKILL.md`）
+
+它**不会**默认把所有文件内容都注入进上下文。
+真正的文件内容仍然通过 `skill_resource` 按需读取。
+
 `skill_resource` 现在按 skill 根目录解析路径，例如：
 
 ```txt
@@ -112,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": true
+  "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.",
+  },
 }
 ```
 
@@ -131,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 发现路径
 
@@ -172,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,6 +34,7 @@
  *   // 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';
@@ -52,4 +53,4 @@ export type SkillsApi = {
     loadSkill: ReturnType<typeof createSkillLoader>;
     skillTool: ReturnType<typeof createSkillTool>;
 };
-export declare const createApi: (config: PluginConfig) => Promise<SkillsApi>;
+export declare const createApi: (config: PluginConfig, client?: PluginInput["client"]) => Promise<SkillsApi>;

package/dist/commands/MirroredSkillCommand.d.ts

@@ -0,0 +1,15 @@
+import type { SkillRegistry } from '../types';
+type HookPart = {
+    type: string;
+    text?: string;
+} & Record<string, unknown>;
+export declare function rewriteMirroredSkillCommandParts(args: {
+    commandName: string;
+    commandArguments: string;
+    mirroredCommands: Set<string>;
+    registry: SkillRegistry;
+    output: {
+        parts: HookPart[];
+    };
+}): Promise<boolean>;
+export {};

package/dist/commands/MirroredSkillCommand.test.d.ts

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

package/dist/commands/SlashCommand.d.ts

@@ -12,7 +12,7 @@ export declare function renderSlashSkillPrompt(args: {
     invocationName: string;
     skill: Skill;
     userPrompt: string;
-}): string;
+}): Promise<string>;
 export declare function renderRecommendSlashPrompt(task: string): string;
 export declare function rewriteRecommendSlashCommandText(text: string): Promise<string | null>;
 export declare function rewriteSlashCommandText(args: {
@@ -20,5 +20,6 @@ export declare function rewriteSlashCommandText(args: {
     registry: SkillRegistry;
     slashCommandName: string;
     enableSkillAliases: boolean;
+    reservedSlashCommands?: string[];
 }): Promise<string | null>;
 export {};

package/dist/config.d.ts

@@ -1,5 +1,16 @@
 import type { PluginInput } from '@opencode-ai/plugin';
-import type { PluginConfig } from './types';
+import type { NotificationConfig, PluginConfig, SkillRecommendConfig, TuiCommandMirrorConfig } 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_TUI_COMMANDS_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>;
+    tuiCommandMirror?: Partial<TuiCommandMirrorConfig>;
+};
 /**
  * Gets OpenCode-compatible config paths for the current platform.
  *
@@ -44,4 +55,16 @@ 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 createDefaultTuiCommandMirrorConfig(): TuiCommandMirrorConfig;
+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
  */