Communitygithub.com

show-and-tell (보여주고-말하기)

공유 브라우저 화면에서 사용자와 양방향으로 소통할 수 있는 포인팅 채널입니다. 하이라이트, 레이블, 탭/스와이프/드래그 같은 제스처 그림을 보여주고, 사용자는 사이드 패널에서 메모와 함께 표시, 클릭/제스처 녹화, 메시지를 보낼 수 있습니다. 또한 Next/Back 버튼이 있는 가이드 투어와 (캡션, 챕터, 카드가 포함된 MP4) 리뷰 비디오 녹화도 지원합니다. '보여줘', '어디 있지?', '내가 표시/보낸/녹화한 거 봐', 워크스루, 데모, 코드 변경 시연, 고객 리뷰 비디오 등에 사용하세요.

show-and-tell (보여주고-말하기)란 무엇인가요?

show-and-tell 스킬은 AI 에이전트(Claude Code, Cursor, Codex 등)와 사용자가 공유 브라우저 창에서 실시간으로 상호작용할 수 있게 해주는 강력한 양방향 포인팅 채널입니다. 에이전트는 웹 페이지의 요소를 하이라이트하거나 레이블, 제스처 애니메이션(탭, 스와이프, 드래그 등)으로 가리킬 수 있고, 사용자는 사이드 패널을 통해 페이지에 직접 표시(annotation)를 하거나 동작을 녹화(record)하거나 메시지를 보내며 응답할 수 있습니다. 이 스킬은 Chrome for Testing 브라우저와 전용 MCP 서버를 기반으로 동작하며, `highlight`, `get_queue`, `wait_for_action` 등의 도구를 제공합니다. 또한 스크립트 기반의 가이드 투어(Next/Back)와 자동 녹화된 MP4 리뷰 비디오(캡션, 챕터, 카드 포함) 기능을 갖추고 있어 워크스루, 코드 변경 시연, 고객 피드백 비디오 제작에 특히 유용합니다. 보안을 위해 허용된 호스트에서만 작동하며, 사용자 세션과 인증 정보를 안전하게 유지합니다.

지원 대상✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/Knyrps/agent-skills/tree/main/skills/show-and-tell

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

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

문서

show-and-tell (보여주고-말하기)은(는) 무엇을 하나요?

당신과 사용자가 공유하는 Chrome for Testing 창입니다. 당신은 페이지의 무언가를 가리키고, 사용자는 show-and-tell 사이드 패널 (주석, 녹화, 메시지)을 통해 응답합니다. 어떤 기능도 투어 없이 바로 사용할 수 있습니다. 가이드 투어와 비디오는 선택적인 추가 기능입니다. 패널은 브라우저 UI의 일부이며 페이지 스크린샷에는 절대 포함되지 않습니다.

<skill>은 이 스킬의 디렉토리(이 SKILL.md가 있는 폴더)를 나타냅니다. 명령어는 모든 셸에서 작동합니다.

구성 요소

  • 브라우저: 자체 프로필을 사용하는 Chrome for Testing, CDP 127.0.0.1:9334, 확장 프로그램이 미리 로드되어 있습니다. start_browser가 이를 실행(멱등)하고 패널을 엽니다; 브라우저는 세션보다 오래 지속됩니다.
  • show-and-tell MCP: start_browser, status, highlight, clear_highlights, hide_overlays, get_queue, wait_for_action, request_demo, set_step, load_tour, goto_step, end_tour, record_tour, stop_recording. 각 도구는 CLI로도 사용 가능합니다: node "<skill>/bridge" <start|status|highlight <css> [--label t] [--gesture g] [--direction d] [--to css] [--url u] [--style s] [--keep]|clear|hide|show|queue [--recent]|wait|cancel|request <prompt>| step <label>|tour <file>|goto <n>|end|record <file> [--name n] [--size s]|record-stop|record-cancel>.
  • 동일 MCP의 browser_* 도구 (이 브라우저에 연결된 Playwright MCP)는 highlight만으로는 부족할 때 페이지를 제어하는 데 사용합니다: browser_snapshot, browser_click, browser_type, browser_evaluate, browser_navigate, … 이 도구들은 필요하면 브라우저를 시작하고 앱 탭에서만 작동하며, 패널에서는 절대 동작하지 않습니다. 호스트에 별도의 일반 playwright 서버가 있다면 그것은 사용자가 보지 못하는 개인 브라우저입니다; 사용자가 보면 안 되는 작업에만 사용하세요.

사용자가 지켜보는 곳에서 작업하기

