@yeyuan98/opencode-bioresearcher-plugin 1.3.0-alpha.0 → 1.3.0

package/README.md

@@ -75,6 +75,32 @@ Download pubmed article data from https://ftp.ncbi.nlm.nih.gov/pubmed/updatefile
 
 Reference: [PubMed Download Data](https://pubmed.ncbi.nlm.nih.gov/download/).
 
+## Skills
+
+Skills are reusable prompt templates discovered from multiple paths:
+
+| Path | Scope |
+|------|-------|
+| `.opencode/skills/` | Project |
+| `~/.config/opencode/skills/` | Global |
+| `.claude/skills/` | Claude Code compatible |
+| `.agents/skills/` | Agents compatible |
+
+This plugin provides a skill tool that overrides Opencode's built-in to support plugin-shipped skills.
+
+See [skill-tools/README.md](skill-tools/README.md) for full documentation.
+
+### Supplied skills
+
+- `demo-skill`: showcase skill tool mechanisms.
+- `python-setup-uv`: setup python runtime in your working directory with uv.
+
+Prompt the following and follow along:
+
+```txt
+Setup python uv with skill
+```
+
 ## Installation
 
 Add the plugin to your `opencode.json`:

package/dist/shared/tool-restrictions.js

@@ -42,6 +42,9 @@ export const AGENT_TOOL_RESTRICTIONS = {
         "read",
         "write",
         "edit",
+        "question",
+        "todowrite",
+        "task"
     ]),
     bioresearcherDR_worker: createAllowlist([
         "biomcp*",
@@ -53,6 +56,7 @@ export const AGENT_TOOL_RESTRICTIONS = {
         "read",
         "write",
         "edit",
+        "todowrite"
     ]),
 };
 /**

package/dist/skill-tools/index.d.ts

@@ -1,3 +1,3 @@
 export { SkillTool } from "./tool";
-export { getAllSkills, getSkill, clearCache, SkillConflictError } from "./registry";
+export { getAllSkills, getSkill, SkillConflictError } from "./registry";
 export type { ExtendedSkill, ExtendedSkillFrontmatter, ParsedSkill } from "./types";

package/dist/skill-tools/index.js

@@ -1,2 +1,2 @@
 export { SkillTool } from "./tool";
-export { getAllSkills, getSkill, clearCache, SkillConflictError } from "./registry";
+export { getAllSkills, getSkill, SkillConflictError } from "./registry";

package/dist/skill-tools/registry.d.ts

@@ -6,6 +6,11 @@ export declare class SkillConflictError extends Error {
     constructor(skillName: string, pluginLocation: string, userLocation: string);
 }
 export declare function loadPluginSkills(): Promise<ExtendedSkill[]>;
-export declare function getAllSkills(): Promise<ExtendedSkill[]>;
-export declare function getSkill(name: string): Promise<ExtendedSkill | undefined>;
-export declare function clearCache(): void;
+export declare function discoverOpencodeProjectSkills(directory?: string): Promise<ExtendedSkill[]>;
+export declare function discoverOpencodeGlobalSkills(): Promise<ExtendedSkill[]>;
+export declare function discoverClaudeProjectSkills(directory?: string): Promise<ExtendedSkill[]>;
+export declare function discoverClaudeGlobalSkills(): Promise<ExtendedSkill[]>;
+export declare function discoverAgentsProjectSkills(directory?: string): Promise<ExtendedSkill[]>;
+export declare function discoverAgentsGlobalSkills(): Promise<ExtendedSkill[]>;
+export declare function getAllSkills(directory?: string): Promise<ExtendedSkill[]>;
+export declare function getSkill(name: string, directory?: string): Promise<ExtendedSkill | undefined>;

package/dist/skill-tools/registry.js

@@ -1,7 +1,19 @@
 import path from "path";
+import { homedir } from "os";
+import { existsSync } from "fs";
 import { fileURLToPath } from "url";
+import { xdgConfig } from "xdg-basedir";
 import { parseSkillFrontmatter } from "./frontmatter";
 const SKILL_GLOB = new Bun.Glob("**/SKILL.md");
