knowledge-cite — 지식 저장소에서 verbatim 인용 포함 아티팩트 만들기

무엇을 하는 스킬인가

~/.claude/knowledge/ 에 정리된 카드·원본 소스·이미지 풀(현재 규모: wc -l ~/.claude/knowledge/summaries/cards.jsonl로 확인)에서 필요한 근거를 안전하게, 순서대로, 인용 왜곡 없이 꺼내와 컨텐츠 아티팩트 (블로그/카드뉴스/뉴스레터/교안/링크드인 글/PPTX/웨비나/숏폼/제안서 등)를 만든다.

언제 이 스킬을 사용하는가

아래 어느 하나라도 해당되면 이 스킬의 4단계 프로토콜을 반드시 따른다.

1. 사용자 요청에 컨텐츠 산출물 동사가 포함됨 — "만들어줘 / 써줘 / 작성해줘 / 초안 / 카드뉴스 / 블로그 / 뉴스레터 / 스레드 / 숏폼 / 교안 / 제안서 / 링크드인 글"
2. 주제 키워드가 포함됨 — 카드뉴스·블로그·뉴스레터·스레드·숏폼·AI 활용·프롬프트· 젠스파크·마케팅·AX·B2B·퍼널·콘텐츠 전략·SEO/AEO·데이터 분석·시각화·태블로· 링크드인·퍼스널브랜딩·커리어·이직·소프트스킬·DOOH·강의·교안·웨비나
3. 개인 강의·링크드인·브런치·뉴스레터 자료를 근거로 인용해야 하는 모든 경우

단, 코드/엔지니어링 작업(버그 수정, 빌드, 리팩토링 등)에는 사용하지 않는다.

4단계 프로토콜 (고정 순서 · 건너뛰기 금지)

Step 1  /knowledge-query "키워드"       (grep-only, body 미열람)
Step 2  knowledge-retriever mode:recommend   (Haiku, frontmatter만)
Step 3  ★ 사용자 확인 게이트 ★            (rank 중 명시적 선택 필수)
Step 4  knowledge-retriever mode:extract     (verbatim 인용 + 이미지)

Step 1 — 후보 스캔 (grep only)

python ~/.claude/skills/knowledge-query/scripts/query.py "키워드"
# 또는 토픽 지정: --topic ai-basics | marketing-ai | linkedin-branding 등

반환: 토픽 × 카드 × 이미지 개수 맵. 카드 body 는 절대 읽지 않는다.

Step 2 — recommend (Haiku 서브에이전트)

knowledge-retriever 에이전트를 mode: recommend 로 호출.

• 입력: Step 1 키워드 + 작업 의도 요약 (한 문장)
• 동작: summaries/cards.jsonl 전체 카탈로그를 Read 하여 의미 기반으로 랭킹 (title/summary/tags/aliases/keywords 필드 활용). Step 1 grep 히트는 boost 신호일 뿐, 후보를 grep 결과로 제한하지 않는다.
• 1-hop 그래프 확장: top 후보의 catalog related 리스트에서 보완재 (개념 카드 ↔ 사례/실전 카드)를 찾아 같은 plan에 짝지어 넣는다
• plan 다양성: 3개 plan은 서로 보완적 (같은 소스의 변형 3개 금지)
• 출력: rank 1/2/3 extract plan, 각 plan 에 cards, slide_files, image_candidates, 한 줄 rationale
• 제약: 카탈로그 + 카드 frontmatter/요약만 본다. body·slide 원문은 안 본다.
• 항상 Haiku. 비싸지 않다.

Step 3 — 사용자 확인 게이트 (필수)

추천 3개 plan 을 짧게 요약해 사용자에게 제시하고 명시적 선택을 받는다.

사용자 응답 예시:

• 1 — rank 1 채택
• 1,2 — rank 1+2 병합
• all — 3개 모두
• "rank 2 에서 linkedin-branding 카드만 빼고" — free-form 조정

묵시적 통과 금지. 사용자 턴이 실제로 돌아와야 다음 단계로 간다.

Step 4 — extract (Haiku 기본, Sonnet 에스컬레이션)

knowledge-retriever 에이전트를 mode: extract, confirmed: <유저응답> 로 호출.

