auto-skill-loader

为你的 AI 代理提供一个持久的技能库，在会话启动时自动加载。

OpenCode 图片说明： OpenCode 在粘贴图片时还无法暴露真实的文件路径——代理看到的是文件名而非路径。解决办法：给代理一个真实的文件路径而不是粘贴图片。技能会在会话启动时按预期自动加载。

mcp-name: io.github.divitkashyap/auto-skill-loader

工作原理

1. 你配置 要在 ~/.config/auto-skill-loader/config.yaml 中自动加载哪些技能

2. MCP 服务器 从你的技能目录读取技能文件，并通过 skills://active 暴露它们

3. 在会话启动时 你的代理读取 skills://active，所有已批准的技能自动注入

4. 无需显式触发 —— 代理已经知道你的技能

Related MCP server: hermes-mcp-server

为什么

主要问题：在 OpenCode 中，技能不会自动加载——代理必须显式调用它们或依赖不可靠的模糊匹配。auto-skill-loader 通过将你的技能库暴露为 MCP 资源并在会话启动时读取来解决这个问题。确定性，无需猜测。

额外好处： 我们的代理工具还绕过了 OpenCode 对 MiniMax 视觉和网络搜索工具损坏的 MCP stdio 传输。

安装

选项 1：uvx（推荐——无需安装）

uvx auto-skill-loader

选项 2：pip

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

选项 3：从源码构建

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

配置

OpenCode

添加到 ~/.config/opencode/opencode.json：

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

Claude Code

注意： Claude Code 需要通过 add-json 使用特定的 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"}}'

将 /FULL/PATH/TO/python 替换为你的 Python 路径（例如 /Users/YOU/auto-skill-loader/.venv/bin/python）。

或者使用 uvx（首次运行需要网络）：

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

已测试环境

技能自动加载已在两个宿主上确认可用。 视觉代理绕过了 OpenCode 损坏的 stdio 传输，但图片粘贴到路径是 OpenCode 中一个独立的渲染问题，需要使用文件路径。

其他兼容 MCP 的宿主（Cursor、Zed 等）应可使用相同的配置——欢迎贡献。

平台差异与已知问题

图片输入：OpenCode vs Claude Code

两个宿主都可以使用 auto-skill-loader 视觉工具，但图片输入的行为不同：

OpenCode 说明： 当你在 OpenCode 中粘贴图片时，它可能会内联渲染，但代理看到的是文件名字符串（例如 logo.png）而不是真实的文件系统路径。这是 OpenCode 已知的渲染行为。

OpenCode 的解决办法： 不要粘贴，而是给代理真实的文件路径：

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

代理在 OpenCode 中可以直接访问本地文件。如果图片只在你的剪贴板中，代理可以先将它提取到 /tmp/。

我们正在关注的内容

我们积极跟踪以下 OpenCode 问题：

• 内联图片渲染（粘贴的图片不会向工具暴露真实路径）

• 本地服务器的 MCP stdio 传输（我们的代理工具绕过了这个问题）

• 技能在重启后的会话持久性

如果 OpenCode 发布了内联图片路径的修复，本文档和 vision-analysis 技能将更新以支持直接粘贴工作流。我们关注 OpenCode 的变更日志和发布说明——请查看此仓库获取更新。

其他已知问题

设置

1. 创建技能目录（符号链接到你的现有技能）：

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

2. 编辑 ~/.config/auto-skill-loader/config.yaml：

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

3. 重启你的代理。它现在会在会话启动时自动加载所有列出的技能。

工具

额外功能：MiniMax 视觉与网络搜索代理

auto-skill-loader 还暴露了两个代理到 minimax-coding-plan-mcp 的工具，使用可用的 stdio 传输：

注意： 对于视觉功能，mmx-cli 现在是推荐方法——它是对 MiniMax VLM 的直接 REST 调用，没有 MCP 传输问题，并且原生支持 URL。如果你想要一个统一的 MCP 接口来同时处理技能加载和视觉功能，这些代理工具会很有用。

OpenCode MCP 缺陷

当 OpenCode 内置的 minimax-coding-plan-mcp MCP 集成（minimax-token-plan）被配置时，understand_image 工具会失败并报错：

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

即使以下情况也会发生：

• ✅ MINIMAX_API_KEY / MINIMAX_TOKEN_PLAN_KEY 设置正确

• ✅ API 密钥有效（相同的密钥通过直接 API 调用可以正常工作）

• ✅ Token Plan 有可用的视觉配额

根本原因： OpenCode 对本地 MCP 服务器的 stdio 传输在发送消息时破坏了 MCP 协议——很可能是批量写入时没有在 JSON-RPC 消息之间正确刷新。使用顺序写入 + flush() 的直接子进程测试可以正常工作。

解决方案： auto-skill-loader 中的代理工具使用正确的顺序 stdio 通信，绕过了 OpenCode 损坏的传输层。

设置

1. 在 ~/.config/opencode/.env 中设置你的 MiniMax Token Plan 密钥：

MINIMAX_TOKEN_PLAN_KEY=sk-cp-your-key-here

2. 将 auto-skill-loader 添加到 ~/.config/opencode/opencode.json：

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

3. 关键： 如果你在 opencode.json 中直接配置了 minimax-coding-plan-mcp（minimax-token-plan 条目），请移除或禁用它——其损坏的 stdio 传输会导致 "login fail" 错误。auto-skill-loader 中的代理工具完全替代了它。

4. 重启 OpenCode 并验证：/ask Do you have auto-skill-loader_minimax_understand_image available?

诊断

如果在设置后看到 "login fail" 错误：

1. 禁用损坏的 minimax MCP —— 确保 "minimax-token-plan": { "enabled": false } 或完全移除它

2. 完全重启 OpenCode —— MCP 服务器会在每个会话中重新生成

3. 检查方式： /ask Call minimax_understand_image with image_source="/any/real/image.png" and prompt="test"

资源

安全性

• 用户控制 —— 只加载 config.yaml 中的技能

• 无网络获取 —— 一切都是本地的

• 无提示注入 —— 技能来自你自己配置的目录

仓库结构

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

要求

• Python 3.9+

• mcp 包（pip install mcp）

• pyyaml 包（pip install pyyaml）

或者直接使用 uvx auto-skill-loader，它会自动获取依赖项。