{
  "markdown": "# auto-skill-loader\n\n**Give your AI agent a persistent skill library it auto-loads at session start.**\n\n> **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.\n\n`mcp-name: io.github.divitkashyap/auto-skill-loader`\n\n## How it works\n\n1. **You configure** which skills to auto-load in `~/.config/auto-skill-loader/config.yaml`\n2. **The MCP server** reads skill files from your skills directory and exposes them via `skills://active`\n3. **At session start** your agent reads `skills://active` and gets all approved skills auto-injected\n4. **No explicit triggers needed** — the agent already knows your skills\n\n## Why\n\nThe 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.\n\n**Bonus:** Our proxy tools also work around OpenCode's broken MCP stdio transport for the MiniMax vision and web search tools.\n\n## Installation\n\n### Option 1: uvx (recommended — no install needed)\n\n```bash\nuvx auto-skill-loader\n```\n\n### Option 2: pip\n\n```bash\npip install auto-skill-loader\nauto-skill-loader\n```\n\n### Option 3: Build from source\n\n```bash\ngit clone https://github.com/divitkashyap/auto-skill-loader.git\ncd auto-skill-loader\npip install -e .\nauto-skill-loader\n```\n\n## Configuration\n\n### OpenCode\n\nAdd to `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"mcp\": {\n    \"auto-skill-loader\": {\n      \"type\": \"local\",\n      \"command\": [\"uvx\", \"auto-skill-loader\"],\n      \"enabled\": true\n    }\n  }\n}\n```\n\n### Claude Code\n\n**Note:** Claude Code requires a specific JSON format via `add-json`:\n\n```bash\nclaude 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\"}}'\n```\n\nReplace `/FULL/PATH/TO/python` with the path to your Python (e.g. `/Users/YOU/auto-skill-loader/.venv/bin/python`).\n\nOr for uvx (requires network on first run):\n\n```bash\nclaude mcp add -s user --transport stdio -e MINIMAX_TOKEN_PLAN_KEY=sk-cp-YOUR-KEY auto-skill-loader -- uvx auto-skill-loader\n```\n\n## Tested On\n\n| Host | Skill Auto-Load | Vision Proxy | Image Paste | Notes |\n|---|---|---|---|---|\n| Claude Code (macOS) | ✅ | ❌ Not needed | ✅ | Use `minimax-token-plan` MCP directly instead |\n| OpenCode (macOS) | ✅ | ✅ Works | ❌ Broken | Give file paths instead of pasting |\n\n**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.\n\nOther MCP-compatible hosts (Cursor, Zed, etc.) should work with the same configuration — contributions welcome.\n\n## Platform Differences & Known Issues\n\n### Image Input: OpenCode vs Claude Code\n\nBoth hosts work with `auto-skill-loader` vision tools, but image input behaves differently:\n\n| Host | How images are passed | Recommended workflow |\n|---|---|---|\n| **Claude Code** | Images uploaded to URL automatically → tool receives URL | Paste image directly ✅ works |\n| **OpenCode** | Inline images render visually but may not give tools a real path | Give a file path instead of pasting |\n\n**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.\n\n**Workaround for OpenCode:** Instead of pasting, give the agent the actual file path:\n```\nanalyze this image: /path/to/your/image.png\n```\n\nThe agent can access local files directly in OpenCode. If the image is only in your clipboard, the agent can extract it to `/tmp/` first.\n\n### What We're Monitoring\n\nWe actively track the following OpenCode issues:\n- Inline image rendering (images pasted don't expose real paths to tools)\n- MCP stdio transport for local servers (our proxy tools work around this)\n- Session persistence of skills across restarts\n\nIf 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.\n\n### Other Known Issues\n\n| Issue | Severity | Workaround |\n|---|---|---|\n| OpenCode inline images show as filename, not path | Medium — affects paste workflow | Use file paths instead |\n| Claude Code auth conflict (ANTHROPIC_AUTH_TOKEN vs managed key) | Low — cosmetic warning | Harmless, can be ignored |\n| First vision call may take 3-5s (uvx download) | Low — one-time | Subsequent calls are ~200ms |\n\n## Setup\n\n1. Create skills directory (symlink to your existing skills):\n\n```bash\nmkdir -p ~/.config/auto-skill-loader\nln -sf ~/.config/opencode/skills ~/.config/auto-skill-loader/skills\n```\n\n2. Edit `~/.config/auto-skill-loader/config.yaml`:\n\n```yaml\nactive_skills:\n  - vision-analysis\n  - context-maintainer\n  - markdown-mcp\nskills_dir: ~/.config/auto-skill-loader/skills\n```\n\n3. Restart your agent. It will now auto-load all listed skills at session start.\n\n## Tools\n\n| Tool | What it does |\n|---|---|\n| `list_skills` | List all available skills in skills_dir with descriptions |\n| `activate_skill` | Add a skill to your approved list (persists to config.yaml) |\n| `deactivate_skill` | Remove a skill from your approved list |\n| `get_skill_info` | Get details about a specific skill |\n| `get_active_skills` | List currently active skill names |\n| `suggest_skills` | If no skills are active, suggests common ones to get started |\n| `check_prerequisites` | Validate a skill's dependencies (MCP tools, API keys, env vars) |\n\n## Bonus: MiniMax Vision & Web Search Proxy\n\nauto-skill-loader also exposes two tools that proxy to `minimax-coding-plan-mcp` with a **working stdio transport**:\n\n| Tool | What it does |\n|---|---|\n| `minimax_understand_image` | Analyze images (JPEG, PNG, GIF, WebP up to 20MB) |\n| `minimax_web_search` | Web search using MiniMax |\n\n**Note:** For vision specifically, [mmx-cli](https://github.com/MiniMax-AI/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.\n\n### The OpenCode MCP Bug\n\nWhen OpenCode's built-in `minimax-coding-plan-mcp` MCP integration (`minimax-token-plan`) is configured, the `understand_image` tool fails with:\n\n```\nAPI Error: login fail: Please carry the API secret key in the 'Authorization' field\n```\n\nThis happens even when:\n- ✅ `MINIMAX_API_KEY` / `MINIMAX_TOKEN_PLAN_KEY` is set correctly\n- ✅ API key is valid (same key works via direct API calls)\n- ✅ Token Plan has available vision quota\n\n**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.\n\n**The fix:** Our proxy tools in auto-skill-loader use proper sequential stdio communication, bypassing OpenCode's broken transport layer.\n\n### Setup\n\n1. Set your MiniMax Token Plan key in `~/.config/opencode/.env`:\n```bash\nMINIMAX_TOKEN_PLAN_KEY=sk-cp-your-key-here\n```\n\n2. Add auto-skill-loader to `~/.config/opencode/opencode.json`:\n```json\n{\n  \"mcp\": {\n    \"auto-skill-loader\": {\n      \"type\": \"local\",\n      \"command\": [\"/path/to/venv/bin/python\", \"-m\", \"server\"],\n      \"enabled\": true\n    }\n  }\n}\n```\n\n3. **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.\n\n4. Restart OpenCode and verify: `/ask Do you have auto-skill-loader_minimax_understand_image available?`\n\n### Diagnosis\n\nIf you see \"login fail\" errors after setup:\n\n1. **Disable the broken minimax MCP** — ensure `\"minimax-token-plan\": { \"enabled\": false }` or remove it entirely\n2. **Restart OpenCode completely** — MCP servers are re-spawned on each session\n3. **Check with:** `/ask Call minimax_understand_image with image_source=\"/any/real/image.png\" and prompt=\"test\"`\n\n## Resources\n\n| Resource | What it does |\n|---|---|\n| `skills://active` | All approved skill contents concatenated — read by host at session init |\n| `skills://config` | Your current config.yaml content |\n\n## Security\n\n- **User-controlled** — only skills in `config.yaml` are loaded\n- **No network fetches** — everything is local\n- **No prompt injection** — skills come from your own configured directory\n\n## Repo Structure\n\n```\nauto-skill-loader/\n├── src/\n│   └── server.py        # MCP server (Python stdlib + mcp package)\n├── pyproject.toml       # Package config\n├── README.md            # This file\n├── SKILL.md             # For agent onboarding\n└── LICENSE              # MIT\n```\n\n## Requirements\n\n- Python 3.9+\n- `mcp` package (`pip install mcp`)\n- `pyyaml` package (`pip install pyyaml`)\n\nOr just use `uvx auto-skill-loader` which fetches dependencies automatically.",
  "bytes": 9369,
  "sha": "95d64aa9bb27299a741b9f28b8c8e347ddd82c029328cd79a18a6d1a7de15b88",
  "repo_slug": "divitkashyap/auto-skill-loader",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_divitkashyap_auto_skill_loader_56b8857d/readme"
}