Communitygithub.com

Birdfolio - 조류 식별 및 생애 목록 관리

새 사진을 식별하고, 생애 목록을 추적하며, 트레이딩 카드를 생성합니다.

Birdfolio - 조류 식별 및 생애 목록 관리란 무엇인가요?

Birdfolio는 사용자가 야생에서 찍은 새 사진을 분석하여 종을 식별하고, 개인 생애 목록(life list)을 구축하며, 포켓몬스터에서 영감을 받은 희귀도 등급(Common / Rare / Super Rare)을 부여하여 시각적인 트레이딩 카드를 생성하는 AI 에이전트 스킬입니다. You.com 검색을 통해 실시간 희귀도 및 지역 데이터를 제공하며, Railway PostgreSQL API와 로컬 `birdfolio/` 폴더에 데이터를 저장합니다. Claude Code, Cursor, Codex 등의 환경에서 동작하며, 사용자가 새 사진을 보내거나 'Birdfolio 설정', '내 지역 설정', '체크리스트 보기' 등과 같은 명령을 내릴 때 활성화됩니다. 초기 설정부터 지속적인 생애 목록 추적 및 트레이딩 카드 생성까지 모든 과정을 처리합니다.

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

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Birdfolio

Birdfolio는 새 사진을 개인 생애 목록으로 바꿔줍니다. 사용자가 야생에서 새를 촬영하여 사진을 보내면, AI가 Vision으로 종을 식별합니다. You.com은 실시간 희귀도 및 지역 데이터를 제공합니다. 각 관찰 기록은 포켓몬스터에서 영감을 받은 희귀도 등급(Common / Rare / Super Rare)과 함께 생애 목록에 기록되며, Telegram을 통해 시각적인 트레이딩 카드가 전송됩니다.

데이터 저장 위치: Railway PostgreSQL (API 사용) + 로컬 birdfolio/ 폴더 (카드, 새 정보, 설정) 스크립트 위치: {baseDir}/scripts/ API: https://api-production-d0e2.up.railway.app (초기화 후 birdfolio/config.json에도 저장됨) 스키마 참조: {baseDir}/references/data-schema.md 검색 쿼리: {baseDir}/references/you-search-queries.md

--workspace 및 --api-url 참고: 모든 데이터 스크립트는 --workspace (birdfolio/의 절대 경로)와 --api-url (API 기본 URL)을 인자로 받습니다. init_birdfolio.py가 실행된 후, API URL과 Telegram ID는 birdfolio/config.json에 저장되어 자동으로 읽힙니다. 이후 스크립트는 --workspace만 필요합니다.

Telegram ID: 수신 메시지 메타데이터(sender_id)에서 읽어옵니다. 첫 번째 설정 시 init_birdfolio.py에 --telegram-id로 전달합니다.


1. 설정 흐름

트리거: 사용자가 "Birdfolio 설정", "내 지역 설정"을 말하거나, 설정이 완료되지 않은 상태에서 사진을 보냅니다.

먼저 확인: 워크스페이스에 birdfolio/config.json이 존재하면 설정이 이미 완료된 것입니다. 관련 흐름으로 건너뜁니다.

단계:

  1. 질문: "당신의 홈 지역은 무엇인가요? (예: 캘리포니아, 텍사스, 영국)"

  2. 워크스페이스 폴더 구조를 생성하고 API에 사용자를 등록하려면 다음을 실행합니다:

    exec: python {baseDir}/scripts/init_birdfolio.py \
      --telegram-id {senderTelegramId} \
      --region "{region}" \
      --api-url "https://api-production-d0e2.up.railway.app" \
      --workspace <워크스페이스 내 birdfolio/의 절대 경로>
    
  3. You.com 검색 (세 가지 모두 실행):

    "{region} 가장 흔한 정원 새 eBird 종 목록"
    "{region} 흔하지 않은 계절별 희귀 새 eBird 체크리스트"
    "{region} 희귀 방랑성 멸종 위기 새 eBird"
    
  4. 검색 결과에서 일반 10종, 희귀 5종, 초희귀 1종으로 체크리스트를 작성합니다. {baseDir}/references/you-search-queries.md의 분류 신호를 사용합니다.

  5. 작성된 체크리스트를 워크스페이스의 birdfolio/checklist.json에 저장합니다:

    {
      "{region}": {
        "common": [
          { "species": "American Robin", "slug": "american-robin", "found": false, "dateFound": null }
        ],
        "rare": [...],
        "superRare": [...]
      }
    }
    
  6. 환영 메시지와 체크리스트 미리보기로 응답합니다:

    🦅 {region}에 대한 Birdfolio가 설정되었습니다!
    
    체크리스트:
    일반 (10종): American Robin, House Sparrow, ...
    희귀 (5종):   Great Blue Heron, ...
    초희귀 (1종):   California Condor
    
    새 사진을 보내주시면 수집을 시작합니다!
    

2. 새 식별 흐름

트리거: 사용자가 사진을 보냅니다.