사용자는 공유 브라우저를 따라가며, 패널은 각 browser_* 호출("클릭 중…", "페이지를 통해 데이터 요청 중…")을 표시합니다. 따라올 수 있도록 유지하세요:

  • 무언가를 보여주거나 재현할 때: 보이는 UI를 사용하세요 (이동, 클릭, 입력). 그러면 페이지에 그 내용이 표시됩니다.
  • 많은 데이터(로그, 목록, JSON)를 읽을 때: browser_evaluate 내에서 fetch로 앱 자체 API를 호출해도 괜찮으며 사용자 세션을 사용하지만, 화면에는 아무 변화가 없습니다. 채팅으로 먼저 말하세요 ("Grafana의 API를 통해 사용자 탭에서 로그를 읽고 있습니다").
  • 이러한 요청은 작게 유지하세요 (짧은 시간 범위, limit): 약 1분 이상 실행되는 호출은 MCP 클라이언트에 의해 중단됩니다. 동일한 쿼리를 재시도하지 말고 긴 범위를 나누세요.

가드레일: 허용된 호스트

공유 브라우저는 사용자의 로그인 정보를 보유하므로, 여기의 모든 도구(포인팅, 투어, 비디오 및 browser_*)는 허용된 호스트에서만 작동합니다. 이 머신은 항상 허용됩니다: localhost, 루프백 주소 및 호스트 파일이 루프백에 매핑하는 이름. 다른 호스트(다른 네트워크의 개인 호스트라도)는 처음 사용할 때 사이드 패널에서 사용자에게 확인을 요청합니다("아니요", "이 세션", "항상"); 호출은 최대 2분 동안 응답을 기다립니다.

  • 허용되지 않음: 사용자가 …을(를) 허용하지 않았습니다: 이를 존중하세요. 재시도하거나 우회 방법을 찾지 마세요.
  • …이(가) 응답하지 않았습니다: 사용자에게 패널이 묻고 있다고 한 줄로 알린 다음, 한 번 재시도하세요.
  • extension/config.json 또는 config.local.json을 직접 편집하지 마세요; 호스트를 허용하는 것은 사용자만이 할 수 있습니다.

감시자: 사용자 듣기

사용자는 언제든지 보낼 수 있습니다. 당신은 감시자라는 백그라운드 셸 작업을 통해 이를 듣습니다.

  • start_browser, status 및 브라우저를 구동하는 모든 도구는 watcher를 반환합니다. running이 false이면 watcher.command를 즉시 백그라운드 작업(셸 도구, background 옵션)으로 시작하고 기다리지 마세요.
  • 완료되면 {"actions": [...]}를 전달합니다: 이를 처리한 다음(다음 섹션), 감시자를 다시 시작하세요. timeout 또는 cancelled로 완료되고 액션이 없으면: 다시 시작하고 아무 말도 하지 마세요.
  • 채팅 중에는 계속 실행 상태로 두세요; 채팅 메시지에 응답하기 위해 절대 취소하지 마세요.
  • 패널은 마지막으로 브라우저를 구동한 세션으로 전송하며 "이 듣고 있습니다"를 표시합니다.
  • 이 툴킷에서는 백그라운드 작업이 없습니다: 사용자가 무언가를 보냈다고 말하면, get_queue를 호출하세요(recent: true는 지난 1시간 동안 전달된 항목도 반환합니다).

사용자에게 무언가 보여주기

highlight({ selector, text?, label?, gesture?, direction?, to?, url?, style?, keep? }):

  • url: 먼저 앱 탭에서 해당 페이지를 엽니다; Playwright가 필요하지 않습니다. 말하기 전에 found: false인지 확인하세요.
  • label: 짧은 설명문입니다. style: outline(기본값), spotlight(나머지 영역을 어둡게), none(박스 없음).
  • gesture: 요소에 애니메이션 일러스트레이션을 반복합니다; 실제로 수행되지는 않습니다. 터치: tap, double-tap, long-press, swipe, pinch. 마우스: click, double-click, right-click, hover, drag, scroll. direction: left/right/up/down(swipe, drag, scroll), in/out(pinch). to: 스와이프/드래그 끝 지점의 CSS 선택자.
  • keep: true: 현재 하이라이트에 추가합니다; 그렇지 않으면 교체됩니다. clear_highlights로 제거합니다.
  • 안정적인 선택자(id, data-testid, aria) + text를 선호하세요. 채팅에서 1~3문장으로 설명하세요.

사용자가 보내는 것

actions의 각 항목에는 type(및 투어가 실행 중인 동안 step)이 있습니다:

  • question: 메시지(text)입니다. 채팅으로 답변하세요.
  • annotation: 사용자가 페이지에 표시를 했습니다("주석": 클릭으로 요소를 표시하거나, 드래그로 그리기) 그리고 text를 작성했습니다. 당신만 볼 수 있는 인라인 이미지를 받습니다: 사용자의 번호가 매겨진 색상 표시와 메모, 그리고 각 마크가 참조하는 요소 주위에 1a, 1b…로 레이블이 지정된 점선 윤곽선. annotations[]은 범례입니다: n, kind(element/rect/arrow/pen), color, rect, arrow from/to, note, elements[] (label, selectors, tag, text, rect). 좌표는 문서 좌표입니다; imageArea는 이미지가 보여주는 영역입니다. 마크를 참조할 때는 1a 레이블이 아닌 번호나 색상 및 요소 텍스트로 참조하세요. imagePath는 사용자 자신의 버전입니다.
  • recording: 사용자가 무언가를 시연했습니다("녹화", 또는 당신의 request_demo에 응답, requestId와 prompt 포함). recording.steps는 Chrome DevTools Recorder 형식을 따릅니다(navigate, click (button: "secondary" 및 modifiers 포함), doubleClick, change, keyDown, scroll) + longPress, swipe, urlChange; 요소 단계에는 selectors, tag, text가 포함됩니다. text는 사용자의 코멘트입니다. demoDeclined: 사용자가 요청을 거부했습니다.
  • 투어 및 비디오 이벤트: next/back, agentStep, stepError, tourEnd, videoReady, videoError, videoDiscarded (아래 섹션 참조).