• 카드 body, 해당 slide-NN.md 원문, 이미지 Gemini Pass 2 해설을 종합
• grounding rule: verbatim 인용은 slide 원문(slide-NN.md)에서만 가져온다. 카드 body 의 인용 블록은 힌트일 뿐 — 원문 대조 없이 verbatim 으로 쓰지 않는다. 원문 확인이 안 된 내용은 (요약, 비원문) 라벨이 붙어 반환된다.
• 반환: 압축 markdown + verbatim 인용 + images-pool/... 경로
• {"escalate_to": "sonnet"} 반환 시 동일 요청을 Sonnet 으로 재호출
• 메인 세션은 이 반환값만으로 아티팩트를 작성 (임의 추가 지식 금지)

금지 사항 (Hard rules)

Step 4.5 — 톤 매칭 (채널형 콘텐츠 필수)

산출물이 브런치/블로그·인스타/스레드·뉴스레터·링크드인 글 등 저자 명의 채널 콘텐츠면, 아티팩트 작성 전에 해당 채널의 톤 레퍼런스를 함께 Read 한다:

어미 패턴·문장 길이·이모지 사용·금지 표현을 산출물에 반영한다. 교안/PPTX/보고서형은 생략 가능.

콘텐츠 각도 탐색(OSMU): 카드뉴스/스레드/브런치 소재 각도가 필요하면 ~/.claude/knowledge/osmu-index/ 의 각도 맵(콘텐츠 유형 → 카드 매핑)을 Step 1 후보 확장으로 참조. 상세 절차는 USAGE.md '교차 도메인 검색 확장 (OSMU)' 절.

엔티티 생명주기 (절판 도구 경고)

extract 번들에 ## ⚠️ 도구 생명주기 절이 오면 반드시 산출물에 반영한다: 절판(sunset)·통합(merged)된 도구를 현재형으로 소개하지 말고, 대체 도구를 병기하거나 "(현재는 X로 통합)" 주석을 단다. 레지스트리: ~/.claude/knowledge/summaries/entities.jsonl.

인용 규격 (verbatim citation)

카드 ## 인용 블록 또는 retriever 반환 인용은 slide 원문 한 문장(최대 2문장) 그대로:

> {slide-NN.md 에서 복사한 문장 — 콜론 추가/어순 변경/요약 금지}
> — sources/{source_id}/slides/slide-{N}.md

verbatim 의 근거는 항상 slide 원문이다. 카드 body 인용은 힌트로만 쓰고, 원문 대조가 안 된 문장은 인용 부호 없이 (요약, 비원문) 라벨로 구분해 쓴다.

나레이션(STT) 소스 예외 (kind: narration — *-recording 소스): 전사 아티팩트인 동일 문장/구절의 연속 반복은 1회로 축약해 인용할 수 있다. 반복 제거 외의 어순 변경·요약·매끄럽게 고치기는 여전히 금지 — 구어체 그대로가 소셜 훅의 진짜 매력이다.

인용 충실도는 audit_quotes_v2.py 로 상시 감사한다 (주간 cron 포함).

이미지 3-field form (모든 아티팩트 공통)

PPTX speaker notes · HTML <img alt> · markdown caption 에 다음 3필드를 보존:

source:   sources/{source_id}/slides/slide-{N}.md
original: images-pool/{source_id}/{original-name}.png
image:    {artifact-local-path-or-url}

PPTX 이미지 삽입 시 aspect ratio 보존 — python-pptx 는 add_picture(path, left, top, width=...) 또는 height=... 하나만 주고 나머지는 자동 계산. letterbox/pillarbox 로 박스에 중앙 정렬.

images-pool 이 비어있을 때 (소스별 fallback)

retriever 가 반환한 image_candidates 가 비어 있거나 ~/.claude/knowledge/images-pool/<source_id>/ 가 존재하지 않으면, 카드 body 만으로 작성하지 말고 원본 소스 폴더를 1순위 fallback 으로 사용한다. (텍스트만 흡수돼 images: 0 인 경우가 흔하다 — 특히 Notion/HTML export 소스.)

fallback 절차 (일반 원칙)

1. retriever extract 결과의 image_candidates 가 비면 → 해당 소스의 원본 폴더(흡수 전 원본 PPTX/PDF/HTML export 가 있던 위치)를 직접 탐색해 이미지를 찾는다.
2. HTML export 소스는 본문의 <img src="..."> 를 긁어 3-field form(source/original/image)으로 보존한다.
3. 만료 가능성이 있는 원격 URL(예: Notion S3 export URL)은 다운로드 재시도 금지 — 이미 만료돼 실패하는 경우가 많다. 로컬 원본 폴더의 이미지를 쓴다.
4. 그래도 없으면 사용자에게 "이미지 후보가 없습니다. 원본 폴더 위치를 알려주실 수 있나요?" 라고 묻고 멈춘다 (다른 폴더에서 임의 재활용 금지).
5. 재활용이 필요하면 사용자에게 명시 승인 받기.

