Communitygithub.com

xFurti/skillctl

에이전트 스킬을 위한 범용 패키지 매니저 CLI — 매니페스트, 락파일, 다중 에이전트 동기화(Cursor, Claude, Codex, Gemini). Node ≥22.13.

skillctl란 무엇인가요?

skillctl은 Cursor, Claude, Codex, Gemini와 같은 여러 AI 에이전트 간에 스킬을 중앙에서 관리할 수 있는 CLI 도구입니다. 단일 저장소(`~/.skillctl/skills/`)에 스킬을 설치하고, 각 에이전트 디렉토리에 심볼릭 링크를 생성하여 동기화합니다. `agent-skills.json` 매니페스트와 `agent-skills.lock` 락파일을 통해 팀 간 재현 가능한 설정을 보장하며, `import` 명령어로 기존 에이전트 디렉토리나 npx 스킬을 쉽게 마이그레이션할 수 있습니다. `doctor` 및 `audit` 명령어를 통해 CI/CD 파이프라인에서도 일관성을 검증할 수 있어, 에이전트 스킬 관리의 포터빌리티와 협업을 크게 개선합니다.

지원 대상✓Claude Code✓Codex CLI✓Cursor✓Gemini CLI✓OpenCode
npx skills add xFurti/skillctl

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

skillctl은(는) 무엇을 하나요?

skillctl CLI를 사용하여 에이전트 스킬을 관리하기 위한 운영 플레이북입니다. 실제 명령을 실행하세요. 출력을 시뮬레이션하거나 SKILL.md 파일을 에이전트 디렉토리 간에 수동으로 복사하지 마십시오.

황금 규칙

  1. 단일 정규 저장소 — 스킬은 ~/.skillctl/skills/<name>/에 위치하며, sync를 통해 에이전트에 심볼릭 링크가 생성됩니다.
  2. 매니페스트 + 락 커밋 — 팀 재현성을 위해 agent-skills.json과 agent-skills.lock을 git에 추적하세요.
  3. 휴대용 지정자만 사용 — file:./<path>, local:imported/<name>, github:, npm:, 또는 skills.sh/를 사용하세요. 절대 경로 홈 디렉토리는 커밋하지 마십시오.
  4. 동기화 전에 설치 — install로 저장소를 구체화하고, sync는 링크만 다시 생성합니다.
  5. 변경 후 검증 — skillctl doctor를 실행하세요(CI에서는 skillctl audit).
  6. 수동 복사보다 가져오기 선호 — 스킬 폴더를 복제하는 대신 import from-project 또는 import from-npx를 사용하세요.

결정 트리

상황명령어
새 프로젝트, 매니페스트 없음skillctl init 또는 skillctl init --with-skill
원격 또는 로컬 스킬 추가skillctl add <지정자> 후 skillctl install
스킬이 이미 .claude/skills, .codex/skills 등에 있음skillctl import from-project
npx skills에서 마이그레이션skillctl import from-npx
다시 링크만 (락 변경 없음)skillctl sync
업스트림에서 다시 가져오기skillctl update 또는 skillctl update <이름>
CI에서 재현 가능한 설치skillctl install --frozen 후 skillctl audit --strict
락에 휴대용이 아닌 경로 있음skillctl install로 다시 작성, skillctl doctor 경고 확인

빠른 레시피

# 부트스트랩
skillctl init --with-skill
skillctl add github:vercel-labs/agent-skills#web-design-guidelines
skillctl install

# 프로젝트 로컬 스킬
skillctl add file:./my-skill
skillctl install
skillctl sync

# 기존 에이전트 디렉토리 가져오기
skillctl import from-project --dry-run
skillctl import from-project

# 검사
skillctl list
skillctl doctor
skillctl audit --json

add file:./my-skill + install 후 예상 결과: 매니페스트 지정자 file:./my-skill, 락 canonicalPath가 ~/.skillctl/skills/my-skill처럼 나타납니다.

휴대성 (0.3.1+)

  • 휴대 가능: file:./rel, local:imported/<name>, 원격 지정자, canonicalPath: ~/.skillctl/skills/<name>.
  • 휴대 불가능: 절대 경로 file:/Users/..., local:/abs/path, 다른 머신의 절대 경로 canonicalPath.
  • doctor가 휴대 가능하지 않은 경로에 대해 경고하면 skillctl install을 실행하여 매니페스트에서 락을 다시 작성하세요.

실패 모드

증상조치
canonical path missingskillctl install
무결성 불일치skillctl update <이름> 또는 skillctl install
심볼릭 링크 실패 (Windows)doctor가 표시, defaultMode: copy 설정
연결된 에이전트 없음skillctl sync, ~/.skillctl/config.json에서 에이전트 활성화
Frozen install failed저장소가 동기화되지 않음, --frozen 없이 install 실행

참고 자료

관련 스킬