theus-cli-darwin-x64 0.2.84

package/vendor/theus-arsenal/skills/analisis-plataformas-competencia/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: analisis-plataformas-competencia
+description: Úsala al delimitar un paisaje competitivo — identificar, categorizar y prefiltrar por puntuación el conjunto de competidores antes de cualquier benchmarking. Decide quién cuenta como competidor, a qué tier pertenece y qué fuentes minar. Primer paso del pipeline competitivo de tres skills; precede a metodologia-benchmarks.
+---
+
+# Análisis de plataformas de competencia
+
+Usa esta skill para decidir **a quién benchmarkear** y **dónde encontrarlos** antes de puntuar nada. Un análisis competitivo vale lo que vale su marco: el conjunto equivocado hace que el cliente parezca imbatible o condenado. La meta es un conjunto defendible y relevante para decidir — no un censo exhaustivo.
+
+## Cuándo activarla
+
+- Al empezar un proyecto de benchmarking competitivo que necesita definir primero el conjunto de competidores.
+- Cuando hay dudas sobre qué empresas van en los tiers Directo / Adyacente / Aspiracional.
+- Cuando se necesita un alcance defendible y podado para un informe de paisaje de mercado.
+- Cuando existe un brief de posicionamiento y hay que identificar quién disputa esa posición.
+- Como primer paso antes de ejecutar `metodologia-benchmarks`.
+
+## Brief de posicionamiento del cliente (establécelo primero)
+
+Antes de delimitar el conjunto, establece el brief de posicionamiento del cliente. Si no lo tienes, realiza una entrevista corta de descubrimiento de marca para obtenerlo — **no** lo inventes y **no** delimites el conjunto a ciegas. El brief aporta:
+
+- **Identidad / registro estético** — qué tipo de estudio o empresa es y cómo se presenta.
+- **Oferta** — qué servicios o productos entrega.
+- **Clientes objetivo** — a quién vende.
+- **Diferenciador** — el foso o argumento de posicionamiento en el que el cliente cree.
+- **Consecuencia de alcance** — la implicación sobre cómo ponderar competidores (p. ej., priorizar por distintividad vs. solapamiento de capacidades vs. precio).
+- **Tensión estratégica** — el par de ejes que define el espacio en blanco del cliente (p. ej., memorabilidad × contratabilidad).
+
+**No avances sin el brief de posicionamiento.** Una lista de competidores delimitada sin la lente del cliente es ruido, no inteligencia. La consecuencia de alcance, en particular, determina qué competidores son rivales *fuertes* (los que disputan el foso del cliente) frente a los que solo solapan en el menú de servicios.
+
+## Criterios de selección
+
+Por cada candidato, captura estos ejes — deciden tanto la inclusión como el tier:
+
+- **Tamaño / modelo** — solo, microestudio (2–8), boutique (menos de 30), agencia mediana. Empareja con la banda del cliente; los estudios de la misma banda son el cara a cara realista.
+- **Nicho / especialización** — cuánto solapa el foco del candidato con la oferta del cliente. Solapamiento más estrecho = más directo.
+- **Geografía / mercado** — UE vs EE. UU. vs remoto-global; idioma; alcance de husos horarios. Anota si ganan los mismos clientes que persigue el cliente.
+- **Precios y modelo de contratación** — sprints productizados, retainer, proyecto, tarifa diaria; transparente vs "contáctanos". Señala madurez de posicionamiento.
+- **Estilo de portafolio** — genérico vs. con criterio/editorial vs. contracorriente. Cuanto más cercano al registro estético del cliente, más disputa su distintividad.
+- **Profundidad técnica / madurez de oficio** — relevante si la historia de credibilidad del cliente incluye proceso público, herramientas abiertas o sistemas documentados.
+- **Fuerza de marca** — ¿el estudio tiene una identidad verbal/visual apropiable o es intercambiable? Pondéralo según la consecuencia de alcance del cliente.
+
+## Taxonomía de jugadores — ejes a poblar
+
+No clasifiques competidores en cubos específicos del nicho; ordénalos a lo largo de unos pocos ejes genéricos para que el paisaje no quede sesgado hacia un arquetipo. Estos ejes aplican a cualquier mercado de servicios creativos (diseño, motion, copywriting, branding, contenido, cine, etc.). Busca amplitud en cada eje primero, luego poda hacia lo más instructivo.
+
+1. **Postura de posicionamiento** — *guiado por marca / editorial* (compite en identidad, voz, punto de vista) vs *guiado por capacidad* (compite en oficio, volumen, resultados). Puebla ambos polos; el espejo más cercano del cliente está en su propio extremo.
+2. **Especialización** — *especialista* (una disciplina o vertical estrecha) vs *generalista* (menú de servicios amplio). Mayor solapamiento con el foco del cliente = más directo.
+3. **Tamaño / modelo** — *solo / micro* vs *boutique* vs *mediano* vs *escala enterprise*. Los de la misma banda son el cara a cara realista; las bandas mayores son la referencia aspiracional / de madurez comercial.
+4. **Formato de contratación** — *productizado* (sprints con nombre, auditorías, paquetes fijos) vs *a medida* (proyecto custom / retainer). Señala madurez de posicionamiento.
+5. **Postura de distintividad** — *convencional / seguro* vs *contracorriente / con manifiesto*. El extremo con criterio es clave para el benchmarking de distintividad en cualquier nicho.
+6. **Modelo de evidencia / credibilidad** — *guiado por resultados* (métricas, clientes nombrados, casos profundos) vs *guiado por estética* (portafolio, premios). Indica cómo gana la confianza cada jugador.
+7. **Fuerza de marca del operador** — *intercambiable* vs *identidad de culto / apropiable* (incluidos independientes senior que prueban el modelo de "marca solo memorable").
+8. **Mercado / alcance** — *local / regional* vs *remoto-global*; anota si ganan los mismos clientes que persigue el cliente.
+
+Ubica a cada candidato en los ejes relevantes; un competidor es *directo* cuando queda cerca del cliente en posicionamiento, especialización, tamaño y mercado a la vez.
+
+## Tiers competitivos (cómo se resuelve el conjunto)
+
+Agrupa el conjunto final en tres tiers — esta estructura se arrastra hasta el informe:
+
+- **Directo** — misma banda, oferta solapada, mismos clientes objetivo. El cara a cara realista.
+- **Adyacente** — solapamiento parcial (una capacidad, o un tamaño de cliente distinto) que presiona en los bordes.
+- **Aspiracional** — jugadores con los que el cliente no compite hoy, pero cuya marca o madurez comercial marca el listón.
+- *(Vigila también a los sustitutos: herramientas no-code/IA, equipos internos, freelancers generalistas — anótalos como vector de amenaza, no como competidor perfilado, salvo que sean materialmente relevantes.)*
+
+## Fuentes de datos (dónde mirar)
+
+Cruza la fuente con la dimensión que necesitas. Los *tipos* de plataforma de abajo son genéricos; sustitúyelos por los nativos del nicho del cliente (p. ej. Dribbble/Behance para diseño, showreel/Vimeo para motion, muestras de escritura/trabajo publicado para copy):
+
+- **Plataformas de portafolio / oficio** — calidad de oficio, rango, registro estético (p. ej. Dribbble, Behance, Vimeo, o el escaparate equivalente del nicho).
+- **Premios / escaparates curados** — ambición de oficio y reconocimiento editorial; sobreindexa lo vistoso, así que cruza con credibilidad comercial (p. ej. Awwwards, listas de premios del sector).
+- **El sitio del propio competidor** — fuente primaria de posicionamiento, voz, empaquetado de oferta, postura de precios, clientes nombrados, manifiesto/punto de vista.
+- **LinkedIn** — tamaño/modelo del equipo, narrativa fundacional, cadencia de publicación, logos de clientes, geografía.
+- **Directorios de reseñas** — reseñas, clientes nombrados, tamaños de proyecto, modelos de contratación; la señal más fuerte de credibilidad comercial y preparación enterprise (p. ej. Clutch.co o el equivalente del nicho).
+- **Trabajo abierto / público** — repos de proceso, muestras publicadas, producción creativa abierta: evidencia de profundidad y transparencia de oficio.
+- **Charlas en conferencias / pódcasts / newsletters** — profundidad de liderazgo de pensamiento y propiedad del punto de vista.
+
+Siempre **verifica las afirmaciones en al menos dos fuentes** antes de tratar un atributo de un competidor como hecho (el copy autorreportado del sitio ≠ resultado verificado). Lleva una disciplina de verificación adversarial a cada perfil.
+
+## Plantilla de matriz de puntuación (etapa de selección)
+
+Un prefiltro ligero para decidir quién pasa al benchmarking completo. Puntúa 1–5; conserva candidatos que puntúen alto en **distintividad** o en **credibilidad** — la tensión estratégica del cliente hace que ambos polos sean instructivos.
+
+| Candidato | Postura de posicionamiento | Especialización | Banda de tamaño | Tier | Solapamiento de oferta (1–5) | Distintividad (1–5) | Credibilidad comercial (1–5) | Proximidad de oficio (1–5) | ¿Incluir? |
+|-----------|----------------------------|-----------------|-----------------|------|------------------------------|----------------------|------------------------------|----------------------------|-----------|
+
+Reglas prácticas (aplícalas según la consecuencia de alcance del brief de posicionamiento):
+
+- Alta distintividad **y** alta credibilidad → perfil obligatorio (demuestra que la tensión objetivo del cliente es alcanzable).
+- Alta distintividad, baja credibilidad → caso de advertencia (memorable pero incontratable — un modo de fallo del que aprender).
+- Alta credibilidad, baja distintividad → la masa "competente pero olvidable" contra la que el cliente se define.
+- Bajo en ambos → descarta, salvo que haga falta para amplitud de paisaje.
+
+## Salida de esta etapa
+
+Un conjunto de competidores delimitado y en tiers (típicamente 10–18 candidatos → 8–12 perfilados), cada uno etiquetado con sus posiciones en los ejes, tier y enlaces a fuentes, listo para entregar a `metodologia-benchmarks`.
+
+## Antipatrones
+
+- **Delimitar sin brief de posicionamiento.** Una lista de competidores construida sin la lente del cliente es ruido. El brief determina qué cuenta como rival real.
+- **Listar toda empresa parecida.** La meta es un conjunto defendible de 10–18 candidatos, no un censo. Amplitud sin poda hace inmanejable el benchmarking.
+- **Difuminar los tiers Directo/Adyacente/Aspiracional.** Cada tier cumple un propósito estratégico distinto. Mezclarlos produce una lista plana que no sirve para decidir.
+- **Depender de una sola fuente por competidor.** El copy autorreportado del sitio es marketing, no hecho. Verifica atributos en al menos dos fuentes.
+- **Saltar directo a la puntuación.** Esta skill delimita y clasifica el conjunto. La puntuación la maneja `metodologia-benchmarks`. No mezcles los dos pasos.
+
+## Ejemplos
+
+**Escenario:** un estudio boutique de identidad de marca (2 personas, remoto en la UE, sprints productizados, estética contracorriente con manifiesto) quiere delimitar su conjunto competitivo antes del benchmarking. La tensión estratégica del brief de posicionamiento es *memorabilidad × contratabilidad*.
+
+**Paso 1 — población en los ocho ejes (muestra de candidatos):**
+
+| Candidato | Postura de posicionamiento | Especialización | Banda de tamaño | Contratación | Distintividad | Modelo de evidencia | Fuerza de marca | Mercado |
+|---|---|---|---|---|---|---|---|---|
+| Estudio A | guiado por marca / editorial | solo identidad | micro | productizado | contracorriente | guiado por estética | de culto | remoto-global |
+| Estudio B | guiado por capacidad | DS+motion amplio | boutique | a medida | convencional | guiado por resultados | intercambiable | EE. UU. |
+| Agencia C | guiado por capacidad | marca+digital | mediano | retainer | convencional | guiado por resultados | intercambiable | UE |
+| Freelancer D | guiado por marca | solo voz de marca | solo | tarifa diaria | editorial | guiado por estética | apropiable | global |
+| Estudio E | guiado por marca | estrategia de marca | micro | productizado | con manifiesto | guiado por resultados | de culto | UE-remoto |
+
+**Paso 2 — puntuación de prefiltro (consecuencia de alcance del cliente: ponderar la distintividad porque su foso es el punto de vista, no la amplitud de capacidades):**
+
+| Candidato | Solapamiento de oferta (1–5) | Distintividad (1–5) | Credibilidad comercial (1–5) | Proximidad de oficio (1–5) | Tier | ¿Incluir? |
+|---|---|---|---|---|---|---|
+| Estudio A | 5 | 5 | 3 | 5 | Directo | ✓ perfil obligatorio |
+| Estudio B | 3 | 2 | 5 | 3 | Adyacente | ✓ ancla de credibilidad |
+| Agencia C | 2 | 1 | 5 | 2 | Aspiracional | ✓ referencia de escala |
+| Freelancer D | 4 | 4 | 2 | 4 | Directo | ✓ caso de advertencia |
+| Estudio E | 5 | 5 | 4 | 4 | Directo | ✓ perfil obligatorio |
+
+**Paso 3 — salida entregada a `metodologia-benchmarks`:**
+Cinco candidatos (3 Directos, 1 Adyacente, 1 Aspiracional), cada uno etiquetado con posiciones en los ejes, tier y enlaces a fuentes. El Estudio A y el Estudio E son los rivales cara a cara más afilados; el Freelancer D es el caso de advertencia "memorable pero incontratable" del que aprender.
+
+## Skills relacionadas
+
+- `descubrimiento-marca` — úsala primero para establecer el brief de posicionamiento y la tensión estratégica que delimitan el conjunto de competidores.
+- `metodologia-benchmarks` — el siguiente paso; toma el conjunto en tiers y puntúa cada competidor en nueve dimensiones.

