Community라이팅 & 에디팅github.com

kricha/knowledge-capture

리포지토리 로컬 지식 캡처를 저장하는 에이전트 스킬입니다.

knowledge-capture란 무엇인가요?

이 스킬은 AI 에이전트가 작업 세션 중 발생하는 결정, 변경 사항, 발견 사항 및 후속 조치를 구조화된 마크다운 파일로 자동 캡처할 수 있도록 설계되었습니다. 주 목적은 작업 완료 후에도 컨텍스트 손실 없이 이후 요약, 재개 또는 핸드오프에 사용할 수 있는 정확한 로컬 지식 베이스를 유지하는 것입니다. Claude Code, Cursor, Codex 등의 플랫폼에서 작동하며, 활성 세션을 가리키는 `.ai/raw/active-session.json` 포인터를 사용합니다. 이 스킬은 작업과 관련 없는 캡처를 생성하지 않고, 활성 워크플로우의 기존 캡처를 업데이트하며, 의미 있는 작업이나 결정이 이루어졌을 때만 캡처합니다. 또한 스키마와 활성 세션 예시를 가이드로 제공하며, 민감한 콘텐츠를 제외하는 보호 장치를 포함하여 로컬에서 구조화된 지식 관리를 가능하게 합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add kricha/knowledge-capture

Installed? Explore more 라이팅 & 에디팅 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

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

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

지식 캡처(Knowledge Capture)

자동 사용

리포지토리 작업에 대한 최종 응답 전에, 파일이 변경되었거나, 테스트가 실행되었거나, 결정/발견/후속 조치가 이루어진 경우, 현재 세션/워크플로우에 대해 정확히 하나의 활성 session 캡처를 생성하거나 업데이트하십시오. 이 작업은 검증 후 및 백로그 정리나 승인 요청 전에 수행합니다.

스킬이 다시 호출되었다고 해서 새로운 캡처를 생성하지 마십시오. 이 워크플로우에 대한 활성 캡처 경로가 알려진 경우 해당 파일을 업데이트합니다. 그렇지 않으면 .ai/raw/active-session.json을 후보 활성 포인터로 읽습니다. 신뢰할 수 있는 활성 캡처가 없거나 워크플로우가 명확히 변경된 경우 새 원시 캡처를 생성하고 포인터를 교체합니다.

이후 사용을 위해 현재 작업의 충분한 세부 정보를 캡처합니다. 현재 워크플로우에 대한 활성 캡처만 읽거나 업데이트하며, v0.2에서는 관련 없는 캡처를 읽기, 업데이트, 중복 제거, 병합, 동기화, 커밋, 게시 또는 승격하지 않습니다.

헬퍼가 파일을 작성했다고 해서 캡처가 완료된 것은 아닙니다. 특히 '사용자 요청', '변경 사항 및 증거', '결정 및 발견 사항', '미해결 질문 및 다음 단계'와 같은 섹션에서 사실이 알려져 있음에도 Not captured.를 남기지 마십시오.

활성 캡처를 업데이트할 때는 현재 워크플로우 단계 이후의 전체 캡처를 작성합니다. 델타 전용 노트를 추가하지 마십시오. 현재 작업 컨텍스트, 보이는 파일, diff, 테스트, 명령 결과 및 핸드오프 텍스트를 증거로 사용합니다. 연속성이 명확하지 않은 경우 누락된 컨텍스트를 임의로 생성하지 말고 새 캡처를 생성합니다.

캡처를 모든 중간 사고가 아닌 현재 현실에 맞게 유지합니다. 이전 결정이 변경되고 작업도 함께 변경된 경우 최종/현재 결정과 증거를 캡처합니다. 대체된 결정은 구현된 코드, 롤백, 해결되지 않은 위험 또는 미해결 질문을 설명할 때만 유지하고, 순전히 이론적인 폐기된 옵션은 생략합니다.

캡처는 .ai/raw/<type-folder>/YYYY-MM-DDTHH-mm-ssZ--<type>--<topic-slug>.md에 저장합니다. 정확한 파일 이름이 이미 존재하는 경우 .md 앞에 --2, --3 등을 추가합니다.

유형: session -> sessions, discussion -> discussions, investigation -> investigations, decision -> decisions, handoff -> handoffs.

session 캡처의 경우 .ai/raw/active-session.json을 활성 워크플로우 캡처에 대한 로컬 포인터로 유지 관리합니다. 최종 응답 후마다 지우지 마십시오. 이는 재개, 압축 및 핸드오프를 지원합니다. 새 워크플로우 캡처가 시작될 때 교체합니다.

캡처(Capture)

