manage-project-skills — 프로젝트 스킬 선택 및 감사

manage-project-skills — 프로젝트 스킬 선택 및 감사은(는) 무엇을 하나요?

0. 규칙 계층 구조 (먼저 읽으세요)

1. 권한 부여 (최우선, 예외 없음): 명시적인 사용자 승인 없이 설치/업데이트/제거, 프로젝트 파일 쓰기 금지; 예외: 승인된 원장 쓰기. 승인 = 특정 스킬 + 출처 + 범위; "내 스킬 관리"는 개별 항목을 승인하지 않습니다.
2. 프로세스: 선택된 모드(T0/T1/T2/감사)를 따르십시오; "금지된" 단계는 효율성을 위해 건너뛰지 않습니다.
3. 지침: 로컬 우선, 자제 — 이유를 명시하면 편차 허용.

핵심: 없는 것이 잘못 설치된 것보다 낫다 — 철회 ≈ 1분; 잘못된 설치 = 영구적인 컨텍스트 + 트리거 경쟁. 자제, 필수 정당성, 로컬 우선.

1. 모드

요구사항 불명확 ⇒ 전체 요구사항 파악 불가 ⇒ 시작 시 대량 설치 금지.

• T0 · 시작 인벤토리 (읽기 전용): 1-2단계 + 채팅 보고 ("포함됨 / 설치 안 함"). 설치/쓰기 없음; 원장 초기화 = 별도 승인된 쓰기. 커버리지 매트릭스 = 스택에서 추론 가능한 요구사항만. 빠른 경로: 원장 존재 && 스킬 언급 없음 ⇒ 원장만 읽기. 다음 경우 재인벤토리: 스킬 디렉토리 / AGENTS.md / lockfile / 에이전트가 변경됨 ∨ 원장 ≠ 디스크 ∨ 사용자 요청.
• T1 · 갭 중심 (작업 중): 먼저 분류. 일회성 답변 (API 세부사항, 단일 명령어) ⇒ 조회, 설치 안 함. 재사용 가능 (이 레포가 다시 접할 워크플로우/표준/도구 체인) ⇒ 스킬 하나 가져오기 ⇒ 기록. 진입은 AGENTS.md 규칙(MAINTENANCE.md 참조)에 의존하며, 모델 자체 평가에 의존하지 않습니다.
• T2 · 계획 확정: 일괄 설치, 각 후보는 확정된 계획에 의해 정당화되어야 함. 전체 1-7단계.
• 감사: 사용자가 검토/정리/정리 요청 ⇒ 마지막 부분 참조.

모든 모드는 프로젝트 원장 .agents/skills-rationale.md(승인된 경우)를 공유합니다; 먼저 읽으십시오.

2. 흐름

1. 프로젝트 프로파일링

있는 경우 읽기(추측하지 마세요): 매니페스트(package.json / pyproject.toml / go.mod / Cargo.toml / *.csproj); 레이아웃 + 모노레포 신호(workspaces, turbo.json); 인프라(.github/workflows, Dockerfile, vercel.json, wrangler.toml); README 헤드, docs/agents/.

2. 커버리지 인벤토리 (로컬 우선; 가져오기 전 중복 제거)

순서: 프로젝트 설치 → 전역 → 레지스트리. 두 가지 클래스:

• 개인 스킬: 전역, 프로젝트 간. 프로젝트에 중복하지 마십시오; 대상 에이전트를 기록하십시오. 전역 존재 ≠ 선언된 프로젝트 종속성.
• 프로젝트 중요: 워크플로우/전달이 이에 의존함. 출처 + 버전/커밋 + 복원 경로 기록 — 전역으로 설치된 경우에도; 새 머신은 전역을 상속하지 않습니다.

스캔: 프로젝트 디렉토리(.agents/skills, .opencode/skills, .claude/skills = 일반적인 예, 에이전트 문서당 확인; 도달 불가능 ⇒ "확인되지 않음", 절대 "스킬 없음" 아님); npx skills ls -g를 통한 전역; 출처 매니페스트 및 skills-lock.json(있는 경우 동기화). 출력: 커버리지 매트릭스(필요 → 충족 / 격차).

3. 신뢰할 수 있는 출처에서 격차 채우기

신뢰 계층: 공급업체 공식(anthropics/skills, openai/skills, supabase/agent-skills) > 원저자(mattpocock/skills, cursor/plugins) > 커뮤니티 > 확인 불가능(조사 강화). 그 외에는 npx skills find <kw> — 설치 횟수는 참조일 뿐, 신뢰가 아닙니다. 맞는 것이 없으면 그렇게 말하고 skill-creator 제안; 근접한 임시방편 금지.

4. 예산: 하드 상한 없음, 필요 기반

• 각 후보는 하나의 구체적인 이유 필요("프로젝트에 X가 있으므로 Y"); 이유 없음 ⇒ 제외.

• ~10개 후보 = 분석 버그 ⇒ 1-2단계 재감사.

