auto-skill-loader

auto-skill-loader

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

How it works

1. You configure which skills to auto-load in ~/.config/auto-skill-loader/config.yaml
2. The MCP server reads skill files from your skills directory and exposes them via skills://active
3. At session start your agent reads skills://active and gets all approved skills auto-injected
4. No explicit triggers needed — the agent already knows your skills

Why

The 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.

Installation

Option 1: uvx (recommended — no install needed)

uvx auto-skill-loader

Option 2: pip

pip install auto-skill-loader
auto-skill-loader

Option 3: Build from source

git clone https://github.com/divitkashyap/auto-skill-loader.git
cd auto-skill-loader
pip install -e .
auto-skill-loader

Configuration

OpenCode

Add to ~/.config/opencode/opencode.json:

{
  "mcp": {
    "auto-skill-loader": {
      "type": "local",
      "command": ["uvx", "auto-skill-loader"],
      "enabled": true
    }
  }
}

Claude Code

Note: Claude Code requires a specific JSON format via add-json:

claude mcp add-json -s user auto-skill-loader '{"type":"stdio","command":"/FULL/PATH/TO/python","args":["-m","server"],"env":{"MINIMAX_TOKEN_PLAN_KEY":"sk-cp-YOUR-KEY-HERE"}}'

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):

claude mcp add -s user --transport stdio -e MINIMAX_TOKEN_PLAN_KEY=sk-cp-YOUR-KEY auto-skill-loader -- uvx auto-skill-loader

Tested On

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.

Platform Differences & Known Issues

Image Input: OpenCode vs Claude Code

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:

analyze this image: /path/to/your/image.png

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.

What We're Monitoring

We actively track the following OpenCode issues:

• Inline image rendering (images pasted don't expose real paths to tools)
• MCP stdio transport for local servers (our proxy tools work around this)
• Session persistence of skills across restarts

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.

Other Known Issues

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

Setup

1. Create skills directory (symlink to your existing skills):

mkdir -p ~/.config/auto-skill-loader
ln -sf ~/.config/opencode/skills ~/.config/auto-skill-loader/skills

2. Edit ~/.config/auto-skill-loader/config.yaml:

active_skills:
  - vision-analysis
  - context-maintainer
  - markdown-mcp
skills_dir: ~/.config/auto-skill-loader/skills

3. Restart your agent. It will now auto-load all listed skills at session start.

Tools

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)

Bonus: MiniMax Vision & Web Search Proxy

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.

The OpenCode MCP Bug

When OpenCode's built-in minimax-coding-plan-mcp MCP integration (minimax-token-plan) is configured, the understand_image tool fails with:

API Error: login fail: Please carry the API secret key in the 'Authorization' field

This happens even when:

• ✅ MINIMAX_API_KEY / MINIMAX_TOKEN_PLAN_KEY is set correctly
• ✅ API key is valid (same key works via direct API calls)
• ✅ Token Plan has available vision quota

Root 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.

Setup

1. Set your MiniMax Token Plan key in ~/.config/opencode/.env:

MINIMAX_TOKEN_PLAN_KEY=sk-cp-your-key-here

2. Add auto-skill-loader to ~/.config/opencode/opencode.json:

{
  "mcp": {
    "auto-skill-loader": {
      "type": "local",
      "command": ["/path/to/venv/bin/python", "-m", "server"],
      "enabled": true
    }
  }
}

3. 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.

4. Restart OpenCode and verify: /ask Do you have auto-skill-loader_minimax_understand_image available?

Diagnosis

If you see "login fail" errors after setup:

1. Disable the broken minimax MCP — ensure "minimax-token-plan": { "enabled": false } or remove it entirely
2. Restart OpenCode completely — MCP servers are re-spawned on each session
3. Check with: /ask Call minimax_understand_image with image_source="/any/real/image.png" and prompt="test"

Resources

Resource	What it does
skills://active	All approved skill contents concatenated — read by host at session init
skills://config	Your current config.yaml content

Security

• User-controlled — only skills in config.yaml are loaded
• No network fetches — everything is local
• No prompt injection — skills come from your own configured directory

Repo Structure

auto-skill-loader/
├── src/
│   └── server.py        # MCP server (Python stdlib + mcp package)
├── pyproject.toml       # Package config
├── README.md            # This file
├── SKILL.md             # For agent onboarding
└── LICENSE              # MIT

Requirements

• Python 3.9+
• mcp package (pip install mcp)
• pyyaml package (pip install pyyaml)

Or just use uvx auto-skill-loader which fetches dependencies automatically.