package/vendor/theus-arsenal/skills/api-x/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: api-x
+description: Integración con la API de X/Twitter para publicar posts e hilos, leer timelines, buscar y analizar métricas. Cubre patrones de autenticación OAuth, límites de tasa y publicación de contenido nativo de la plataforma. Úsala cuando se quiera interactuar con X programáticamente.
+---
+
+# API de X
+
+> **Skill propensa a desactualizarse.** Los endpoints, niveles de acceso, cuotas y
+> permisos de escritura de la API de X cambian con frecuencia. Verifica la
+> documentación de desarrollador vigente y el acceso de la cuenta antes de citar
+> límites de tasa o implementar un flujo de publicación/búsqueda.
+
+Interacción programática con X (Twitter) para publicar, leer, buscar y analizar métricas.
+
+## Cuándo activarla
+
+- Se quieren publicar posts o hilos programáticamente
+- Leer timeline, menciones o datos de usuarios desde X
+- Buscar contenido, tendencias o conversaciones en X
+- Construir integraciones o bots para X
+- Analítica y seguimiento de engagement
+- El usuario dice "publica en X", "tuitea", "API de X" o "API de Twitter"
+
+## Autenticación
+
+### OAuth 2.0 Bearer Token (solo app)
+
+Mejor para: operaciones de mucha lectura, búsqueda, datos públicos.
+
+```bash
+# Configuración del entorno
+export X_BEARER_TOKEN="tu-bearer-token"
+```
+
+```python
+import os
+import requests
+
+bearer = os.environ["X_BEARER_TOKEN"]
+headers = {"Authorization": f"Bearer {bearer}"}
+
+# Buscar tuits recientes
+resp = requests.get(
+    "https://api.x.com/2/tweets/search/recent",
+    headers=headers,
+    params={"query": "theus cli", "max_results": 10}
+)
+tweets = resp.json()
+```
+
+### OAuth 1.0a (contexto de usuario)
+
+Requerido para: publicar posts, gestionar la cuenta, DMs y cualquier flujo de escritura.
+
+```bash
+# Configuración del entorno — cárgala antes de usar
+export X_CONSUMER_KEY="tu-consumer-key"
+export X_CONSUMER_SECRET="tu-consumer-secret"
+export X_ACCESS_TOKEN="tu-access-token"
+export X_ACCESS_TOKEN_SECRET="tu-access-token-secret"
+```
+
+Pueden existir alias heredados como `X_API_KEY`, `X_API_SECRET` y `X_ACCESS_SECRET` en configuraciones antiguas. Prefiere los nombres `X_CONSUMER_*` y `X_ACCESS_TOKEN_SECRET` al documentar o cablear flujos nuevos.
+
+```python
+import os
+from requests_oauthlib import OAuth1Session
+
+oauth = OAuth1Session(
+    os.environ["X_CONSUMER_KEY"],
+    client_secret=os.environ["X_CONSUMER_SECRET"],
+    resource_owner_key=os.environ["X_ACCESS_TOKEN"],
+    resource_owner_secret=os.environ["X_ACCESS_TOKEN_SECRET"],
+)
+```
+
+## Operaciones básicas
+
+### Publicar un post
+
+```python
+resp = oauth.post(
+    "https://api.x.com/2/tweets",
+    json={"text": "Hola desde Theus"}
+)
+resp.raise_for_status()
+tweet_id = resp.json()["data"]["id"]
+```
+
+### Publicar un hilo
+
+```python
+def post_thread(oauth, tweets: list[str]) -> list[str]:
+    ids = []
+    reply_to = None
+    for text in tweets:
+        payload = {"text": text}
+        if reply_to:
+            payload["reply"] = {"in_reply_to_tweet_id": reply_to}
+        resp = oauth.post("https://api.x.com/2/tweets", json=payload)
+        tweet_id = resp.json()["data"]["id"]
+        ids.append(tweet_id)
+        reply_to = tweet_id
+    return ids
+```
+
+### Leer el timeline de un usuario
+
+```python
+resp = requests.get(
+    f"https://api.x.com/2/users/{user_id}/tweets",
+    headers=headers,
+    params={
+        "max_results": 10,
+        "tweet.fields": "created_at,public_metrics",
+    }
+)
+```
+
+### Buscar posts
+
+```python
+resp = requests.get(
+    "https://api.x.com/2/tweets/search/recent",
+    headers=headers,
+    params={
+        "query": "from:usuario_ejemplo -is:retweet",
+        "max_results": 10,
+        "tweet.fields": "public_metrics,created_at",
+    }
+)
+```
+
+### Extraer posts originales recientes para modelar la voz
+
+```python
+resp = requests.get(
+    "https://api.x.com/2/tweets/search/recent",
+    headers=headers,
+    params={
+        "query": "from:usuario_ejemplo -is:retweet -is:reply",
+        "max_results": 25,
+        "tweet.fields": "created_at,public_metrics",
+    }
+)
+voice_samples = resp.json()
+```
+
+### Obtener un usuario por nombre de usuario
+
+```python
+resp = requests.get(
+    "https://api.x.com/2/users/by/username/usuario_ejemplo",
+    headers=headers,
+    params={"user.fields": "public_metrics,description,created_at"}
+)
+```
+
+### Subir un medio y publicar
+
+```python
+# La subida de medios usa el endpoint v1.1
+
+# Paso 1: subir el medio
+media_resp = oauth.post(
+    "https://upload.twitter.com/1.1/media/upload.json",
+    files={"media": open("image.png", "rb")}
+)
+media_id = media_resp.json()["media_id_string"]
+
+# Paso 2: publicar con el medio
+resp = oauth.post(
+    "https://api.x.com/2/tweets",
+    json={"text": "Mira esto", "media": {"media_ids": [media_id]}}
+)
+```
+
+## Límites de tasa
+
+Los límites de tasa de la API de X varían por endpoint, método de autenticación y nivel de cuenta, y cambian con el tiempo. Siempre:
+- Consulta la documentación de desarrollador vigente de X antes de codificar suposiciones
+- Lee las cabeceras `x-rate-limit-remaining` y `x-rate-limit-reset` en tiempo de ejecución
+- Aplica backoff automático en lugar de confiar en tablas estáticas en el código
+
+```python
+import time
+
+remaining = int(resp.headers.get("x-rate-limit-remaining", 0))
+if remaining < 5:
+    reset = int(resp.headers.get("x-rate-limit-reset", 0))
+    wait = max(0, reset - int(time.time()))
+    print(f"Acercándose al límite de tasa. Se reinicia en {wait}s")
+```
+
+## Manejo de errores
+
+```python
+resp = oauth.post("https://api.x.com/2/tweets", json={"text": content})
+if resp.status_code == 201:
+    return resp.json()["data"]["id"]
+elif resp.status_code == 429:
+    reset = int(resp.headers["x-rate-limit-reset"])
+    raise Exception(f"Límite de tasa alcanzado. Se reinicia en {reset}")
+elif resp.status_code == 403:
+    raise Exception(f"Prohibido: {resp.json().get('detail', 'revisa los permisos')}")
+else:
+    raise Exception(f"Error de la API de X {resp.status_code}: {resp.text}")
+```
+
+## Seguridad
+
+- **Nunca incrustes tokens en el código.** Usa variables de entorno o archivos `.env`.
+- **Nunca comitees archivos `.env`.** Añádelos al `.gitignore`.
+- **Rota los tokens** si se exponen. Regenera en developer.x.com.
+- **Usa tokens de solo lectura** cuando no se necesite acceso de escritura.
+- **Guarda los secretos OAuth de forma segura** — no en el código fuente ni en los logs.
+
+## Integración con el motor de contenido
+
+Usa `voz-de-marca` junto con `motor-de-contenido` para generar contenido nativo de la plataforma y luego publicarlo vía la API de X:
+1. Extrae posts originales recientes cuando importe igualar la voz
+2. Construye o reutiliza un `PERFIL DE VOZ`
+3. Genera el contenido con `motor-de-contenido` en formato nativo de X
+4. Valida la longitud y la estructura del hilo
+5. Devuelve el borrador para aprobación salvo que el usuario haya pedido explícitamente publicar ya
+6. Publica vía la API de X solo tras la aprobación
+7. Rastrea el engagement vía `public_metrics`
+
+## Skills relacionadas
+
+- `voz-de-marca` — construir un perfil de voz reutilizable a partir de material real de X y del sitio/fuentes
+- `motor-de-contenido` — generar contenido nativo de plataforma para X
+- `publicacion-cruzada` — distribuir contenido entre X, LinkedIn y otras plataformas