Communitygithub.com

Birdfolio

Identificação de aves, rastreamento de lista de vida e geração de cartas colecionáveis.

O que é Birdfolio?

Birdfolio é uma skill que transforma fotos de aves enviadas pelo usuário em uma lista de vida pessoal, combinando identificação por visão computacional, dados de raridade da API You.com e geração de cartas colecionáveis em estilo Pokémon. Quando o usuário envia uma foto, a skill identifica a espécie, busca dados de raridade e curiosidades, registra a observação em uma lista de vida e gera uma carta visual com a foto original — tudo isso com suporte para plataformas como Telegram e OpenClaw. A skill também gerencia a configuração inicial com região e checklist personalizado, permite consultar progresso, visualizar a lista de vida e buscar informações sobre espécies específicas sem registrar observação. O armazenamento de dados é feito via API PostgreSQL (Railway) e arquivos locais na pasta birdfolio/, enquanto os scripts Python e Node.js executam tarefas como inicialização, registro, geração de cartas e upload para Cloudflare R2.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/modbender/skill-library-mcp/tree/HEAD/data/birdfolio

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que Birdfolio faz?

Birdfolio transforma fotos de aves em uma lista de vida pessoal. Os usuários fotografam aves na natureza, enviam a foto para você, e você identifica a espécie com Visão. O You.com fornece dados de raridade e região em tempo real. Cada avistamento é registrado em uma lista de vida com uma classificação de raridade inspirada em Pokémon (Comum / Raro / Super Raro) e ganha uma carta colecionável visual enviada de volta via Telegram.

Dados armazenados em: Railway PostgreSQL (via API) + pasta local birdfolio/ (cartas, aves, configuração) Scripts armazenados em: {baseDir}/scripts/ API: https://api-production-d0e2.up.railway.app (também salva em birdfolio/config.json após a inicialização) Referência de esquema: {baseDir}/references/data-schema.md Consultas de pesquisa: {baseDir}/references/you-search-queries.md

Nota sobre --workspace e --api-url: Cada script de dados aceita --workspace (caminho absoluto para birdfolio/) e --api-url (URL base da API). Após a execução de init_birdfolio.py, a URL da API e o ID do Telegram são salvos em birdfolio/config.json e lidos automaticamente — scripts subsequentes precisam apenas de --workspace.

ID do Telegram: Lido dos metadados da mensagem recebida (sender_id). Passe como --telegram-id para init_birdfolio.py na configuração inicial.


1. Fluxo de Configuração

Gatilho: O usuário diz "Configurar meu Birdfolio", "definir minha região" ou envia uma foto antes da configuração existir.

Verificar primeiro: Se birdfolio/config.json existir no seu workspace, a configuração já está concluída — pule para o fluxo relevante.

Passos:

  1. Pergunte: "Qual é a sua região de origem? (ex.: São Paulo, Brasil, Portugal)"

  2. Execute para criar a estrutura de pastas do workspace e registrar o usuário na API:

    exec: python {baseDir}/scripts/init_birdfolio.py \
      --telegram-id {senderTelegramId} \
      --region "{region}" \
      --api-url "https://api-production-d0e2.up.railway.app" \
      --workspace <caminho absoluto para birdfolio/ no seu workspace>
    
  3. Pesquise no You.com (execute todos os três):

    "{region} aves mais comuns em quintais lista de espécies WikiAves"
    "{region} aves incomuns sazonais raras checklist WikiAves"
    "{region} aves raras vagantes ameaçadas de extinção WikiAves"
    
  4. A partir dos resultados, monte um checklist com 10 comuns, 5 raras, 1 super rara espécies. Use sinais de classificação de {baseDir}/references/you-search-queries.md.

  5. Escreva o checklist preenchido em birdfolio/checklist.json no seu workspace:

    {
      "{region}": {
        "common": [
          { "species": "Sabiá-laranjeira", "slug": "sabia-laranjeira", "found": false, "dateFound": null }
        ],
        "rare": [...],
        "superRare": [...]
      }
    }
    
  6. Responda com uma mensagem de boas-vindas e pré-visualização do checklist:

    🦅 Birdfolio configurado para {region}!
    
    Seu checklist:
    Comuns (10):  Sabiá-laranjeira, Pardal, ...
    Raras (5):    Garça-azul, ...
    Super Rara:   Ararinha-azul
    
    Envie uma foto de ave para começar a colecionar!
    

