설치된 스킬 나열

학습 후 할 수 있는 것

• openskills list를 사용하여 모든 설치된 스킬 확인
• (project) 및 (global) 위치 라벨의 차이점 이해
• 프로젝트 스킬과 전역 스킬의 수량을 빠르게 통계 확인
• 스킬 설치 성공 여부 판단

현재의 어려움

몇 개의 스킬을 설치한 후 다음과 같은 문제에 부딪혔을 수 있습니다:

• "방금 어떤 스킬들을 설치했는지 잊어버렸어요"
• "이 스킬은 프로젝트에 설치했을까, 아니면 전역으로 설치했을까?"
• "왜 어떤 스킬은 A 프로젝트에서는 보이는데 B 프로젝트에서는 안 보일까?"
• "안 쓰는 스킬을 삭제하고 싶은데 정확한 이름을 모르겠어"

openskills list 명령은 바로 이런 의문을 해결하기 위해 설계되었습니다 — 마치 스킬의 "목차"처럼, 모든 설치된 스킬과 그 위치를 한눈에 보여줍니다.

이 명령을 사용하는 경우

시나리오	동작
스킬 설치 후 성공 여부 확인	openskills list 실행하여 스킬이 표시되는지 확인
새 프로젝트로 전환 후 사용 가능한 스킬 확인	openskills list 실행하여 어떤 project 스킬이 있는지 확인
스킬 정리 전에 재고 파악	openskills list 실행하여 모든 스킬 나열 후, 불필요한 것 삭제
스킬 로딩 문제 디버깅	스킬 이름과 설치 위치가 정확한지 확인

핵심 개념

OpenSkills는 4개의 위치에서 스킬을 설치할 수 있습니다 (우선순위 순):

1. project .agent/skills - 프로젝트 레벨의 범용 스킬 디렉토리 (다중 에이전트 환경)
2. global .agent/skills - 전역 범용 스킬 디렉토리 (다중 에이전트 환경)
3. project .claude/skills - 프로젝트 레벨의 Claude Code 스킬 디렉토리
4. global .claude/skills - 전역 Claude Code 스킬 디렉토리

openskills list 명령은:

1. 이 4개의 디렉토리를 순회하며 모든 스킬을 찾습니다
2. 중복 제거: 동일한 스킬명은 한 번만 표시됩니다 (project 버전 우선)
3. 정렬: project 스킬이 먼저, global 스킬이 다음; 같은 위치 내에서는 알파벳 순서
4. 위치 태그: (project) 및 (global) 라벨로 구분
5. 통계 요약: project 스킬 수, global 스킬 수 및 총합 표시

왜 중복 제거가 필요한가?

프로젝트와 전역 모두에 동일한 스킬(예: pdf)을 설치한 경우, OpenSkills는 project 버전을 우선적으로 사용합니다. list 명령은 한 번만 표시하여 혼란을 방지합니다.

따라 해보기

1단계: 모든 설치된 스킬 나열

이유 빠르게 현재 환경에 어떤 스킬이 사용 가능한지 확인

다음 명령을 실행합니다:

npx openskills list

예상 결과

스킬이 설치되어 있지 않다면 다음과 같이 표시됩니다:

Available Skills:

No skills installed.

Install skills:
  npx openskills install anthropics/skills         # Project (default)
  npx openskills install owner/skill --global     # Global (advanced)

스킬이 설치되어 있다면 다음과 비슷한 화면을 볼 수 있습니다:

Available Skills:

  pdf                         (project)
    Comprehensive PDF manipulation toolkit for extracting text and tables...

  code-analyzer                (project)
    Static code analysis tool for identifying security vulnerabilities...

  email-reader                 (global)
    Read email content and attachments via IMAP protocol...

Summary: 2 project, 1 global (3 total)

2단계: 출력 형식 이해하기

이유 각 행이 무엇을 의미하는지 알아야 필요한 정보를 빠르게 찾을 수 있습니다

출력 형식 설명:

부분	설명
pdf	스킬 이름 (SKILL.md의 name 필드에서 추출)
(project)	위치 태그: 파란색은 프로젝트 레벨 스킬, 회색은 전역 스킬을 표시
Comprehensive PDF...	스킬 설명 (SKILL.md의 description 필드에서 추출)
Summary: 2 project, 1 global (3 total)	통계 요약: project 스킬 수, global 스킬 수, 총합

3단계: 위치 태그 검증하기

이유 스킬이 예상한 위치에 설치되었는지 확인하여 "이 프로젝트에서 이 스킬이 왜 안 보여?" 같은 의문 방지

위치 태그를 이해하기 위해 다음 작업을 시도해보세요:

# 1. 프로젝트 레벨 스킬 설치
npx openskills install anthropics/skills -y

