gh skill로 에이전트 스킬 관리하기

좋아 보이는 에이전트 스킬을 동료 깃허브 저장소에서 발견해서 따라 써보고 싶은데, 막상 적용하려고 하면 막막할 때가 있죠. SKILL.md 파일을 다운로드해서 어디다 저장할지 검색하고, 의존하는 스크립트까지 같이 챙겨오고, 며칠 뒤에 원본이 업데이트되면 또 수동으로 덮어쓰고… 😅

게다가 직접 만든 스킬을 동료에게 공유할 때도 비슷한 문제가 생깁니다. 스펙에 맞게 잘 작성했는지 확인하기도 쉽지 않고, 검색이 잘 되도록 메타데이터를 챙기는 일도 신경 쓸 게 한두 가지가 아니거든요.

GitHub이 이 문제를 해결하려고 GitHub CLI에 새로 추가한 명령어가 바로 gh skill입니다. 스킬을 검색하고, 미리 보고, 버전 핀을 걸어 설치하고, 업데이트하고, 게시까지 한 흐름으로 처리할 수 있어요. 이번 글에서는 gh skill의 핵심 기능을 살펴보겠습니다.

gh skill이 뭔가요?

gh skill은 깃허브 저장소에 올라와 있는 에이전트 스킬을 로컬 환경으로 가져오거나, 반대로 내가 만든 스킬을 다른 사람이 쓸 수 있도록 게시하는 명령어입니다. 한마디로 npm이나 Homebrew가 패키지를 다루는 것처럼, 에이전트 스킬을 패키지로 다루게 해주는 도구라고 보면 됩니다.

스킬은 마크다운 파일과 보조 스크립트 묶음이라서 이론적으로는 그냥 git clone만 해도 됩니다. 그런데 실제로 여러 스킬을 운영하다 보면 신경 쓸 게 많아요. 어느 버전이 깔려 있는지, 어느 커밋을 기준으로 가져왔는지, 본인이 수정한 부분과 원본 업데이트가 충돌하지는 않는지, 어떤 에이전트 호스트(Claude Code, Cursor, Copilot 등)에 깔지 등등. gh skill은 이런 운영 측면을 모두 GitHub CLI 차원에서 처리합니다.

지원하는 에이전트 호스트도 폭넓은데요. GitHub Copilot은 물론이고 Claude Code, Cursor, Codex, Gemini CLI, Antigravity까지 한 명령어로 다 다룰 수 있습니다.

설치

gh skill은 GitHub CLI 2.90.0 버전부터 포함되어 있습니다. 아직 프리뷰 상태라 명령어 인터페이스가 바뀔 수 있다는 점은 미리 알아두는 게 좋아요.

이미 gh가 깔려 있다면 버전을 확인하고 필요하면 업데이트만 하면 됩니다.

gh --version

버전이 2.90.0 미만이라면 macOS는 Homebrew로 업그레이드합니다.

brew upgrade gh

설치 자체는 GitHub CLI 사용법 글에 자세히 적어두었으니 처음 다루는 분은 먼저 그쪽을 보고 오시면 좋습니다.

gh skill 명령어를 단독으로 실행하면 사용 가능한 서브커맨드 목록이 나옵니다.

gh skill --help

서브커맨드는 search, preview, install, update, publish 다섯 개로 단순합니다. 이름만 봐도 무슨 일을 하는지 짐작이 가실 텐데요. 하나씩 살펴보겠습니다. 참고로 gh skills(복수형)도 별칭으로 동작하니 어느 쪽을 써도 됩니다.

스킬 검색하기

먼저 어떤 스킬이 있는지 둘러봐야겠죠. gh skill search 명령어로 키워드 검색을 할 수 있습니다.

gh skill search terraform

이 명령어를 실행하면 깃허브에 공개된 스킬 중에서 키워드와 일치하는 것들을 보여줍니다. 검색어 없이 그냥 실행하면 인기 스킬을 둘러보는 용도로도 쓸 수 있어요.

특정 저장소를 미리 알고 있다면 검색 단계는 건너뛰고 바로 다음 단계로 넘어가도 됩니다. 예를 들어 GitHub이 운영하는 github/awesome-copilot 저장소에 예제 스킬이 여럿 모여 있어요.

설치 전에 미리 보기

