370025263/red-bucket

Skill red-bucket

Esta skill orienta agentes de IA na interação com servidores red-bucket. red-bucket é um hub para ativos de agentes de IA (skills, configurações MCP, instruções como CLAUDE.md e AGENTS.md, subagentes, plugins) organizados pelo namespace user/bucket, com tradução de formato entre plataformas feita sob demanda nos formatos codex, claude, agents e openclaw.

---

Diretrizes e Invariantes do Agente

1. Autenticação: Todas as operações de escrita e acesso a buckets privados pertencentes ao usuário exigem Authorization: Bearer <token>. A leitura de buckets públicos é anônima e não requer cabeçalho.
2. Segurança de Credenciais: Nunca imprima, registre ou vaze senhas, tokens de API ou segredos na saída ou em transcrições do usuário.
3. Invariante de Bucket Privado 404: Qualquer requisição a um bucket privado ou seus sub-recursos por parte de um chamador não autenticado ou não proprietário DEVE retornar HTTP 404 Not Found (nunca 403 Forbidden). Não proprietários não podem distinguir se um bucket privado existe ou não.
4. Cotas e Limites:
   • Cota padrão de buckets: 5 buckets por usuário (exceder retorna 403 com código bucket_quota_exceeded).
   • Limite de armazenamento do bucket: 10MB por bucket (exceder retorna 413 com código bucket_storage_exceeded).
5. Escopo da API: Todos os endpoints estão sob /api/v1/.

---

A Regra dos Três Nomes

Nunca confunda ou misture estas três operações:

• copy (POST /api/v1/users/{username}/buckets/{bucket}/copies): Duplica um ativo de um bucket de origem legível para o seu próprio bucket de destino, com histórico de proveniência. Retorna um objeto JSON InstallRecord.
• install-script (GET /api/v1/users/{username}/buckets/{bucket}/install-script): Retorna texto de script de shell executável que baixa e coloca os ativos traduzidos no sistema de arquivos local.
• translated fetch (GET .../translated): Obtém bytes brutos traduzidos ou um arquivo zip transformado em tempo real para uma plataforma alvo especificada.

---

Instalação e Descoberta

1. Instalação da Skill no Agente (via npx skills)

Para instalar esta skill em um ambiente de agente:

# Instalação global para acesso do agente
npx skills add 370025263/red-bucket --skill red-bucket -g -y

# Lista skills disponíveis sem instalar
npx skills add 370025263/red-bucket --list

2. O cliente incluído: scripts/rb.mjs

Esta skill vem com seu próprio cliente. Ele precisa de Node 18+ e nada mais — sem sh, sem curl, sem unzip, sem jq, sem npm install. Prefira-o em vez de montar manualmente as chamadas HTTP; ele já faz normalização de origem, permissões de arquivo e gravações atômicas corretamente.

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

login imprime o link e então espera --wait segundos (padrão 20) pelo navegador. Se sua ferramenta de shell tiver um tempo limite, tudo bem: ao expirar, ela sai com 0, mantém o código pendente em pending.json ao lado do arquivo de autenticação e informa. Diga ao usuário para aprovar, então execute login ou status novamente; o token é coletado e salvo então. Nenhum segundo código é emitido enquanto o primeiro ainda for válido, portanto, nunca "tente novamente" matando o processo e recomeçando.

install escreve no diretório atual; --dest DIR ou $RED_BUCKET_DEST coloca em outro lugar. --origin URL ou $RED_BUCKET_URL aponta para um servidor auto-hospedado. Buckets privados funcionam depois que você faz login — o mesmo comando, usando a credencial armazenada.

create e upload são a parte de publicação. upload envia cada arquivo sob o diretório local como um único ativo: arquivos de texto como texto, qualquer outra coisa como base64, enraizado em --path (padrão: o próprio nome do diretório). --type é o que o ativo é (skill, mcp, instructions, subagent, plugin) e --harness é para qual plataforma ele foi escrito — o servidor traduz a partir daí. O servidor valida o ativo e o cliente imprime exatamente o que ele objetou, por exemplo validation failed: SKILL.md: SKILL.md missing. Ambos precisam de um login. Prefira estes em vez de corpos POST .../assets construídos manualmente: os endpoints brutos abaixo são o contrato, o cliente é a ferramenta.

