설명

SEART CSV 내보내기(저장소 목록)를 수집하고, 각 저장소에서 SKILL.md 파일을 스캔하여 결과를 단일 출력 CSV로 내보냄으로써 SKILL.md 파일이 포함된 GitHub 저장소를 발견하고 단기 명단을 추출합니다.

이 스킬은 AI 코딩 에이전트와 자동화 스크립트가 속도 제한을 인식하고 재개 가능한 실행 방식으로 대규모 저장소 집합에 대해 반복 가능하고 읽기 전용인 마이닝을 수행하도록 설계되었습니다.

이 스킬을 사용해야 하는 경우

다음과 같은 경우에 이 스킬을 사용하세요.

SEART로 생성된 GitHub 저장소 식별자가 포함된 CSV 파일 폴더가 있는 경우
기본 이름이 SKILL.md인 파일이 포함된 저장소를 찾아야 하는 경우
이후 처리(다운로드, 파싱, 인덱싱)를 위해 단기 명단 CSV를 내보내야 하는 경우

내용 추출, 라이선스 준수 검토, 취약점 스캔 또는 저장소 수정에는 이 스킬을 사용하지 마십시오.

입력

필수

SEART CSV 폴더
- 하나 이상의 .csv 파일이 포함된 디렉터리 경로
- 각 CSV는 owner/repo 형식의 GitHub 저장소 식별자를 재구성할 수 있는 충분한 정보를 포함해야 합니다.
출력 CSV 경로
- 스캔 결과를 기록할 경로

선택적 구성

match_name: 기본값 SKILL.md
case_sensitive: 기본값 true
search_paths: 기본값 ["/SKILL.md"]
- 원하는 경우 공통 위치를 포함하도록 이 목록을 확장할 수 있습니다.
include_negative_results: 기본값 true
- false인 경우 일치하는 항목이 발견된 저장소만 출력합니다.
max_repos: 기본값 0 (제한 없음)
resume: 기본값 true
- 이전 출력 파일에서 계속 진행할 수 있습니다.
concurrency: 기본값 8
min_stars: 기본값 0
allow_forks: 기본값 true
allow_archived: 기본값 true

예상 CSV 스키마 (SEART)

SEART 내보내기는 다양합니다. 이 스킬은 여러 패턴을 지원합니다. 저장소는 다음 중 하나에서 파생될 수 있습니다.

권장 열 패턴

full_name (예: psf/requests)
repo (예: psf/requests)
repository (예: psf/requests)

대체 패턴

owner 및 name (owner/name으로 결합)
org 및 repo_name (org/repo_name으로 결합)
repo_owner 및 repo_name (repo_owner/repo_name으로 결합)
html_url 또는 url (https://github.com/owner/repo에서 owner/repo 추출)

파싱 규칙

공백을 제거합니다.
접미사 .git이 있으면 제거합니다.
https://github.com/owner/repo/...를 owner/repo로 정규화합니다.
모든 CSV에서 저장소를 중복 제거합니다.

CSV에서 지원되는 열을 찾을 수 없으면 입력 수준 오류를 기록하고 나머지 파일로 계속 진행합니다.

출력

출력 CSV: `skill_md_scan_results.csv`

저장소당 하나의 행이 있는 단일 CSV입니다(일치 경로당 여러 행을 내보내도록 선택하지 않은 경우).

권장 열

repo owner/repo 표준 식별자
source_csv 원본 SEART CSV의 파일 이름(병합된 경우 MULTIPLE)
found true|false
match_name 사용된 파일 이름 규칙, 일반적으로 SKILL.md
match_path 일치하는 경로(예: /SKILL.md)
default_branch 가능한 경우 기본 분기 이름
ref_scanned 사용된 분기 또는 커밋 참조(예: HEAD 또는 main)
match_url 찾은 경우 파일의 표준 URL
match_sha 가능한 경우 Git blob SHA
match_size_bytes 가능한 경우 크기
scan_method contents_api | code_search | sparse_checkout | local_clone
http_status 해당하는 경우 API 호출의 상태 코드
error_type none | not_found | rate_limited | auth | network | invalid_repo | other
error_message 간단한 오류 세부 정보, 비밀은 포함하지 마십시오.
scanned_at_utc ISO 타임스탬프
stars (선택 사항)
fork (선택 사항)
archived (선택 사항)

단기 명단 CSV (선택 사항)

include_negative_results=false인 경우 출력 자체가 단기 명단이 됩니다. 그렇지 않으면 두 번째 파일을 생성합니다.

skill_md_shortlist.csv에는 found=true인 항목만 포함됩니다.

기능

1) SEART CSV 폴더 수집

