opencode-dynamic-skills 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 zenobi.us
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,180 @@
+# OpenCode Dynamic Skills
+
+[中文文档](./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
+
+## Attribution
+
+This project is derived from and adapted from:
+
+- https://github.com/zenobi-us/opencode-skillful
+
+The current codebase restructures and extends that work for a fresh restart.
+
+## Goals
+
+- Keep skills **lazy-loaded**, instead of injecting all skills into every session
+- Support **slash commands** for skill invocation
+- Resolve skill file references **relative to the skill directory root**
+- Follow current OpenCode plugin / command / skill conventions
+
+## What ships in the current release
+
+### Dynamic skill tools
+
+The plugin provides:
+
+- `skill_find`
+- `skill_recommend`
+- `skill_use`
+- `skill_resource`
+
+### Slash skill command
+
+Default form:
+
+```txt
+/skill <skill-id> [request]
+```
+
+Example:
+
+```txt
+/skill git_release draft a release checklist
+```
+
+Recommendation form:
+
+```txt
+/skill-recommend draft a release checklist
+```
+
+Optional aliases are also supported:
+
+```txt
+/git-release draft a release checklist
+```
+
+Aliases are disabled by default to avoid collisions with native or official OpenCode commands.
+
+### Skill-root-relative resources
+
+`skill_resource` now resolves paths from the skill root, for example:
+
+```txt
+references/guide.md
+scripts/setup.sh
+assets/logo.svg
+templates/pr.md
+```
+
+Safety rules:
+
+- accepts `./references/guide.md`
+- accepts Windows `\` separators
+- rejects absolute paths
+- rejects `..` traversal
+
+## Installation
+
+Register the plugin in `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-dynamic-skills"]
+}
+```
+
+## Configuration
+
+Example:
+
+```json
+{
+  "debug": false,
+  "promptRenderer": "xml",
+  "modelRenderers": {
+    "claude-3-5-sonnet": "xml",
+    "gpt-4": "json"
+  },
+  "slashCommandName": "skill",
+  "enableSkillAliases": false
+}
+```
+
+Fields:
+
+- `debug`
+- `basePaths`
+- `promptRenderer`
+- `modelRenderers`
+- `slashCommandName`
+- `enableSkillAliases`
+
+## Skill discovery
+
+The rewrite supports current OpenCode-compatible locations:
+
+- `.opencode/skills`
+- `.claude/skills`
+- `.agents/skills`
+- `~/.config/opencode/skills`
+- `~/.claude/skills`
+- `~/.agents/skills`
+
+Project-local paths are walked upward from the current working directory to the git worktree.
+
+## Skill format
+
+Each skill must contain `SKILL.md` with valid frontmatter:
+
+```md
+---
+name: git-release
+description: Create consistent releases and changelogs
+compatibility: opencode
+---
+
+## What I do
+
+- Draft release notes
+- Propose version bumps
+```
+
+Rules:
+
+- `name` is required
+- `name` must match the directory name
+- `name` must satisfy OpenCode naming rules
+- `description` is required
+
+## Development
+
+```bash
+bun install
+bun run typecheck
+bun run lint
+bun run format:check
+bun test
+bun run build
+```
+
+To format the repo:
+
+```bash
+bun run format
+```

package/README.zh-CN.md

@@ -0,0 +1,180 @@
+# OpenCode Dynamic Skills
+
+[English README](./README.md)
+
+这是一个专注于三件事的 OpenCode 插件：
+
+1. 动态加载 skill
+2. 用 slash 方式使用 skill
+3. 让 skill 内文件引用统一基于 skill 根目录
+
+## 当前状态
+
+这是对已归档 `opencode-skillful` 仓库的重启版本。
+
+- 包名：`opencode-dynamic-skills`
+- 版本：`1.0.0`
+- 协议：MIT
+
+## 来源说明
+
+本项目来自并改造于：
+
+- https://github.com/zenobi-us/opencode-skillful
+
+当前版本在此基础上做了重新组织和重启开发。
+
+## 目标
+
+- 保持 **按需加载**，不把所有 skill 预注入到每个会话
+- 支持 **slash 方式** 调用 skill
+- 让 skill 文件引用 **相对 skill 根目录** 解析
+- 对齐当前 OpenCode 的 plugin / command / skill 约定
+
+## 当前版本已完成内容
+
+### 动态技能工具
+
+插件提供：
+
+- `skill_find`
+- `skill_recommend`
+- `skill_use`
+- `skill_resource`
+
+### Slash 技能命令
+
+默认形式：
+
+```txt
+/skill <skill-id> [请求]
+```
+
+示例：
+
+```txt
+/skill git_release 帮我起草 release checklist
+```
+
+推荐形式：
+
+```txt
+/skill-recommend 帮我推荐适合 release checklist 的 skill
+```
+
+也支持可选 alias：
+
+```txt
+/git-release 帮我起草 release checklist
+```
+
+alias 默认关闭，避免与 OpenCode 内置命令或官方 commands 冲突。
+
+### Skill 根目录相对资源
+
+`skill_resource` 现在按 skill 根目录解析路径，例如：
+
+```txt
+references/guide.md
+scripts/setup.sh
+assets/logo.svg
+templates/pr.md
+```
+
+安全规则：
+
+- 支持 `./references/guide.md`
+- 支持 Windows `\` 分隔符
+- 拒绝绝对路径
+- 拒绝 `..` 越界
+
+## 安装
+
+在 `opencode.json` 中注册插件：
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-dynamic-skills"]
+}
+```
+
+## 配置
+
+示例：
+
+```json
+{
+  "debug": false,
+  "promptRenderer": "xml",
+  "modelRenderers": {
+    "claude-3-5-sonnet": "xml",
+    "gpt-4": "json"
+  },
+  "slashCommandName": "skill",
+  "enableSkillAliases": false
+}
+```
+
+字段：
+
+- `debug`
+- `basePaths`
+- `promptRenderer`
+- `modelRenderers`
+- `slashCommandName`
+- `enableSkillAliases`
+
+## Skill 发现路径
+
+当前重构支持这些 OpenCode 兼容位置：
+
+- `.opencode/skills`
+- `.claude/skills`
+- `.agents/skills`
+- `~/.config/opencode/skills`
+- `~/.claude/skills`
+- `~/.agents/skills`
+
+项目本地路径会从当前目录向上遍历到 git worktree。
+
+## Skill 格式
+
+每个 skill 都必须包含 `SKILL.md`，frontmatter 示例：
+
+```md
+---
+name: git-release
+description: Create consistent releases and changelogs
+compatibility: opencode
+---
+
+## What I do
+
+- Draft release notes
+- Propose version bumps
+```
+
+规则：
+
+- `name` 必填
+- `name` 必须和目录名一致
+- `name` 必须符合 OpenCode 命名规则
+- `description` 必填
+
+## 开发
+
+```bash
+bun install
+bun run typecheck
+bun run lint
+bun run format:check
+bun test
+bun run build
+```
+
+格式化：
+
+```bash
+bun run format
+```

