Community생산성 & 협업github.com

xls-스킬

Excel 통합 문서(.xlsx/.xlsm/.xls)를 AI가 읽을 수 있는 Markdown으로 변환하며, 일반적인 Excel 리더가 놓치는 셀 내부에 포함된 이미지까지 포함하여 모든 그림을 원래 위치에 배치합니다. 사진, 라벨, 로고, 스크린샷, 그림, 서명이 포함된 스프레드시트를 읽거나 변환, 감사, 질문할 때 사용하세요.

xls-스킬란 무엇인가요?

이 스킬은 Excel 파일을 구조화된 Markdown으로 변환하여 AI 에이전트가 셀 값, 수식, 숨겨진 구조 및 모든 이미지를 정확히 원래 위치(셀 내부 또는 그리드 위)에서 해석할 수 있도록 합니다. openpyxl이나 pandas 같은 일반 라이브러리는 '셀 안에 배치'된 이미지(WPS Office의 `=DISPIMG` 또는 Microsoft 365의 `IMAGE` 함수)를 처리하지 못하지만, 이 스킬은 `xl/cellimages.xml` 및 `xl/metadata.xml`과 같은 패키지 내부 파일을 파싱하여 이를 추출합니다. 또한 떠 있는 그림, 텍스트 상자, 수식, 병합/숨겨진 구조를 추출하고 OCR을 통해 그림 내 텍스트를 인식합니다. 지원하는 플랫폼: Python 3.9+ (openpyxl 필요), 선택적으로 Pillow (이미지 크기), Tesseract OCR (그림 내 텍스트), `.xls` 변환을 위한 Microsoft Excel 또는 LibreOffice. 변환 결과는 Markdown 테이블, 이미지 파일, CSV 매니페스트(이미지, 수식, 도형), JSON 보고서로 제공되어 에이전트가 사람이 만든 스프레드시트를 완전히 이해할 수 있게 합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/hougw/xls-skill/tree/HEAD

Installed? Explore more 생산성 & 협업 skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

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

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

미리보기

스킬 README에서

부품!B2

문서

xls-스킬: Excel → Markdown, 그림은 셀 안에 그대로 유지

이 스킬이 필요한 이유

대부분의 Excel 리더(openpyxl, pandas, CSV 내보내기)는 셀 값만 봅니다. 두 종류의 그림이 누락됩니다.

  1. 셀 내부 이미지. 그림이 셀의 내용입니다.
    • WPS Office "셀에 포함": 셀에 =DISPIMG("ID_...",1)만 표시됨; 그림은 xl/cellimages.xml에 있습니다.
    • Microsoft 365 "셀에 배치" / IMAGE: 셀에 #VALUE!가 표시됨; 그림은 xl/metadata.xml 및 xl/richData/를 통해 접근합니다.
  2. 그리드 위에 그려진 떠 있는 그림 및 텍스트 상자 (공정 사진, 라벨, 양식 번호 처리).

이 스킬은 이 모든 것을 추출하여 각 그림을 파일로 저장하고, 그림이 있는 셀의 Markdown 테이블에 다시 기록하여 독자가 테이블과 그림을 함께 볼 수 있도록 합니다:

| # | A | B | C | D |
|---|---|---|---|---|
| 2 | 브래킷 | ![부품!B2](images/01_부품_B2_cell1.png) | 브래킷 \| 셀 내부 그림 | 4 |

실행 방법

python <skill-dir>/scripts/xlsx_to_md.py <파일-또는-폴더> [...] -o <출력-디렉토리> [--ocr auto|off] [--ocr-lang eng+chi_sim]
  • .xlsx, .xlsm, .xls 파일 또는 폴더(재귀적)를 허용합니다. 통합 문서당 한 줄씩 그림 개수와 함께 출력합니다.
  • Python 3.9+ 및 openpyxl이 필요합니다. 선택사항: Pillow (이미지 크기), Tesseract OCR (그림 내 텍스트), .xls를 열기 위한 Microsoft Excel 또는 LibreOffice.
  • 자체 테스트: python <skill-dir>/tests/run_tests.py는 합성 WPS 및 Microsoft 365 통합 문서를 생성하고 모든 그림이 해당 셀에 배치되는지 확인합니다.

통합 문서당 얻는 결과물 (<출력-디렉토리>/<이름>/)

