딥시크 하니스의 Skill Provider는 프로젝트 루트, 사용자 루트, 공유 에이전트 루트, 사용자 지정 디렉터리를 구성 대상으로 다룰 수 있습니다. 다만 실제 기본 경로와 탐색 순서는 설치한 버전의 설정 문서와 도구 소스에서 다시 확인해야 합니다. 공식 배포 저장소의 스킬 구조도 함께 확인하는 것이 좋습니다. (공식 저장소)

프로젝트별 배치의 장점은 변경 이력을 코드와 함께 검토할 수 있다는 점입니다. 특정 브랜치가 특정 테스트 규칙을 요구한다면 Skill도 같은 브랜치에서 함께 바뀌어야 합니다. 반대로 사용자 전역 Skill은 여러 저장소에 즉시 적용할 수 있지만, 잘못된 지침이 예상하지 못한 프로젝트에 들어갈 수 있습니다.

단일 프로젝트 개발자

저장소 전용 빌드 명령, 테스트 순서, 코드 생성 규칙은 프로젝트 루트 가까이에 두는 편이 낫습니다. 새 팀원이 저장소를 내려받은 뒤 같은 Skill을 받을 수 있고, 변경 내용도 검토 요청에 포함할 수 있습니다.

장점은 세 가지입니다.

• 코드 버전과 Skill 버전을 함께 고정할 수 있습니다.
• 프로젝트별 경로와 도구를 명확히 적을 수 있습니다.
• 다른 저장소의 실행 방식에 영향을 주지 않습니다.

단점도 분명합니다. 여러 저장소에 같은 Skill을 복사하면 수정 누락이 생깁니다. 또한 SKILL.md 안에 개인 컴퓨터의 비밀키, 계정 이름, 절대 경로를 넣으면 저장소 유출 범위가 커집니다. Skill은 단순 메모가 아니라 에이전트의 행동을 바꾸는 지시 자산으로 취급해야 합니다.

주의: 저장소에 넣을 파일은 재현 가능한 규칙만 담으세요. 인증 정보는 환경 변수나 별도 비밀 관리 수단으로 분리하고, 커밋 전에는 Skill 파일도 일반 코드처럼 검토해야 합니다.

여러 프로젝트를 다루는 개인 사용자

사용자 전역 배치는 경로와 저장소에 의존하지 않는 기능에만 적합합니다. 예를 들어 일반적인 코드 리뷰 형식, 커밋 메시지 검사, 문서 표준처럼 어느 프로젝트에서도 같은 결과를 원하는 기능입니다.

전역 배치의 편의성은 업데이트 한 번으로 여러 프로젝트에 반영된다는 점입니다. 그러나 그 편의성이 곧 위험입니다.

• 설명이 넓은 Skill이 의도하지 않은 작업에 선택될 수 있습니다.
• 업데이트 후 여러 프로젝트의 결과가 동시에 달라질 수 있습니다.
• 프로젝트가 요구하는 이전 버전으로 되돌리기 어렵습니다.
• 전역 디렉터리에 쓰기 권한이 넓으면 다른 작업이나 계정이 내용을 바꿀 수 있습니다.

따라서 전역 Skill에는 특정 저장소 이름, 내부 명령, 사내 경로를 넣지 않는 것이 좋습니다. 그런 정보가 필요해지는 순간 프로젝트별 배치로 되돌리세요.

소규모 팀

팀에는 프로젝트별 설정과 읽기 전용 공유 원본을 결합한 이중 계층이 적합합니다. 공유 원본은 팀 표준을 관리하는 기준점으로 사용하고, 각 프로젝트는 승인된 버전을 참조하거나 동기화합니다.

공유 원본을 모든 맥의 전역 폴더에 복사하는 방식은 처음에는 간단합니다. 하지만 업데이트 시점이 달라지고, 누가 어떤 파일을 바꿨는지 추적하기 어렵습니다. 프로젝트에서 직접 수정할 수 있는 복사본과 공유 원본을 동시에 운영하면 더 큰 혼란이 생깁니다.

다음 조건으로 선택하면 됩니다.

• 한 저장소에서만 사용하고 저장소별 규칙이 다르면 프로젝트별을 선택합니다.
• 여러 프로젝트에서 같은 동작을 요구하고 경로 의존성이 없으면 사용자 전역을 선택합니다.
• 팀 표준이지만 프로젝트마다 적용 시점을 통제해야 하면 공유 원본과 프로젝트별 버전을 함께 둡니다.
• 실행 풀이 여러 개이고 재시작 뒤에도 같은 목록이 필요하면 환경 이미지나 초기화 자산에 포함합니다.
• 서로 다른 신뢰 경계의 프로젝트가 같은 맥을 사용하면 쓰기 가능한 전역 Skill을 피합니다.
• 오프라인 전달과 빠른 회귀가 중요하면 프로젝트 저장소에 승인된 사본을 고정합니다.

새 Skill이 보이지 않는다면 다음 순서로 확인하세요. 이 순서는 단순히 파일을 복사하는 것보다 원인을 빨리 좁힐 수 있습니다.

