Skill Miner
과거 코딩 에이전트 세션에 묻혀 있던 신호를 새롭거나 기존의 "Agent Skills"로 바꿉니다. 세션이 스킬이 되려면 다음 게이트를 통과해야 합니다. 반복 가능 AND (개선 여지 있음 OR 반복 요청) :
- 반복 가능 — 작업이나 지식이 반복되거나, 명백히 반복될 가능성이 있습니다. 과거 반복이 가장 강력한 증거이지만, 그럴듯하게 반복될 작업도 포함됩니다; 진정한 일회성 작업은 절대 포함되지 않습니다. (필수.)
- 개선 여지 있음 — 의미 있는 피드백이 있어서 다음 번이 첫 번째보다 나아집니다:
- 환경 피드백 — 작업을 실행하면서 드러난 것들: 실패, 이 환경의 반복적인 특성, 우회 경로와 지름길, 어렵게 얻은 경험 법칙. 이것들은 말 그대로 스킬입니다.
- 사용자 피드백 — 사용자는 전문가이며 그들의 피드백은 드뭅니다; 사용자의 지식을 활용하기 위해 이를 발굴하세요 (수정, 사용자가 알고 있던 더 나은 방법, 우리가 잘못 알고 있던 사실).
- 반복 요청 — 사용자가 동일한 것을 계속 요청합니다; 한 번 추출해서 다시 요청할 필요가 없게 만듭니다.
파이프라인: 발견 → 추출(저비용 LLM, 대화별) → 그룹화, 판단 및 생성.
0. 사전 요구사항
소형 LLM에 접근 가능해야 합니다. 먼저 확인하세요:
python3 scripts/llm.py --check # 사용할 백엔드를 출력하거나, 활성화 방법을 알려줍니다.
OPENAI_API_KEY / GEMINI_API_KEY / OPENROUTER_API_KEY 중 하나를 설정하거나, PATH에 claude / codex / gemini CLI가 있어야 합니다. 모델을 재정의하려면 SKILL_MINER_MODEL을, 백엔드를 강제하려면 SKILL_MINER_LLM을 설정하세요.
1–2. 파이프라인 실행 (스크립트가 저비용 LLM 작업을 처리합니다)
작업 디렉토리를 실행 디렉토리로 유지하세요: 모든 아티팩트는 ./out 아래에 생성됩니다.
OUT=./out
python3 scripts/discover.py --since 35 --out $OUT/inventory.jsonl # 에이전트별 트랜스크립트 찾기
python3 scripts/extract.py --inventory $OUT/inventory.jsonl --out $OUT/conversations.jsonl --workers 10
discover.py는common.py:ADAPTERS의 각 어댑터(Claude Code, Codex, opencode; 여기에 더 추가 가능)를 탐색하고 최근--since일 이내의 세션을 유지합니다. 사용자가 더 요청하지 않는 한 최대 100개의 대화로 시작하세요. 빠른 샘플링을 위해extract.py에--limit 15를 추가하세요.extract.py는 각 대화를 파싱하고 JSONL 행 하나를 생성합니다:agent, session_id, path, main_dir, datetime, n_user_turns, topics[], tasks[], skills_used[], env_feedback[], user_feedback[].main_dir= 대부분의 작업이 발생한 가장 깊은 폴더 (편집/읽기/참조된 파일에서 추론), 실행 cwd가 아닙니다.topics는 범위입니다 (보통 하나 — 그룹화를 위한 헤드라인 역할).tasks,env_feedback,user_feedback은 저비용 LLM이 사용자 자신의 말에서 복사한 짧은 배열입니다 (일반적인 세션에서 각[]) — 이는 게이트의 세 가지 차원에 매핑됩니다. 저비용 호출은 사용자 턴만 보므로,env_feedback은 사용자가 실행된 것에 대해 말한 내용이지 원시 도구 출력이 아닙니다 — 4단계에서 확인하세요.
3. 대화 그룹화
conversations.jsonl을 읽으세요 — 세션당 한 행입니다. 100행 이하에서는 전체 파일이 컨텍스트에 들어가므로 한 번에 읽으세요. (더 많이 발굴했다면 jq/grep으로 env_feedback / user_feedback이 비어 있지 않은 행을 먼저 살펴본 다음, 흥미로운 부분을 읽으세요.) topics가 <error>이거나 사소하거나 비어 있는 행은 무시하세요.
작업 유형별로 클러스터링하세요 — 디렉토리만이 아닌 작업의 종류 (예: "CI 배포 디버깅", "설정 UI 반복 작업", "의존성 마이그레이션") — 이를 통해 차원 1(반복 가능) 을 판단합니다: 어떤 작업이 반복되거나 명백히 반복될 수 있는지. 그런 다음, 행 전체에서 다른 두 가지 차원을 수집하세요:
- 차원 2 — 다음 번에 작업을 더 잘 수행할 방법을 가리키는
env_feedback및user_feedback(환경 피드백을 먼저 제시). 어렵게 얻은 하나의 교훈은 주변에 클러스터가 없어도 하나의 리드입니다. - 차원 3 — 많은 세션의
tasks에서 반복되는 세부 사항 (사용자가 동일한 것을 계속 요청함).
일회성 설정 단계와 단독으로 나온 우연한 언급은 제쳐두세요. 짧은 메모를 유지하세요: 명명된 그룹, 각각의 대화 수, 지배적인 main_dir(들), 그룹이 가진 피드백/반복 요청, 다음 단계에서 증거로 열어볼 몇 가지 예시 path.
4. 판단 및 생성
references/quality-bar.md를 읽고 해당 게이트를 적용하세요: 반복 가능 AND (피드백 OR 반복 요청).
- 전체 상황을 파악하세요. 확장할 수 있는 기존 스킬이 있는지 확인하세요 — 특히 피드백이 부족함을 나타내는 스킬이 있다면; 후보가 이와 중복되면 해당
SKILL.md를 열고 그 자리에서 편집하세요. 스킬 파일 경로를 찾으려면:
편집할 파일을 찾는 용도로만 사용하세요; 컨텍스트는 전체 상황에 대한 진실 공급원(source of truth)으로 남습니다. 후보가 특정 저장소에 초점을 맞추고 있다면 해당 저장소에 이미 존재하는 Markdown 문서(python3 scripts/skills_inventory.pyREADME.md, 디자인 문서, 계획)를 확인하세요; 반복되는 지식이 스킬 대신 해당 문서에 속한다면 보고서에서 사용자에게 이를 권장하세요. - 트랜스크립트로 확인하세요. 각 리드에 대해 1-3개의 예시 트랜스크립트(
path필드)를 열어 신호가 실제인지 확인하고 구체적인 내용을 포착하세요 — 정확한 규칙, 정확한 오류와 해결 방법, 사용자가 지적한 더 나은 경로, 반복 요청. 수정 사항 주변과[skill used: X]마커 주변의 사용자 말을 읽으세요. 요약된 행은 사용자 턴만 보여주므로, 트랜스크립트는 환경이 실제로 무엇을 했는지 확인하는 곳입니다. 반복적인 특성(기록)과 일회성 설정(기껏해야 한 줄짜리 함정)을 구분하세요. - 게이트에 따라 결정하세요. 리드는 반복 가능하고 개선 여지(피드백) 또는 반복 요청 중 하나가 있을 때만 스킬이 됩니다. 세 가지 차원은 동일한 비중을 가집니다 — 작업이 한 번만 나타났다고 해서 어렵게 얻은 교훈을 버리지 마세요. 명백히 반복된다면 포함하고, 개선할 점도 반복 요청도 없는 반복 가능한 작업은 출시하지 마세요.
- 최대 5개의 스킬을 생성/수정하세요. 각각을 구체적인 내용으로 작성하세요: 규칙, 트리거, 단계/명령어, 특성 및 해결 방법 — 파일 경로는 저장소 루트 기준 상대 경로(
src/pages/Run.tsx)로 작성하고, 트랜스크립트에서 복사한 머신별 절대 경로(/home/<user>/…)는 사용하지 마세요. 배치 위치:- 기존 스킬 확장 → 스킬 경로에서 그 자리에서 편집하세요. 포크하거나 복사하지 마세요.
- 완전히 새로운 스킬 →
~/.agents/skills/generated-skills/<name>/아래에 작성하고, 사용자가 검토하고 승격할 수 있도록 스테이징하세요 — 새 스킬을 라이브 홈에 직접 넣지 마세요.
- 보고하세요. 생성/수정한 항목과 각 항목이 어떤 차원에서 비롯되었는지 나열하세요. 주목할 만한 거부된 각 후보에 대해 놓친 차원을 한 줄로 설명하세요. 스킬 변경 대신 또는 추가로 업데이트해야 한다고 생각되는 저장소 문서를 포함하세요.
다른 에이전트로 확장
각 에이전트는 트랜스크립트를 다르게 저장합니다. 새로운 에이전트(Gemini CLI, Cursor 등)를 지원하려면 common.py:ADAPTERS에 (discover_fn, parse_fn) 쌍을 추가하여 정규화된 레코드(_norm(...))를 생성하세요. 나머지 파이프라인은 변경되지 않습니다. Cursor(sqlite state.vscdb)는 아직 연결되지 않았습니다 — opencode의 어댑터가 DB 기반(SQLite) 템플릿으로 참고할 수 있습니다.
참고 사항
- 트랜스크립트에 대해 읽기 전용입니다; 유일한 쓰기 작업은
--out아티팩트와 생성 또는 개선하기로 선택한 스킬입니다 — 새 스킬은~/.agents/skills/generated-skills/아래에 스테이징되고, 편집은 기존 스킬에서 제자리에서 이루어집니다. - 하위 에이전트/리뷰 스레드(Claude Code sidechain, Codex
thread_source: subagent)는 필터링됩니다 — 실제 사용자 대화만 발굴됩니다.
결과 보기
독립 실행형으로 실행하면 결과는 일반 파일입니다: ./out 아래의 아티팩트와 변경한 스킬(제자리 편집 또는 generated-skills/ 아래에 스테이징). 이 스킬은 또한 Skill Studio와 함께 제공됩니다. 이 데스크톱 앱에서 사용자는 실행을 실시간으로 보고, generated-skills/ 아래에 스테이징된 각 새 스킬을 제안됨 카드로 검토하여 수락 또는 폐기할 수 있으며, 제자리 편집을 git 추적 변경 사항으로 보고 버전으로 저장하거나 되돌릴 수 있습니다.