Communitygithub.com

TikTok 경쟁사 레이더

TikTok에서 브랜드의 콘텐츠 성과, 참여 데이터 및 토론 트렌드를 비교하고, 과거 데이터를 분석하여 차이점, 증거 및 실행 가능한 기회를 제공합니다. 경쟁사 분석, 브랜드 비교, 단계별 변화 판단, 브랜드 전파 분석 및 브랜드 전략 최적화에 사용됩니다.

TikTok 경쟁사 레이더란 무엇인가요?

이 스킬은 TikTok의 공개 콘텐츠 데이터를 수집하고 분석하여 경쟁사 분석, 브랜드 벤치마킹, 인플루언서 선별 및 트렌드 모니터링을 지원하는 도구입니다. 세 가지 주요 기능을 제공합니다: 키워드 검색(좋아요/관련도 기준 정렬, 게시 시간 필터링 가능), 크리에이터 게시물 가져오기(프로필 링크 또는 사용자 이름 기반, 최신/인기 정렬 지원), 비디오 댓글 스크래핑(비디오 링크 또는 ID 기준, 작성자, 참여 데이터, 태그, 링크가 포함된 구조화된 JSON 반환). Claude Code, Cursor, Codex와 같은 AI 에이전트 플랫폼에서 명령어 기반으로 사용할 수 있으며, Node.js 환경에서 `GUAIKEI_API_TOKEN` 환경 변수만 필요합니다. 모든 데이터 읽기 전용이며 TikTok 계정 로그인 없이 공개 데이터만 수집하여 개인정보 보호 및 규정 준수를 보장합니다. 반환된 구조화된 JSON을 기반으로 AI가 자동으로 요약, 비교, 정렬, 클러스터링 및 보고서를 생성할 수 있어 수동으로 TikTok을 스크롤할 필요가 없습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add why20261/tiktok-competitor-radar

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

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

문서

🎯 TikTok 경쟁사 분석 및 브랜드 비교

1. 능력 개요

💡한 줄 가치 : 구어체 명령 하나로 TikTok 공개 비디오/작성자/댓글 데이터를 가져와서 구조화된 JSON으로 바로 출력합니다. 크리에이터 선별, 데이터 분석, 시장 조사, 여론 모니터링, 인기 콘텐츠 발굴, 벤치마크 계정 모니터링, 댓글 여론 분석, 트렌드 추적 등에 활용하세요. 더 이상 TikTok을 수동으로 스크롤할 필요가 없습니다.

능력진입 스크립트필수 매개변수반환
키워드 검색scripts/tiktok/search-cli.js--keyword게시물 목록: 작성자, 좋아요/댓글/공유/저장, 태그, 재생 주소
크리에이터 게시물scripts/tiktok/post-cli.js--url (프로필 또는 사용자 이름)해당 크리에이터의 공개 게시물 목록 (최신/인기 정렬 지원)
비디오 댓글scripts/tiktok/comment-cli.js--url (비디오 링크 또는 ID)댓글 본문, 댓글 작성자, 좋아요 수, 답글 수

적용 대상

  • 🎯 브랜드사 — 트렌드에 편승하여 입소문 콘텐츠 제작
  • 🏢 MCN 기관 — 높은 참여율의 잠재력 있는 계정 발굴
  • ✍️ 콘텐츠 크리에이터 — 벤치마크 샘플 찾기, 창작 영감 얻기
  • 📊 콘텐츠 운영자 — 주간 보고서 주제 선정 및 경쟁사 분석

전제 조건 : 스킬 루트 디렉토리에서 실행해야 하며, 환경 변수 GUAIKEI_API_TOKEN이 설정되어 있어야 합니다. 설정되지 않은 경우 모든 명령은 종료 코드 3, error_code=AUTH_REQUIRED를 반환합니다. 이 경우 사용자에게 Token 설정을 직접 안내하고, 재시도하거나 매개변수를 변경하지 마십시오.


2. 호출 시점 / 호출하지 말아야 할 시점

2.1 호출해야 하는 경우

  • 사용자가 TikTok의 공개 콘텐츠(비디오/이미지/작성자/댓글/트렌드)를 조회하려는 경우
  • 사용자가 인기 콘텐츠 주제 조사, 경쟁사 계정 모니터링, 인플루언서 선별, 댓글 여론 분석, 콘텐츠 스타일 분석을 수행하려는 경우
  • 사용자가 TikTok 키워드, 비디오 링크, 크리에이터 프로필 링크를 제공하고 구조화된 데이터를 받고자 하는 경우
  • 사용자가 데이터를 받은 후 요약, 비교, 정렬, 클러스터링, 보고서/표 작성을 계속하려는 경우