저장소 현재 상태 (2026-04-22)

• 7 토픽: ai-basics, career-growth, data-analytics, dooh, linkedin-branding, marketing, marketing-ai
• 카드/소스 규모는 스냅샷 금지 — wc -l summaries/cards.jsonl(카드), ls sources/ | wc -l(소스)로 실측
• FAITHFUL 인용 80.1% · cards_lint exit 0
• 허브 카드(토픽별 in-degree top-1): cards/<topic>/index.md 참조

예시 흐름

User: "링크드인 알고리즘과 네트워킹 원리로 카드뉴스 초안 써줘"

[자동 트리거: "카드뉴스" + "링크드인" → knowledge-cite 발동]

Step 1 ▸
$ python ~/.claude/skills/knowledge-query/scripts/query.py "링크드인 알고리즘 네트워킹"
→ linkedin-branding: 4 cards, 7 images
   marketing-ai: 1 card
   career-growth: 2 cards

Step 2 ▸ (knowledge-retriever, mode: recommend)
Rank 1: ks-1025-linkedin-algorithm-networking + classu-linkedin-writing-system
        (hub card + 반응율 원칙 · 5 images)
Rank 2: rank1 + flexwork-linkedin-005-portfolio-and-hiring
        (소프트스킬 포트폴리오 관점 추가)
Rank 3: rank2 + jobseeker-ad-pr-networking-strategy
        (구직자 대상 맥락 · 브리지 카드)

Step 3 ▸ [사용자에게 3 rank 제시, 응답 대기]

User: "1로"

Step 4 ▸ (knowledge-retriever, mode: extract, confirmed: "1")
→ 압축 markdown + verbatim 인용 4건 + images-pool/ks-1025/*.png 3장 반환

[메인 세션이 반환값으로 카드뉴스 10장 초안 작성, 인용·이미지 3-field 보존]

새 소스 추가가 필요한가 판단

Step 1 결과가 비었거나 얇으면 → Skill: knowledge-absorb 호출 (7단계 흡수 파이프라인: 정규화 → 이미지풀/OCR/Vision → 카드 제안 → 사용자 승인 → 스캐폴딩 → Haiku body-fill → relink+curate → lint+audit) → 완료되면 이 스킬로 복귀.

흡수는 항상 knowledge-absorb 경유 (지식화 유일 정문). 저수준 스크립트(ingest.py·scaffold_cards.py·cards_lint.py)는 라이브러리로만 존재하며 디버깅·기존 카드 수리 전용. 임시로 웹 검색·일반 지식으로 채우지 말 것.

체크리스트 (아티팩트 제출 직전)

• (채널형 콘텐츠) Step 4.5 톤 레퍼런스를 읽고 어미·문장 패턴을 반영했다
• (교안/모듈) 클립 매니페스트 경유 + verify_module_coverage exit 0 (USAGE.md 교안 규칙)
• (벌크 N모듈) 모듈별 반복이 아니라 벌크 생성 모드(일괄 recommend→확인 1회)를 썼다
• Step 1~4 를 모두 거쳤는가
• Step 3 에서 사용자 명시 선택을 받았는가
• 인용은 slide 원문 verbatim 인가 (콜론 추가·어순 변경 없음)
• 이미지 경로는 retriever 반환값 그대로인가
• 3-field form (source / original / image) 이 보존되었는가
• PPTX 라면 aspect ratio letterbox 로 맞췄는가
• cards/**, sources/**, images-pool/** 를 직접 Read 하지 않았는가

관련 리소스

• 단일 참조 가이드: ~/.claude/knowledge/USAGE.md
• 글로벌 규칙 섹션: ~/.claude/CLAUDE.md "지식·인용 시스템"
• 설계 스펙: ~/.claude/knowledge/docs/2026-04-18-knowledge-system-redesign.md §8.2
• P7 완결 리포트: ~/.claude/knowledge/docs/2026-04-22-card-p7-final.md
• 재검증 대상: ~/.claude/knowledge/docs/2026-04-22-quote-quality-hotspots.md
• 하위 스킬:
  • knowledge-query — Step 1 구현
  • knowledge-absorb — 신규 자료 7단계 흡수 (정규화 → 카드 → audit)
  • (저수준 라이브러리) knowledge-ingest/scripts/·knowledge-cards-build/scripts/ — 스킬 아님, absorb가 내부 사용
• 서브에이전트: knowledge-retriever (Haiku, recommend/extract 2-mode)