디렉터리(재귀적 선택 사항)에서 모든 .csv 파일을 찾습니다.
강력한 열 감지를 통해 저장소 식별자를 추출합니다.
표준 저장소 목록으로 중복 제거 및 정규화합니다.

2) 저장소에서 `SKILL.md` 스캔

이 스킬은 계층적이고 속도 제한을 인식하는 전략을 사용합니다.

계층 A (권장): GitHub Contents API

정확한 경로를 알고 있을 때 가장 빠르고 효율적입니다.

기본 분기 참조에 대해 후보 경로(기본값 /SKILL.md)를 확인합니다.
200은 찾음, 404는 찾지 못함으로 기록합니다.

계층 B (선택 사항): GitHub 코드 검색 (저장소 내 파일 이름 검색)

다음과 같은 경우에만 사용합니다.

하위 디렉터리에서 SKILL.md를 찾으려는 경우
대소문자를 구분하지 않는 일치를 원하는 경우
Contents API 경로를 알 수 없는 경우

권장 쿼리 형식:

repo:owner/repo filename:SKILL.md

계층 C (대체): 스파스 체크아웃 얕은 복제

API를 사용할 수 없거나, 속도 제한이 있거나, 검색 API 없이 GitHub Enterprise를 지원해야 하는 경우에만 사용합니다.

전체 기록과 큰 blob을 피하는 필터링된 복제를 수행합니다.
스파스 체크아웃을 사용하여 후보 경로만 가져옵니다.

3) 결과를 출력 CSV로 내보내기

작업 손실을 방지하기 위해 증분(스트리밍) 방식으로 출력을 기록합니다.
결정론적 열을 보장합니다.
이미 스캔된 저장소를 건너뛰어 재개 모드를 지원합니다.

워크플로

0단계: 사전 조건

읽기 전용 작업만 수행합니다.
많은 저장소를 스캔하는 경우 더 높은 속도 제한을 위해 GitHub 인증이 있는지 확인하십시오.

환경 옵션(우선 순위 순서로 해결):

--github-tokens ghp_tok1,ghp_tok2 CLI 플래그 — 다중 토큰 순환을 위한 쉼표로 구분된 목록 (토큰당 5000 req/hr)
--github-token ghp_tok CLI 플래그 — 단일 토큰 재정의
GH_TOKENS=ghp_tok1,ghp_tok2 — 환경 변수, 쉼표로 구분 (새로운 다중 토큰 변수)
GH_TOKEN=ghp_tok — 환경 변수, 단일 토큰 (이전 버전과 호환 가능)
GITHUB_TOKEN=ghp_tok — 환경 변수, 대체 단일 토큰
GitHub CLI gh auth login — 대화형 사용용
인증되지 않음 — 60 core req/hr만 가능 (대량 스캔에는 적합하지 않음)

여러 토큰이 제공되면 src/github_client/의 TokenPool이 자동으로 다음을 수행합니다.

각 요청에서 가장 높은 남은 할당량이 있는 토큰을 선택합니다.
X-RateLimit-* 응답 헤더에서 토큰별 할당량을 업데이트합니다.
현재 토큰이 소진되면 사용 가능한 다음 토큰으로 순환합니다.
모든 토큰이 소진되면 가장 빠른 재설정 시간까지 대기합니다.
대기가 구성 가능한 최대 시간을 초과하면 RateLimitExhaustedError를 발생시킵니다.

1단계: SEART CSV에서 저장소 목록 구축

입력 CSV를 열거합니다.
각 CSV에 대해:
- 저장소 열을 감지합니다.
- owner/repo를 추출하고 정규화합니다.
- source_csv를 추적합니다.
모든 파일에서 중복을 제거합니다.

2단계: 사전 점검

토큰 존재 여부를 확인합니다(인증되지 않은 경우 경고).
선택적으로 속도 제한 상태를 쿼리하고 보수적인 동시성을 설정합니다.

3단계: 각 저장소 스캔

각 owner/repo에 대해:

(선택 사항) 저장소 메타데이터 가져오기:
- 저장소가 존재하는지 확인합니다.
- 기본 분기, 보관 여부, 포크 여부, 별표를 기록합니다.
- 필터(별표, 포크, 보관)를 적용합니다.
계층 A를 사용하여 SKILL.md를 스캔합니다.
활성화되었고 필요한 경우 계층 B를 실행하여 더 깊이 검색합니다.
활성화되었고 필요한 경우 계층 C를 실행하여 대체합니다.
단일 최적 일치(또는 구성된 경우 모든 일치)를 기록합니다.
결과 행을 즉시 기록합니다.

4단계: 단기 명단 생성

found=true인 항목을 필터링합니다.
단기 명단 CSV를 내보냅니다.

5단계: 요약 보고

마지막에 다음을 보고합니다.

스캔된 총 저장소 수
발견된 개수 및 백분율
error_type별 오류 분석
유효 스캔 속도 및 발생한 속도 제한

사용 예

예 A: 정확한 루트 경로만 스캔 (빠름)

입력:
- seart_dir = data/seart_csvs/
- search_paths = ["/SKILL.md"]
출력:
- outputs/skill_md_scan_results.csv

예 B: 저장소 어디에서나 `SKILL.md` 찾기

입력:
- 코드 검색 활성화
- case_sensitive=false
출력:
- outputs/skill_md_scan_results.csv
- outputs/skill_md_shortlist.csv

예 C: 부분 스캔 재개

outputs/skill_md_scan_results.csv가 이미 존재하면 이미 있는 저장소를 건너뛰고 계속 진행합니다.

운영 제약 및 보호 장치

읽기 전용

커밋을 푸시하거나, PR을 열거나, 이슈를 생성하거나, 저장소 내용을 수정하지 마십시오.
선택한 출력 폴더 외부의 사용자 디렉터리에 쓰지 마십시오.

속도 제한 및 정중한 스캔

복제보다는 Contents API 확인을 선호합니다.
제한된 동시성과 지수 백오프를 다음에 사용합니다.
- 403 2차 속도 제한
- 429 요청이 너무 많음
부분 진행 상황을 지속적으로 저장합니다.

데이터 최소화

대체가 필요하지 않은 한 전체 저장소를 다운로드하지 마십시오.
로그 또는 출력 CSV에 토큰, 쿠키 또는 원시 인증 헤더를 저장하지 마십시오.

재현 가능성

scanned_at_utc 및 ref_scanned를 기록합니다.
구성(경로, 대소문자 구분, 활성화된 계층)을 출력과 함께 유지합니다.

오류 처리 규칙

저장소 파싱 오류

행을 owner/repo로 파싱할 수 없으면 버리고 CSV당 행 수준 파싱 오류 요약을 기록합니다.

누락되었거나 비공개 저장소

저장소가 404이거나 액세스할 수 없는 경우:
- error_type=invalid_repo 또는 error_type=auth
- found=false

일시적 오류

네트워크 시간 초과, 5xx 응답:
- 백오프와 함께 재시도
- 여전히 실패하면 error_type=network로 표시하고 계속 진행

속도 제한

속도가 제한된 경우:
- 동시성 감소
- 백오프 및 재시도
- 여전히 차단되면 error_type=rate_limited 기록

권장 기본 구성

match_name = "SKILL.md"
case_sensitive = true
search_paths = ["/SKILL.md"]
include_negative_results = true
resume = true
concurrency = 8
활성화된 계층:
- 계층 A: 켜짐
- 계층 B: 꺼짐 (필요한 경우에만 활성화)
- 계층 C: 꺼짐 (필요한 경우에만 활성화)

완료 조건

출력 CSV가 존재하고 스캔된 각 저장소에 대해 하나의 행을 포함하거나(또는 구성된 경우 발견된 저장소만) 포함합니다.
found=true 행에는 작동하는 match_url 및 match_path가 포함됩니다.
스캔은 행을 중복하지 않고 재개할 수 있습니다.
요약 통계가 보고되고 오류 분석을 사용할 수 있습니다.

다운스트림 처리를 위한 참고 사항

이 스킬에서 생성된 단기 명단은 이후 파이프라인 단계의 입력으로 사용됩니다. 예를 들어:

SKILL.md 내용 다운로드 및 파싱
구조화된 섹션(설명, 기능, 워크플로, 제약 조건) 추출
저장소별 에이전트가 검색 가능한 스킬 데이터 세트 구축

다운스트림 단계는 SKILL.md 내용을 신뢰할 수 없는 입력으로 처리하고 사용 전에 추출된 텍스트를 삭제해야 합니다.

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

문서

설명