request_demo({ prompt })는 사용자에게 무언가를 보여달라고 요청합니다; 패널이 녹화를 시작합니다.

가이드 투어

  1. 계획: 채팅에서 단계를 계획하세요: 제목과 각 단계가 보여줄 내용, 단계당 하나의 아이디어.
  2. 스크립트: { steps: [{ title, explanation, url?, actions?, highlights?, agent? }] }:
    • explanation: 2~5문장, 패널에 표시됩니다.
    • url: 먼저 이동합니다. 뒤로 가기는 가장 가까운 이전 url 단계부터 재생되므로, 페이지 상태를 변경하는 모든 단계에 접근 가능한 url을 제공하세요.
    • actions: {click|fill|waitFor|hover|doubleClick|rightClick|longPress|swipe|drag|scroll: css, text?, value?, to?, direction?, ms?}, {scrollBy: px, in?: css}, {press: key, on?: css}, {wait: ms}.
    • highlights: highlight()와 동일; 첫 번째는 교체하고 나머지는 추가됩니다.
    • agent: true: 당신이 직접 수행해야 하는 단계에만 사용하세요: 실행, set_step("n/N – title"), 하이라이트, 설명, 그리고 next가 도착하면 goto_step(n+1). 먼저 선택자를 확인하세요(browser_evaluate); 누락된 선택자는 stepError가 됩니다.
  3. 시작: start_browser(감시자 시작), bridge.panelOpen 확인, 그런 다음 load_tour({ tour })를 호출하고 사용자에게 투어가 패널에서 실행 중이라고 한 줄로 알리세요.
  4. 반응: stepError → 단계를 수정하고 load_tour를 start: step과 함께 호출. tourEnd → end_tour 및 간단한 요약. 투어 중 질문과 표시는 현재 step을 참조합니다.

코드 변경 시연하기

  1. 범위: 커밋되지 않은 변경사항(git diff HEAD), 또는 그렇지 않으면 브랜치의 베이스와 비교. 불명확하면 물어보세요.
  2. 매핑: 각 변경된 파일을 그 효과가 나타나는 화면과 요소에 매핑하세요; 가시적인 효과가 없는 변경사항은 하나의 마무리 요약 단계에 넣으세요.
  3. 앱: 도달할 수 없으면 프로젝트 스크립트에서 dev 서버를 백그라운드 작업으로 시작하세요. 그런 다음 보이는 변경사항당 하나의 투어 단계, 앱의 자연스러운 순서로 진행하세요.

리뷰 비디오

record_tour({ tour, name?, size?, pace?, captions?, cards?, zoom?, hidpi?, out? })는 스크립트된 투어를 자동으로 재생하고 탭을 MP4로 녹화합니다. 캡션, 챕터 레이블, 진행 막대, 도입/섹션/종료 카드, 모든 동작에 대한 그려진 커서 또는 손가락, .vtt 및 챕터 목록이 포함됩니다. 즉시 반환하며, 감시자는 videoReady { path, vtt, chapters, durationMs, … } 또는 videoError { step, error }를 받습니다. 비디오 투어를 작성하기 전에 references/video.md를 읽으세요.

증거 스크린샷

일반 페이지를 보여주는 스크린샷을 찍기 전에 hide_overlays(true)를 호출하고, 이후에 hide_overlays(false)를 호출하세요.

문제 해결

  • extensionConnected: false: start_browser를 다시 실행하세요; 확장 프로그램이 약 15초 내에 재연결되고 그동안 사용자가 보낸 내용을 재생합니다.
  • bridge not running: MCP가 연결되지 않았습니다; CLI(start, wait)는 자체적으로 작동합니다.
  • browser_* 호출이 브라우저가 닫혔다고 말함: 자체적으로 한 번 재연결을 시도합니다; 여전히 실패하면 start_browser를 실행하고 재시도하세요.
  • 하나의 브라우저는 한 번에 하나의 투어 또는 비디오만 처리합니다. status가 설정하지 않은 단계를 표시하면 다른 세션이 사용 중인 것입니다: 사용자에게 먼저 물어보세요.
  • Chrome for Testing이 없음: npx playwright install chromium을 실행하거나 DEMO_BROWSER_PATH를 설정하세요.

관련 스킬