skills-compat-manager: AI 에이전트의 스킬 실행 오류 방지 도구

AI 에이전트가 스킬 실행 도중 중단되는 현상을 방지하세요.

사전 점검(pre-flight check) 기능이 내장된, 모든 에이전트 스킬을 위한 단일 라이브러리입니다.

Quick Start · 작동 원리 · CLI · MCP Server · 中文文档

여러분은 수많은 AI 에이전트 스킬을 직접 만들거나 다운로드했습니다. 이 스킬들은 여러분의 로컬 환경에서는 잘 작동하지만, 어느 순간 작동하지 않게 됩니다.

"Claude Code에서는 작동했는데 Cursor에서는 실행할 수 없습니다."
"에이전트가 작업을 시작하더니 ModuleNotFoundError: pandas 오류와 함께 멈췄습니다."
"로컬에 OPENAI_API_KEY를 설정했는데도 에이전트가 빈 문자열을 반환합니다."

Skills Compat Manager는 다음 두 가지 단계로 이 문제를 해결합니다:

🗂️ 하나의 라이브러리로 모든 에이전트 대응. 스킬들을 하나의 폴더에 담으세요. Claude Code, Cursor, Codex CLI, OpenCode 모두 MCP를 통해 동일한 위치에서 스킬을 읽어옵니다. 더 이상 도구 설정(tool configs)마다 스킬을 일일이 복사해서 붙여넣을 필요가 없습니다.

🛡️ 실행 전 사전 점검(Pre-flight check). 에이전트가 스킬을 로드할 때마다, 선언된 의존성(패키지 · CLI 도구 · 환경 변수 · 플랫폼 기능)을 기준으로 환경을 스캔하고 상단에 **강력한 호환성 프로토콜(hard compatibility protocol)**을 주입합니다. pandas가 누락되었나요?
에이전트는 10,000개의 토큰을 낭비하기 전에 멈춰서 질문합니다.

이것을 AI 에이전트 스킬을 위한 package.json + lockfile 검사기라고 생각하세요.

Agent: loading skill "pdf-tools" via MCP...
⚠ COMPATIBILITY DELTA — pdf-tools @ claude_code
Status: BLOCKED
...

에이전트는 코드 한 줄을 작성하기 전에 무엇이 누락되었는지 알게 됩니다.

지원하는 기능 (Does)

Python 패키지, CLI 바이너리, 환경 변수 및 선언된 플랫폼 기능의 존재 여부 감지
구조화된 Delta를 통해 스킬 실행 전에 누락된 의존성을 에이전트에게 노출
표준화된, 에이전트가 읽을 수 있는 호환성 프로토콜(OK / DEGRADED / BLOCKED) 제공
AI 추론 또는 정적 규칙을 통한 COMPAT.yaml 생성

