Communitygithub.com

why20261/tiktok-competitor-radar

Compara el rendimiento del contenido, los datos de interacción y las tendencias de discusión de marcas en TikTok, permitiendo análisis históricos para generar diferencias, evidencia y oportunidades ejecutables para análisis competitivo, comparación de marcas y optimización de estrategias.

¿Qué es tiktok-competitor-radar?

Esta skill está diseñada para extraer datos públicos de TikTok (videos, autores y comentarios) y devolverlos en formato JSON estructurado, ideal para análisis competitivo, monitoreo de tendencias y selección de influencers. Soporta tres capacidades principales: búsqueda por palabras clave (con filtros por likes, relevancia y tiempo), obtención de publicaciones de un creador específico (por enlace de perfil o nombre de usuario, con ordenación por fecha o popularidad) y extracción de comentarios de un video (incluyendo autor, interacciones y metadatos). La integración se realiza a través de scripts CLI sencillos que requieren una API Token almacenada en la variable de entorno `GUAIKEI_API_TOKEN`. Está optimizada para agentes de IA como Claude Code o Cursor, proporcionando datos crudos que luego pueden ser analizados, resumidos o presentados en tablas, gráficos o informes.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add why20261/tiktok-competitor-radar

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

🎯 Análisis de Competidores en TikTok y Comparación de Marcas

1. Resumen de Capacidades

💡Valor en una frase: Con una instrucción en lenguaje natural obtén datos públicos de TikTok (videos, autores y comentarios) y recíbelos en JSON estructurado: ideal para selección de creadores, análisis de datos, investigación de mercado, monitoreo de opinión, temas virales, seguimiento de cuentas competidoras, análisis de comentarios y tendencias, sin tener que hacer scroll manualmente en TikTok.

CapacidadScript de entradaParámetros obligatoriosDevuelve
Búsqueda por palabra clavescripts/tiktok/search-cli.js--keywordLista de publicaciones: autor, likes/comentarios/compartidos/guardados, etiquetas, URL de reproducción
Publicaciones de un creadorscripts/tiktok/post-cli.js--url (perfil o nombre de usuario)Lista de publicaciones públicas de ese creador (ordenación por fecha o popularidad)
Comentarios de un videoscripts/tiktok/comment-cli.js--url (enlace o ID del video)Texto del comentario, autor, número de likes, número de respuestas

Público objetivo

  • 🎯 Marcas: aprovechar tendencias para crear contenido de marketing.
  • 🏢 Agencias MCN: descubrir cuentas con alto potencial de interacción.
  • ✍️ Creadores de contenido independientes: encontrar referentes e inspiración.
  • 📊 Gestores de contenido: análisis semanal de temas y competidores.

Requisito previo: Debe ejecutarse en el directorio raíz de la skill, y la variable de entorno GUAIKEI_API_TOKEN debe estar configurada. Si no está configurada, todos los comandos devuelven código de salida 3, error_code=AUTH_REQUIRED; en ese caso, indica directamente al usuario que configure el Token, no reintentes ni cambies los parámetros.


2. Cuándo invocar / Cuándo no invocar

2.1 Debe invocarse

  • El usuario quiere consultar contenido público de TikTok (videos / imágenes / autores / comentarios / tendencias).
  • El usuario quiere hacer investigación de temas virales, monitoreo de cuentas competidoras, selección de influencers, análisis de opinión en comentarios, o desglose de estilos de contenido.
  • El usuario proporciona palabras clave de TikTok, enlaces de video o enlaces de perfil de creador, y desea obtener datos estructurados.
  • Después de obtener los datos, el usuario quiere continuar con resúmenes, comparaciones, ordenaciones, agrupaciones o generar informes / tablas.

2.2 No debe invocarse

  • El usuario solo necesita texto / títulos / guiones, sin consultar datos de TikTok.
  • La plataforma no es TikTok, sino otra (Douyin, Xiaohongshu, Bilibili, Weibo, WeChat Official Accounts) → enruta a la skill correspondiente. Esta skill solo maneja TikTok.
  • Se requieren datos que necesiten inicio de sesión, sean privados u ocultos → no es compatible.
  • Hay tanto una palabra clave como un enlace identificable y el objetivo no está claro → pregunta primero, no adivines.

2.3 Límites de capacidad (explícitamente no hacer)

No se admiten operaciones de escritura como publicar, dar like, comentar, seguir o enviar mensajes privados; no se inicia sesión en ninguna cuenta; no se recopilan campos privados como números de teléfono, ubicación o mensajes directos; no se toman decisiones de marketing por el usuario: la responsabilidad es obtener los datos, el análisis se deja a un nivel superior.


3. Enrutamiento de invocación (primero evalúa, luego ejecuta)