2.2 호출하지 말아야 하는 경우

  • 사용자가 TikTok 데이터를 조회하지 않고 단순히 카피/제목/스크립트만 원하는 경우
  • 플랫폼이 TikTok이 아니라 다른 플랫폼(틱톡, 샤오홍슈, 빌리빌리, 웨이보, 위챗 공식계정)인 경우 → 해당 스킬로 라우팅하십시오. 본 스킬은 TikTok만 처리합니다.
  • 로그인 상태, 비공개, 숨겨진 데이터가 필요한 경우 → 지원하지 않습니다.
  • 키워드와 식별 가능한 링크가 모두 있고 목표가 불명확한 경우 → 먼저 질문하고, 추측하지 마십시오.

2.3 능력 범위 (명확히 하지 않음)

게시/좋아요/댓글/팔로우/메시지 등 쓰기 작업은 일절 지원하지 않습니다. 어떤 계정에도 로그인하지 않습니다. 전화번호, 위치, 메시지 등 개인정보 필드를 수집하지 않습니다. 사용자를 대신하여 마케팅 결정을 내리지 않습니다. 역할은 데이터를 가져오는 것이며, 분석은 상위 레이어에 맡깁니다.


3. 호출 라우팅 (먼저 판단한 후 실행)

사용자 의도스크립트판단 키워드
키워드 검색, 특정 콘텐츠 찾기, 인기 콘텐츠 찾기search-cli검색 / 찾기 / 키워드 / 인기 / 가장 핫한
특정 크리에이터/인플루언서의 게시물, 프로필, 계정, 최근 게시물 보기post-cli게시물 / 프로필 / 계정 / 크리에이터 / 인플루언서 / KOL
특정 비디오의 댓글, 답글 보기comment-cli댓글 / 답글 / 댓글란의 의견

3.1 모호성 해소 규칙 (반드시 준수)

  1. "비디오" 두 글자만 단독으로 나오면 기본적으로 post-cli로 간주하지 마십시오.
    • "키워드"가 있고 "댓글"이 없음 → search-cli (사용자가 이런 종류의 비디오를 검색하려는 경우)
    • "이 비디오의 댓글/답글"이 명확함 → comment-cli
    • "게시물/프로필/계정/크리에이터/인플루언서"만 나타남 → post-cli
  2. 댓글 우선순위가 게시물보다 높습니다: 제공된 링크가 /video/<id>이고 댓글에 대해 묻는 경우 → comment-cli; "이 사람의 게시물"에 대해 묻는 경우 → post-cli (@username 사용).
  3. 사용자가 /video/<id> 링크를 제공하면서 "게시물 목록"을 요청하는 경우 → 먼저 해당 크리에이터의 게시물인지 해당 비디오의 댓글인지 확인하십시오.

3.2 매개변수 추론 규칙

사용자 표현매개변수
관련도 / 기본--sort 0 (검색)
가장 인기 / 좋아요 가장 많은 / 인기 / 가장 핫한--sort 1 (검색)
최근 게시 / 시간 역순--sort 0 (게시물)
가장 인기 있는 게시물--sort 1 (게시물)
하루 / 24시간--time 1
일주일 / 7일--time 7
한 달 / 세 달 / 반 년--time 30 / 90 / 180
N개 / 상위 N개 / N개 필요--limit N

기본값: sort=0, time=0, limit=10.

⚠️ 검색의 --sort와 게시물의 --sort를 혼용하지 마십시오: 전자는 "관련도/최다 좋아요", 후자는 "최신/가장 인기"입니다.

불법 값으로 인해 매개변수가 대체되는 경우 출력 JSON의 warnings 배열에 나타나며, 반드시 사용자에게 표시해야 하고 원래 값이 적용된 것처럼 처리해서는 안 됩니다.


4. 실행 방식

전체 매개변수 설명은 references/options.md를 참조하십시오. 필드 수준 스키마는 assets/ 아래 6개의 JSON 스키마(draft-07)를 참조하십시오.

# 키워드 검색
node scripts/tiktok/search-cli.js --keyword "AI" --sort 1 --limit 20
node scripts/tiktok/search-cli.js --keyword "AI model" --time 7 --limit 20