+function getOpenCodeConfigDir() {
+    const envDir = process.env.OPENCODE_CONFIG_DIR;
+    if (envDir)
+        return envDir;
+    return path.join(xdgConfig, "opencode");
+}
+function getClaudeConfigDir() {
+    return process.env.CLAUDE_CONFIG_DIR || path.join(homedir(), ".claude");
+}
 export class SkillConflictError extends Error {
     skillName;
     pluginLocation;
@@ -19,12 +31,13 @@ function getPluginSkillsDir() {
     const currentDir = path.dirname(fileURLToPath(import.meta.url));
     return path.join(currentDir, "..", "skills");
 }
-export async function loadPluginSkills() {
-    const skillsDir = getPluginSkillsDir();
+async function loadSkillsFromDir(dir, source) {
+    if (!existsSync(dir))
+        return [];
     const skills = [];
     try {
         for await (const match of SKILL_GLOB.scan({
-            cwd: skillsDir,
+            cwd: dir,
             absolute: true,
             onlyFiles: true,
         })) {
@@ -38,27 +51,82 @@ export async function loadPluginSkills() {
                 content: parsed.content,
                 agent: parsed.frontmatter.agent,
                 allowedTools: parsed.frontmatter.allowedTools,
-                source: "plugin",
+                source,
             });
         }
     }
     catch {
-        // Plugin skills directory may not exist
+        // Directory may not be readable
     }
     return skills;
 }
-let cachedSkills = null;
-export async function getAllSkills() {
-    if (cachedSkills)
-        return cachedSkills;
-    const pluginSkills = await loadPluginSkills();
-    cachedSkills = pluginSkills;
-    return pluginSkills;
+export async function loadPluginSkills() {
+    return loadSkillsFromDir(getPluginSkillsDir(), "plugin");
 }
-export async function getSkill(name) {
-    const skills = await getAllSkills();
-    return skills.find((s) => s.name === name);
+export async function discoverOpencodeProjectSkills(directory) {
+    const dir = directory ?? process.cwd();
+    return loadSkillsFromDir(path.join(dir, ".opencode", "skills"), "opencode-project");
+}
+export async function discoverOpencodeGlobalSkills() {
+    return loadSkillsFromDir(path.join(getOpenCodeConfigDir(), "skills"), "opencode-global");
+}
+export async function discoverClaudeProjectSkills(directory) {
+    const dir = directory ?? process.cwd();
+    return loadSkillsFromDir(path.join(dir, ".claude", "skills"), "claude-project");
 }
-export function clearCache() {
-    cachedSkills = null;
+export async function discoverClaudeGlobalSkills() {
+    return loadSkillsFromDir(path.join(getClaudeConfigDir(), "skills"), "claude-global");
+}
+export async function discoverAgentsProjectSkills(directory) {
+    const dir = directory ?? process.cwd();
+    return loadSkillsFromDir(path.join(dir, ".agents", "skills"), "agents-project");
+}
+export async function discoverAgentsGlobalSkills() {
+    return loadSkillsFromDir(path.join(homedir(), ".agents", "skills"), "agents-global");
+}
+export async function getAllSkills(directory) {
+    const dir = directory ?? process.cwd();
+    const [opencodeProject, opencodeGlobal, claudeProject, claudeGlobal, agentsProject, agentsGlobal, plugin] = await Promise.all([
+        discoverOpencodeProjectSkills(dir),
+        discoverOpencodeGlobalSkills(),
+        discoverClaudeProjectSkills(dir),
+        discoverClaudeGlobalSkills(),
+        discoverAgentsProjectSkills(dir),
+        discoverAgentsGlobalSkills(),
+        loadPluginSkills(),
+    ]);
+    const userSkills = [
+        ...opencodeProject,
+        ...opencodeGlobal,
+        ...claudeProject,
+        ...claudeGlobal,
+        ...agentsProject,
+        ...agentsGlobal,
+    ];
+    const pluginNames = new Set(plugin.map((s) => s.name));
+    const conflicts = userSkills.filter((s) => pluginNames.has(s.name));
+    if (conflicts.length > 0) {
+        throw new SkillConflictError(conflicts[0].name, "", conflicts[0].location);
+    }
+    const seen = new Set();
+    return [
+        ...opencodeProject,
+        ...opencodeGlobal,
+        ...claudeProject,
+        ...claudeGlobal,
+        ...agentsProject,
+        ...agentsGlobal,
+        ...plugin,
+    ].filter((skill) => {
+        if (seen.has(skill.name)) {
+            console.warn(`[skill] Duplicate skill "${skill.name}" - using higher priority version`);
+            return false;
+        }
+        seen.add(skill.name);
+        return true;
+    });
+}
+export async function getSkill(name, directory) {
+    const skills = await getAllSkills(directory);
+    return skills.find((s) => s.name === name);
 }

package/dist/skill-tools/tool.js

@@ -53,8 +53,8 @@ export const SkillTool = tool({
         name: tool.schema.string().describe("The name of the skill from available_skills"),
     },
     async execute(params, ctx) {
-        const skills = await getAllSkills();
-        const skill = await getSkill(params.name);
+        const skills = await getAllSkills(ctx.directory);
+        const skill = await getSkill(params.name, ctx.directory);
         if (!skill) {
             const available = skills.map((s) => s.name).join(", ");
             throw new Error(`Skill "${params.name}" not found. Available skills: ${available || "none"}`);

package/dist/skill-tools/types.d.ts

@@ -6,6 +6,7 @@ export declare const ExtendedSkillFrontmatter: z.ZodObject<{
     allowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 export type ExtendedSkillFrontmatter = z.infer<typeof ExtendedSkillFrontmatter>;
+export type SkillSource = "plugin" | "opencode-project" | "opencode-global" | "claude-project" | "claude-global" | "agents-project" | "agents-global";
 export interface ExtendedSkill {
     name: string;
     description: string;
@@ -13,7 +14,7 @@ export interface ExtendedSkill {
     content: string;
     agent?: string;
     allowedTools?: string[];
-    source: "plugin";
+    source: SkillSource;
 }
 export interface ParsedSkill {
     frontmatter: ExtendedSkillFrontmatter;

package/dist/skills/demo-skill/SKILL.md

@@ -21,7 +21,7 @@ This skill demonstrates the plugin skill integration system.
 Run the bundled script to verify resources are properly resolved:
 
 ```bash
-python3 demo_script.py
+python demo_script.py
 ```
 
 Expected output:

package/dist/skills/demo-skill/demo_script.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python3
+#!/usr/bin/env python
 """Demo script to verify skill resource resolution."""
 
 import os

package/dist/skills/python-setup-uv/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: python-setup-uv
+description: Setup Python environment with uv package manager - download binaries, create symlink, and install packages
+allowedTools:
+  - Bash
+  - Read
+---
+
+# Python Environment Setup with uv
+
+This skill sets up a Python environment using the uv package manager.
+
+## Prerequisites
+- Internet connection for downloading uv
+- Python 3.8+ should be available on PATH (or uv will prompt to install it)
+
+## Steps
+
+**ABSOLUTE RULE:** Follow steps below EXACTLY AS IS. Do NOT skip/modify steps (nor detailed subtasks in each step) nor assume anything based on user platform information. Use URLs below EXACTLY AS IS. Follow steps below INCLUDING ALL DETAILS AND SUBSTEPS EXACTLY AS IS.
+
+### Step 1: Ask user question about which installer to use
+
+Use the question tool to ask which installer should be used:
+
+- Official astral-uv installer (https://astral.sh)
+- China mainland uv-custom installer (https://gitee.com/wangnov/uv-custom)
+
+### Step 2: Detect Shell and Download uv Binary
+
+First, detect your shell environment:
+
+```bash
+# Detect shell type
+# MSYSTEM is set by Git Bash, MINGW_PREFIX by MSYS2
+if [ -n "$MSYSTEM" ] || [ -n "$MINGW_PREFIX" ] || command -v curl >/dev/null 2>&1; then
+  echo "Unix-like shell detected (Git Bash, bash, zsh, etc.)"
+  IS_UNIX_SHELL=true
+else
+  echo "Windows cmd.exe detected"
+  IS_UNIX_SHELL=false
+fi
+```
+
+Then download uv based on your shell (see below).
+
+Choose the correct `UV_INSTALLER_URL` depending on answer you received in Step 1 from the user:
+
+- If opted "Official astral-uv", UV_INSTALLER_URL should be `https://astral.sh/uv/install.sh` (Unix-like) or `https://astral.sh/uv/install.ps1` (Windows)
+- If opted "China mainland uv-custom", UV_INSTALLER_URL should be `https://gitee.com/wangnov/uv-custom/releases/download/latest/uv-installer-custom.sh` (Unix-like) or `https://gitee.com/wangnov/uv-custom/releases/download/latest/uv-installer-custom.ps1` (Windows)
+
+**For Unix-like shells (Git Bash / macOS / Linux; use correct UV_INSTALLER_URL):**
+```bash
+mkdir -p .uv
+curl -LsSf UV_INSTALLER_URL | UV_INSTALL_DIR="$(pwd)/.uv" sh
+```
+
+**For Windows cmd.exe (if Git Bash unavailable; use correct UV_INSTALLER_URL):**
+```bash
+powershell -NoProfile -Command "New-Item -ItemType Directory -Force -Path .uv | Out-Null; $env:UV_INSTALL_DIR = (Get-Location).Path + '\.uv'; Invoke-RestMethod UV_INSTALLER_URL | Invoke-Expression"
+```
+
+### Step 3: Create Symlink or Copy uv to Working Directory
+
+**For Unix-like shells (Git Bash / macOS / Linux):**
+```bash
+ln -sf .uv/uv uv
+```
+
+**For Windows cmd.exe:**
+
+Try symlink first, fall back to copy if no Admin rights:
+```bash
+cmd /c "(mklink uv .uv\uv.exe) 2>nul || copy /Y .uv\uv.exe uv.exe"
+```
+
+### Step 4: Create Virtual Environment and Install pandas
+
+NOTE: this step (package installation) may timeout. If timed out, use the question tool to ask if the user would like to retry package installation. If successful, do NOT ask any question and continue to Step 5.
+
+**For Unix-like shells:**
+```bash
+./uv venv
+./uv pip install pandas
+```
+
+**For Windows cmd.exe:**
+```bash
+uv.exe venv
+uv.exe pip install pandas
+```
+
+### Step 5: Verification
+
+**For Unix-like shells:**
+```bash
+./uv --version
+./uv run python -c "import pandas; print(pandas.__version__)"
+```
+
+**For Windows cmd.exe:**
+```bash
+uv.exe --version
+uv.exe run python -c "import pandas; print(pandas.__version__)"
+```
+
+### Step 6: Update AGENTS.md
+
+Use the question tool to ask if the user want to update AGENTS.md in WORKING DIRECTORY to "direct agents to use the installed UV Python" (options: "Yes" / "No"). If received no answer, continue to Step 7 (do NOT modify AGENTS.md NOR create directories). If received yes answer, follow steps belows.
+
+1. If AGENTS.md not found in WORKING DIR, create an empty AGENTS.md.
+2. Inspect AGENTS.md content. If you do not see the content block below, APPEND EXACTLY AS IS to end of AGENTS.md.
+3. Check if `./.code/py` exist. If not, create the directories.
+
+Content block:
+
+```md
+## Important note about Python
+
+ALWAYS use the uv package manager available in WORKING DIRECTORY, including `uv add ...` or `uv pip ...` for package management and `uv run ...` to run python package executables.
+
+ALWAYS save python scripts under path `./.code/py/` and run the script with `uv run python ...` whenever your work involves executing python scripts. Your script MUST contain concise docstrings and comments and use good engineering practices including separation of concerns.
+```
+
+### Step 7: Return summary to user (Usage After Setup)
+
+**For Unix-like shells:**
+```bash
+./uv run python your_script.py
+```
+
+**For Windows cmd.exe:**
+```bash
+uv.exe run python your_script.py
+```
+
+## Notes
+- Add `.uv/` and `.venv/` to `.gitignore`
+- `uv run` handles venv activation automatically
+- Use `./uv add <package>` (Unix) or `uv.exe add <package>` (Windows cmd.exe) for project dependencies
+- Windows with Git Bash: Follow Unix-like shell instructions
+- Windows cmd.exe without Admin rights: `uv.exe` is copied instead of symlinked

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeyuan98/opencode-bioresearcher-plugin",
-  "version": "1.3.0-alpha.0",
+  "version": "1.3.0",
   "description": "OpenCode plugin that adds a bioresearcher agent",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -32,6 +32,7 @@
   "dependencies": {
     "@opencode-ai/plugin": "^1.2.6",
     "fast-xml-parser": "^5.3.5",
+    "xdg-basedir": "^5.1.0",
     "xlsx": "^0.18.5",
     "zod": "^4.1.8"
   },