1. 현재 실행 위치가 의도한 프로젝트 루트인지 확인합니다.
2. Skill 디렉터리가 프로젝트 루트, 사용자 루트, 공유 에이전트 루트, 사용자 지정 경로 중 어디에 속하는지 확인합니다.
3. 폴더 안에 정확한 이름의 SKILL.md가 있는지 확인합니다.
4. 파일의 설명 영역에 문법 오류나 해석하기 어려운 특수 구문이 없는지 점검합니다.
5. DSH_HOME을 사용한다면 현재 셸과 실행 프로세스에 같은 값이 전달되는지 확인합니다.
6. 목록 명령 또는 Skill 도구로 현재 카탈로그를 다시 확인합니다.
7. 실행 중에 파일을 추가했다면 새 세션을 열고 다시 검사합니다.
8. 심볼릭 링크를 사용했다면 링크 대상의 소유자, 읽기 권한, 실제 경로를 확인합니다.
9. 원격 맥을 재시작한 뒤 동일한 Skill이 다시 발견되는지 확인합니다.
10. 다른 프로젝트를 열어 전역 Skill이 의도하지 않게 나타나지 않는지 확인합니다.

공개된 다른 터미널형 구현도 작업 공간과 사용자 영역을 나누어 Skill을 발견하고, SKILL.md를 각 Skill의 기준 파일로 사용합니다. 따라서 파일 이름과 배치 위치를 임의로 바꾸기보다 현재 구현의 탐색 규칙을 먼저 확인해야 합니다. (공개 터미널형 구현의 구성 예시)

경험상 중요한 점: 심볼릭 링크는 배포를 단순하게 만들 수 있지만 신뢰 경계를 없애지는 않습니다. 링크가 가리키는 원본이 수정 가능하면, 읽기 전용 폴더를 연결한 것처럼 보여도 실제로는 변경 가능한 지시 자산이 됩니다.

플랫폼 팀은 개인 홈 디렉터리를 배포 수단으로 삼지 않는 것이 좋습니다. 원격 지속 환경에서는 다음 세 가지 가운데 하나로 전달합니다.

• 실행 이미지에 승인된 Skill을 포함합니다.
• 초기화 단계에서 버전이 고정된 원본을 내려받습니다.
• 환경 생성 시 프로젝트 저장소의 승인된 디렉터리를 연결합니다.

클라우드 맥을 여러 명이 번갈아 사용한다면, 장비를 선택하는 단계에서 맥 미니 대여 가격과 운영 조건을 확인하는 것만으로 끝내면 안 됩니다. Skills 디렉터리를 어디에 배치하는지, 재시작 후 어떻게 복구하는지, 사용자 계정별 쓰기 권한을 어떻게 나누는지까지 인수 조건에 포함해야 합니다.

그 뒤에는 파일이 존재하는지만 보지 말고 실행 결과를 검증해야 합니다. 대표 테스트 작업을 하나 정하고, Skill이 목록에 보이는지, 실제 요청에서 필요할 때만 로드되는지, 다른 프로젝트에 영향을 주지 않는지 확인합니다. 세션 종료와 맥 재시작 뒤에도 같은 검사가 반복되어야 합니다.

공식 배포 저장소는 Skill 파일과 보조 스크립트를 함께 배포하는 구조를 보여 줍니다. 즉, SKILL.md만 복사하고 옆의 스크립트나 참고 파일을 빠뜨리면 설치는 성공한 것처럼 보여도 실제 작업은 달라질 수 있습니다. (공식 스킬 배포 자료)

Skill은 실행 명령, 파일 수정 방식, 도구 사용 순서를 에이전트에게 지시할 수 있습니다. 그러므로 다음 항목을 승인 절차에 넣어야 합니다.

• 출처와 커밋 또는 버전 식별자
• 파일 소유자와 그룹
• 디렉터리와 파일의 쓰기 권한
• 심볼릭 링크의 대상과 링크 탈출 여부
• 외부 명령, 네트워크, 비밀 정보 접근 여부
• 프로젝트 간 공유가 허용되는 신뢰 수준

특히 쓰기 가능한 전역 디렉터리는 편하지만 통제하기 어렵습니다. 개인용 테스트 환경에서는 허용할 수 있어도, 팀 실행 풀에서는 읽기 전용 공유 원본과 프로젝트별 승인본을 우선해야 합니다.

마지막에는 같은 작업을 세 번 실행하세요.

1. 프로젝트 전용 Skill만 있는 저장소에서 실행합니다.
2. 사용자 전역 Skill이 추가된 다른 저장소에서 실행합니다.
3. 원격 환경을 재시작한 뒤 다시 실행합니다.

각 단계에서 확인할 것은 네 가지입니다. 원하는 Skill이 발견되는가, 설명에 맞을 때만 로드되는가, 다른 프로젝트의 규칙이 섞이지 않는가, 재시작 후에도 같은 버전이 남는가입니다. 하나라도 실패하면 전역 공유를 확대하지 말고 프로젝트별 배치로 되돌리는 편이 안전합니다.

현재 개인 맥이나 일반적인 원격 환경에서 Skills를 관리하면 계정별 홈 디렉터리 차이, 수동 복사 누락, 재시작 뒤 복구 실패가 반복될 수 있습니다. 장기간 고정된 고부하 작업이나 물리 장치 연결이 필요하다면 직접 장비를 운영하는 편이 맞습니다. 반대로 여러 팀원이 짧게 검증하거나, 승인된 Skill 버전을 클라우드 맥에 전달하고 인수 시험까지 해야 한다면 KVMNODE의 맥 환경이 더 깔끔한 선택이 될 수 있습니다. KVMNODE의 맥 대여 안내를 확인할 때는 장비 자체보다 Skills 디렉터리, 버전, 권한, 재시작 복구 기록을 함께 전달받을 수 있는지 먼저 확인하세요.