auto-skill-loader

auto-skill-loader

为你的 AI Agent 提供一个可在会话开始时自动加载的持久技能库。

OpenCode 图片说明： 在 OpenCode 中粘贴图片时，目前不会提供真实文件路径，Agent 看到的只是文件名。解决方法：提供实际文件路径，而不是直接粘贴。技能会按预期在会话开始时自动加载。

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

工作原理

1. 你配置要在 ~/.config/auto-skill-loader/config.yaml 中自动加载的技能
2. MCP 服务从你的技能目录读取技能文件，并通过 skills://active 提供
3. 会话开始时，你的 Agent 会读取 skills://active，并自动注入所有已批准的技能
4. 无需显式触发——Agent 已经了解你的技能

为什么需要

主要问题：在 OpenCode 中，技能不会自动加载——Agent 必须显式调用技能，或者依赖不可靠的模糊匹配。auto-skill-loader 将你的技能库作为 MCP 资源提供，并在会话开始时读取，从而解决了这个问题。确定可靠，无需猜测。

**额外好处：**我们的代理工具还可以绕过 OpenCode 中损坏的 MCP stdio 传输，让 MiniMax 视觉和网页搜索工具正常工作。

安装

选项 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

测试环境

宿主	技能自动加载	视觉代理	粘贴图片	备注
Claude Code（macOS）	✅	❌ 无需使用	✅	请直接使用 minimax-token-plan MCP
OpenCode（macOS）	✅	✅ 可用	❌ 已损坏	提供文件路径，而不是直接粘贴

**已确认技能自动加载在两种宿主上均可正常工作。**视觉代理绕过了 OpenCode 中损坏的 stdio 传输，但粘贴图片转为路径属于 OpenCode 中单独的渲染问题，需要使用文件路径。

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

平台差异与已知问题

图片输入：OpenCode 与 Claude Code

两种宿主都能使用 auto-skill-loader 视觉工具，但图片输入的行为有所不同：

宿主	图片传递方式	推荐工作流
Claude Code	自动将图片上传到 URL → 工具接收 URL	直接粘贴图片 ✅ 可用
OpenCode	行内图片会渲染显示，但可能不会向工具提供真实路径	提供文件路径，而不是直接粘贴

**OpenCode 说明：**在 OpenCode 中粘贴图片时，图片可能会以行内形式渲染，但 Agent 看到的是文件名字符串（例如 logo.png），而不是实际的文件系统路径。这是 OpenCode 已知的渲染行为。

**OpenCode 的解决方法：**不要直接粘贴，而是提供实际文件路径：

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

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

我们正在跟踪的问题

我们会持续跟踪以下 OpenCode 问题：

• 行内图片渲染（粘贴的图片不会向工具提供真实路径）
• 本地服务的 MCP stdio 传输（我们的代理工具可以绕过此问题）
• 重启后技能的会话持久性

如果 OpenCode 发布了修复行内图片路径问题的版本，我们将更新本文档和视觉分析技能，以支持直接粘贴的工作流。我们会关注 OpenCode 的更新日志和发行说明——请查看此代码库以获取更新。

其他已知问题

问题	严重程度	解决方法
OpenCode 内联图片显示为文件名，而非路径	中 — 影响粘贴工作流	改用文件路径
Claude Code 身份验证冲突（ANTHROPIC_AUTH_TOKEN 与托管密钥）	低 — 外观警告	无害，可忽略
首次视觉调用可能需要 3-5 秒（uvx 下载）	低 — 仅一次	后续调用约为 200ms

设置

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. 重启 Agent。现在，它会在会话开始时自动加载所有列出的技能。

工具

工具	功能
list_skills	列出 skills_dir 中所有可用技能及其描述
activate_skill	将技能添加到已批准列表（保存到 config.yaml）
deactivate_skill	从已批准列表中移除技能
get_skill_info	获取特定技能的详细信息
get_active_skills	列出当前已启用的技能名称
suggest_skills	如果没有启用技能，则推荐一些常用技能以供入门
check_prerequisites	验证技能的依赖项（MCP 工具、API 密钥、环境变量）

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

auto-skill-loader 还提供两个代理至 minimax-coding-plan-mcp 的工具，使用可正常工作的 stdio 传输：

工具	功能
minimax_understand_image	分析图片（JPEG、PNG、GIF、WebP，最大 20MB）
minimax_web_search	使用 MiniMax 进行网页搜索

注意： 对于视觉功能，现推荐使用 mmx-cli——它直接通过 REST 调用 MiniMax VLM，没有 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"

资源

资源	功能
skills://active	拼接所有已批准技能的内容——由宿主在会话初始化时读取
skills://config	当前 config.yaml 的内容

安全性

• 由用户控制——仅加载 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 package（pip install mcp）
• pyyaml package（pip install pyyaml）

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