Intención del usuarioScriptPalabras clave de decisión
Buscar palabra clave, encontrar cierto tipo de contenido, encontrar tendenciassearch-clibuscar / encontrar / palabra clave / tendencia / más popular
Ver publicaciones / perfil / cuenta / creador / influencer, publicaciones recientespost-clipublicaciones / perfil / cuenta / creador / influencer / KOL
Ver comentarios / respuestas de un video determinadocomment-clicomentarios / respuestas / opiniones en la sección de comentarios

3.1 Reglas de desambiguación (obligatorias)

  1. Cuando aparezca solo "video", no lo asignes por defecto a post-cli.
    • Si hay "palabra clave" y no "comentarios" → search-cli (el usuario quiere buscar ese tipo de videos).
    • Si dice explícitamente "comentarios / respuestas de este video" → comment-cli.
    • Solo si aparecen "publicaciones / perfil / cuenta / creador / influencer" → post-cli.
  2. La prioridad de comentarios es mayor que la de publicaciones: si el enlace es /video/<id> y la pregunta es sobre comentarios → comment-cli; si la pregunta es "publicaciones de esta persona" → post-cli (usando @username).
  3. Si el usuario da un enlace /video/<id> pero quiere "lista de publicaciones" → primero confirma si se refiere a las publicaciones del autor o a los comentarios de ese video.

3.2 Reglas de inferencia de parámetros

Lo que dice el usuarioParámetro
Relevancia / por defecto--sort 0 (búsqueda)
Más popular / más likes / tendencia / más visto--sort 1 (búsqueda)
Publicaciones recientes / en orden cronológico inverso--sort 0 (publicaciones)
Publicaciones más populares--sort 1 (publicaciones)
Un día / 24 horas--time 1
Una semana / 7 días--time 7
Un mes / tres meses / seis meses--time 30 / 90 / 180
N resultados / los primeros N / quiero N--limit N

Valores por defecto: sort=0, time=0, limit=10.

⚠️ No confundir --sort de búsqueda con --sort de publicaciones: el primero es "relevancia / más likes", el segundo es "más reciente / más popular".

Cualquier parámetro que se degrade por valor inválido aparecerá en el array warnings del JSON de salida, y debe mostrarse al usuario; no se debe asumir que el valor original ha surtido efecto.


4. Modo de ejecución

La documentación completa de parámetros está en references/options.md; los esquemas JSON a nivel de campo están en los 6 archivos de assets/ (draft-07).

# Búsqueda por palabra clave
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

# Publicaciones de un creador
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

# Comentarios de un video
node scripts/tiktok/comment-cli.js --url "https://www.tiktok.com/@username/video/1234567890123456789" --limit 40

Formatos de entrada disponibles

  • Creador: https://www.tiktok.com/@username, enlace con parámetros https://www.tiktok.com/@username?lang=en, o directamente author_sec_uid
  • Video: https://www.tiktok.com/@username/video/<id>, enlace corto, o directamente el <id> del video

Disciplina de ejecución

  • Solo trata stdout como salida legible por máquina (JSON puro); los banners, el progreso y los logs de error están en stderr, no los mezcles al analizar.
  • Se recomienda un único --limit ≤ 1000.
  • No reintentes automáticamente si obtienes un resultado vacío: informa primero al usuario del resultado vacío y deja que él decida si cambiar la palabra clave o ampliar --time.

5. Contrato de salida (lectura obligatoria para la IA)

Todas las entradas producen el mismo envoltorio, con estructura idéntica para éxito y error:

{
  "status": "success | empty | error",
  "error_code": "OK | NO_MATCH | AUTH_REQUIRED | INVALID_KEYWORD | ...",
  "message": "Explicación legible por humanos",
  "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": ["La cantidad 99999 no es válida, se ha degradado a 10"]
}

5.1 Semántica de status

statusSignificadoresultsQué hacer
successDatos obtenidos correctamenteArray no vacíoAnalizar directamente
emptyLa solicitud fue exitosa, pero no hay datosnullConsiderarlo un resultado válido, informa al usuario que no se encontró nada, no lo trates como un error
errorLa solicitud fallónullProcesar según error_code, no inventes datos

5.2 Códigos de salida

Código de salidaSignificadoComportamiento del agente
0Éxito (success o empty)Continuar el análisis
1Error de ejecución (red / timeout / excepción de API / parámetro inválido)Mostrar message, preguntar al usuario si desea reintentar con otros parámetros
3AUTH_REQUIRED: Token faltante o con formato incorrectoDetenerse inmediatamente, indicar que configure GUAIKEI_API_TOKEN, prohibido reintentar

5.3 Manejo de códigos de error