# 2. 목록 확인 (project 태그 표시되어야 함)
npx openskills list

# 3. 전역 스킬 설치
npx openskills install anthropics/skills --global -y

# 4. 다시 목록 확인 (동일한 pdf 스킬, 한 번만 표시, project 태그)
npx openskills list

예상 결과

Available Skills:

  pdf                         (project)
    Comprehensive PDF manipulation toolkit for extracting text...

Summary: 1 project, 0 global (1 total)

전역과 프로젝트 모두에 동일한 스킬을 설치했더라도 list 명령은 한 번만 표시합니다. 왜냐하면 project 버전이 더 높은 우선순위를 가지기 때문입니다.

체크포인트 ✅

다음 내용을 확인하세요:

• [ ] openskills list 실행 시 설치된 스킬 목록이 표시됨
• [ ] (project) 및 (global) 태그를 구분할 수 있음 (색상이 다름: 파란색 vs 회색)
• [ ] Summary 통계 숫자가 올바름 (project 스킬 수 + global 스킬 수 = 총합)
• [ ] 동일한 스킬명은 한 번만 표시되는 규칙을 이해함

자주 발생하는 문제들

문제 1: 방금 설치한 스킬을 찾을 수 없음

현상: install 명령은 성공했지만 list에 보이지 않음

해결 방법:

1. 올바른 프로젝트 디렉토리에 있는지 확인 (project 스킬은 현재 프로젝트에서만 보임)
2. 전역으로 설치했는지 확인 (--global 플래그 사용 여부)
3. 설치 위치를 검증:

# 프로젝트 디렉토리 확인
ls -la .claude/skills/

# 전역 디렉토리 확인
ls -la ~/.claude/skills/

문제 2: 이상한 스킬 이름을 봄

현상: 예상한 이름이 아님 (예: 폴더명 vs SKILL.md의 name)

원인: OpenSkills는 SKILL.md의 name 필드를 스킬명으로 사용하며, 폴더명은 사용하지 않습니다

해결 방법: SKILL.md의 frontmatter를 확인:

---
name: pdf  # list 명령에 표시되는 이름
description: Comprehensive PDF manipulation toolkit...
---

문제 3: 설명이 잘림

현상: 스킬 설명이 잘려서 보임

원인: 터미널 너비 제한으로 인해 발생하며, 스킬 콘텐츠에는 영향을 주지 않습니다

해결 방법: SKILL.md 파일을 직접 열어 전체 설명을 확인

강의 요약

openskills list는 스킬 관리의 "목차" 명령입니다:

• 📋 모든 스킬 조회: 설치된 스킬을 한눈에 볼 수 있음
• 🏷️ 위치 태그 구분: (project)는 프로젝트 레벨, (global)은 전역 레벨을 의미
• 📊 통계 요약: project와 global 스킬의 수량을 빠르게 파악
• 🔍 문제 해결: 스킬 설치 성공 여부 검증 및 스킬 위치 확인

핵심 규칙:

1. 동일한 이름의 스킬은 한 번만 표시됨 (project가 우선)
2. project 스킬이 먼저, 그 다음 global 스킬
3. 같은 위치 내에서는 알파벳 순서로 정렬

다음 강의 예고

다음 강의에서는 **스킬 업데이트**를 학습합니다.

배울 내용:

• 설치된 스킬을 소스 저장소에서 새로고침하는 방법
• 모든 스킬을 일괄 업데이트하는 방법
• 메타데이터가 없는 이전 스킬 처리 방법

---

부록: 소스코드 참조

소스코드 위치 확인 (클릭하여 펼치기)

최종 업데이트: 2026-01-24

기능	파일 경로	라인 번호
list 명령 구현	src/commands/list.ts	7-43
모든 스킬 찾기	src/utils/skills.ts	30-64
검색 디렉토리 설정	src/utils/dirs.ts	18-25
Skill 타입 정의	src/types.ts	1-6

핵심 함수:

• listSkills(): 모든 설치된 스킬을 나열하고 형식화하여 출력
• findAllSkills(): 4개의 검색 디렉토리를 순회하며 모든 스킬 수집
• getSearchDirs(): 4개의 검색 디렉토리 경로 반환 (우선순위 순)

핵심 상수:

• 없음 (검색 디렉토리 경로는 동적으로 계산됨)

핵심 로직:

1. 중복 제거: Set을 사용하여 이미 처리된 스킬명 기록 (skills.ts:32-33, 43, 57)
2. 위치 판단: dir.includes(process.cwd())로 project 디렉토리인지 판단 (skills.ts:48)
3. 정렬 규칙: project가 우선, 동일 위치 내에서는 알파벳 순서 (list.ts:21-26)