2. Fluxo de Identificação de Aves

Gatilho: O usuário envia uma foto.

Obtendo o caminho do arquivo da foto: Quando um usuário envia uma foto via Telegram, o OpenClaw a baixa e disponibiliza o caminho do arquivo local nos metadados do anexo da mensagem. Capture este caminho — você precisará dele para a geração da carta na Etapa 5. Se o OpenClaw fornecer a imagem inline sem um caminho, use exec para encontrar o arquivo baixado mais recentemente na pasta temp/media do OpenClaw, ou verifique %APPDATA%\openclaw\media\ no Windows. Salve a foto em birdfolio/birds/{slug}-{timestamp}.jpg para armazenamento permanente:

exec: copy "<caminho do anexo>" "birdfolio/birds/<slug>-<timestamp>.jpg"

Etapa 1 — Identificar com Visão

A foto enviada está diretamente visível no seu contexto. Analise-a (ou use a ferramenta image se não estiver inline):

Identifique a espécie de ave nesta foto. Retorne apenas JSON:
{
  "commonName": "...",
  "scientificName": "...",
  "confidence": "alta|média|baixa",
  "features": ["característica visível 1", "característica visível 2"]
}

Regras de raridade:

  • A ave ESTÁ no checklist → use seu nível: common, rare ou superRare
  • A ave NÃO ESTÁ no checklist → use bonus (mostra um selo neutro "Achado Bônus", sem raridade atribuída)

Regras de confiança:

  • "alta" → prossiga automaticamente, nenhuma confirmação necessária
  • "média" → pergunte: "Acho que pode ser um(a) [espécie] — com base em [características]. Isso parece correto para você?" → aguarde confirmação antes de continuar
  • "baixa" → responda: "Esta foto não está clara o suficiente para eu ter confiança. Você poderia enviar uma foto mais nítida?" → pare, não registre nada

Etapa 2 — Consulta de raridade

Pesquise no You.com:

"{commonName} {homeRegion} frequência WikiAves quão comum raro"

Classifique usando estes sinais:

NívelValor do scriptSinais
Comum 🟢common"abundante", "generalizada", "residente anual", >50% dos checklists
Raro 🟡rare"incomum", "sazonal", "migratório", "ocasional", 5–50% dos checklists
Super Raro 🔴superRare"raro", "vagante", "acidental", "ameaçado", <5% dos checklists

Quando estiver em dúvida → use como padrão rare. Sempre use o valor do script (ex.: superRare, não Super Rare) ao passar --rarity para qualquer script.

Etapa 3 — Obter um fato curioso

Pesquise no You.com:

"{commonName} ave fatos interessantes habitat comportamento"

Extraia um fato impactante (1–2 frases).

Etapa 4 — Registrar o avistamento

Salve o avistamento em birdfolio/lifeList.json no seu workspace:

exec: python {baseDir}/scripts/log_sighting.py \
  --species "{commonName}" \
  --scientific-name "{scientificName}" \
  --rarity "{rarity}" \
  --region "{homeRegion}" \
  --notes "" \
  --workspace <caminho absoluto para birdfolio/ no seu workspace>

Capture da saída: isLifer, totalSightings, totalSpecies.

Etapa 5 — Atualizar checklist

Marque a espécie como encontrada em birdfolio/checklist.json:

exec: python {baseDir}/scripts/update_checklist.py \
  --species "{commonName}" \
  --region "{homeRegion}" \
  --workspace <caminho absoluto para birdfolio/ no seu workspace>

Etapa 6 — Gerar carta colecionável

A carta tem um design de duas colunas: a foto do usuário preenche o painel esquerdo (280px), um painel de informações escuro sólido fica à direita. Sempre use a foto real enviada pelo usuário — não uma imagem de banco de imagens.