# 크리에이터 게시물
node scripts/tiktok/post-cli.js --url "https://www.tiktok.com/@username" --limit 30
node scripts/tiktok/post-cli.js --url "https://www.tiktok.com/@username" --sort 1 --limit 30

# 비디오 댓글
node scripts/tiktok/comment-cli.js --url "https://www.tiktok.com/@username/video/1234567890123456789" --limit 40

사용 가능한 입력 형태

  • 크리에이터: https://www.tiktok.com/@username, 매개변수가 포함된 링크 https://www.tiktok.com/@username?lang=en 또는 직접 author_sec_uid
  • 비디오: https://www.tiktok.com/@username/video/<id>, 단축 링크 또는 직접 게시물 <id>

실행 규율

  • stdout만 머신이 읽을 수 있는 출력(순수 JSON)으로 처리합니다. 배너/진행 상황/오류 로그는 모두 stderr에 있으므로 혼합하여 구문 분석하지 마십시오.
  • 단일 --limit는 1000 이하를 권장합니다.
  • 한 번의 빈 결과로 인해 자동으로 조건을 완화하여 재시도하지 마십시오. 먼저 빈 결과를 사용자에게 알리고, 사용자가 키워드를 변경할지 아니면 --time을 완화할지 결정하도록 하십시오.

5. 출력 규약 (AI 파싱 필독)

모든 진입점은 동일한 봉투를 출력하며, 성공과 실패 구조가 일관됩니다:

{
  "status": "success | empty | error",
  "error_code": "OK | NO_MATCH | AUTH_REQUIRED | INVALID_KEYWORD | ...",
  "message": "사람이 읽을 수 있는 설명",
  "timestamp": "2026-09-16 21:00:00",
  "request": {
    "command": "search",
    "keyword": "AI",
    "sort": 1,
    "time": 0,
    "limit": 20
  },
  "metadata": {
    "skill_version": "1.0.0",
    "skill_name": "tiktok-creator-videos",
    "runtime_version": "22.22.2",
    "execution_time": 8421
  },
  "results": [],
  "warnings": ["숫자 99999가 유효하지 않아 10으로 대체되었습니다"]
}

5.1 status 의미

status의미results해야 할 일
success데이터 획득 성공비어 있지 않은 배열직접 분석
empty요청 성공, 그러나 데이터 없음null유효한 결과로 간주하여 사용자에게 검색 결과가 없음을 알리고, 실패로 간주하지 않음
error요청 실패nullerror_code에 따라 처리하고, 데이터를 만들지 않음

5.2 종료 코드

종료 코드의미Agent 행동
0성공 (success 또는 empty)계속 분석
1실행 오류 (네트워크/시간 초과/인터페이스 예외/매개변수 불법)message를 표시하고 사용자에게 매개변수를 변경하여 재시도할지 물음
3AUTH_REQUIRED: Token 누락 또는 형식 오류즉시 중단, GUAIKEI_API_TOKEN 설정을 안내하고 재시도 금지

5.3 오류 코드 처리

error_code처리 방식
AUTH_REQUIRED중단하고 Token 설정 안내. 재시도 금지, 매개변수 변경으로 우회 금지
INVALID_KEYWORD키워드는 2~100자, < > " ' & 및 http 링크를 포함할 수 없음을 안내
NO_MATCH유효한 빈 결과, 키워드 변경 또는 --time 완화 제안
NETWORK_ERROR내장 재시도 포함. 여전히 실패하면 네트워크 확인 안내, 최대 1회 수동 재시도
TIMEOUT_ERROR내장 재시도 포함. 여전히 실패하면 --limit를 줄인 후 재시도 제안
기타 (서버 측 코드)error_code + message를 원래대로 표시하고, 의미를 스스로 추측하지 않음

5.4 warnings 반드시 표시

전달된 매개변수가 유효하지 않아 자동으로 대체될 때(예: --sort 9, --limit 99999), warnings 배열은 "어떤 매개변수가 무엇으로 변경되었는지"를 설명합니다. 반드시 그대로 사용자에게 전달해야 하며, 매개변수가 원래 값으로 적용된 것처럼 가장해서는 안 됩니다.