3. Instalando um bucket sem esta skill

GET .../install-script?target=<harness> com Accept: text/plain retorna um programa Node autossuficiente. Salve o corpo como rb-install.mjs e execute node rb-install.mjs. Mesma dependência exclusiva de Node, mesmas substituições RED_BUCKET_URL / RED_BUCKET_DEST.

(Para buckets privados não há programa público colável: busque GET .../translated com Authorization: Bearer <token> ou apenas use rb.mjs install enquanto estiver logado.)

---

Fazendo Login e Onde o Token Fica

Ler buckets públicos não precisa de nada. Tudo que escreve — criar um bucket, enviar um ativo, abrir uma issue ou pull request — precisa de um token bearer.

Nunca peça a senha do red-bucket do usuário. Use a transferência pelo navegador abaixo. É a única forma autorizada para um agente obter um token.

Onde o token é mantido

$RED_BUCKET_AUTH                                     se definido, esse arquivo exato
%APPDATA%\red-bucket\auth.json                       no Windows
${XDG_CONFIG_HOME:-~/.config}/red-bucket/auth.json   em todos os outros lugares

Procure lá primeiro. Se uma entrada ativa para esta origem já existir, use-a — não envie o usuário de volta pelo navegador para um token que ele já concedeu a você.

Modo de diretório 0700, modo de arquivo 0600. Escreva atomicamente (arquivo temporário no mesmo diretório, depois renomeie) para que uma gravação interrompida não possa deixar um arquivo pela metade. Forma, indexada por origem para que um servidor auto-hospedado e o público possam coexistir:

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

Resolva a identidade nesta ordem: $RED_BUCKET_TOKEN se definido, depois a entrada naquele arquivo cuja chave corresponde à origem com a qual você está falando, depois anônimo. Envie como Authorization: Bearer <token>.

Normalize a origem antes de usá-la como chave, tanto ao escrever quanto ao consultar: transforme esquema e host em minúsculas, remova a barra final, remova a porta quando for o padrão para o esquema. Então https://RedBucket.store:443/ e https://redbucket.store são uma chave, não três. Pule isso e você enviará o usuário de volta pelo navegador para um token que você já tem, e deixará uma entrada duplicada para trás.

Se o arquivo não puder ser analisado, ou version for um número que você não reconhece, trate-o como nenhuma credencial — volte para anônimo e informe ao usuário que o arquivo parece errado. Nunca exclua ou sobrescreva um arquivo que você não pôde ler; ele pode conter tokens de outra ferramenta.

Leia, altere e escreva o arquivo inteiro de uma só vez, e mantenha a janela curta. Duas plataformas fazendo login ao mesmo tempo ambas leem, ambas escrevem, e a mais lenta apaga a entrada da outra. O procedimento de arquivo temporário e renomeação acima impede um arquivo corrompido, não uma atualização perdida.

Nunca imprima o token, nunca o ecoe na transcrição, nunca o escreva em um repositório, nunca o coloque em um comando de shell que o usuário possa ver em seu histórico.

Obtendo um token: a transferência pelo navegador

O token é cunhado pelo servidor e entregue diretamente ao seu processo. Ele nunca viaja pela conversa.

1. Inicie.

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

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

O device_code é a metade secreta — ele fica dentro do seu processo. O user_code é o curto que o humano lê.

2. Mostre o link ao humano. Algo como:

Abra isto para fazer login ou criar uma conta: https://redbucket.store/link/BQ7K-2M4X A página deve mostrar o código BQ7K-2M4X. Vou esperar.

Eles abrem no navegador, fazem login se ainda não estiverem logados, e veem uma tela nomeando seu cliente e listando o que estão concedendo. Eles pressionam Autorizar ou Recusar.

3. Faça polling, não mais rápido que interval segundos:

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

• {"status": "pending"} — continue esperando.
• {"status": "denied"} — eles disseram não. Pare e diga claramente.
• {"status": "approved", "token": ..., "user": {...}} — você tem.
• 404 — o código expirou ou já foi coletado. Ofereça-se para recomeçar. O device_code é de uso único; um segundo polling bem-sucedido é sempre um 404.