Etapa 6a — Detectar posição da ave com Visão: Use a ferramenta image na foto enviada:

"Onde a ave está posicionada horizontalmente nesta foto? Dê-me aproximadamente a porcentagem a partir da borda esquerda em que o centro da ave está (0–100)."

Converta a resposta em um valor CSS: "40% center", "60% center", "center center", etc. Use isso como --object-position.

Etapa 6b — Gerar o HTML da carta com a foto incorporada:

exec: python {baseDir}/scripts/generate_card.py \
  --species "{commonName}" \
  --scientific-name "{scientificName}" \
  --rarity "{rarity}" \
  --region "{homeRegion}" \
  --date "{YYYY-MM-DD}" \
  --fun-fact "{funFact}" \
  --image-path "<caminho absoluto para a foto enviada>" \
  --object-position "{objectPosition}" \
  --life-count {totalSpecies} \
  --workspace <caminho absoluto para birdfolio/ no seu workspace>

--image-path incorpora a foto real do usuário como base64 diretamente no HTML. Nenhuma etapa de incorporação separada é necessária.

Fallback se o caminho da foto não estiver disponível: omita --image-path e passe --image-url "<URL da foto de banco de imagens>" (encontre uma URL via You.com: "{commonName} ave foto vida selvagem").

Capture cardPath da saída.

Etapa 6c — Capturar tela, salvar, fazer upload e enviar: Execute o script de captura de tela para renderizar a carta em 600×400 e salvar um PNG:

exec: node {baseDir}/scripts/screenshot_card.js "<cardPath>"

Capture pngPath da saída.

Faça upload para Cloudflare R2 e obtenha uma URL pública:

exec: python {baseDir}/scripts/upload_card.py "<pngPath>"

Capture url da saída.

Atualize a URL da carta do avistamento na API (use o id da saída do log_sighting):

PATCH /users/{telegram_id}/sightings/{sighting_id}/card
Body: {"card_png_url": "<url>"}

Envie o PNG via Telegram:

message(action="send", media="<pngPath>")

Etapa 7 — Responder

  • Se isLifer for verdadeiro: "🎉 Novo lifer! Esse é o seu primeiro [commonName]! Pássaro #[totalSpecies] no seu Birdfolio."

    Se totalSpecies == 1 (este é o primeiro pássaro deles de todos): também envie o link PWA pessoal: "🦅 Seu Birdfolio está no ar! Marque este link para ver sua lista de vida: https://birdfolio.tonbistudio.com/app/[telegram_id]"

    O telegram_id é o ID do Telegram do remetente dos metadados da mensagem recebida (sender_id). Também está armazenado em birdfolio/config.json após a inicialização.

  • Caso contrário: "[commonName] avistado(a)! Você já viu [N] espécies no seu Birdfolio."

Inclua: emoji do selo de raridade, o fato curioso, status do checklist (se a espécie estava no checklist, mencione).

Fallback se a captura de tela falhar: Envie uma carta de texto formatada:

🦅 [RARITY_EMOJI] [Nome Comum]
Científico: [Nome Científico]
Região: [Região] | Avistado: [Data]
Raridade: [Raridade]
💡 [Fato Curioso]
Pássaro #[N] no seu Birdfolio

3. Checklist e Estatísticas

Gatilho: "Como está meu checklist?", "Progresso do Birdfolio", "Quantas aves eu encontrei?"

exec: python {baseDir}/scripts/get_stats.py \
  --workspace <caminho absoluto para birdfolio/ no seu workspace>

Formate a resposta usando checklistProgress da saída:

📋 {region} Checklist

Comuns     ✅✅✅⬜⬜⬜⬜⬜⬜⬜  3/10
Raras       ✅⬜⬜⬜⬜              1/5
Super Raras ⬜                      0/1

🐦 {totalSpecies} espécies | {totalSightings} avistamentos totais
📍 Último avistamento: {mostRecentSighting.commonName} em {date}
🏆 Achado mais raro: {rarestBird.commonName} ({rarity})

