skillctl은(는) 무엇을 하나요?
skillctl CLI를 사용하여 에이전트 스킬을 관리하기 위한 운영 플레이북입니다. 실제 명령을 실행하세요. 출력을 시뮬레이션하거나 SKILL.md 파일을 에이전트 디렉토리 간에 수동으로 복사하지 마십시오.
황금 규칙
- 단일 정규 저장소 — 스킬은
~/.skillctl/skills/<name>/에 위치하며,sync를 통해 에이전트에 심볼릭 링크가 생성됩니다. - 매니페스트 + 락 커밋 — 팀 재현성을 위해
agent-skills.json과agent-skills.lock을 git에 추적하세요. - 휴대용 지정자만 사용 —
file:./<path>,local:imported/<name>,github:,npm:, 또는skills.sh/를 사용하세요. 절대 경로 홈 디렉토리는 커밋하지 마십시오. - 동기화 전에 설치 —
install로 저장소를 구체화하고,sync는 링크만 다시 생성합니다. - 변경 후 검증 —
skillctl doctor를 실행하세요(CI에서는skillctl audit). - 수동 복사보다 가져오기 선호 — 스킬 폴더를 복제하는 대신
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 missing | skillctl install |
| 무결성 불일치 | skillctl update <이름> 또는 skillctl install |
| 심볼릭 링크 실패 (Windows) | doctor가 표시, defaultMode: copy 설정 |
| 연결된 에이전트 없음 | skillctl sync, ~/.skillctl/config.json에서 에이전트 활성화 |
Frozen install failed | 저장소가 동기화되지 않음, --frozen 없이 install 실행 |
참고 자료
- commands.md — 전체 명령어 치트 시트
- specifiers.md — 지정자 문법
- manifest-lock.md — 매니페스트 및 락 의미론
- workflows.md — 팀 온보딩, 마이그레이션, CI
- troubleshooting.md — doctor, Windows, 공존