스킬을 무작정 깔기 전에 어떤 내용인지 먼저 보고 싶을 때가 있습니다. SKILL.md 파일에 적힌 지침이 우리 워크플로우에 맞는지, 보조 스크립트가 뭘 하는지 확인하고 싶을 텐데요. 이럴 때 gh skill preview를 씁니다.

gh skill preview github/awesome-copilot documentation-writer

소유자/저장소 스킬이름 형식으로 지정하면 해당 스킬의 내용을 보여줍니다. 로컬에 설치하지 않고 미리 훑어볼 수 있으니 신뢰가 가지 않는 저장소에서 가져올 때 유용합니다. 공급망 보안 관점에서도, 잘 모르는 스킬을 바로 깔지 않고 한 번 검토하는 단계로 활용하면 좋겠죠.

스킬 설치하기

내용을 확인하고 마음에 들면 gh skill install로 실제로 설치합니다.

gh skill install github/awesome-copilot documentation-writer

이렇게 하면 현재 환경에 깔린 에이전트 호스트의 스킬 디렉토리에 자동으로 복사됩니다. Claude Code라면 ~/.claude/skills/, Cursor라면 Cursor 쪽 경로처럼, 호스트가 기대하는 위치에 알아서 들어가요.

저장소 안에 어떤 스킬이 있는지 잘 모르겠다면 스킬 이름을 빼고 실행할 수도 있습니다. 그러면 대화형으로 설치할 스킬을 고르게 해줍니다.

gh skill install github/awesome-copilot

여러 에이전트 호스트를 같이 쓰는 환경이라면 --agent 플래그로 어디에 설치할지 명시하는 게 좋습니다.

gh skill install github/awesome-copilot documentation-writer --agent claude-code

원격 저장소가 업데이트되더라도 지금 동작이 검증된 버전을 그대로 유지하고 싶을 때가 있죠. 이럴 때 버전이나 커밋 SHA를 핀으로 박아둘 수 있습니다.

# 태그 버전을 지정해서 설치
gh skill install github/awesome-copilot documentation-writer@v1.2.0

# 특정 커밋으로 고정
gh skill install github/awesome-copilot documentation-writer@abc123def

# --pin 플래그로 고정 의도를 명시
gh skill install github/awesome-copilot documentation-writer --pin v1.2.0

@v1.2.0처럼 즉시 지정하는 방식과 --pin으로 명시적으로 핀을 거는 방식이 함께 제공됩니다. 핀을 걸어두면 나중에 gh skill update를 실행해도 자동으로 올라가지 않으니 안정성이 중요한 환경에서 유용합니다.

내부적으로는 git tree SHA 기반의 콘텐츠 주소 지정 방식을 써서 원본이 변경됐는지 감지합니다. 그래서 같은 태그를 누가 슬쩍 바꿔치기해도 SHA가 달라지면 변경을 알아챌 수 있어요. 공급망 공격을 막는 기본 장치라고 보면 됩니다.

스킬 업데이트하기

설치 후 시간이 지나면 원본이 갱신될 수 있죠. 이럴 때 gh skill update로 갱신 여부를 확인하고 반영할 수 있습니다.

gh skill update

인자 없이 실행하면 설치된 스킬 중 업데이트가 필요한 것들을 보여줍니다. 특정 스킬만 갱신하고 싶으면 이름을 지정하면 돼요.

gh skill update git-commit

전부 한 번에 갱신하려면 --all 플래그를 씁니다.

gh skill update --all

핀을 걸어둔 스킬은 자동 갱신 대상에서 빠지기 때문에, 신경 쓰지 않고 --all을 써도 안전합니다. 이게 핀을 걸어두는 가장 큰 이유 중 하나예요.

스킬 게시하기

지금까지는 남이 만든 스킬을 가져오는 흐름이었다면, 반대로 내가 만든 스킬을 다른 사람도 쓸 수 있게 게시하는 것도 가능합니다. 깃허브 저장소를 만들고 그 안에 SKILL.md 파일을 잘 갖춰 두면, gh skill publish가 게시에 필요한 검증과 정리를 해줍니다.

gh skill publish

이 명령어는 에이전트 스킬 스펙에 맞춰 SKILL.md를 검사합니다. frontmatter 필드가 빠지지 않았는지, description이 너무 길거나 짧지 않은지, 보조 파일 경로가 올바른지 같은 것들이죠. 검증만 하고 실제 게시는 하지 않으려면 --dry-run을 씁니다.

gh skill publish --dry-run

