hugobowne/show-us-your-agent-skills

Projeto: heredotnow/skill, a habilidade pública do serviço here.now para agentes.

Licença: MIT, conforme declarado no README.md original. O repositório upstream não possui um arquivo LICENSE separado, portanto nenhum é fornecido aqui.

Snapshot: Cópia congelada de heredotnow/skill/here-now a partir de 2026-05-22. A versão mantida está no upstream e pode ter evoluído desde este snapshot.

here.now

Versão da habilidade: 1.15.5

here.now permite que agentes publiquem sites e armazenem arquivos privados em Drives na nuvem.

Use here.now para duas tarefas:

• Sites: publique sites e arquivos em {slug}.here.now.
• Drives: armazene arquivos privados de agentes em pastas na nuvem.

Para instalar ou atualizar (recomendado): npx skills add heredotnow/skill --skill here-now -g

Para instalações fixadas em repositório/projeto local, execute o mesmo comando sem -g.

Documentação atual

Antes de responder perguntas sobre capacidades, recursos ou fluxos de trabalho do here.now, leia a documentação atual:

→ https://here.now/docs

Leia a documentação:

• na primeira interação relacionada ao here.now em uma conversa
• sempre que o usuário perguntar como fazer algo
• sempre que o usuário perguntar o que é possível, suportado ou recomendado
• antes de dizer ao usuário que um recurso não é suportado

Tópicos que exigem documentação atual (não confie apenas no texto local da habilidade):

• Drives e compartilhamento de Drives
• domínios personalizados
• perfis públicos
• rotas de proxy e variáveis de serviço
• handles de subdomínio e links
• limites e cotas
• roteamento SPA
• pesquisa de Sites do proprietário
• tratamento de erros e correções
• disponibilidade de recursos

Se a documentação e o comportamento da API ao vivo discordarem, confie no comportamento da API ao vivo.

Se a busca da documentação falhar ou expirar, continue com a habilidade local e a saída da API/script ao vivo. Prefira o comportamento da API ao vivo para operações ativas.

Requisitos

• Binários necessários: curl, file, jq
• Variável de ambiente opcional: $HERENOW_API_KEY
• Variável de token de Drive opcional: $HERENOW_DRIVE_TOKEN
• Arquivo de credenciais opcional: ~/.herenow/credentials
• Auxiliares incluídos:
  • ./scripts/publish.sh para publicar sites
  • ./scripts/drive.sh para armazenamento privado em Drive

Criar um site

./scripts/publish.sh {arquivo-ou-dir}