Use ✅ para encontrado, ⬜ para não encontrado. Uma caixa por espécie.

Cartão de checklist visual opcional: Gere um cartão de checklist HTML visual e capture a tela:

exec: python {baseDir}/scripts/generate_checklist_card.py \
  --workspace <caminho absoluto para birdfolio/ no seu workspace>

Depois capture a tela com screenshot_card.js e envie o PNG.


4. Visualização da Lista de Vida

Gatilho: "Mostrar meu Birdfolio", "Mostrar minha lista de vida"

Leia birdfolio/lifeList.json do seu workspace.

Agrupe os lifers por raridade (Super Raro primeiro, depois Raro, depois Comum). Formate como uma lista de texto ou gere uma galeria HTML, salve em birdfolio/my-birdfolio.html no seu workspace e capture a tela.


5. Consulta de Espécie (sem registro)

Gatilho: "Fale sobre [espécie]"

Pesquise no You.com:

"{species} ave fatos habitat alcance comportamento dieta"
"{species} ave {homeRegion} frequência WikiAves residente ou migratório"

Retorne um resumo conversacional. Não registre um avistamento nem gere uma carta.


6. Ave Mais Rara

Gatilho: "Qual é a minha ave mais rara?", "Mostrar meu melhor achado"

exec: python {baseDir}/scripts/get_stats.py \
  --workspace <caminho absoluto para birdfolio/ no seu workspace>

Leia rarestBird da saída e responda com o nome da espécie, raridade, data do avistamento e região.


Referência Rápida

ScriptPrincipais argumentosRetorna
init_birdfolio.py--telegram-id, --region, --api-url, --workspace{status, workspace, files_created, next}
log_sighting.py--species, --scientific-name, --rarity, --region, --date, --workspace{status, sighting, isLifer, totalSightings, totalSpecies}
update_checklist.py--species, --region, --workspace{status, tier, dateFound} ou {status: not_on_checklist}
get_stats.py--workspace{totalSightings, totalSpecies, checklistProgress, mostRecentSighting, rarestBird}
generate_card.py--species, --scientific-name, --rarity, --region, --date, --fun-fact, --image-path (preferido) OU --image-url, --object-position, --life-count, --workspace{status, cardPath, filename}
generate_checklist_card.py--workspace{status, cardPath} — cartão de checklist HTML visual
screenshot_card.js<cardPath> [outputPath]{status, pngPath} — salva PNG em birdfolio/cards/
upload_card.py<pngPath> [--secrets path]{status, url} — envia para R2, retorna URL pública

Todos os scripts Python produzem JSON no stdout. Sempre passe o caminho absoluto --workspace. screenshot_card.js usa o playwright-core incluído do OpenClaw + Chrome/Edge do sistema (nenhuma instalação separada necessária).

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

modbender/skill-library-mcp

Paid acquisition strategy, budget allocation, and avoiding common advertising mistakes across platforms

modbender/skill-library-mcp

Complete investment portfolio risk management system. Analyze positions, calculate risk metrics, stress test scenarios, optimize allocations, and generate institutional-grade risk reports — all wit...

modbender/skill-library-mcp

Borrow from Aave via credit delegation. Agent self-funds by borrowing against delegator collateral. Supports borrow, repay, health checks. Works on Aave V2/V3.

modbender/skill-library-mcp

Discover and register autonomous AI agents. Use when: browsing the agent registry, submitting an agent for verification, or embedding agent badges. NOT for: general web search or agent capability analysis.

modbender/skill-library-mcp

Create AI avatar and talking head videos with OmniHuman, Fabric, PixVerse via inference.sh CLI. Models: OmniHuman 1.5, OmniHuman 1.0, Fabric 1.0, PixVerse Lipsync. Capabilities: audio-driven avatars, lipsync videos, talking head generation, virtual presenters. Use for: AI presenters, explainer videos, virtual influencers, dubbing, marketing videos. Triggers: ai avatar, talking head, lipsync, avatar video, virtual presenter, ai spokesperson, audio driven video, heygen alternative, synthesia alternative, talking avatar, lip sync, video avatar, ai presenter, digital human

