370025263/red-bucket

Skill red-bucket

Este skill guía a los agentes de IA en la interacción con servidores red-bucket. red-bucket es un hub para activos de agentes de IA (skills, configuraciones MCP, instrucciones como CLAUDE.md y AGENTS.md, subagentes, plugins) organizados por espacio de nombres user/bucket, con traducción de formato entre plataformas en el momento de la descarga a través de codex, claude, agents y openclaw.

---

Guardas e Invariantes del Agente

1. Autenticación: Todas las operaciones de escritura y el acceso a buckets privados propiedad del usuario requieren Authorization: Bearer <token>. La lectura de buckets públicos es anónima y no requiere cabecera.
2. Seguridad de Credenciales: Nunca imprimas, registres o filtres contraseñas, tokens de API o secretos en la salida o en las transcripciones del usuario.
3. Invariancia de Bucket Privado 404: Cualquier solicitud a un bucket privado o sus subrecursos desde un llamante no autenticado o un no propietario DEBE devolver HTTP 404 Not Found (nunca 403 Forbidden). Los no propietarios no pueden distinguir si un bucket privado existe o no.
4. Cuotas y Límites:
   • Cuota predeterminada de buckets: 5 buckets por usuario (superarlo devuelve 403 con código bucket_quota_exceeded).
   • Límite de almacenamiento del bucket: 10MB por bucket (superarlo devuelve 413 con código bucket_storage_exceeded).
5. Ámbito de la API: Todos los endpoints residen bajo /api/v1/.

---

La Regla de los Tres Nombres

Nunca confundas ni mezcles estas tres operaciones:

• copy (POST /api/v1/users/{username}/buckets/{bucket}/copies): Duplica un activo de un bucket fuente legible a tu propio bucket de destino con historial de procedencia. Devuelve un objeto JSON InstallRecord.
• install-script (GET /api/v1/users/{username}/buckets/{bucket}/install-script): Devuelve texto de script de shell ejecutable que descarga y coloca activos traducidos en el sistema de archivos local.
• translated fetch (GET .../translated): Obtiene bytes traducidos sin procesar o un archivo zip transformado sobre la marcha para una plataforma de destino especificada.

---

Instalación y Descubrimiento

1. Instalación del Skill del Agente (vía npx skills)

Para instalar este skill en un entorno de agente:

# Instalación global para acceso del agente
npx skills add 370025263/red-bucket --skill red-bucket -g -y

# Listar skills disponibles sin instalar
npx skills add 370025263/red-bucket --list

2. El cliente incluido: scripts/rb.mjs

Este skill incluye su propio cliente. Necesita Node 18+ y nada más — ni sh, ni curl, ni unzip, ni jq, ni npm install. Prefiérelo sobre implementar manualmente las llamadas HTTP; ya realiza la normalización de origen, los permisos de archivo y las escrituras atómicas correctamente.

node <directorio-del-skill>/scripts/rb.mjs login   --client claude
node <directorio-del-skill>/scripts/rb.mjs status
node <directorio-del-skill>/scripts/rb.mjs logout
node <directorio-del-skill>/scripts/rb.mjs install alice/tools --target claude
node <directorio-del-skill>/scripts/rb.mjs create  alice/tools --visibility private --description "mi kit"
node <directorio-del-skill>/scripts/rb.mjs upload  alice/tools ./my-skill --type skill --harness claude --path skills/my-skill

login imprime el enlace y luego espera --wait segundos (predeterminado 20) para el navegador. Si tu herramienta de shell tiene un tiempo de espera, está bien: al alcanzarlo sale con 0, mantiene el código pendiente en pending.json junto al archivo de autenticación y lo informa. Dile al usuario que apruebe y luego ejecute login o status de nuevo; el token se recoge y guarda en ese momento. No se emite un segundo código mientras el primero sigue siendo válido, así que nunca "reintentes" matando el proceso y empezando de nuevo.

install escribe en el directorio actual; --dest DIR o $RED_BUCKET_DEST lo coloca en otro lugar. --origin URL o $RED_BUCKET_URL apunta a un servidor autoalojado. Los buckets privados funcionan una vez que has iniciado sesión — el mismo comando, usando la credencial almacenada.