error_codeManejo
AUTH_REQUIREDDetenerse e indicar que configure el Token. Prohibido reintentar o cambiar parámetros para evitarlo
INVALID_KEYWORDIndicar que la palabra clave debe tener entre 2 y 100 caracteres, no puede contener < > " ' & ni enlaces http
NO_MATCHResultado vacío válido, sugerir cambiar la palabra clave o ampliar --time
NETWORK_ERRORYa tiene reintentos incorporados; si aún falla, indica al usuario que verifique la red, máximo 1 reintento manual
TIMEOUT_ERRORYa tiene reintentos incorporados; si aún falla, sugerir reducir --limit y reintentar
Otros (códigos de servidor)Mostrar error_code + message tal cual, sin adivinar su significado

5.4 warnings deben mostrarse

Cuando un parámetro introducido no es válido y se degrada automáticamente (ej. --sort 9, --limit 99999), el array warnings explicará "qué parámetro se ha cambiado a qué". Debes informar al usuario exactamente igual, no puedes fingir que el valor original ha surtido efecto.

5.5 Comportamientos prohibidos

  • ❌ No inventar, no completar, no rellenar ningún dato de memoria.
  • ❌ Al recibir AUTH_REQUIRED, no reintentar, no cambiar de script, no modificar parámetros.
  • ❌ No interpretar empty como "el contenido que el usuario quiere no existe" más allá de esa conclusión (no significa que la interfaz esté rota).
  • ❌ No ampliar automáticamente las condiciones de búsqueda sin el consentimiento del usuario.

6. Sugerencias para el consumo de resultados (mejora la calidad final)

Una vez obtenidos los results, orgánizalos según el objetivo original del usuario, no los presentes como JSON en bruto:

  • Investigación de temas → ordenar por digg_count descendente y tomar los Top N, resumir patrones de títulos / etiquetas / duración
  • Monitoreo de competidores → ordenar por create_time para ver la cadencia de publicación, calcular frecuencia de actualización y porcentaje de publicaciones virales
  • Análisis de comentarios → ordenar por digg_count para agrupar opiniones de los comentarios más populares, mostrar proporción de positivos y negativos
  • Selección de influencers → cruzar author_nickname / interacción media / frecuencia de publicación, ofrecer una lista de candidatos
  • Necesidad de archivo → cada ejecución guarda automáticamente un archivo de registro; la ruta aparece en stderr en la línea "Guardado en …"

7. Seguridad y Cumplimiento (Trust)

  • Solo lectura: no se inicia sesión en cuentas de TikTok, no se ejecuta ninguna operación de escritura como publicar, dar like, comentar, seguir o enviar mensajes privados; no hay riesgo de bloqueo por infracción.
  • Mínimos privilegios: solo solicita la variable de entorno GUAIKEI_API_TOKEN necesaria para el negocio; no lee otros archivos locales, no escribe fuera del directorio de la skill (los registros se escriben en el directorio temporal del sistema).
  • Protección de credenciales: el Token solo se lee de la variable de entorno, no se escribe en stdout, no se incluye en los registros, no aparece en los mensajes de error.
  • Ámbito de envío de datos (imprescindible saber): al realizar la llamada, se envía a www.guaikei.com: tu API Token, la palabra clave de búsqueda o URL/ID de destino, junto con el nombre de la skill y la versión de Node. No se recopila ninguna otra información local.
  • Cumplimiento de datos: solo se obtienen datos visibles públicamente de TikTok (nombre de usuario, publicaciones públicas, comentarios públicos). No incluye datos privados como números de teléfono, ubicación o mensajes directos. Los datos están destinados únicamente para análisis interno personal o de equipo; antes de su divulgación pública o uso comercial, el usuario debe confirmar la autorización correspondiente y anonimizar campos como los nombres de usuario.
  • Sin dependencias de terceros: solo utiliza módulos integrados de Node.js (https / fs / path / os / querystring), sin dependencias npm, sin carga de scripts remotos, sin eval / child_process.

8. Preguntas Frecuentes

ProblemaCausa y solución
Código de salida 3 / AUTH_REQUIREDEl Token no está configurado o su formato es incorrecto (debe tener entre 16 y 256 caracteres alfanuméricos, guiones bajos y guiones)
Resultados de búsqueda vacíosPrueba con una palabra clave más genérica o --time 0 para eliminar el filtro de tiempo; empty es un resultado normal, no un error
Número de resultados menor que --limitEl servidor no tiene más datos para devolver, o el límite único se ha truncado; reduce a ≤ 1000 y obtén en lotes
Timeout constanteReduce --limit y reintenta; el script ya tiene reintentos con retroceso exponencial
Quieres ver "publicaciones más populares" pero aparecen en orden cronológico inversoEn post-cli debes usar --sort 1
El parámetro no surte efecto / el orden no es el esperadoRevisa los warnings en la salida; si el parámetro no es válido, se degrada silenciosamente al valor por defecto
¿Dónde está el archivo de registro?Consulta la línea "Guardado en …" en stderr (directorio temporal del sistema tiktok-guaikei/logs/<fecha>/)

9. Entorno y Soporte

Skills relacionados