modbender/skill-library-mcp

AI代码编辑器规则模板集合 - 为Cursor、Windsurf、Claude Code、Cline等AI编辑器提供项目规则配置。适用于需要配置AI编码助手规则的开发者,包含全栈Web、移动端、Vue3+SpringBoot等技术栈模板。

modbender/skill-library-mcp

Generate landing page code from product descriptions

modbender/skill-library-mcp

Create AI marketing videos for ads, promos, product launches, and brand content. Models: Veo, Seedance, Wan, FLUX for visuals, Kokoro for voiceover. Types: product demos, testimonials, explainers, social ads, brand videos. Use for: Facebook ads, YouTube ads, product launches, brand awareness. Triggers: marketing video, ad video, promo video, commercial, brand video, product video, explainer video, ad creative, video ad, facebook ad video, youtube ad, instagram ad, tiktok ad, promotional video, launch video

modbender/skill-library-mcp

Generate AI music videos end-to-end. Creates music with Suno (sunoapi.org), generates visuals with OpenAI/Seedream/Google/Seedance, and assembles into music video with ffmpeg. Supports timestamped lyrics (auto SRT), Suno native music video generation, slideshow/video/hybrid modes. Token-based cost tracking per generation.

modbender/skill-library-mcp

Generate AI-powered notes from videos (document, outline, or graphic-text formats)

modbender/skill-library-mcp

The video AI notes tool is provided by Baidu. Based on the video download address provided by the user, it downloads and parses the video, and finally generates AI notes corresponding to the video (a total of three types of notes can be generated: document notes, outline notes, and image-text notes).

modbender/skill-library-mcp

Automated appointment management for beauty salons, clinics, studios, and photo booths. Handles booking requests, calendar sync, conflict detection, reminders, no-show tracking, and waitlist management.

modbender/skill-library-mcp

Multi-project task and research management (JSON-first CLI)

modbender/skill-library-mcp

Track stock and crypto portfolios with CLI - real-time prices, P&L, dividend tracking, multiple portfolios

modbender/skill-library-mcp

Track cryptocurrency portfolios with real-time prices, P&L calculations, and allocation analysis. Query Bitcoin, Ethereum, Solana and 10,000+ token holdings.

modbender/skill-library-mcp

加密貨幣Portfolio追蹤 - 支援TRON/ETH/BSC,分析持倉、收益、Gas費用

modbender/skill-library-mcp

Lead strategy with competitive analysis, strategic planning, growth roadmaps, and business portfolio management.

modbender/skill-library-mcp

Create ATS-optimized resumes and CVs with proper structure, metrics, and industry targeting.

modbender/skill-library-mcp

Use this skill when the user asks to build, create, design, develop, or improve ANY frontend interface, web page, UI component, or visual element. This includes: - Building landing pages, websites, web apps, dashboards, portfolios, or any web interface - Creating UI components (buttons, forms, cards, navbars, modals, etc.) - Designing pages with React, Vue, Next.js, Svelte, or any frontend framework - Adding styling or improving visual design of existing components - Implementing specific design aesthetics (modern, dark, minimalist, brutalist, etc.) - User mentions "frontend", "UI", "UX", "design", "interface", "web design", or "styling" - User asks for "beautiful", "modern", "professional", "clean", or any aesthetic adjective - User requests help with CSS, Tailwind, styled-components, or any styling approach This skill automatically retrieves the appropriate design system prompt (Neo-brutalism, Modern Dark, Bauhaus, Cyberpunk, Material, etc.) to help create visually distinctive, production-grade frontend...

modbender/skill-library-mcp

Native video analysis using Google Gemini API. Upload and analyze video files — describe scenes, extract text/UI, answer questions about content, transcribe speech, identify objects and actions. Use when: (1) User sends a video file and wants it analyzed, (2) Video summarization or description needed, (3) Extracting text, UI elements, or information from screen recordings, (4) Answering questions about video content, (5) Comparing multiple videos, (6) Analyzing tutorials, demos, or walkthroughs.

Habilidades Relacionadas