create y upload son la parte de publicación. upload envía cada archivo bajo el directorio local como un solo activo: archivos de texto como texto, cualquier otra cosa como base64, enraizado en --path (predeterminado: el nombre del propio directorio). --type es lo que es el activo (skill, mcp, instructions, subagent, plugin) y --harness es para qué plataforma fue escrito — el servidor traduce desde allí. El servidor valida el activo y el cliente imprime exactamente a lo que objetó, por ejemplo validation failed: SKILL.md: SKILL.md missing. Ambos necesitan iniciar sesión. Prefiere estos sobre los cuerpos POST .../assets hechos a mano: los endpoints sin procesar a continuación son el contrato, el cliente es la herramienta.

3. Instalar un bucket sin este skill

GET .../install-script?target=<plataforma> con Accept: text/plain devuelve un programa Node autónomo. Guarda el cuerpo como rb-install.mjs y ejecuta node rb-install.mjs. Misma dependencia solo de Node, mismas anulaciones de RED_BUCKET_URL / RED_BUCKET_DEST.

(Para buckets privados no hay un programa público que se pueda pegar: obtén GET .../translated con Authorization: Bearer <token> en su lugar, o simplemente usa rb.mjs install mientras has iniciado sesión).

---

Inicio de Sesión y Dónde se Almacena el Token

Leer buckets públicos no necesita nada. Todo lo que escribe — crear un bucket, subir un activo, abrir un issue o un pull request — necesita un token de portador.

Nunca preguntes al usuario por su contraseña de red-bucket. Utiliza el mecanismo de entrega al navegador a continuación. Es la única forma autorizada para que un agente obtenga un token.

Dónde se guarda el token

$RED_BUCKET_AUTH                                     si está configurado, ese archivo exacto
%APPDATA%\red-bucket\auth.json                       en Windows
${XDG_CONFIG_HOME:-~/.config}/red-bucket/auth.json   en cualquier otro lugar

Mira allí primero. Si ya existe una entrada activa para este origen, úsala — no envíes al usuario a través del navegador de nuevo para un token que ya te concedió.

Modo de directorio 0700, modo de archivo 0600. Escríbelo atómicamente (archivo temporal en el mismo directorio, luego renombrar) para que una escritura interrumpida no pueda dejar un archivo a medias. Forma, clave por origen para que un servidor autoalojado y el público puedan coexistir:

{
  "version": 1,
  "hosts": {
    "https://redbucket.store": {
      "username": "stone91",
      "token": "...",
      "created_at": "2026-09-03T04:07:19Z",
      "client": "claude"
    }
  }
}

Resuelve la identidad en este orden: $RED_BUCKET_TOKEN si está configurado, luego la entrada en ese archivo cuya clave coincida con el origen al que te estás comunicando, luego anónimo. Envíalo como Authorization: Bearer <token>.

Normaliza el origen antes de usarlo como clave, tanto al escribir como al buscar: escribe en minúsculas el esquema y el host, elimina una barra diagonal final, elimina el puerto cuando sea el predeterminado para el esquema. Así que https://RedBucket.store:443/ y https://redbucket.store son una clave, no tres. Saltate esto y enviarás al usuario de vuelta al navegador para un token que ya tienes, y dejarás una entrada duplicada.

Si el archivo no se puede analizar, o version es un número que no reconoces, trátalo como si no hubiera credencial — recurre a anónimo y dile al usuario que el archivo parece incorrecto. Nunca elimines ni sobrescribas un archivo que no pudiste leer; puede contener los tokens de otra herramienta.

Lee, cambia y escribe el archivo completo de una vez, y mantén la ventana corta. Si dos plataformas inician sesión al mismo tiempo, ambas leen, ambas escriben, y la más lenta borra la entrada de la otra. El mecanismo de archivo-temporal-luego-renombrar de arriba detiene un archivo roto, no una actualización perdida.

Nunca imprimas el token, nunca lo repitas en la transcripción, nunca lo escribas en un repositorio, nunca lo pongas en un comando de shell que el usuario pueda ver en su historial.