package/dist/api.d.ts

@@ -0,0 +1,96 @@
+/**
+ * API Factory - Plugin Initialization and Tool Creation
+ *
+ * WHY: Centralizes the creation of all plugin components (logger, registry, tools, renderers)
+ * in one place. Makes it easy to test different configurations, mock components,
+ * and understand the complete initialization flow.
+ *
+ * RESPONSIBILITY: This is the only place that knows how to wire together:
+ * - 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)
+ *
+ * INITIALIZATION TIMING (CRITICAL):
+ * - createLogger(): synchronous, immediate
+ * - createSkillRegistry(): synchronous factory call (returns a SkillRegistry object)
+ * - createPromptRenderer(): synchronous, immediate (format selection at runtime)
+ * - registry.initialise(): NOT called here, caller must do this separately
+ *
+ * WHY NOT CALL initialise(): The caller (index.ts) needs to await initialise()
+ * and handle errors. We can't do that in the factory without making it more complex.
+ *
+ * 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)
+ * - findSkills: Tool creator function for skill search
+ * - readResource: Tool creator function for resource reading
+ * - loadSkill: Tool creator function for skill loading
+ *
+ * EXAMPLE:
+ *   const api = await createApi(config);
+ *   const { registry, config, findSkills, readResource, loadSkill } = api;
+ *   // Note: registry is created but NOT yet initialized
+ *   // Must be done by caller: await registry.initialise()
+ */
+import type { PluginConfig } from './types';
+export declare const createApi: (config: PluginConfig) => Promise<{
+    registry: import("./types").SkillRegistry;
+    logger: import("./types").PluginLogger;
+    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[];
+    }>;
+}>;

package/dist/commands/SlashCommand.d.ts