파일내용
<이름>.md통합 문서 색인, 각 시트를 완전한 Markdown 테이블(잘림 없음)로 표시하며 그림은 해당 셀에 인라인으로 포함; 각 테이블 위에 시트 정보(숨겨짐 상태, 병합 범위, 숨겨진 행/열, 주석, 텍스트 상자, 차트 개수) 제공
<이름>.images.md그림당 한 항목: 그림, 시트!셀, 종류, 크기, 주변 셀 텍스트, OCR 텍스트, 설명 슬롯
images/모든 그림을 파일로 저장, 이름은 `<시트번호><시트><셀>_<셀
sheets_csv/시트 값; 그림 셀은 [image: images/...]로 표시
image_manifest.csv시트, 셀, 종류(in-cell (WPS DISPIMG) / in-cell (Microsoft 365) / floating), 파일, 패키지 부분, 대체 텍스트, 크기, OCR, 주변 텍스트
formula_manifest.csv셀당 수식 텍스트 및 캐시된 값
shapes_manifest.csv떠 있는 텍스트 상자/도형의 텍스트, 앵커 셀과 함께
conversion_report.json개수, 경고, review_required

에이전트를 위한 워크플로우

  1. 변환. 통합 문서에 대해 스크립트를 실행합니다.
  2. 먼저 보고서를 읽습니다. conversion_report.json을 엽니다. 모든 경고에 대해 조치합니다:
    • image not found in package -> 셀이 [image missing: ID]로 표시됨; 그렇게 말하고 그림을 추측하지 마십시오.
    • .emf/.wmf saved as-is -> 보기 전에 PNG로 변환합니다(예: Windows에서는 Pillow, 그 외에는 LibreOffice).
    • charts > 0 -> 차트는 개수만 세어지고 렌더링되지 않음; 차트가 중요하다면 시트를 열거나 내보냅니다.
    • OCR이 건너뛰어졌거나 언어가 누락된 경우 -> 직접 그림을 보는 데 의존합니다.
  3. 그림을 봅니다. <이름>.images.md에 나열된 모든 파일을 열고 각 description 자리 표시자를 그림이 보여주는 내용(개체, 읽을 수 있는 텍스트(라벨, 모델 번호, 표시), 기호, 그리고 주변 셀과의 관계)으로 대체합니다. OCR은 힌트일 뿐 정답이 아닙니다. 작은 라벨 텍스트는 종종 자르기나 확대가 필요합니다.
  4. 테이블과 그림을 함께 보고 답변합니다. 정확한 셀 값, 수식 및 구조에는 Markdown 테이블을 사용하고, "어떻게 생겼는지 / 부품에 무엇이 적혀 있는지"에는 그림을 사용합니다. 둘 다에 대해 시트!셀을 인용합니다.
  5. 갭을 정직하게 보고합니다. 2단계의 어떤 항목이 해결되지 않은 상태로 남아 있으면 통합 문서를 수동 검토가 필요함으로 표시합니다.

규칙

  • 통합 문서에 그림, 텍스트 상자, 색상 또는 숨겨진 내용이 있을 때 CSV 또는 값 전용 테이블은 완전한 증거가 아닙니다. 시트 정보와 매니페스트를 확인하십시오.
  • 각 그림을 해당 셀 및 이웃과 짝지으십시오. 절대 그림 순서만으로 판단하지 마십시오.
  • 중요한 텍스트는 셀 외부에 있을 수 있습니다: 텍스트 상자(양식 번호, 개정 표시), 주석, 머리글/바닥글. 텍스트 상자와 주석은 추출됩니다. 머리글/바닥글은 추출되지 않습니다. 문서 번호가 누락된 경우 Excel에서 확인하십시오.
  • 색상은 데이터일 수 있습니다(합격/불합격, 위험 수준, 상태). 이 스크립트는 채우기나 조건부 서식을 디코딩하지 않습니다. 색상이 의미를 전달한다면 openpyxl 또는 페이지 내보내기로 검사하고 매핑을 명시하십시오.
  • 병합된 범위는 왼쪽 위 셀에만 값을 유지합니다. 빈 셀을 해석하기 전에 merged: 줄을 읽으십시오.
  • 숨겨진 시트, 행 및 열은 변환되어 나열되며 삭제되지 않습니다. 숨겨진 내용에서 답이 나온 경우 반드시 말하십시오.
  • 터미널에서 깨진 경로를 신뢰하지 마십시오. 파일이 누락되었다고 보고하기 전에 실제 경로가 존재하는지 확인하십시오.

제한 사항

  • 떠 있는 그림은 왼쪽 위 앵커 셀에 연결됩니다. 여러 셀에 걸친 그림은 매니페스트에서 to_cell과 함께 나열됩니다.
  • 그룹화된 도형은 읽히지만, 별도 도형으로 그려진 화살표와 설명선은 페이지 렌더링에서만 사진과의 관계를 유지합니다. 레이아웃이 중요할 때("어떤 화살표가 어디를 가리키는가") Excel 또는 LibreOffice로 시트를 PDF/PNG로 내보내고 Markdown과 함께 보십시오.
  • 머리글/바닥글(VML) 및 주석 내의 그림은 추출되지 않습니다.
  • .xls는 먼저 변환하기 위해 Microsoft Excel(Windows, pywin32) 또는 LibreOffice가 필요합니다. 없으면 셀 값만 읽히고 보고서에 그렇게 명시됩니다.

관련 스킬