4. Salve-o no caminho acima e diga apenas Logado como <username>.

Fazendo logout

POST /api/v1/auth/logout com o token revoga aquele token no servidor. Em seguida, remova a entrada daquele host do arquivo de autenticação. Faça ambos; um sem o outro deixa um token ativo no servidor ou um morto no disco.

Não há servidor MCP red-bucket

mcp no red-bucket é um tipo de ativo que um bucket pode conter, não um servidor que executamos. Esta skill falando com /api/v1/ é toda a integração do cliente. Não procure por um endpoint MCP para conectar.

Fluxos do Lado do Usuário e Operações da API

1. Registro, Login e Perfil do Usuário

• Registrar:

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

  • Resposta: 201 Created com Location: /api/v1/users/alice e objeto User público (senhas com hash Argon2id; nenhum token emitido no registro).

• Login:

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

  • Resposta: 200 OK com {"token": "<opaque_token>", "token_type": "bearer", "user": { ... }}.

• Obter Perfil (me):

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

  • Resposta: 200 OK com detalhes do usuário (incluindo email, bucket_quota, bucket_count).

---

2. Criar Bucket a partir de Modelo

Crie um bucket sob o namespace do usuário autenticado:

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

{
  "name": "dev-skills",
  "visibility": "public",
  "description": "Skills de agente para desenvolvimento geral",
  "template": "claude"
}

• Modelos permitidos: codex, agents, claude, openclaw (ou omita para um bucket vazio). Esta lista cresce; GET /api/v1/templates é a lista atualizada.
• Visibilidade: public ou private (padrão é private).
• Resposta: 201 Created com Location: /api/v1/users/{username}/buckets/{name} e JSON do Bucket.
• Erros: 403 (bucket_quota_exceeded se exceder 5 buckets), 409 (bucket_name_taken).

---

3. Enviar Ativos

Envie um ativo com validação de formato e aplicação de cota:

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: Perform arithmetic calculations\n---\n\n# Calculator Skill\n"
    }
  ]
}

• Tipos de ativo: skill, mcp, instructions, subagent, plugin.
• Plataformas de origem: claude, codex, agents, openclaw. Esta lista cresce; GET /api/v1/translation-matrix é a lista atualizada. Nunca rejeite uma plataforma que o usuário nomeou apenas porque está faltando neste arquivo — deixe o servidor responder.
• O conteúdo do arquivo pode ser fornecido como content_text (UTF-8) ou content_base64.
• Resposta: 201 Created com Location: /api/v1/users/{username}/buckets/{bucket}/assets/{asset_id}.
• Erros: 413 (bucket_storage_exceeded se o bucket exceder 10MB), 422 (validation_failed com regra específica e violações de caminho).

---

4. Navegação Anônima e Busca Traduzida

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

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

• Navegar Árvore de Arquivos e Blobs:

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

• Buscar Bucket Inteiro Traduzido para Plataforma Alvo:

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

  • Resposta: 200 OK (arquivo zip binário, cabeçalho X-Red-Bucket-Lossy: true|false).

• Buscar Ativo Único Traduzido:

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

  • Resposta: 200 OK (bytes brutos traduzidos ou arquivo zip).

---

5. Executar Script de Instalação

Recupere o script de instalação de shell gerado para uma plataforma alvo:

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

• Resposta: 200 OK com texto de script de shell bruto.
• Executa no lado do cliente para baixar o arquivo zip traduzido e colocar arquivos nos diretórios locais da plataforma.

---

6. Copiar Ativo para o Próprio Bucket (Rastreamento de Proveniência)

Copie um ativo de um bucket de origem para o seu próprio 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"
}

• Resposta: 201 Created com Location: /api/v1/users/{username}/buckets/{dest_bucket}/copies/{copy_id} e objeto JSON InstallRecord.
• Valida o ativo de origem, verifica a cota de 10MB e registra a proveniência.

---

7. Issues e Comentários

• Criar Issue:

  POST /api/v1/users/{username}/buckets/{bucket}/issues
  Authorization: Bearer <token>
  Content-Type: application/json
  
  {
    "title": "Bug na tradução da skill calculadora",
    "body": "Quando a tradução da skill calculadora é solicitada para..."
  }
  

