Tracked Repositories

팀 공유와 손쉬운 업데이트를 위해 --track으로 설치한 git repo.

언제 중요한가요?

Tracked repo는 조직이 공유 skill을 배포하는 방법입니다. --track으로 한 번 설치하면 단일 명령으로 업데이트할 수 있습니다. 변경 사항은 관리자의 repo에서 모든 팀원에게 흘러갑니다.

개요

Tracked repository는 .git 디렉터리를 그대로 보존한 채 source에 clone된 git repo입니다. 이를 통해 다음이 가능합니다:

• 팀 공유: 모두가 같은 repo를 설치
• 손쉬운 업데이트: skillshare update <name>이 git pull을 실행
• 버전 관리: 어떤 커밋에 있는지 추적

---

일반 Skill vs Tracked Repo

측면	일반 Skill	Tracked Repo
Source	source로 복사됨	.git과 함께 clone됨
Update	install --update	update <name> (git pull)
접두사	없음	_ 접두사
중첩 skill	평탄화됨	__로 평탄화됨

---

Tracked Repo 설치하기

skillshare install github.com/team/shared-skills --track
skillshare sync

일어나는 일:

1. repo가 ~/.config/skillshare/skills/_team-shared-skills/로 clone됨
2. .git 디렉터리가 보존됨
3. clone 디렉터리가 관리되는 .gitignore 블록에 추가되어 머신 로컬 상태로 유지되며, 중첩된 git repo로 커밋되지 않음
4. 활성 install 임계값(audit.block_threshold 또는 --threshold)을 사용해 전체 repo가 보안 감사됨
5. AI CLI를 위해 중첩된 skill이 평탄화됨

발견 사항이 임계값에 도달하면 --force를 사용하지 않는 한 설치가 차단됩니다. 차단 시 skillshare는 clone된 repo를 자동으로 제거합니다. 정리에 실패하면 수동 정리를 위한 정확한 경로를 명령이 보고합니다.

---

언더스코어 접두사

Tracked repo는 일반 skill과 구분하기 위해 _ 접두사가 붙습니다:

~/.config/skillshare/skills/
├── my-skill/           # Regular skill (no prefix)
├── code-review/        # Regular skill
└── _team-skills/       # Tracked repo (underscore prefix)

디렉터리 이름은 소유자와 repo 이름으로 정해집니다(_<owner>-<repo>). 그래서 alice/skills와 bob/skills는 각각 _alice-skills, _bob-skills로 설치되어 충돌하지 않습니다. 다른 이름을 쓰려면 --name을 사용하세요. 이전에 설치한 repo는 기존 이름을 유지합니다.

--into로 설치한 tracked repo는 devops/_team-skills/처럼 폴더 안에 놓입니다. 그래도 하나의 repo로 취급됩니다. 안에 있는 skill은 그 아래로 묶이고, status에서도 집계되며, 업데이트나 제거할 때는 devops/_team-skills라는 이름을 사용합니다. 최상위 아래에서는 git clone된 _ 폴더만 tracked repo로 간주되므로, devops/_drafts/ 같은 일반 폴더는 그대로 일반 폴더입니다.

---

중첩 Skill과 자동 평탄화

skill repo는 종종 폴더 안에 skill을 정리합니다. skillshare는 AI CLI를 위해 이를 자동으로 평탄화합니다:

SOURCE                              TARGET
(your organization)                 (what AI CLI sees)
────────────────────────────────────────────────────────────
_team-skills/
├── frontend/
│   ├── react/          ───►   _team-skills__frontend__react/
│   └── vue/            ───►   _team-skills__frontend__vue/
├── backend/
│   └── api/             ───►   _team-skills__backend__api/
└── devops/
    └── deploy/         ───►   _team-skills__devops__deploy/

• _ prefix = tracked repository
• __ (double underscore) = path separator

왜 자동 평탄화인가?

이점	설명
AI CLI 호환성	대부분의 AI CLI는 중첩 폴더가 아닌 평평한 디렉터리에 skill이 있기를 기대합니다
조직 구조 보존	CLI 요구 사항을 충족하면서 source에서는 논리적인 폴더 구조를 유지합니다
추적성	평탄화된 이름이 출처 경로를 보여줍니다 (예: _team__frontend__react → _team/frontend/react/에서 왔음을 알 수 있음)
수작업 불필요	skillshare가 sync 중에 자동으로 변환을 처리합니다