• 경계 ⇒ "연기" 목록 (철회는 저렴함).
• 중복 제거 ≠ 자동 정리: 설명 중복 ⇒ 후보 그룹 ⇒ 트리거/입출력/부작용/의존성/버전 비교 ⇒ 대체 증거 + 사용자 승인이 있는 경우에만 병합/제거; 그렇지 않으면 둘 다 유지, 비교 대상으로 표시.

5. 보안 게이트: 설치 전, 사용자 승인

SKILL.md뿐만 아니라 전체 패키지 검토:

1. SKILL.md 전체 + 참조된 모든 파일/스크립트/설정/의존성 읽기; 스크립트별 확인: 실행 / 네트워크 / 쓰기 / 자격 증명.
2. 스캔 증거 기록: 스캐너 + 판정 + 일치하는 버전 + 날짜. 스캔 없음 = 알 수 없음, 안전하지 않음. 스캐너 불일치 ⇒ 목록 작성, 평균 내지 않음.
3. 스캔 없는 비공개 출처 ⇒ 수동 전체 파일 검토가 게이트를 대체하며, "스캔되지 않음"으로 표시.
4. 중간+ 위험 또는 설명되지 않은 동작 ⇒ 사용자가 결정; 불명확한 동안에는 아무것도 설치되지 않음.

6. 설치

# 에이전트 자동 감지 (감지 결과 사용자에게 보고); 다중 에이전트 머신: --agent 전달
npx skills add <owner/repo>@<skill> --copy -y

• 채널 2 — 버전 고정 / npm 도달 불가능 대체: gh skill install <owner/repo> <skill[@version]> --agent opencode (미리보기; 파일 복사, skills-lock 업데이트 없음 ⇒ 원장이 출처+버전 기록; 항상 --agent 전달 — 비대화형 기본값은 github-copilot). 스킬당 하나의 채널 — 혼합 금지.
• --copy = 스냅샷 격리, 버전 고정 아님: 업스트림 동기화 없음, 버전 정체성 없음, 재설치 시 변경됨. 재현 가능성 ⇒ 원장 기록: 출처 + 경로 + 버전/커밋 (+해시).
• 프로젝트 중요 워크플로우 스킬: --copy, 절대 심링크 금지 (심링크는 업스트림을 추적함).
• skills-lock.json 생성 ⇒ 커밋 (복원: npx skills experimental_install); .agents/가 gitignore되지 않았는지 확인.
• 효과는 다양함: OpenCode는 핫 리로드(확인됨); 다른 에이전트는 재시작이 필요할 수 있음 ⇒ 사용자에게 재시작 및 재확인 요청.
• GitHub 도달 불가능 ⇒ 보고 + 로컬 캐시 제안; 조용히 건너뛰지 마십시오.

7. 확인 및 기록 (네 계층; 누락된 계층 = "확인되지 않음")

• 파일: 존재, 경로 정확, 참조 완전
• 매니페스트: npx skills ls가 lockfile 및 디스크와 일치 (보이는 것 ≠ 로드 가능)
• 로드: 대상 에이전트가 실제로 스킬을 로드
• 동작: 대표적인 긍정 작업 하나가 작동
• 결정 사항(무엇/이유/연기/확인 대상) → .agents/skills-rationale.md에 기록
• 제거: npx skills remove <name> -y 선호 (매개변수는 npx skills --help 참조); 디렉토리만 삭제하지 마십시오 (lockfile 동기화 해제); 삭제 전 출처+버전 기록; 복구 불가능하면 백업; 이후 네 계층 재확인.

3. 감사 모드

이 스킬 자체를 포함합니다. 보고 → 사용자 승인 → 실행. 검사:

1. 중복: 설명 클러스터링 ⇒ 후보 그룹 ⇒ 트리거/입출력/부작용/의존성/버전 비교; 대체 증거 + 승인 ⇒ 병합/제거; 그렇지 않으면 둘 다 유지 (비교 대상). 유사성만으로 삭제 금지.
2. 충돌: 동일 시나리오 모순 ⇒ 인용 + 범위 기록 ⇒ 사용자 판단.
3. 비대: 사용 원격 측정 없음 — "트리거되지 않음" = 사용자 제공. 측정 가능: 설명 대비 기능, 더 높은 빈도 스킬과의 중복. 다운그레이드 ⇒ 상태 복원 경로.
4. 죽은 참조: 필요한 입력 (누락 = 차단) / 선택적 의존성 (없음 = 건너뜀) / 예상 출력 (런타임 생성; 없음 ≠ 오류). 죽은 참조 ⇔ 필요한 입력 누락 + 복구 불가능. 보고: 증거 → 권장 사항 → 영향 → 승인. 삭제 전: 복구 가능성 확인(npx skills find); 복구 불가능 ⇒ 백업 + 문의. 결과 → 원장.

4. 유지보수 및 시행

AGENTS.md 규칙 템플릿, 트리거 실패 진단 루프, 15개 시나리오 테스트 세트, 릴리스 흐름 → MAINTENANCE.md — 이 스킬을 편집하기 전/후에 실행하십시오.