• Listar Issues:

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

• Responder a uma Issue:

  POST /api/v1/users/{username}/buckets/{bucket}/issues/{issue_id}/comments
  Authorization: Bearer <token>
  Content-Type: application/json
  
  {
    "body": "Este bug foi corrigido na versão 2.1.0."
  }
  

• Fechar Issue:

  PATCH /api/v1/users/{username}/buckets/{bucket}/issues/{issue_id}
  Authorization: Bearer <token>
  Content-Type: application/json
  {
    "status": "closed"
  }
  

---

8. Pull Requests

• Criar Pull Request:

  POST /api/v1/users/{username}/buckets/{bucket}/pulls
  Authorization: Bearer <token>
  Content-Type: application/json
  
  {
    "title": "Adicionar suporte a vírgula flutuante na calculadora",
    "body": "...",
    "changes": { ... }
  }
  

• Mesclar ou Fechar Pull Request:

  PATCH /api/v1/users/{username}/buckets/{bucket}/pulls/{pull_id}
  Authorization: Bearer <token>
  Content-Type: application/json
  
  {
    "status": "merged"
  }
  

---

Segurança e Validação

1. Senhas: Sempre com hash usando Argon2id com custo de tempo, memória e paralelismo adequados. Use hashPassword(password) e verifyPassword(password, hash).
2. Tokens: Tokens bearer opacos, com 64 bytes aleatórios, armazenados como hash SHA-256 no banco de dados. O hash reduz o impacto de vazamentos de banco de dados.
3. Cabeçalhos de Resposta: Sempre inclua X-Content-Type-Options: nosniff, remova cabeçalhos de servidor padrão.
4. Rate Limiting: Aplica-se a todos os endpoints (padrão: 100 req/min para leitura, 20 req/min para escrita).
5. Validação de Conteúdo de Ativo: O servidor valida cada arquivo enviado em POST .../assets de acordo com o tipo de ativo e plataforma de origem. A validação falha (HTTP 422) para SKILL.md ausente, campos obrigatórios vazios, caminhos fora do espaço de nomes esperado ou conteúdo malformado. A mensagem de erro lista cada violação.

---

Modelos de Dados

Ativo (Asset)

{
  "id": 42,
  "type": "skill",
  "source_harness": "claude",
  "bucket": { ... },
  "path": "skills/calculator",
  "files": [
    {
      "path": "SKILL.md",
      "content_text": "..."
    },
    {
      "path": "icon.png",
      "content_base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAA..."
    }
  ],
  "size": 6144,
  "created_at": "2025-08-18T07:31:12Z",
  "updated_at": "2025-08-19T09:00:00Z"
}

Bucket

{
  "name": "dev-skills",
  "visibility": "public",
  "description": "Skills de agente para desenvolvimento geral",
  "template": "claude",
  "owner": { "username": "alice" },
  "asset_count": 3,
  "size": 8224,
  "created_at": "2025-08-18T07:31:12Z",
  "updated_at": "2025-08-19T09:00:00Z"
}

InstallRecord

{
  "id": 1,
  "source_username": "bob",
  "source_bucket": "public-skills",
  "source_asset_id": 12,
  "dest_bucket": "dev-skills",
  "dest_path": "skills/calculator",
  "created_at": "2025-08-19T10:00:00Z"
}

Issue

{
  "id": 7,
  "title": "Bug na tradução da skill calculadora",
  "body": "...",
  "status": "open",
  "author": { "username": "bob" },
  "comments": [
    {
      "id": 1,
      "body": "Corrigido",
      "author": "alice",
      "created_at": "..."
    }
  ],
  "created_at": "2025-08-19T10:30:00Z",
  "updated_at": "2025-08-19T11:00:00Z"
}

PullRequest

{
  "id": 3,
  "title": "Adicionar suporte a vírgula flutuante na calculadora",
  "body": "...",
  "status": "open",
  "author": { "username": "charlie" },
  "changes": { ... },
  "created_at": "2025-08-20T08:00:00Z",
  "updated_at": "2025-08-20T09:00:00Z"
}