지원하지 않는 기능 (Doesn't (yet))

COMPAT.yaml에 명시적으로 선언되지 않은 경우 패키지 버전 검증
API 키가 유효한지, 활성 상태인지, 또는 남은 할당량(quota)이 있는지 확인
플랫폼 기능의 런타임 테스트(Runtime-test) — 플랫폼이 선언한 성능(caps)을 신뢰함
규정을 준수하지 않는 에이전트가 호환성 블록(compatibility block)을 무시하는 것을 방지

이것은 샌드박스(sandbox)가 아니라, **엄격한 프로토콜을 가진 권고 계층(advisory layer with a hard protocol)**입니다.

AI 에이전트의 "스킬(skills)"은 에이전트에게 작업을 수행하는 방법(예: PDF 파싱, Obsidian 보관함 관리, 프론트엔드 디자인 생성)을 알려주는 재사용 가능한 지침 파일(SKILL.md)입니다.

스킬은 항상 존재하지 않는 요소들에 암묵적으로 의존할 수 있습니다:

차원 (Dimension)	예시 (Example)	발생하는 문제 (What goes wrong)
Python 패키지 (Python packages)	`pandas`, `python-docx`	작업 도중 `ModuleNotFoundError` 발생
CLI 도구 (CLI tools)	`pdftotext`, `ffmpeg`	에이전트가 존재하지 않는 명령어를 생성함
환경 변수 (Env variables)	`VAULT_PATH`, `OPENAI_API_KEY`	빈 문자열로 조용히 대체(fallback)되어 출력이 손상됨
플랫폼 기능 (Platform capabilities)	`bash`, `web_search`	에이전트가 플랫폼에 없는 도구를 사용하려고 시도함

사전 점검(pre-flight check) 없이는 에이전트가 스킬을 로드하고 작업을 시작했다가 중간에 실패하게 되며, 이는 토큰, 시간, 그리고 사용자의 신뢰를 낭비하게 만듭니다.

Skills Compat Manager는 에이전트가 스킬을 실행하기 전에 스킬을 스캔하고, 구조화된 **델타(Delta, 차이 분석)**를 계산하여 로드 시점에 스킬 내용에 주입합니다.

┌─────────────────────────────────┐
│ 에이전트가 MCP를 통해 "pdf" 스킬을 로드함 │
└────────────────┬────────────────┘
...

이제 에이전트는 코드 한 줄을 작성하기 전에 무엇이 누락되었는지 알게 됩니다.

모든 스킬의 의존성은 네 가지 차원으로 분류됩니다.

COMPAT.yaml 예시:

schema_version: "2.0"
requires:
code_deps:
...

이것을 직접 작성하고 싶지 않으신가요?

skills-compat infer <skill>을 실행하면 AI가 SKILL.md로부터 이를 생성합니다.

pip install git+https://github.com/hnaymyh123-henry/skills-compat-manager.git
# 선택 사항: AI 기반 COMPAT.yaml 추론 활성화
pip install "git+https://github.com/hnaymyh123-henry/skills-compat-manager.git#egg=skills-compat[ai]"

# 설치된 플랫폼(Claude Code, Cursor 등)을 자동 감지하고
# MCP 서버 항목을 구성합니다.
skills-compat setup --skill-library ~/my-skills

# 단일 스킬을 스캔합니다.
skills-compat scan pdf
# 라이브러리의 모든 스킬을 스캔합니다.
...

# AI가 SKILL.md를 분석하여 COMPAT.yaml을 생성하도록 합니다.
skills-compat infer my-skill
# 아직 COMPAT.yaml이 없는 모든 스킬에 대해 추론을 수행합니다.
...

MCP 서버는 주요 런타임 인터페이스(runtime interface)입니다. 에이전트가 get_skill을 호출하면:

원본 SKILL.md 내용을 읽습니다 (Reads)
런타임 환경(설치된 패키지, CLI 도구, 환경 변수)을 스캔합니다 (Scans)
플랫폼의 기능 프로필(capability profile)과 비교하여 델타(Delta)를 계산합니다 (Computes)
스킬 내용 상단에 델타 블록을 주입합니다 (Injects)
증강된(augmented) 내용을 에이전트에게 반환합니다 (Returns)

에이전트는 스킬 지침이 시작되기 전에 호환성 상태를 확인하며, 어떻게 진행할지 결정할 수 있습니다.

CLI는 설정 및 진단 도구입니다:

skills-compat setup → 플랫폼 자동 감지, MCP 구성
skills-compat status → 라이브러리 상태 개요
skills-compat scan → 델타(Delta) 분석 실행, 누락된 요소 확인
...

verify는 종료 코드(exit code) 0 (OK), 1 (DEGRADED), 2 (BLOCKED), 3 (UNSCANNED), 또는 4 (error)를 반환합니다. skills-compat verify pdf && deploy와 같이 CI(지속적 통합) 환경에 적용해 보세요.

fix는 루프를 완성합니다. 누락된 종속성(dependency)마다 LLM에 2~3가지 해결 경로를 요청하며(각 경로는 SAFE/MANUAL + agent_or_user/user_only로 태그됨), SAFE 경로를 샌드박스 허용 목록(sandbox allowlist)을 통해 실행한 후, 재스캔을 수행하고 상태 전이(예: BLOCKED → DEGRADED)를 출력합니다. CI를 위해서는 --auto를, 확인 프롬프트를 건너뛰려면 --yes를 사용하세요.

MCP 클라이언트 설정에 다음을 추가하세요:

Claude Code (~/.claude/settings.json):

{
"mcpServers": {
"skills-compat": {
...

Cursor (.cursor/mcp.json):

{
"mcpServers": {
"skills-compat": {
...

또는 CLI가 자동으로 수행하도록 할 수 있습니다:

skills-compat setup --skill-library /path/to/your/skills

도구 (Tool)	설명 (Description)
`list_skills`	라이브러리의 모든 스킬 (skills) 목록 나열
`get_skill`	Delta 블록이 주입된 스킬 콘텐츠 로드
`scan_skills`	모든 스킬에 대해 호환성 스캔 (compatibility scan) 실행
`get_skill_info`	스킬의 메타데이터 및 COMPAT.yaml 가져오기
`search_skills`	키워드로 스킬 검색
`suggest_fix`	AI 기반 수정 제안 가져오기 (각 경로는 actor + safety 태그가 지정됨)
`apply_fix`	샌드박스 허용 목록 (sandbox allowlist)을 통해 안전한 (SAFE) 수정 명령을 실행한 후 재스캔
`refresh_runtime`	런타임 (runtime) 환경 재감지

플랫폼 (Platform)	기능 (Capabilities)	신뢰도 (Confidence)	자동 감지 (Auto-detected)
Claude Code	`bash` `file_read` `file_write` `web_search` `web_fetch` `python_runtime` `lsp` `notebook` `subagent` `monitor`	verified	✓
Cursor	`bash` `file_read` `file_write` `web_search`	partial	✓
Codex CLI	`bash` `file_read` `file_write` `python_runtime`	verified	✓
OpenCode	`bash` `file_read` `file_write` `web_search` `web_fetch` `python_runtime` `lsp`	verified	✓
Claude Desktop	`file_read` `file_write`	partial	✓

신뢰도 (Confidence) 수준은 기능 목록이 공식 문서와 얼마나 잘 검증되었는지를 반영합니다 (verified = 공식 문서 기반, partial = 문서가 불완전하거나 접근 불가능, unverified = 최선의 추정치). 출처 및 검증 날짜는 data/platform_profiles.yaml을 참조하세요.

알아두면 좋은 몇 가지 플랫폼별 참고 사항: Codex CLI는 모든 샌드박스 모드에서 기본적으로 네트워크가 차단되어 있어 내장된 web_search 기능이 없습니다. Claude Desktop의 기본 도구 세트는 최소한입니다. 대부분의 기능(web, shell, 전체 파일 시스템)은 내장 기능이 아니라 사용자가 설치한 MCP 서버를 통해 제공됩니다.

플랫폼 감지는 MCP 핸드셰이크 (clientInfo.name)를 통해 자동으로 수행되므로 수동 설정이 필요하지 않습니다. 새로운 플랫폼을 추가하려면 data/platform_profiles.yaml을 편집하기만 하면 됩니다. 만약 사용 중인 에이전트 플랫폼이 capabilities.experimental["skills-compat:platform-tools"]를 통한 자가 보고 (self-reporting)를 지원한다면

MCP initialize 핸드셰이크 (handshake) 과정에서, 해당 기능들은 직접적으로 사용되며 정적 프로필 (static profile)보다 우선순위를 갖습니다.

COMPAT.yaml 추론 (inference)은 자동 폴백 (fallback) 기능이 포함된 세 가지 제공자 (provider)를 지원합니다:

OpenAI (gpt-4o) → Anthropic Claude → 규칙 기반 (Rules-based, API 키 불필요)

AI는 사용자의 SKILL.md 내용을 분석하여 다음과 같은 요소가 포함된 완전한 COMPAT.yaml을 생성합니다:

표준 라이브러리 필터링 (stdlib filtering)— Python 표준 라이브러리 모듈은 자동으로 제외됩니다.
PyPI 이름 해석 (PyPI name resolution)— 임포트 (import) 이름이 정확한 pip 패키지 이름으로 매핑됩니다 (yaml → pyyaml, cv2 → opencv-python).
필수/선택 분류 (required/optional classification)— 각 의존성 (dependency)은 스킬 내에서의 역할을 바탕으로 필수 (required) 또는 선택 (optional) 사항으로 판단됩니다.

스캐너 (scanner)가 누락된 의존성을 발견하면, suggest_fix가 2~3개의 실행 가능한 해결 경로 (solution paths)를 생성합니다. 모든 경로는 두 가지 축을 기준으로 분류되어 에이전트가 자율적으로 무엇을 할 수 있는지 정확히 알 수 있게 합니다:

경로 A: 설치 [SAFE · agent_or_user · low effort]
→ pip install camelot-py
경로 B: 대체 라이브러리 사용 [MANUAL · user_only · medium effort]
...

SAFE + agent_or_user → 에이전트는 허용 목록 (allowlist: pip, npm, yarn, mkdir, touch) 및 엄격한 차단 목록 (denylist: sudo, rm, |sh, >/etc, &&rm 등)을 준수하는 범위 내에서 apply_fix (또는 skills-compat fix --auto)를 통해 이를 실행할 수 있습니다.
MANUAL 또는 user_only → 에이전트는 명령어를 사람에게 제시할 뿐, 절대 직접 실행하지 않습니다.

skills-compat-manager/
├── app/
│ ├── cli.py # CLI 진입점 (9개 명령어)
...

skills-compat-manager: AI 에이전트의 스킬 실행 오류 방지 도구

요약

핵심 포인트

댓글