@@ -0,0 +1,26 @@
+import type { Skill, SkillRegistry } from '../types';
+export declare const SLASH_COMMAND_SENTINEL = "<!-- opencode-dynamic-skills:slash-expanded -->";
+export declare const RECOMMEND_COMMAND_SENTINEL = "<!-- opencode-dynamic-skills:skill-recommend-expanded -->";
+type ParsedSlashCommand = {
+    invocationName: string;
+    skillSelector: string;
+    userPrompt: string;
+};
+export declare function parseSlashCommand(text: string, slashCommandName: string): ParsedSlashCommand | null;
+export declare function findSkillBySelector(registry: SkillRegistry, selector: string): Skill | null;
+export declare function renderSlashSkillPrompt(args: {
+    invocationName: string;
+    renderedSkill: string;
+    skill: Skill;
+    userPrompt: string;
+}): string;
+export declare function renderRecommendSlashPrompt(task: string): string;
+export declare function rewriteRecommendSlashCommandText(text: string): Promise<string | null>;
+export declare function rewriteSlashCommandText(args: {
+    text: string;
+    registry: SkillRegistry;
+    renderSkill: (skill: Skill) => string;
+    slashCommandName: string;
+    enableSkillAliases: boolean;
+}): Promise<string | null>;
+export {};

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

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

package/dist/config.d.ts

@@ -0,0 +1,47 @@
+import type { PluginInput } from '@opencode-ai/plugin';
+import type { PluginConfig } from './types';
+/**
+ * Gets OpenCode-compatible config paths for the current platform.
+ *
+ * Matches OpenCode's path resolution logic from internal/config/config.go:
+ * - Uses XDG_CONFIG_HOME if set
+ * - Falls back to LOCALAPPDATA on Windows, ~/.config on Unix
+ * - Also includes ~/.opencode/ as an alternative
+ *
+ * @returns Array of config directory paths in priority order (lowest to highest)
+ */
+export declare function getOpenCodeConfigPaths(): string[];
+/**
+ * Expands tilde (~) in a path to the user's home directory.
+ *
+ * WHY: When users configure paths in JSON config files, shell expansion
+ * doesn't happen automatically. Paths like "~/my-skills" remain literal
+ * strings, causing file operations to fail.
+ *
+ * HANDLES:
+ * - "~" alone → home directory
+ * - "~/path" → home directory + path
+ * - Other paths → unchanged
+ *
+ * @param path - The path string to expand
+ * @returns The expanded path with ~ resolved to home directory
+ */
+export declare function expandTildePath(path: string): string;
+/**
+ * Resolve a configured base path to an absolute path.
+ *
+ * Resolution rules:
+ * - "~" / "~/..." are expanded to the user home directory
+ * - Absolute paths are preserved
+ * - Relative paths are resolved from the project directory
+ */
+export declare function resolveBasePath(basePath: string, projectDirectory: string): string;
+/**
+ * Normalize configured base paths:
+ * - Resolve to absolute paths
+ * - Remove empty entries
+ * - Remove duplicates while preserving priority order
+ */
+export declare function normalizeBasePaths(basePaths: string[], projectDirectory: string): string[];
+export declare function getProjectSkillBasePaths(directory: string, worktree?: string): string[];
+export declare function getPluginConfig(ctx: PluginInput): Promise<PluginConfig>;

package/dist/config.test.d.ts

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

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * OpenCode Dynamic Skills Plugin
+ *
+ * Implements Anthropic's Agent Skills Specification (v1.0) for OpenCode.
+ *
+ * Features:
+ * - Discovers SKILL.md files from .opencode/skills/, ~/.opencode/skills/, and ~/.config/opencode/skills/
+ * - Validates skills against Anthropic's spec (YAML frontmatter + Markdown)
+ * - Provides unified skill discovery and loading via two main tools:
+ *   - use_skills(): Load one or more skills by name
+ *   - 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
+ *
+ * Design Decisions:
+ * - Consolidates 50+ individual skill tools into 2 unified tools (cleaner namespace)
+ * - Skills are discovered resources, not always-on capabilities
+ * - Lazy loading: skills only inject when explicitly requested
+ * - Tool restrictions handled at agent level (not skill level)
+ * - 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
+ *
+ * @see https://github.com/anthropics/skills
+ */
+import { type Plugin } from '@opencode-ai/plugin';
+export declare const SkillsPlugin: Plugin;