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 리소스로 노출하여 이 문제를 해결합니다. 결정적이며 추측이 필요 없습니다.

보너스: 프록시 도구는 또한 MiniMax 비전 및 웹 검색 도구에 대해 OpenCode의 손상된 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는 또한 작동하는 stdio 전송으로 minimax-coding-plan-mcp에 프록시하는 두 가지 도구를 노출합니다:

참고: 비전의 경우 특히 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. MiniMax Token Plan 키를 ~/.config/opencode/.env에 설정:

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를 사용하세요.