vineethsoma/birdmate

Overview

This skill is an APM package for birdmate, a natural language bird search engine that helps users discover bird species by describing what they see or hear. It packages prompts, agent personas, and instruction guardrails to integrate with AI agents and streamline bird identification workflows. The skill is implemented in TypeScript and designed to be plugged into agent runtimes that support APM packages.

How this skill works

The skill provides three core primitives: instructions for safety and output standards, prompts that encapsulate executable identification workflows, and specialized agent personas tuned for ornithological reasoning. Agents use the prompts to convert user descriptions (visual features, calls, behavior, location) into candidate species and supporting evidence. Instructions enforce consistency, e.g., citation formats and confidence reporting, while agents apply the persona logic to prioritize likely matches and ask follow-up questions.

When to use it

• When a user describes a bird visually or by sound and needs likely species identified.
• During conversational workflows that require follow-up questions to refine an identification.
• For building bird-search features in apps, chatbots, or voice assistants.
• When you need structured outputs (species name, confidence, distinguishing features, references).

Best practices

• Start with an open-ended user description, then prompt the agent to extract discrete attributes (size, color, pattern, call, habitat, location).
• Use the persona agents for different expertise levels (layperson vs. expert) to tailor explanation depth.
• Require the agent to include confidence scores and at least one distinguishing feature for each candidate.
• Keep prompts modular: separate attribute extraction, candidate generation, and verification steps.
• Validate high-confidence IDs with authoritative field guides or range maps for critical use cases.

Example use cases

• A birdwatching app where users upload photos or type descriptions to get candidate species and identification tips.
• A voice assistant for hikers that identifies likely species from short audio descriptions of calls.
• An educational chatbot that teaches users how to distinguish similar species using field marks.
• A backend service that translates unstructured birder reports into structured sightings for a citizen science platform.