CI 파이프라인에서 PR마다 스킬 스펙을 검증하는 용도로 활용하기 좋습니다. 메인 브랜치에 머지되기 전에 스펙을 어긋난 변경을 잡을 수 있으니까요.

자잘한 메타데이터 문제는 손으로 고치지 않아도 자동으로 정리해주는 옵션이 있습니다.

gh skill publish --fix

--fix는 흔히 누락되는 필드를 채우거나 형식을 맞추는 식으로 자동 수정을 시도합니다. 처음 스킬을 만들 때 손이 가장 많이 가는 부분이 메타데이터인데, 이 옵션을 쓰면 그 작업 시간을 꽤 줄일 수 있어요.

게시 과정에서는 저장소 보안 설정도 함께 점검합니다. 태그 보호가 걸려 있는지, 시크릿/코드 스캐닝이 활성화되어 있는지 같은 항목인데요. 다른 사람이 가져다 쓸 코드 자산이라는 점에서 이런 보안 점검이 큰 의미가 있습니다.

핀과 프로비넌스

gh skill을 처음 써볼 때 그냥 지나치기 쉬운데, 가장 가치 있는 부분이 바로 버전 핀과 프로비넌스 메타데이터입니다.

버전 핀은 위에서 살펴본 대로 특정 태그나 커밋을 박아두는 기능이에요. 직접 npm 의존성을 다뤄보신 분이라면 package-lock.json이 하는 역할과 비슷하다고 보시면 됩니다. 같은 명령어를 다른 머신에서 실행해도 정확히 같은 스킬 내용을 받을 수 있도록 보장해주죠.

프로비넌스 메타데이터는 설치된 스킬 파일 자체에 어디서, 어느 버전에서, 어떤 커밋 SHA로 가져왔는지를 기록해 두는 정보입니다. 나중에 “이 스킬 어디서 가져왔더라?” 같은 상황이 생겼을 때 추적이 가능해요. 팀이 공유하는 환경에서 누가 어떤 스킬을 깔았는지 감사가 필요할 때 특히 유용합니다.

이런 장치들은 결국 공급망 보안 문제를 해결하기 위한 것입니다. 에이전트 스킬은 사실상 코드 실행 권한을 가진 명령어 묶음이라, 출처와 무결성을 검증하는 일이 점점 더 중요해지고 있거든요.

어떤 에이전트와 같이 쓸 수 있나요?

gh skill이 지원하는 에이전트 호스트는 현재 다음과 같습니다.

• GitHub Copilot — --agent copilot
• Claude Code — --agent claude-code
• Cursor — --agent cursor
• Codex — --agent codex
• Gemini CLI — --agent gemini
• Antigravity — --agent antigravity

각 호스트마다 스킬을 어디에 두는지가 조금씩 다른데, gh skill이 내부적으로 호스트별 표준 위치를 알고 있어서 우리는 신경 쓰지 않아도 됩니다. 한 머신에 여러 호스트가 깔려 있다면 --agent 플래그로 매번 명시하거나, 모두에게 동시에 설치하는 옵션을 검토해볼 수 있어요.

Claude Code의 내장 스킬과 헷갈릴 수 있는데, 그건 Claude Code 안에 미리 박혀 있는 스킬이고 gh skill은 외부 저장소에서 가져오는 사용자 스킬을 다룬다는 점에서 결이 다릅니다. 두 가지가 함께 쓰이도록 설계되어 있어요.

마치며

gh skill은 파일 다운로드를 자동화하는 데 그치지 않고, 에이전트 스킬을 하나의 패키지처럼 다룰 수 있는 토대를 제공합니다. 검색부터 미리 보기, 핀이 가능한 설치, 업데이트 추적, 게시 검증까지 흐름이 끊김 없이 이어진다는 게 가장 큰 장점이에요. 특히 AGENTS.md 같은 컨텍스트 파일과 짝을 이뤄 팀 단위로 에이전트 워크플로우를 표준화하는 데 큰 도움이 될 겁니다.

직접 스킬을 만들어 게시해보면 더 빠르게 감이 잡히실 텐데요. 작은 SKILL.md 하나를 깃허브 저장소에 올리고, gh skill publish --dry-run으로 검증해보고, 동료 머신에서 gh skill install로 받아 보는 식으로 한 사이클을 돌려보시길 권합니다.

더 자세한 내용은 GitHub CLI 매뉴얼의 gh skill 페이지를 참고하세요.