사진 파일 경로 얻기: 사용자가 Telegram을 통해 사진을 보내면, OpenClaw가 다운로드하여 메시지 첨부 파일 메타데이터에 로컬 파일 경로를 제공합니다. 이 경로를 캡처하여 5단계에서 카드 생성에 사용합니다. OpenClaw가 이미지를 인라인으로 제공하고 경로가 없는 경우, exec를 사용하여 OpenClaw의 임시/미디어 폴더에서 가장 최근에 다운로드된 파일을 찾거나 Windows의 경우 %APPDATA%\openclaw\media\를 확인하세요. 사진을 birdfolio/birds/{slug}-{timestamp}.jpg에 영구 저장합니다:

exec: copy "<attachment path>" "birdfolio/birds/<slug>-<timestamp>.jpg"

1단계 — Vision으로 식별

제출된 사진이 컨텍스트에 직접 표시됩니다. 분석하거나(인라인이 아닌 경우 image 도구 사용) 다음을 수행합니다:

이 사진의 새 종을 식별하세요. JSON만 반환:
{
  "commonName": "...",
  "scientificName": "...",
  "confidence": "high|medium|low",
  "features": ["보이는 특징 1", "보이는 특징 2"]
}

희귀도 규칙:

  • 새가 체크리스트에 있음 → 해당 등급 사용: common, rare, 또는 superRare
  • 새가 체크리스트에 없음 → bonus 사용 (중립적인 "Bonus Find" 배지 표시, 희귀도 미할당)

신뢰도 규칙:

  • "high" → 자동 진행, 확인 불필요
  • "medium" → 질문: "이것은 [특징]을 기반으로 [종]일 수 있다고 생각합니다. 그렇게 보이나요?" → 계속하기 전에 확인 대기
  • "low" → 응답: "이 사진은 제가 확신할 수 있을 만큼 선명하지 않습니다. 더 선명한 사진을 보내주시겠어요?" → 중지, 아무것도 기록하지 않음

2단계 — 희귀도 조회

You.com 검색:

"{commonName} {homeRegion} eBird 빈도 얼마나 흔한 희귀한"

다음 신호를 사용하여 분류:

등급스크립트 값신호
일반 🟢common"풍부함", "광범위함", "연중 서식", 체크리스트의 >50%
희귀 🟡rare"흔하지 않음", "계절별", "철새", "가끔", 체크리스트의 5–50%
초희귀 🔴superRare"희귀함", "방랑성", "우연한", "멸종 위기", 체크리스트의 <5%

확실하지 않을 때 → 기본값 rare 사용. 모든 스크립트에 --rarity를 전달할 때 항상 스크립트 값(예: superRare, Super Rare 아님)을 사용합니다.

3단계 — 재미있는 사실 얻기

You.com 검색:

"{commonName} 새 흥미로운 사실 서식지 행동"

간결한 사실 하나를 추출합니다 (1-2 문장).

4단계 — 관찰 기록

워크스페이스의 birdfolio/lifeList.json에 관찰을 저장합니다:

exec: python {baseDir}/scripts/log_sighting.py \
  --species "{commonName}" \
  --scientific-name "{scientificName}" \
  --rarity "{rarity}" \
  --region "{homeRegion}" \
  --notes "" \
  --workspace <워크스페이스 내 birdfolio/의 절대 경로>

출력에서 캡처: isLifer, totalSightings, totalSpecies.

5단계 — 체크리스트 업데이트

birdfolio/checklist.json에서 해당 종을 발견됨으로 표시:

exec: python {baseDir}/scripts/update_checklist.py \
  --species "{commonName}" \
  --region "{homeRegion}" \
  --workspace <워크스페이스 내 birdfolio/의 절대 경로>

6단계 — 트레이딩 카드 생성

카드는 2열 디자인입니다. 사용자의 사진이 왼쪽 패널(280px)을 채우고, 오른쪽에는 단색의 어두운 정보 패널이 있습니다. 항상 사용자가 제출한 실제 사진을 사용합니다 — 스톡 이미지가 아닙니다.

6a 단계 — Vision으로 새 위치 감지: 제출된 사진에 image 도구 사용:

"이 사진에서 새가 수평으로 어디에 위치해 있나요? 왼쪽 가장자리에서 새의 중심이 대략 몇 퍼센트(%) 떨어져 있는지 알려주세요(0–100)."

답변을 CSS 값으로 변환: "40% center", "60% center", "center center" 등. 이것을 --object-position으로 사용합니다.

6b 단계 — 사진이 포함된 카드 HTML 생성:

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 "<제출된 사진의 절대 경로>" \
  --object-position "{objectPosition}" \
  --life-count {totalSpecies} \
  --workspace <워크스페이스 내 birdfolio/의 절대 경로>

--image-path는 사용자의 실제 사진을 base64로 직접 HTML에 포함시킵니다. 별도의 포함 단계가 필요하지 않습니다.

사진 경로를 사용할 수 없는 경우의 대체: --image-path를 생략하고 대신 --image-url "<스톡 사진 URL>"을 전달합니다(You.com에서 URL 찾기: "{commonName} bird photo wildlife").

출력에서 cardPath를 캡처합니다.