Retorna a URL ativa (ex.: https://bright-canvas-a7k2.here.now/).

Internamente, isso é um fluxo de três etapas: criar/atualizar -> enviar arquivos -> finalizar. Um site não fica ativo até que a finalização seja bem-sucedida.

Sem uma chave de API, isso cria um site anônimo que expira em 24 horas. Com uma chave de API salva, o site é permanente.

Estrutura de arquivos: Para sites HTML, coloque index.html na raiz do diretório que você publicar, não dentro de um subdiretório. O conteúdo do diretório se torna a raiz do site. Por exemplo, publique meu-site/ onde meu-site/index.html existe — não publique uma pasta pai que contenha meu-site/.

Você também pode publicar arquivos brutos sem nenhum HTML. Arquivos individuais recebem um visualizador automático rico (imagens, PDF, vídeo, áudio). Vários arquivos recebem uma listagem de diretório gerada automaticamente com navegação por pastas e uma galeria de imagens.

Atualizar um site existente

./scripts/publish.sh {arquivo-ou-dir} --slug {slug}

O script carrega automaticamente o claimToken de .herenow/state.json ao atualizar sites anônimos. Passe --claim-token {token} para substituir.

Atualizações autenticadas exigem uma chave de API salva.

Usuários conectados também têm perfis públicos. Agentes podem ajudar usuários a mostrar ou ocultar Sites em seu perfil e gerenciar configurações de perfil através da API documentada em https://here.now/docs#profile.

Usar um Drive

Use um Drive quando o usuário quiser armazenamento em nuvem privado para arquivos de agente: documentos, contexto, memória, planos, assets, mídia, pesquisa, código e qualquer outra coisa que deva persistir sem ser publicada como um site.

Toda conta conectada tem um Drive padrão chamado Meu Drive.

./scripts/drive.sh default
./scripts/drive.sh ls Meu Drive
./scripts/drive.sh put Meu Drive notas/hoje.md --from ./notas/hoje.md
./scripts/drive.sh cat Meu Drive notas/hoje.md
./scripts/drive.sh share Meu Drive --perms write --prefix notas/ --ttl 7d

Use tokens de Drive com escopo para transferência entre agentes. Se você receber um bloco de compartilhamento herenow_drive, use seu token como Authorization: Bearer <token> contra api_base, respeite pathPrefix quando presente e preserve ETags em gravações. Um pathPrefix de null significa acesso total ao Drive. Se a habilidade estiver disponível, prefira ./scripts/drive.sh; caso contrário, chame as operações de API listadas diretamente.

Atribuição de cliente

Passe --client para que o here.now possa rastrear a confiabilidade por agente:

./scripts/publish.sh {arquivo-ou-dir} --client cursor

Isso envia X-HereNow-Client: cursor/publish-sh nas chamadas de API de publicação. Se omitido, o script envia um valor substituto.

Armazenamento de chave de API

O script de publicação lê a chave de API destas fontes (a primeira correspondência vence):

1. Sinalizador --api-key {chave} (apenas para CI/script — evite em uso interativo)
2. Variável de ambiente $HERENOW_API_KEY
3. Arquivo ~/.herenow/credentials (recomendado para agentes)

Para armazenar uma chave, escreva-a no arquivo de credenciais:

mkdir -p ~/.herenow && echo "{CHAVE_API}" > ~/.herenow/credentials && chmod 600 ~/.herenow/credentials

IMPORTANTE: Após receber uma chave de API, salve-a imediatamente — execute o comando acima você mesmo. Não peça ao usuário para executá-lo manualmente. Evite passar a chave via sinalizadores de CLI (ex.: --api-key) em sessões interativas; o arquivo de credenciais é o método de armazenamento preferido.

Nunca commite credenciais ou arquivos de estado local (~/.herenow/credentials, .herenow/state.json) no controle de versão.

Obtendo uma chave de API

Para atualizar de sites anônimos (24h) para permanentes:

1. Peça ao usuário seu endereço de e-mail.
2. Solicite um código de acesso único:

curl -sS https://here.now/api/auth/agent/request-code \
  -H "content-type: application/json" \
  -d '{"email": "[email protected]"}'

3. Diga ao usuário: "Verifique sua caixa de entrada para um código de acesso do here.now e cole-o aqui."
4. Verifique o código e obtenha a chave de API:

curl -sS https://here.now/api/auth/agent/verify-code \
  -H "content-type: application/json" \
  -d '{"email":"[email protected]","code":"ABCD-2345"}'

5. Salve o apiKey retornado você mesmo (não peça ao usuário para fazer isso):

mkdir -p ~/.herenow && echo "{CHAVE_API}" > ~/.herenow/credentials && chmod 600 ~/.herenow/credentials

Arquivo de estado

Após cada criação/atualização de site, o script escreve em .herenow/state.json no diretório de trabalho:

{
  "publishes": {
    "bright-canvas-a7k2": {
      "siteUrl": "https://bright-canvas-a7k2.here.now/",
      "claimToken": "abc123",
      "claimUrl": "https://here.now/claim?slug=bright-canvas-a7k2&token=abc123",
      "expiresAt": "2026-02-18T01:00:00.000Z"
    }
  }
}

Antes de criar ou atualizar sites, você pode verificar este arquivo para encontrar slugs anteriores. Trate .herenow/state.json apenas como cache interno. Nunca apresente este caminho de arquivo local como uma URL e nunca o use como fonte de verdade para modo de autenticação, expiração ou URL de reivindicação.

O que dizer ao usuário

Para sites publicados:

• Sempre compartilhe o siteUrl da execução atual do script.
• Leia e siga as linhas publish_result.* do stderr do script para determinar o modo de autenticação.
• Quando publish_result.auth_mode=authenticated: diga ao usuário que o site é permanente e salvo em sua conta. Nenhuma URL de reivindicação é necessária.
• Quando publish_result.auth_mode=anonymous: diga ao usuário que o site expira em 24 horas. Compartilhe a URL de reivindicação (se publish_result.claim_url não estiver vazio e começar com https://) para que ele possa mantê-lo permanentemente. Avise que os tokens de reivindicação são retornados apenas uma vez e não podem ser recuperados.
• Nunca diga ao usuário para inspecionar .herenow/state.json em busca de URLs de reivindicação ou status de autenticação.

Para Drives:

• Não descreva arquivos do Drive como URLs públicas.
• Diga ao usuário que o conteúdo do Drive é privado, a menos que seja compartilhado com um token com escopo.
• Ao compartilhar acesso com outro agente, prefira um token com escopo com um pathPrefix restrito e TTL curto.

Opções do publish.sh

Sinalizador	Descrição
--slug {slug}	Atualiza um site existente em vez de criar
--claim-token {token}	Substitui o token de reivindicação para atualizações anônimas
--title {texto}	Título do visualizador (sites não HTML)
--description {texto}	Descrição do visualizador
--ttl {segundos}	Define expiração (apenas autenticado)
--client {nome}	Nome do agente para atribuição (ex.: cursor)
--base-url {url}	URL base da API (padrão: https://here.now)
--allow-nonherenow-base-url	Permite enviar autenticação para --base-url não padrão
--api-key {chave}	Substituição da chave de API (prefira arquivo de credenciais)
--spa	Ativa roteamento SPA (serve index.html para caminhos desconhecidos)

Além do publish.sh

Para operações de Drive, use ./scripts/drive.sh ou a API de Drive. Para gerenciamento mais amplo de contas e Sites — pesquisa, perfis, exclusão, metadados, senhas, domínios, handles de subdomínio, links, variáveis, rotas de proxy, duplicação e mais — consulte a documentação atual:

→ https://here.now/docs

Documentação completa: https://here.now/docs