/capture를 현재 세션 캡처 생성/업데이트로 취급합니다. /capture <type>을 해당 캡처 유형(session, discussion, investigation, decision 또는 handoff)으로 취급합니다.

컨텍스트 압축, 압축 또는 핸드오프 전에 의미 있는 작업이나 결정이 아직 캡처되지 않은 경우 먼저 캡처합니다.

Node를 사용할 수 있는 경우 의존성 없는 헬퍼가 첫 번째 캡처를 생성하거나, 알려진 활성 캡처를 --update <path>로 교체하거나, 포인터가 가리키는 캡처를 --update-active로 교체할 수 있습니다. --stdin을 통해 풍부한 섹션별 세부 정보를 전달하거나 마크다운을 직접 작성합니다. 헬퍼는 기본적으로 제목/요약 전용 캡처를 차단합니다(유용한 세션 지식이 손실되므로).

node .agents/skills/knowledge-capture/scripts/capture.js --type session --title "auth refresh token fix" --summary "Fixed expired refresh token behavior" --stdin
node .agents/skills/knowledge-capture/scripts/capture.js --type session --title "auth refresh token fix" --update .ai/raw/sessions/2026-07-04T18-22-10Z--session--auth-refresh-token-fix.md --stdin
node .agents/skills/knowledge-capture/scripts/capture.js --type session --title "auth refresh token fix" --update-active --stdin

stdin에 references/raw-capture-schema.md의 마크다운 제목을 제공합니다. Node 또는 셸 실행을 사용할 수 없는 경우 마크다운을 직접 생성하거나 업데이트합니다.

활성 세션 캡처에 대해 다음 순서를 사용합니다.

  1. 현재 컨텍스트에서 활성 경로를 알고 있으면 해당 경로를 업데이트합니다.
  2. 그렇지 않으면 .ai/raw/active-session.json을 후보 포인터로 읽습니다.
  3. 포인터와 런타임 모두 agent_session_id를 노출하고 일치하면 업데이트합니다.
  4. 세션 ID가 다르거나, 누락되었거나, 사용할 수 없지만 사용자 요청 또는 핸드오프가 명확히 동일한 워크플로우를 계속하는 경우 업데이트하고 포인터를 새로 고칩니다.
  5. 그렇지 않으면 새 캡처를 생성하고 포인터를 교체합니다. 최신 파일 이름 추측으로 선택하지 마십시오.

보호 장치(Guardrails)

  • 유용한 원시 세부 정보를 캡처하되, 대본, 큰 로그 및 전체 파일은 피합니다.
  • 변경된 파일, 테스트, 명령 및 증거를 변경 사항 및 증거 아래에 배치합니다. 여러 파일이 변경된 경우 목적별로 파일을 그룹화합니다.
  • 드물고, 명확하지 않거나, 결정과 관련된 명령/결과만 포함합니다. 나중에 중요하지 않은 일상적인 명령은 생략합니다.
  • 활성 캡처를 정확하고 유용하게 만들기 위해서만 재구성합니다. 사실을 임의로 만들거나 더 이상 유효하지 않은 이론을 여전히 사실인 것처럼 조용히 유지하지 마십시오.
  • agent_session_id를 워크플로우의 정의가 아닌 유용한 보호 장치로 취급합니다. 새 에이전트 세션이 동일한 워크플로우를 계속할 수 있습니다.
  • --agent-session-id는 런타임이 안정적인 현재 세션, 대화, 스레드 또는 실행 ID를 명확히 노출하는 경우에만 사용합니다. 사용할 수 없으면 생략합니다. 절대 임의로 생성하지 마십시오.
  • 비밀, 자격 증명, API 키, 개인 키, 고객 개인 데이터 및 관련 없는 개인 기억은 제외합니다.
  • 민감한 콘텐츠가 있는 경우 캡처를 생성하지 말고 먼저 추상적으로 요약합니다.
  • 원시/로컬 전용 상태는 캡처별 워크플로우 필드가 아닌 .ai/raw/ 경로 및 스킬 정책에서 비롯됩니다.
  • Node 헬퍼를 선택 사항으로 취급합니다. 직접 파일 생성도 여전히 유효합니다.

저장 후 경로, 유형 및 생성 또는 업데이트 여부를 보고합니다. 헬퍼가 캡처를 차단하는 경우 경고를 보고하고 원시 내용을 저장하지 마십시오.

참조(References)

  • references/raw-capture-schema.md는 수동으로 작성하거나 스키마를 변경할 때만 읽습니다.
  • references/active-session-example.md는 업데이트된 워크플로우 캡처가 어떻게 보여야 하는지 확실하지 않을 때 읽습니다.
  • references/agent-portability.md는 이 스킬을 다른 에이전트에 적용할 때만 읽습니다.

관련 스킬