Obtener un token: la entrega al navegador

El token es acuñado por el servidor y entregado directamente a tu proceso. Nunca viaja a través de la conversación.

1. Inícialo.

POST /api/v1/auth/device
{"client": "claude"}

201 te da device_code, user_code, verification_url_complete, expires_in (600) e interval (5).

El device_code es la mitad secreta — permanece dentro de tu proceso. El user_code es el corto que el humano lee.

2. Muéstrale al humano el enlace. Algo como:

Abre esto para iniciar sesión o crear una cuenta: https://redbucket.store/link/BQ7K-2M4X La página debería mostrar el código BQ7K-2M4X. Esperaré.

Lo abren en un navegador, inician sesión si no lo han hecho ya, y ven una pantalla que nombra a tu cliente y enumera lo que están concediendo. Pulsan Autorizar o Rechazar.

3. Realiza sondeos, no más rápido que interval segundos:

POST /api/v1/auth/device/token
{"device_code": "..."}

• {"status": "pending"} — sigue esperando.
• {"status": "denied"} — dijeron que no. Detente, y dilo claramente.
• {"status": "approved", "token": ..., "user": {...}} — lo tienes.
• 404 — el código expiró, o ya fue recogido. Ofrece empezar de nuevo. El device_code es de un solo uso; un segundo sondeo exitoso es siempre un 404.

4. Guárdalo en la ruta de arriba y di solo Sesión iniciada como <nombre_de_usuario>.

Cerrar sesión

POST /api/v1/auth/logout con el token revoca ese token en el lado del servidor. Luego elimina la entrada de ese host del archivo de autenticación. Haz ambas cosas; una sin la otra deja un token activo en el servidor o uno muerto en el disco.

No hay un servidor MCP de red-bucket

mcp en red-bucket es un tipo de activo que un bucket puede contener, no un servidor que ejecutamos. Este skill hablando con /api/v1/ es toda la integración del cliente. No busques un endpoint MCP al que conectarte.

Flujos del Lado del Usuario y Operaciones de la API

1. Registro, Inicio de Sesión y Perfil de Usuario

• Registrarse:

  POST /api/v1/auth/register
  Content-Type: application/json
  
  {
    "username": "alice",
    "email": "[email protected]",
    "password": "strongpassword123"
  }
  

  • Respuesta: 201 Created con Location: /api/v1/users/alice y objeto User público (las contraseñas se hashean con Argon2id; no se emite token en el registro).

• Iniciar Sesión:

  POST /api/v1/auth/login
  Content-Type: application/json
  
  {
    "email": "[email protected]",
    "password": "strongpassword123"
  }
  

  • Respuesta: 200 OK con {"token": "<token_opaco>", "token_type": "bearer", "user": { ... }}.

• Obtener Perfil (me):

  GET /api/v1/users/me
  Authorization: Bearer <token>
  

  • Respuesta: 200 OK con detalles del usuario (incluyendo email, bucket_quota, bucket_count).

---

2. Crear Bucket desde Plantilla

Crea un bucket bajo el espacio de nombres del usuario autenticado:

POST /api/v1/users/{username}/buckets
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "dev-skills",
  "visibility": "public",
  "description": "Skills de agente de desarrollo general",
  "template": "claude"
}

• Plantillas permitidas: codex, agents, claude, openclaw (u omitir para un bucket vacío). Esta lista crece; GET /api/v1/templates es la actual.
• Visibilidad: public o private (predeterminado es private).
• Respuesta: 201 Created con Location: /api/v1/users/{username}/buckets/{name} y JSON Bucket.
• Errores: 403 (bucket_quota_exceeded si se superan 5 buckets), 409 (bucket_name_taken).

---

3. Subir Activos

Sube un activo con validación de formato y aplicación de cuotas:

POST /api/v1/users/{username}/buckets/{bucket}/assets
Authorization: Bearer <token>
Content-Type: application/json

{
  "type": "skill",
  "source_harness": "claude",
  "path": "skills/calculator",
  "files": [
    {
      "path": "SKILL.md",
      "content_text": "---\nname: calculator\ndescription: Realiza cálculos aritméticos\n---\n\n# Skill Calculadora\n"
    }
  ]
}

