GitHub CLI gh skill 사용법: Claude Code·Codex·Copilot 스킬 관리

GitHub CLI 2.99.0의 gh skill은 에이전트 스킬을 내려받아 정해진 폴더에 복사하고 출처 메타데이터를 붙여 업데이트까지 맡는 명령군이다. Claude Code, Codex, GitHub Copilot마다 스킬 경로를 외워 수동 복사하던 일을 줄여준다.

다만 완성된 패키지 관리자로 보면 곤란하다. 아직 public preview이고 삭제 명령도 없다. 설치 전에 내용을 읽어야 한다는 보안 책임 역시 사용자에게 남는다. 이 글은 2.99.0 바이너리로 확인한 동작을 기준으로 설명한다.

한눈에 보기

요구 버전은 GitHub CLI 2.90.0 이상이다. 여기서는 2.99.0을 검증했다.
install, list, preview, search, update, publish 여섯 하위 명령을 제공한다.
2.99.0 도움말에는 48개 에이전트 호스트가 나온다. Claude Code, Codex, GitHub Copilot, Cursor, Gemini CLI, OpenCode 등이 포함된다.
기본값은 프로젝트 범위와 GitHub Copilot이다. 비대화형 실행에서 별도 지정이 없으면 이 조합을 쓴다.
gh skill remove나 uninstall은 없다. 설치 경로를 확인한 뒤 폴더를 직접 지워야 한다.

`gh skill`이 해결하는 문제

에이전트 스킬은 최소한 YAML frontmatter와 Markdown 본문을 가진 SKILL.md 파일로 구성된다. 필요하면 scripts, references, assets도 함께 둔다. 형식은 단순하지만 호스트마다 검색하는 경로가 다르고 복사본의 원본과 버전을 추적하기도 어렵다.

gh skill은 GitHub 저장소에서 스킬을 찾고 설치 전에 내용을 보여주며 선택한 에이전트가 읽는 경로로 파일을 복사한다. 설치본에는 저장소, ref, tree SHA 같은 출처 정보가 추가된다. update는 이 정보를 사용해 원본 변경 여부를 확인한다. 로컬 디렉터리에서 설치할 때도 심볼릭 링크가 아니라 파일을 복사하고 로컬 경로 메타데이터를 넣는다.

설치와 업그레이드 확인

먼저 버전을 확인한다.

gh --version
gh skill --help

2.90.0보다 낮다면 운영체제에 맞는 공식 설치 방법으로 GitHub CLI를 업그레이드한다. 정확히 2.99.0을 재현해야 한다면 2.99.0 릴리스 자산과 공식 체크섬 파일을 함께 받아 SHA-256을 검증하는 편이 안전하다.

검증 환경의 출력은 다음과 같았다.

gh version 2.99.0 (2026-09-01)

2.99.0 릴리스에서 gh skill이 처음 생긴 것은 아니다. GitHub 문서는 2.90.0 이상을 요구한다. 2.99.0에서 눈에 띄는 스킬 관련 변경은 Codex의 사용자 범위 설치 경로를 ~/.agents/skills로 바로잡은 수정이다.

검색, 미리보기, 설치

공개 저장소의 스킬을 주제로 검색할 수 있다.

gh skill search terraform --limit 5

search는 GitHub Code Search API를 쓰므로 로그인이 필요하다. 로그아웃 상태에서 2.99.0으로 실행했을 때 HTTP 401과 gh auth login 안내가 반환됐다. 반면 공개 저장소의 preview와 install은 테스트에서 로그인 없이 동작했다. 비공개 저장소 접근과 실제 발행에는 인증이 필요하다.

검색 결과를 곧바로 설치하지 말고 먼저 읽는다.

GH_PAGER=cat gh skill preview github/awesome-copilot documentation-writer

preview는 설치 없이 파일 트리와 SKILL.md를 렌더링한다. 여러 파일이 있으면 대화형 모드에서 개별 파일도 열어볼 수 있다.

내용을 확인했다면 프로젝트 범위에 설치한다.

gh skill install github/awesome-copilot documentation-writer --agent github-copilot --scope project

Claude Code 사용자 범위라면 대상과 범위를 명시한다.

gh skill install github/awesome-copilot git-commit --agent claude-code --scope user

Codex도 같은 방식이다.

gh skill install github/awesome-copilot git-commit --agent codex --scope user

저장소의 최신 태그가 있으면 태그를 먼저 선택하고 태그가 없으면 기본 브랜치 HEAD를 쓴다. 재현 가능한 설치가 필요하면 ref를 지정한다. 업데이트에서도 그 버전을 건너뛰게 만들려면 --pin을 쓰는 편이 분명하다.

gh skill install cli/cli gh --pin v2.99.0 --agent codex --scope project

실제 2.99.0 테스트에서 skill@v2.99.0 형식은 해당 ref를 설치했지만 gh skill list의 pinned 값은 false였다. --pin v2.99.0으로 설치했을 때는 pinned가 true였고 update --dry-run이 건너뛰었다. 장기 고정이 목적이라면 --pin을 권한다.

로컬에서 만든 스킬도 별도 인증 없이 복사할 수 있다.

gh skill install ./my-skills-repo demo-skill --from-local --dir ./sandbox-skills

--dir은 에이전트와 범위 설정을 덮어쓴다. 새 스킬을 시험하거나 기존 전역 설정을 건드리지 않으려는 경우에 유용하다.

설치 위치와 범위

프로젝트 범위는 현재 Git 저장소 루트를 기준으로 한다. 사용자 범위는 홈 디렉터리를 기준으로 모든 프로젝트에서 읽을 수 있게 설치한다.