5.5 금지 행위

  • ❌ 어떤 데이터도 만들거나, 보충하거나, 기억에 의존하여 채우지 않습니다.
  • ❌ AUTH_REQUIRED 수신 후 재시도하지 않고, 스크립트를 변경하지 않으며, 매개변수를 변경하지 않습니다.
  • ❌ empty를 "사용자가 찾는 콘텐츠가 존재하지 않는다" 이외의 결론(예: 인터페이스 오류)으로 간주하지 않습니다.
  • ❌ 사용자의 동의 없이 자동으로 검색 조건을 완화하지 않습니다.

6. 결과 소비 제안 (최종 전달 품질 향상)

results를 얻은 후에는 원본 JSON을 그대로 출력하는 대신 사용자의 원래 목표에 따라 출력을 구성하십시오:

  • 주제 조사 → digg_count 기준 내림차순으로 상위 N개를 가져와서 제목 구문/태그/길이 분포 패턴 요약
  • 경쟁사 모니터링 → create_time 기준 게시 리듬 정렬, 업데이트 빈도 및 인기 콘텐츠 비율 통계
  • 댓글 인사이트 → digg_count 기준 높은 좋아요 수의 댓글을 가져와 의견 클러스터링, 긍정/부정 비율 출력
  • 인플루언서 선별 → author_nickname/평균 참여율/게시 빈도 교차 분석, 후보 목록 제공
  • 기록 보관 필요 → 각 실행 시 로그 파일이 자동으로 작성되며, 경로는 stderr의 "다음에 저장됨 …" 행에 있습니다.

7. 보안 및 규정 준수 (Trust)

  • 읽기 전용 : TikTok 계정에 로그인하지 않으며, 게시/좋아요/댓글/팔로우/메시지 등 모든 쓰기 작업을 수행하지 않아 계정 차단 위험이 없습니다.
  • 최소 권한 : 비즈니스에 필요한 하나의 환경 변수 GUAIKEI_API_TOKEN만 요청합니다. 로컬의 다른 파일을 읽지 않으며, 스킬 디렉토리 외부 경로에 쓰지 않습니다(로그는 시스템 임시 디렉토리에 기록).
  • 자격 증명 보호 : Token은 환경 변수에서만 읽으며, stdout에 쓰지 않고, 로그에 기록하지 않으며, 오류 메시지에 나타나지 않습니다.
  • 데이터 외부 전송 범위 (반드시 숙지) : 호출 시 www.guaikei.com으로 다음을 전송합니다: 귀하의 API Token, 쿼리 키워드 또는 대상 URL/ID, 스킬 이름 및 Node 버전. 이 외에는 로컬 정보를 수집하지 않습니다.
  • 데이터 규정 준수 : TikTok 공개 데이터(닉네임, 공개 게시물, 공개 댓글)만 획득합니다. 전화번호, 위치, 메시지 등 개인정보 필드를 포함하지 않습니다. 데이터는 개인/팀 내부 분석에만 사용하십시오. 외부 게시 또는 상업적 사용 전에 직접 승인을 확인하고 사용자 닉네임 등을 비식별화 처리하십시오.
  • 타사 종속성 없음 : Node.js 내장 모듈(https/fs/path/os/querystring)만 사용하며, npm 종속성, 원격 스크립트 로드, eval/child_process가 없습니다.

8. 자주 묻는 질문

현상원인 및 처리
종료 코드 3 / AUTH_REQUIREDToken이 설정되지 않았거나 형식이 잘못됨 (16~256자 영숫자, 밑줄, 하이픈 필요)
검색 결과가 비어 있음더 일반적인 키워드로 변경하거나 --time 0으로 시간 범위 해제. empty는 정상 결과이며 오류가 아님
결과 개수가 --limit보다 적음서버에서 더 이상 반환할 수 없거나 단일 상한에 도달. 1000 이하로 나누어 가져오기
계속 시간 초과--limit 줄인 후 재시도. 스크립트에 지수 백오프 재시도 내장
"가장 인기 있는 게시물"을 보고 싶은데 시간 역순으로 정렬됨post-cli에서 --sort 1 사용해야 함
매개변수가 적용되지 않음/예상 정렬과 다름출력의 warnings 확인. 매개변수가 유효하지 않으면 자동으로 기본값으로 대체됨
로그 파일 위치stderr에서 "다음에 저장됨 …" 행 확인 (시스템 임시 디렉토리 tiktok-guaikei/logs/<날짜>/)

9. 환경 및 지원

관련 스킬