• Tipos de activos: skill, mcp, instructions, subagent, plugin.
• Plataformas fuente: claude, codex, agents, openclaw. Esta lista crece; GET /api/v1/translation-matrix es la actual. Nunca rechaces una plataforma que el usuario nombre solo porque falte en este archivo — deja que el servidor responda.
• El contenido del archivo se puede proporcionar como content_text (UTF-8) o content_base64.
• Respuesta: 201 Created con Location: /api/v1/users/{username}/buckets/{bucket}/assets/{asset_id}.
• Errores: 413 (bucket_storage_exceeded si el bucket supera los 10MB), 422 (validation_failed con regla específica y violaciones de ruta).

---

4. Navegación Anónima y Obtención Traducida

• Navegar Bucket (Público/Anónimo):

  GET /api/v1/users/{username}/buckets/{bucket}
  

• Navegar Árbol de Archivos y Blobs:

  GET /api/v1/users/{username}/buckets/{bucket}/tree
  GET /api/v1/users/{username}/buckets/{bucket}/blob/{*path}
  

• Obtener Bucket Completo Traducido para Plataforma Destino:

  GET /api/v1/users/{username}/buckets/{bucket}/translated?target=codex
  

  • Respuesta: 200 OK (archivo zip binario, cabecera X-Red-Bucket-Lossy: true|false).

• Obtener Activo Individual Traducido:

  GET /api/v1/users/{username}/buckets/{bucket}/assets/{asset_id}/translated?target=codex
  

  • Respuesta: 200 OK (bytes traducidos sin procesar o archivo zip).

---

5. Ejecutar Script de Instalación

Recupera el script de instalación de shell generado para una plataforma de destino:

GET /api/v1/users/{username}/buckets/{bucket}/install-script?target=claude
Accept: text/plain

• Respuesta: 200 OK con texto del script de shell sin procesar.
• Se ejecuta en el lado del cliente para descargar el archivo zip traducido y colocar los archivos en los directorios locales de la plataforma.

---

6. Copiar Activo a tu Propio Bucket (Seguimiento de Procedencia)

Copia un activo de un bucket fuente a tu propio bucket de destino:

POST /api/v1/users/{username}/buckets/{dest_bucket}/copies
Authorization: Bearer <token>
Content-Type: application/json

{
  "source_username": "bob",
  "source_bucket": "public-skills",
  "source_asset_id": 12,
  "dest_path": "skills/calculator"
}

• Respuesta: 201 Created con Location: /api/v1/users/{username}/buckets/{dest_bucket}/copies/{copy_id} y objeto JSON InstallRecord.
• Valida el activo fuente, verifica la cuota de 10MB y registra la procedencia.

---

7. Issues y Comentarios

• Crear Issue:

  POST /api/v1/users/{username}/buckets/{bucket}/issues
  Authorization: Bearer <token>
  Content-Type: application/json
  
  {
    "title": "Error en la traducción del skill calculadora",
    "body": "Cuando se traduce el skill calculadora de claude a codex, la función de suma no se traslada correctamente."
  }
  

  • Respuesta: 201 Created con Location: /api/v1/users/{username}/buckets/{bucket}/issues/{issue_id} y objeto JSON Issue.

• Listar Issues:

  GET /api/v1/users/{username}/buckets/{bucket}/issues
  

  • Respuesta: 200 OK con array de objetos Issue.

• Comentar en un Issue:

  POST /api/v1/users/{username}/buckets/{bucket}/issues/{issue_id}/comments
  Authorization: Bearer <token>
  Content-Type: application/json
  
  {
    "body": "He confirmado este error. Las funciones matemáticas se serializan de forma diferente entre plataformas."
  }
  

  • Respuesta: 201 Created con objeto JSON Comment.

---

Lista de Verificación de Cumplimiento de Privacidad para el Agente

1. Todos los endpoints requieren autenticación para lecturas privadas.
   • Las solicitudes no autenticadas a buckets privados devuelven 404 Not Found, nunca 403.
