서론

gh skill이라는 명령어가 있다는 것은 알고 있었지만, 잘 모르는 채로 방치하고 있었습니다. 그래서 실제로 시도해 보니 대략 어떤 것인지 알게 되어 정리해 둡니다.

자신의 Claude Code 스킬을 공개하고, 다른 환경에서 설치할 수 있는지 확인하는 것이 목적입니다. gh skill 자체는 아직 프리뷰(Preview) 단계이므로 변경될 가능성이 있습니다.

gh skill이란

GitHub CLI의 확장 명령어로, 에이전트 스킬(Claude Code 등이 사용하는 SKILL.md)을 GitHub을 통해 공개 및 설치할 수 있습니다. 공식 문서(Official Documentation)는 여기 있습니다.

서브 커맨드(Subcommand)는 5개가 있습니다.

gh skill publish # 스킬을 공개 (GitHub Release를 생성)
gh skill install # 스킬을 설치
gh skill update # 설치된 스킬을 업데이트
...

스킬의 리포지토리 구조

스킬은 skills/*/SKILL.md 패턴으로 자동 검출됩니다. 여러 스킬을 하나의 리포지토리(Repository)에 모아서 둘 수 있습니다.

my-skills/
├── .gitignore
├── README.md
...

SKILL.md의 최소 구성은 이것뿐입니다.

---
name: skill-name # 디렉토리명과 일치시켜야 함
description: 무엇을 하는 스킬인지, 언제 사용하는지를 작성
...

name은 디렉토리명과 일치하지 않으면 에러가 발생합니다. description은 에이전트가 스킬 선택 시 사용하므로, "무엇을 하는지", "언제 사용하는지"를 구체적으로 작성하는 것이 중요합니다.

publish 흐름

# 1. 리포지토리 생성
gh repo create my-skills --public
# 2. push
...

gh skill publish가 내부적으로 수행하는 작업:

• SKILL.md의 사양(Specification) 체크
• GitHub Release 생성 (gh release create에 해당)
• 리포지토리에 agent-skills 토픽(Topic) 부여

즉, GitHub Releases의 얇은 래퍼(Wrapper)입니다. git push만으로는 설치할 수 없으니 주의하세요. 설치는 GitHub Release를 참조하므로 반드시 publish가 필요합니다.

dry-run으로 사전 확인

--dry-run을 사용하면 공개하지 않고 검증만 할 수 있습니다.

$ gh skill publish --dry-run
warning zenn-article-writer recommended field missing: license
warning no git remote found. Create a GitHub repository with: gh repo create
...

자주 발생하는 warning:

• license 필드가 없음 → frontmatter에 license: MIT 등을 추가
• 태그 보호 규칙 세트(Tag Protection Ruleset)가 없음 → GitHub의 Settings > Rules > Rulesets에서 설정 (후술)

태그 보호 규칙 세트

gh skill install --pin v0.1.0과 같이 버전을 고정하여 설치했을 경우, 태그가 나중에 변경되면 참조 대상이 바뀌어 버립니다. 이를 방지하는 것이 태그 보호 규칙 세트입니다.

GitHub API로 추가할 수 있습니다.

gh api repos/<owner>/<repo>/rulesets \--method POST \--header "Content-Type: application/json" \...

install과 스코프

# 프로젝트 스코프 (기본값) → .claude/skills/ 에 들어감
gh skill install <owner>/<repo> <skill-name> --agent claude-code
# 유저 스코프 → ~/.agents/skills/ 에 들어감
...

--scope user로 설정하면 ~/.agents/skills/에 저장됩니다.

에 들어가므로, 방심하면 기존 스킬을 덮어쓸 수도 있습니다. 동일한 이름의 스킬이 있는 경우에는 사전에 확인해 두는 것이 좋을 것 같습니다.

update と search

# 설치된 스킬을 모두 업데이트
gh skill update --all
# 스킬을 검색
...

gh skill search는 publish 직후에는 나타나지 않습니다. 인덱스 (Index) 반영에 시간이 다소 걸립니다 (수 시간 단위인 것 같습니다).

새로운 스킬을 추가하여 릴리스(Release)했을 경우, update로는 추가되지 않으며 install이 필요합니다. update는 기존 스킬의 업데이트만 수행합니다.

세션을 재시작하지 않으면 새로 설치한 스킬이 인식되지 않는 점에서도 은근히 막혔습니다.

おわりに

gh skill publish는 GitHub Releases의 래퍼 (Wrapper)이며, 구조를 파악하고 나면 단순합니다. 스킬의 리포지토리 (Repository) 구조도 skills/*/SKILL.md 패턴만 기억해 두면 우선 작동합니다.

글로벌 (Global)과 프로젝트 스코프 (Project Scope)의 우선순위, 그리고 ~/.claude/skills가 심볼릭 링크 (Symbolic Link)라는 점은 저처럼 기존 스킬이 있는 환경에서 테스트할 때 빠지기 쉬운 함정이므로 주의하시기 바랍니다.

테스트한 리포지토리는 여기입니다 → https://github.com/optimisuke/hello-gh-skills