여러분은 정리하고, skillshare는 맞춥니다. 어떤 폴더 구조로든 skill을 작성하세요. 어디서든 동작할 것입니다.

팁

자동 평탄화는 모든 skill에 적용되며, tracked repo에만 국한되지 않습니다. 개인 skill도 폴더로 정리할 수 있습니다. 폴더로 정리하기를 참고하세요.

---

새 Clone 이후 복구하기

Tracked repo clone 디렉터리는 자체 .git 디렉터리를 포함하기 때문에 의도적으로 git에서 무시됩니다. 새 머신에서 skillshare source repo를 clone하거나 pull하면, _team-skills/ clone 디렉터리가 아직 없는 상태에서 .metadata.json이 이미 tracked repo를 선언하고 있을 수 있습니다.

메타데이터로부터 누락된 tracked repo clone을 재생성하려면 인자 없이 install을 실행하세요:

skillshare install
skillshare sync

Project mode의 경우 다음을 실행하세요:

skillshare install -p
skillshare sync -p

status, check, update --all, doctor는 누락된 tracked repo clone을 보고하며, 조용히 무시하는 대신 skillshare install을 제안합니다.

---

Tracked Repo 업데이트하기

단일 repo

skillshare update _team-skills
skillshare sync

모든 tracked repo

skillshare update --all
skillshare sync

일어나는 일:

격리 후보 → git pull → 감사 → 승인한 commit 게시

업데이트 중 보안 동작:

• 격리된 후보에서 pull과 감사를 실행하며 기존 target 링크는 기존 checkout을 계속 읽습니다.
• Sparse-checkout 선택 범위와 기존 integrity hashes를 유지합니다. 해석할 수 없거나 후보 밖을 가리키는 symlink는 스캔 오류로 업데이트를 거부합니다.
• 차단에는 활성 임계값(audit.block_threshold 또는 --threshold/-T)을 사용합니다.
• TTY 모드에서는 임계값 이상의 findings에 대한 확인을 요청합니다. 비 TTY 모드에서는 기본적으로 후보를 거부합니다.
• 거부 또는 스캔 오류 시 기존 checkout과 metadata가 유지됩니다. --force는 스캔 오류를 무시할 수 없으며 --skip-audit는 스캔을 비활성화합니다.
• 승인한 정확한 commit을 게시하며 upstream에서 다시 pull하지 않습니다. 게시는 여러 파일의 원자적 전환이 아닙니다.

---

제거하기

skillshare uninstall _team-skills

일어나는 일:

1. 커밋되지 않은 변경 사항이 있는지 확인하고, 변경 사항이 있거나 git status를 읽을 수 없으면 중단 (--force로 무시)
2. 디렉터리를 휴지통으로 이동 (7일 보관)
3. 다음 sync에서 target의 symlink 제거

---

Project Mode

Tracked repo는 project mode에서도 동작합니다. repo는 .skillshare/skills/에 clone되어 .skillshare/.gitignore에 추가됩니다 (tracked repo의 git 히스토리가 여러분 프로젝트의 git과 충돌하지 않도록). Project 로그(.skillshare/logs/), trash(.skillshare/trash/), backup(.skillshare/backups/), 설치 메타데이터(.skillshare/skills/.metadata.json)도 기본적으로 무시됩니다.

Tracked repo를 설치하면 .skillshare/.metadata.json에 tracked: true가 자동으로 기록되어, 새 팀원이 skillshare install -p를 통해 올바른 clone 동작을 얻을 수 있습니다:

{
  "skills": [
    {
      "name": "_team-shared-skills",
      "source": "github.com/team/shared-skills",
      "tracked": true
    }
  ]
}

# Install tracked repo into project
skillshare install github.com/team/shared-skills --track -p
skillshare sync

# Update via git pull
skillshare update team-skills -p
skillshare sync

# Force update (discard local changes)
skillshare update team-skills -p --force

# Uninstall
skillshare uninstall team-skills -p

디렉터리 구조:

<project-root>/
└── .skillshare/
    ├── .gitignore           # Contains: logs/, trash/, skills/.metadata.json, and skills/_team-skills
    └── skills/
        └── _team-skills/    # Tracked repo with .git/ preserved
            ├── .git/
            ├── frontend/ui/
            └── backend/api/

프로젝트 로그를 의도적으로 커밋하고 싶다면, .skillshare/.gitignore의 관리 블록 뒤에 !logs/와 !logs/*.log를 추가하세요.

중첩 skill은 global mode와 동일한 방식으로 자동 평탄화됩니다 — _team-skills/frontend/ui는 target에서 _team-skills__frontend__ui가 됩니다.

---

커스텀 이름

skillshare install github.com/team/skills --track --name acme-skills
# Installed as: _acme-skills/

--track --name의 이름 제약 조건:

• _로 시작하는 tracked repo 디렉터리 이름으로 해석되어야 합니다.
• 경로 구분자(/, \)나 상위 디렉터리 탐색(..)을 포함할 수 없습니다.
• 유효하지 않은 이름은 clone 전에 거부됩니다.

---

브랜치 추적

저장소의 특정 브랜치를 추적할 수 있습니다:

skillshare install github.com/team/skills --track --branch frontend

Tracked repo는 clone된 뒤 지정된 브랜치를 따릅니다. skillshare update를 통한 업데이트는 자동으로 해당 브랜치에서 pull합니다.

동일한 repo를 여러 브랜치로 설치하려면, 이름 충돌을 피하기 위해 --name을 사용하세요:

skillshare install github.com/team/skills --track --branch frontend --name team-frontend
skillshare install github.com/team/skills --track --branch backend --name team-backend

브랜치는 일반(tracked가 아닌) install에서도 동작합니다:

skillshare install github.com/team/skills --branch develop --all

브랜치는 skill 메타데이터에 유지되므로, skillshare update와 skillshare check가 자동으로 올바른 브랜치를 사용합니다.

재현 가능한 설치를 위해 --branch는 tag 또는 commit SHA도 허용합니다:

skillshare install github.com/team/skills --branch v1.2.0 --all
skillshare install github.com/team/skills --branch 8f14e45 --all

tag와 commit SHA는 --track과 함께 사용할 수 없습니다. tracked repo는 브랜치에서 pull하는데, detached 체크아웃에는 pull할 대상이 없습니다. tag나 SHA를 고정하려면 일반 install을 사용하세요.

---

충돌 감지

여러 skill이 같은 name 필드를 공유할 때, sync는 include/exclude 필터가 적용된 후 실제로 동일한 target에 도달하는지 확인합니다.

필터가 충돌을 격리함 — 아무것도 출력되지 않습니다. 해당 skill은 같은 target에 도달하지 않습니다.

충돌이 동일한 target에 도달함 — 실행 가능한 경고입니다:

! 1 duplicate skill names detected
  ui                              _team-a/ vs _team-b/
  Rename one in SKILL.md or adjust include/exclude filters
  1 name collision(s) excluded

target_naming: prefixed에서는 tracked skill이 이미 그 접두사 이름을 가진 skill과 충돌할 수도 있습니다(_alpha/prototype은 alpha-prototype이 됩니다). tracked skill은 SKILL.md에서 이름을 바꿀 수 없으므로 sync는 다른 skill의 이름을 바꾸거나 --name으로 repo를 다시 track하도록 안내합니다.

모범 사례 — skill에 네임스페이스를 부여하거나 필터를 사용하세요:

# Option 1: Namespace in SKILL.md
name: team-a-ui

# Option 2: Route with filters (global config)
targets:
  codex:
    path: ~/.codex/skills
    include: [_team-a__*]
  claude:
    path: ~/.claude/skills
    include: [_team-b__*]

# Option 2: Route with filters (project config)
targets:
  - name: claude
    exclude: [codex-*]
  - name: codex
    include: [codex-*]

전체 문법과 예시는 Target Filters를 참고하세요.

---

참고

• install — --track으로 설치
• update — 최신 변경 사항 pull
• check — 사용 가능한 업데이트 확인
• Organization-Wide Skills — 팀 공유 가이드