6c 단계 — 스크린샷, 저장, 업로드 및 전송: 스크린샷 스크립트를 실행하여 카드를 600×400으로 렌더링하고 PNG로 저장합니다:

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

출력에서 pngPath를 캡처합니다.

Cloudflare R2에 업로드하여 공개 URL을 얻습니다:

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

출력에서 url을 캡처합니다.

API에서 관찰의 카드 URL을 업데이트합니다 (log_sighting 출력의 id 사용):

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

Telegram을 통해 PNG를 전송합니다:

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

7단계 — 응답

  • isLifer가 참인 경우: "🎉 새로운 첫 기록! 당신의 첫 번째 [commonName]입니다! Birdfolio의 #[totalSpecies]번째 새입니다."

    totalSpecies == 1인 경우(이것이 첫 번째 새인 경우): 또한 개인 PWA 링크를 전송합니다: "🦅 당신의 Birdfolio가 활성화되었습니다! 이 링크를 북마크하여 생애 목록을 확인하세요: https://birdfolio.tonbistudio.com/app/[telegram_id]"

    telegram_id는 수신 메시지 메타데이터(sender_id)의 발신자 Telegram ID입니다. 초기화 후 birdfolio/config.json에도 저장됩니다.

  • 그 외의 경우: "[commonName] 발견! 이제 Birdfolio에서 [N]종을 보셨습니다."

포함: 희귀도 배지 이모지, 재미있는 사실, 체크리스트 상태 (종이 체크리스트에 있었으면 언급).

스크린샷 실패 시 대체: 형식화된 텍스트 카드 전송:

🦅 [RARITY_EMOJI] [Common Name]
학명: [Scientific Name]
지역: [Region] | 발견 날짜: [Date]
희귀도: [Rarity]
💡 [Fun Fact]
Birdfolio의 #[N]번째 새

3. 체크리스트 및 통계

트리거: "체크리스트 확인", "Birdfolio 진행 상황", "몇 마리의 새를 찾았나요?"

exec: python {baseDir}/scripts/get_stats.py \
  --workspace <워크스페이스 내 birdfolio/의 절대 경로>

출력의 checklistProgress를 사용하여 응답 형식 지정:

📋 {region} 체크리스트

일반     ✅✅✅⬜⬜⬜⬜⬜⬜⬜  3/10
희귀     ✅⬜⬜⬜⬜              1/5
초희귀   ⬜                      0/1

🐦 {totalSpecies}종 | 총 {totalSightings}회 관찰
📍 마지막 발견: {mostRecentSighting.commonName} ({date})
🏆 최고 희귀 발견: {rarestBird.commonName} ({rarity})

발견됨은 ✅, 미발견은 ⬜를 사용합니다. 종당 하나의 상자입니다.

선택적 시각적 체크리스트 카드: 시각적 HTML 체크리스트 카드를 생성하고 스크린샷을 찍습니다:

exec: python {baseDir}/scripts/generate_checklist_card.py \
  --workspace <워크스페이스 내 birdfolio/의 절대 경로>

그런 다음 screenshot_card.js로 스크린샷을 찍고 PNG를 전송합니다.


4. 생애 목록 보기

트리거: "내 Birdfolio 보기", "내 생애 목록 보기"

워크스페이스에서 birdfolio/lifeList.json을 읽습니다.

첫 기록을 희귀도별로 그룹화합니다 (초희귀 먼저, 그 다음 희귀, 일반). 텍스트 목록으로 형식화하거나 HTML 갤러리를 생성하여 워크스페이스의 birdfolio/my-birdfolio.html에 저장하고 스크린샷을 찍습니다.


5. 종 조회 (기록하지 않음)

트리거: "[종]에 대해 알려줘"

You.com 검색:

"{species} 새 사실 서식지 범위 행동 식단"
"{species} 새 {homeRegion} eBird 빈도 텃새 또는 철새"

대화형 요약을 반환합니다. 관찰을 기록하거나 카드를 생성하지 않습니다.


6. 가장 희귀한 새

트리거: "내 가장 희귀한 새는?", "내 최고 발견 보여줘"

exec: python {baseDir}/scripts/get_stats.py \
  --workspace <워크스페이스 내 birdfolio/의 절대 경로>

출력에서 rarestBird를 읽고 종 이름, 희귀도, 발견 날짜, 지역으로 응답합니다.


빠른 참조

스크립트주요 인자반환값
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} 또는 {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 (권장) 또는 --image-url, --object-position, --life-count, --workspace{status, cardPath, filename}
generate_checklist_card.py--workspace{status, cardPath} — 시각적 HTML 체크리스트 카드
screenshot_card.js<cardPath> [outputPath]{status, pngPath} — PNG를 birdfolio/cards/에 저장
upload_card.py<pngPath> [--secrets path]{status, url} — R2에 업로드, 공개 URL 반환

모든 Python 스크립트는 stdout에 JSON을 출력합니다. 항상 절대 --workspace 경로를 전달하세요. screenshot_card.js는 OpenClaw에 번들된 playwright-core + 시스템 Chrome/Edge를 사용합니다 (별도 설치 불필요).

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.

관련 스킬