Agent Skill Loader 🧠

Agent Skill Loader는 정적 Claude Code 스킬 라이브러리와 동적 AI 에이전트(Claude Desktop, Cursor 또는 기타 MCP 클라이언트) 사이의 가교 역할을 하는 MCP(Model Context Protocol) 서버입니다.

이 서버는 스킬을 MCP 프롬프트(슬래시 명령, 도구 호출 불필요)와 MCP 도구(프로그래밍 방식 사용)로 모두 노출합니다. 스킬은 구성된 디렉토리에서 자동으로 검색되며 실시간으로 유지됩니다. 새로운 SKILL.md를 추가하면 클라이언트에 자동으로 알림이 전송됩니다.

🚀 주요 기능

• MCP 프롬프트: 스킬이 클라이언트에서 슬래시 명령으로 나타납니다. 주입을 위해 도구를 호출할 필요가 없습니다.

• 실시간 업데이트: 스킬이 추가되거나 제거되면(파일 감시자를 통해) listChanged 알림이 발생합니다.

• 검색: list_skills — 구성된 스킬 디렉토리를 스캔하며, 선택적으로 검색 필터를 사용할 수 있습니다.

• 동적 학습: read_skill — SKILL.md 콘텐츠를 가져옵니다.

• 영구 저장: install_skill — 스킬을 프로젝트에 영구적으로 복사합니다.

• 구성: manage_search_paths — 런타임에 스킬 디렉토리를 추가/제거합니다.

• 문제 해결: debug_info — 구성 및 경로 문제를 진단합니다.

🛠️ 설정

사전 요구 사항

• Node.js >= 18

옵션 A: npm에서 설치 (권장)

npm install -g agent-skill-loader

그런 다음 .mcp.json에 등록합니다:

"agent-skill-loader": {
  "command": "agent-skill-loader"
}

옵션 B: 소스에서 빌드

git clone https://github.com/back1ply/agent-skill-loader.git
cd agent-skill-loader
npm install
npm run build

그런 다음 .mcp.json에 등록합니다:

"agent-skill-loader": {
  "command": "node",
  "args": ["<path-to-repo>/build/index.js"]
}

📂 구성

서버는 작업 공간을 자동으로 감지하고 다음 위치에서 스킬 경로를 집계합니다:

1. 기본값: %USERPROFILE%\.claude\plugins\cache (표준 위치)

2. 동적 구성: skill-paths.json (프로젝트 루트에 위치)

환경 변수

동적 경로 관리

구성 파일을 수동으로 편집할 필요가 없습니다. 도구를 사용하여 런타임에 경로를 관리하세요:

• 추가: manage_search_paths(operation="add", path="F:\\My\\Deep\\Skills")

• 제거: manage_search_paths(operation="remove", path="...")

• 목록: manage_search_paths(operation="list")는 skill-paths.json을 생성/업데이트합니다.

🤖 사용법

MCP 프롬프트 (슬래시 명령)

클라이언트가 MCP 프롬프트를 지원하는 경우(Claude Desktop, Cursor 등), 스킬이 슬래시 명령으로 자동 나타납니다. 슬래시 명령 메뉴에서 스킬을 선택하여 콘텐츠를 직접 주입하세요. 도구 호출이 필요하지 않습니다.

도구

에이전트는 다음 5가지 도구에 액세스할 수 있습니다:

• list_skills(query?): 사용 가능한 스킬의 JSON 목록을 반환합니다. 선택적 query는 이름/설명 하위 문자열로 필터링합니다(대소문자 구분 안 함).

• read_skill(skill_name): 스킬에 대한 마크다운 지침을 반환합니다.

• install_skill(skill_name, target_path?): 스킬 폴더를 .agent/skills/<name>으로 복사합니다. 보안을 위해 target_path는 현재 작업 공간 내에 있어야 합니다.

• manage_search_paths(operation, path?): 스킬 검색 경로를 추가, 제거 또는 나열합니다.

• debug_info(): 진단 정보(경로, 상태, 경고)를 반환합니다.

에이전트 프롬프트 예시

"DAX 측정값을 작성해야 하는데 모범 사례를 잘 모르겠어."

에이전트가 자동으로 list_skills를 호출하고 writing-dax-measures를 찾아 read_skill을 호출한 다음 전문가 지식으로 답변합니다. 또는 사용자가 슬래시 명령으로 직접 스킬을 호출할 수도 있습니다.

🔧 문제 해결

스킬이 검색되지 않으면 debug_info()를 사용하여 다음을 확인하세요:

• search_paths: 스캔 중인 디렉토리

• path_status: 각 경로의 존재 여부 및 읽기 가능 여부

• warnings: 스캔 중 발생한 오류(권한 거부, 빈 파일 등)

출력 예시:

{
  "workspace_root": "C:/projects/agent-skill-loader",
  "search_paths": {
    "base": ["C:/Users/pc/.claude/plugins/cache"],
    "dynamic": ["F:/My/Skills"],
    "effective": ["C:/Users/pc/.claude/plugins/cache", "F:/My/Skills"]
  },
  "path_status": [
    { "path": "C:/Users/pc/.claude/plugins/cache", "exists": true, "readable": true },
    { "path": "F:/My/Skills", "exists": false, "readable": false }
  ],
  "skills_found": 12,
  "warnings": [
    { "path": "F:/My/Skills", "reason": "Directory does not exist" }
  ]
}

📦 프로젝트 구조

• src/index.ts: 메인 서버 로직 (도구 + 프롬프트 + 감시자).

• src/utils.ts: 스킬 스캔, 설명 추출, 프롬프트 도우미, 디바운스.

• build/: 컴파일된 JavaScript 출력.

• package.json: 종속성 (@modelcontextprotocol/sdk, chokidar, zod).

🤝 기여

새로운 스킬을 추가하려면 감시 중인 디렉토리 중 하나에 SKILL.md 파일이 포함된 폴더를 추가하세요. 서버가 자동으로 이를 감지하고 listChanged 알림을 보냅니다. 재시작은 필요하지 않습니다.