The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Auto Skill Loader listing page.
Give your AI agent a persistent skill library it auto-loads at session start.
OpenCode image note: OpenCode doesn't yet expose real file paths when you paste images — the agent sees a filename instead. Workaround: give the agent an actual file path instead of pasting. Skills auto-load at session start as expected.
mcp-name: io.github.divitkashyap/auto-skill-loader
~/.config/auto-skill-loader/config.yamlskills://activeskills://active and gets all approved skills auto-injectedThe main problem: In OpenCode, skills don't auto-load — the agent has to explicitly invoke them or rely on unreliable fuzzy matching. auto-skill-loader solves this by exposing your skill library as an MCP resource that gets read at session start. Deterministic, no guessing.
Bonus: Our proxy tools also work around OpenCode's broken MCP stdio transport for the MiniMax vision and web search tools.
Add to ~/.config/opencode/opencode.json:
Note: Claude Code requires a specific JSON format via add-json:
Replace /FULL/PATH/TO/python with the path to your Python (e.g. /Users/YOU/auto-skill-loader/.venv/bin/python).
Or for uvx (requires network on first run):
| Host | Skill Auto-Load | Vision Proxy | Image Paste | Notes |
|---|---|---|---|---|
| Claude Code (macOS) | ✅ | ❌ Not needed | ✅ | Use minimax-token-plan MCP directly instead |
| OpenCode (macOS) | ✅ | ✅ Works | ❌ Broken | Give file paths instead of pasting |
Skill auto-loading confirmed working on both hosts. The vision proxy bypasses OpenCode's broken stdio transport, but image paste-to-path is a separate rendering issue in OpenCode that requires using file paths.
Other MCP-compatible hosts (Cursor, Zed, etc.) should work with the same configuration — contributions welcome.
Both hosts work with auto-skill-loader vision tools, but image input behaves differently:
| Host | How images are passed | Recommended workflow |
|---|---|---|
| Claude Code | Images uploaded to URL automatically → tool receives URL | Paste image directly ✅ works |
| OpenCode | Inline images render visually but may not give tools a real path | Give a file path instead of pasting |
OpenCode note: When you paste an image in OpenCode, it may render inline but the agent sees it as a filename string (e.g. logo.png) rather than a real filesystem path. This is a known OpenCode rendering behavior.
Workaround for OpenCode: Instead of pasting, give the agent the actual file path:
The agent can access local files directly in OpenCode. If the image is only in your clipboard, the agent can extract it to /tmp/ first.
We actively track the following OpenCode issues:
If OpenCode releases a fix for inline image paths, this documentation and the vision-analysis skill will be updated to support direct paste workflow. We monitor OpenCode's changelog and release notes — check this repo for updates.
| Issue | Severity | Workaround |
|---|---|---|
| OpenCode inline images show as filename, not path | Medium — affects paste workflow | Use file paths instead |
| Claude Code auth conflict (ANTHROPIC_AUTH_TOKEN vs managed key) | Low — cosmetic warning | Harmless, can be ignored |
| First vision call may take 3-5s (uvx download) | Low — one-time | Subsequent calls are ~200ms |
~/.config/auto-skill-loader/config.yaml:| Tool | What it does |
|---|---|
list_skills | List all available skills in skills_dir with descriptions |
activate_skill | Add a skill to your approved list (persists to config.yaml) |
deactivate_skill | Remove a skill from your approved list |
get_skill_info | Get details about a specific skill |
get_active_skills | List currently active skill names |
suggest_skills | If no skills are active, suggests common ones to get started |
check_prerequisites | Validate a skill's dependencies (MCP tools, API keys, env vars) |
auto-skill-loader also exposes two tools that proxy to minimax-coding-plan-mcp with a working stdio transport:
| Tool | What it does |
|---|---|
minimax_understand_image | Analyze images (JPEG, PNG, GIF, WebP up to 20MB) |
minimax_web_search | Web search using MiniMax |
Note: For vision specifically, mmx-cli is now the recommended approach — it's a direct REST call to MiniMax VLM, no MCP transport issues, and handles URLs natively. These proxy tools are useful if you want a unified MCP interface for both skill loading and vision.
When OpenCode's built-in minimax-coding-plan-mcp MCP integration (minimax-token-plan) is configured, the understand_image tool fails with:
This happens even when:
MINIMAX_API_KEY / MINIMAX_TOKEN_PLAN_KEY is set correctlyRoot cause: OpenCode's stdio transport for local MCP servers sends messages in a way that breaks the MCP protocol — likely batched writes without proper flush between JSON-RPC messages. Direct subprocess tests with sequential writes + flush() work fine.
The fix: Our proxy tools in auto-skill-loader use proper sequential stdio communication, bypassing OpenCode's broken transport layer.
~/.config/opencode/.env:~/.config/opencode/opencode.json:Critical: If you have minimax-coding-plan-mcp configured directly in opencode.json (the minimax-token-plan entry), remove or disable it — its broken stdio transport will cause "login fail" errors. The proxy tools in auto-skill-loader replace it entirely.
Restart OpenCode and verify: /ask Do you have auto-skill-loader_minimax_understand_image available?
If you see "login fail" errors after setup:
"minimax-token-plan": { "enabled": false } or remove it entirely/ask Call minimax_understand_image with image_source="/any/real/image.png" and prompt="test"| Resource | What it does |
|---|---|
skills://active | All approved skill contents concatenated — read by host at session init |
skills://config | Your current config.yaml content |
config.yaml are loadedmcp package (pip install mcp)pyyaml package (pip install pyyaml)Or just use uvx auto-skill-loader which fetches dependencies automatically.