에이전트	프로젝트 범위	사용자 범위
GitHub Copilot	`.agents/skills`	`~/.copilot/skills`
Claude Code	`.claude/skills`	`~/.claude/skills`
Codex	`.agents/skills`	`~/.agents/skills`

Claude Code는 CLAUDE_CONFIG_DIR가 설정돼 있으면 그 아래 skills를 사용자 범위로 사용한다. 여러 호스트가 같은 .agents/skills를 공유하면 gh skill은 같은 목적지에 중복 복사하지 않는다.

팀 규칙처럼 저장소와 함께 버전 관리할 스킬은 프로젝트 범위가 낫다. 개인이 여러 저장소에서 쓰는 도구라면 사용자 범위가 편하다. 다만 사용자 범위는 영향을 받는 프로젝트가 넓으므로 출처를 더 엄격히 검토해야 한다.

목록, 업데이트, 삭제

설치 상태는 JSON으로 확인할 수 있다.

gh skill list --json skillName,sourceURL,scope,version,pinned,path

변경 없이 업데이트 가능 여부만 확인하려면 --dry-run을 붙인다.

gh skill update --dry-run

확인 후 전체를 업데이트한다.

gh skill update --all

고정된 스킬은 업데이트에서 제외된다. --unpin은 고정을 풀고 업데이트 대상에 넣는다. --force --all은 원본이 같아도 다시 내려받으며 로컬에서 수정한 원본 파일을 덮어쓴다. 추가로 만든 파일은 지우지 않는다.

2.99.0에는 삭제 하위 명령이 없다. 다음 명령으로 정확한 경로를 찾고 해당 스킬 디렉터리의 내용을 확인한 뒤 직접 삭제해야 한다.

gh skill list --json skillName,path

설치와 업데이트는 수동 복사보다 낫지만 전체 수명 주기를 맡는 패키지 관리자에는 아직 못 미친다.

스킬 발행

스킬 저장소를 운영한다면 실제 릴리스를 만들기 전에 로컬 검증부터 실행한다.

gh skill publish --dry-run

이 명령은 디렉터리 이름과 name 일치 여부, 필수 name과 description, 이름 규칙, allowed-tools 형식, 설치 메타데이터 포함 여부를 검사한다. 테스트용 유효 스킬은 원격 저장소와 로그인 없이도 dry run을 통과했다. 원격 설정 점검과 GitHub Release 생성까지 진행하는 실제 publish에는 인증과 저장소 권한이 필요하다.

수정 가능한 설치 메타데이터 문제만 정리하려면 다음 명령을 쓸 수 있다. 이 명령 자체는 발행하지 않는다.

gh skill publish --fix

실제 발행은 태그를 지정하거나 대화형 흐름을 따른다.

gh skill publish --tag v1.0.0

수동 복사나 다른 스킬 관리자와 비교

수동 복사는 의존성이 없고 동작이 투명하다. 파일 하나만 관리하거나 네트워크가 막힌 환경에서는 여전히 가장 단순하다. 대신 호스트별 경로, 원본 URL, 설치 ref, 업데이트 여부를 직접 기록해야 한다.

gh skill의 장점은 기존 GitHub CLI 안에서 검색부터 출처 추적, 업데이트, 발행 검증까지 이어진다는 점이다. 저장소가 GitHub에 있고 팀이 이미 gh를 쓰는 경우 특히 잘 맞는다. 반대로 여러 Git 호스트와 자체 레지스트리를 함께 쓰거나 제거, 의존성 해결, 서명 검증이 필요하다면 전용 스킬 관리자 쪽이 낫다. gh skill은 스킬 내용을 신뢰해도 된다고 보증하지 않는다.

보안과 현재 한계

GitHub 문서는 스킬이 GitHub의 검증을 받지 않으며 prompt injection, 숨은 지시, 악성 스크립트를 포함할 수 있다고 경고한다. SKILL.md만 훑고 끝내지 말고 scripts, references, assets까지 확인해야 한다. 특히 allowed-tools에 shell이나 bash가 있으면 에이전트가 어떤 명령을 사전 승인받는지 살펴볼 필요가 있다.

현재 주의할 점은 명확하다.

public preview라 명령과 경로 정책이 예고 없이 바뀔 수 있다.
검색과 실제 발행에는 GitHub 인증이 필요하다.
삭제 명령이 없고 의존성 해결이나 암호학적 신뢰 검증도 제공하지 않는다.
--force 업데이트는 설치 후 수정한 파일을 덮어쓸 수 있다.
기본이 프로젝트 범위라 현재 디렉터리가 Git 저장소가 아니면 루트를 찾지 못한다. 이때는 올바른 저장소로 이동하거나 --scope user, --dir을 명시한다.

누구에게 맞나

GitHub 저장소에서 Claude Code, Codex, Copilot 스킬을 함께 관리하고 설치 출처와 업데이트 여부를 CLI에서 확인하려는 개발자에게 유용하다. 팀이 프로젝트 범위 스킬을 저장소와 함께 다루는 경우에도 잘 맞는다.

스킬 하나를 직접 작성해 고정된 폴더에 두는 사용자, GitHub 인증을 쓰기 어려운 환경, 설치 코드에 대한 강한 검증과 자동 제거가 필요한 조직은 서두를 이유가 없다. preview가 끝날 때까지 수동 복사나 기존 관리 도구를 유지해도 된다.

검증일: 2026-09-16. 공식 GitHub CLI 2.99.0 Linux amd64 아카이브의 SHA-256 체크섬을 확인한 뒤 도움말, 로컬 설치, 공개 저장소 preview/install, list, update dry run, publish dry run을 실행했다. 기존 사용자 범위 스킬은 건드리지 않았다.