2. El inicio de sesión con contraseña nunca está mediado por el agente.
   • El único flujo de autenticación es la concesión del dispositivo: el agente muestra un enlace y sondea, la contraseña nunca pasa por el agente.
3. Los tokens se almacenan de forma segura en el sistema de archivos (0600/0700).
   • El cliente es responsable de los permisos de archivo y las escrituras atómicas; el agente nunca debe copiar tokens a la transcripción.
4. El consentimiento del usuario es explícito.
   • La página de autorización del dispositivo enumera explícitamente el cliente y los alcances; el usuario debe hacer clic en Autorizar antes de que se emita un token.
5. No hay fuga de datos a través de mensajes de error.
   • Los buckets privados no existen desde la perspectiva de un observador no autorizado; los mensajes de error no filtran nombres de bucket, nombres de activos ni metadatos.
6. Los usuarios pueden revocar tokens en cualquier momento.
   • GET /api/v1/auth/tokens lista todas las sesiones activas; DELETE /api/v1/auth/tokens/{token_id} las revoca; POST /api/v1/auth/logout revoca el token actual.

---

Referencia de la API

Autenticación

Método	Ruta	Descripción
GET	/api/v1/auth/tokens	Listar tokens activos para el usuario
DELETE	/api/v1/auth/tokens/{token_id}	Revocar un token específico
POST	/api/v1/auth/device	Iniciar flujo de autenticación de dispositivo
POST	/api/v1/auth/device/token	Sondear para la aprobación del usuario
POST	/api/v1/auth/logout	Revocar el token actual del portador

Buckets

Método	Ruta	Descripción
POST	/api/v1/users/{username}/buckets	Crear un nuevo bucket
GET	/api/v1/users/{username}/buckets/{bucket}	Obtener metadatos del bucket
PATCH	/api/v1/users/{username}/buckets/{bucket}	Actualizar bucket (visibilidad, descripción)
DELETE	/api/v1/users/{username}/buckets/{bucket}	Eliminar un bucket y su contenido

Activos

Método	Ruta	Descripción
POST	/api/v1/users/{username}/buckets/{bucket}/assets	Subir un activo
GET	/api/v1/users/{username}/buckets/{bucket}/assets	Listar activos en un bucket
GET	/api/v1/users/{username}/buckets/{bucket}/assets/{asset_id}	Obtener metadatos del activo
DELETE	/api/v1/users/{username}/buckets/{bucket}/assets/{asset_id}	Eliminar un activo
GET	/api/v1/users/{username}/buckets/{bucket}/assets/{asset_id}/translated	Obtener activo traducido sin procesar

Copias y Traducción

Método	Ruta	Descripción
POST	/api/v1/users/{username}/buckets/{dest_bucket}/copies	Copiar activo con procedencia
GET	/api/v1/users/{username}/buckets/{bucket}/copies	Listar copias en este bucket
GET	/api/v1/users/{username}/buckets/{bucket}/translated	Obtener bucket completo traducido
GET	/api/v1/users/{username}/buckets/{bucket}/install-script	Obtener script de instalación de shell

Utilidades

Método	Ruta	Descripción
GET	/api/v1/templates	Listar plantillas de bucket disponibles
GET	/api/v1/translation-matrix	Listar plataformas fuente y destino disponibles

---

Buenas Prácticas de Uso

• Siempre usa el cliente incluido (rb.mjs) para operaciones de creación y subida, ya que maneja la validación, la serialización de archivos y el manejo de errores correctamente.
• Revisa pending.json después de un inicio de sesión fallido por tiempo de espera; contiene el código de dispositivo no reclamado que se puede usar para completar el inicio de sesión.
• Usa variables de entorno (RED_BUCKET_URL, RED_BUCKET_DEST, RED_BUCKET_AUTH) para configurar directorios de almacenamiento y URL de servidor personalizados.
• Respeta la invariancia 404 de los buckets privados: nunca adivines ni enumeres espacios de nombres de buckets privados.
• Usa translated en lugar de install-script cuando trabajes con buckets privados, ya que install-script está destinado a ser pegado y ejecutado directamente por el usuario.

---

Red-bucket — Traducción de activos de agentes de IA, simplificada.