SKM은 GitHub 리포지토리 또는 로컬 디렉터리로부터 글로벌 AI agent의 SKILL을 관리하는 CLI 도구입니다. 이 도구는 리포지토리를 클론하거나 로컬 경로를 링크하고, SKILL.md 파일을 통해 SKILL을 감지하며, YAML config 파일에 기반하여 감지된 SKILL을 agent 디렉터리 (~/.claude/skills/, ~/.codex/skills/ 등)에 심볼릭 링크(symlink)하는 기능을 수행합니다. SKM은 프로젝트 스코프(project-scoped)가 아닌 사용자 레벨(user-level)에서 SKILL을 관리하는 데 중점을 둡니다.

설치 및 기본 작동 방식:
SKM은 uv tool install git+https://github.com/reorx/skm 명령어를 통해 설치할 수 있습니다.
SKM의 핵심 사용 흐름은 ~/.config/skm/skills.yaml 파일을 생성하여 관리할 SKILL 패키지들을 정의하는 것입니다. 이 설정 파일은 packages 리스트를 포함하며, 각 패키지는 repo (Git 리포지토리 URL) 또는 local_path (로컬 디렉터리 경로) 중 하나를 소스로 지정해야 합니다. 선택적으로 각 패키지 내에서 설치할 특정 SKILL 목록(skills)이나 해당 패키지를 설치할 agent들을 필터링(agents 및 excludes)할 수 있습니다. 전역 agent 설정은 skills.yaml 파일의 최상위 agents 섹션에 정의하여 기본적으로 활성화될 agent들을 지정할 수 있습니다. 파일 설정 후 skm install 명령을 실행하면, 정의된 SKILL 패키지들이 사용자의 agent 디렉터리로 복제(clone)되거나 링크(symlink)됩니다.

명령어 및 기능:

• skm install:
  • 인자 없이 실행 시: skills.yaml에 정의된 모든 패키지를 설치합니다. 이 과정에서 리포지토리 클론, SKILL 감지, agent 디렉터리로의 심볼릭 링크 생성, 그리고 skills-lock.yaml 파일에 현재 상태를 기록하는 작업을 수행합니다. 이 명령어는 멱등성(idempotent)을 가지며, 더 이상 필요 없는(stale) 링크들을 제거하여 skills.yaml에 정의된 선언적 상태(declarative state)와 agent 디렉터리의 실제 상태를 동기화합니다.
  • $<source> [skill]$과 함께 실행 시: skills.yaml을 수정할 필요 없이 GitHub 리포지토리 URL 또는 로컬 경로에서 직접 SKILL을 설치합니다. 이 경우 SKILL 및 agent를 대화형으로 선택할 수 있으며, 선택된 패키지는 자동으로 skills.yaml에 추가됩니다. --agents-includes 또는 --agents-excludes 플래그를 사용하여 대화형 프롬프트를 건너뛸 수 있습니다.
• skm list: 현재 설치된 SKILL과 그 링크된 경로를 보여줍니다. --all 플래그와 함께 사용하면 모든 agent 디렉터리의 SKILL을 표시하고 SKM에 의해 관리되는 SKILL을 명시합니다.
• $skm view <source>$: 설치하지 않고 리포지토리 URL 또는 로컬 경로의 SKILL을 미리 보고 탐색합니다.
• skm check-updates: 원격(remote) 리포지토리를 페치(fetch)하여 사용 가능한 업데이트를 확인합니다. local_path로 지정된 패키지는 건너뜀니다.
• $skm update <skill>$: 특정 SKILL의 리포지토리에 대해 최신 변경사항을 풀(pull)하고, SKILL을 재감지하며, 링크를 재연결하고, 락 파일을 업데이트합니다. local_path로 지정된 패키지는 건너뜁니다.

핵심 방법론 (SKILL Detection 및 Sync Behavior):
SKM의 핵심은 SKILL 감지(Skill Detection) 로직과 설치 동기화(Install Sync Behavior)입니다. SKILL 감지: SKM은 디렉터리 내에 SKILL.md 파일이 존재하고 해당 파일에 YAML frontmatter에 name 필드가 포함되어 있을 때 이를 SKILL로 인식합니다. 감지 순서는 다음과 같습니다:

1. 리포지토리의 루트 디렉터리에 SKILL.md가 존재하면, 리포지토리 자체를 단일 SKILL로 간주합니다.
2. ./skills/ 하위 디렉터리가 존재하면, 해당 디렉터리의 자식(children)들을 스캔합니다.
3. 위 두 가지 경우가 아니면, 리포지토리 루트부터 모든 하위 디렉터리를 순회합니다.

SKILL.md 파일을 찾으면 해당 디렉터리의 스캔을 중단하며, 중첩된(nested) SKILL은 감지하지 않습니다.

설치 동기화: skm install은 skills.yaml을 원하는 상태를 선언하는 파일로 간주합니다. 매 실행마다 agent 디렉터리를 이 config 파일과 일치하도록 동기화합니다.

• skills.yaml에 새로 추가된 SKILL은 agent 디렉터리에 링크됩니다.
• skills.yaml에서 제거된 SKILL(패키지의 skills 목록에서 삭제되거나 전체 패키지가 제거된 경우)의 링크는 삭제됩니다.
• agent config(excludes 등)가 변경되면, 제외된 agent들로부터 해당 링크가 제거되고 다른 agent들의 링크는 유지됩니다.
• 이러한 동기화는 skills-lock.yaml에 기록된 링크에만 영향을 미칩니다. agent 디렉터리에 수동으로 생성되었거나 다른 도구에 의해 설치된 파일이나 SKILL은 절대 건드리지 않습니다.

주요 경로 및 오버라이드:
SKM은 다음의 기본 경로들을 사용합니다:

• Config: ~/.config/skm/skills.yaml
• Lock: ~/.config/skm/skills-lock.yaml
• Store: ~/.local/share/skm/skills/ (클론된 리포지토리 및 로컬 경로 패키지의 실제 SKILL 파일이 저장되는 곳)
• Known Agents: standard (~/.agents/skills/), claude (~/.claude/skills/), codex (~/.codex/skills/), openclaw (~/.openclaw/skills/)

테스트 또는 커스텀 설정을 위해 --config, --store, --lock, --agents-dir CLI 플래그를 통해 이러한 기본 경로들을 오버라이드할 수 있습니다.