# Skills Reference

Complete documentation for all built-in Familiar skills.

---

## Email Management

### `email` - Basic Email Operations

**Tools:**
- `check_inbox` - Get recent/unread email summary
- `read_email` - Read full email content by search
- `search_emails` - Search by sender, subject, keywords
- `draft_email` - Compose without sending
- `send_email` - Send (requires confirmation)

**Examples:**
```
"Check my inbox"
"Show me emails from John"
"Search for emails about budget"
"Draft an email to sarah@example.com about the meeting"
"Send that email"
```

**Setup:** Set `EMAIL_ADDRESS` and `EMAIL_PASSWORD` environment variables.

---

### `triage` - Email Categorization

**Tools:**
- `triage_inbox` - Categorize all emails
- `filter_emails` - Show one category
- `inbox_summary` - Quick category counts
- `teach_sender` - Train sender → category mapping

**Categories:**
- Campaign, Trans Pride, GJL Operations, Staff, Board
- Coalitions, Donors, Grants, Media, Volunteers, Other

**Examples:**
```
"Sort my inbox"
"Show me Board emails"
"How many unread emails in each category?"
"Emails from jane@funder.org should be Grants"
```

---

## Task Management

### `tasks` - To-Do List

**Tools:**
- `add_task` - Create task with priority, due date, category
- `list_tasks` - View tasks (filter by status/category/priority)
- `complete_task` - Mark done
- `update_task` - Modify details
- `delete_task` - Remove task
- `daily_briefing` - Overdue + due today + upcoming

**Priorities:** urgent, high, normal, low

**Categories:** grants, donors, board, events, compliance, programs, general

**Examples:**
```
"Add task: Submit 990 form, urgent, due March 15, category compliance"
"What tasks are due this week?"
"Show me grant tasks"
"Complete the budget review task"
"Daily briefing"
```

---

## Nonprofit Management

### `nonprofit` - Donors & Grants

**Donor Tools:**
- `log_donor` - Record donations/interactions
- `search_donors` - Find by name or giving level
- `donor_details` - Full donor record
- `donors_needing_thanks` - Recent gifts without thank-you

**Grant Tools:**
- `add_grant` - Track prospect/application/award
- `list_grants` - View all grants
- `grant_deadlines` - Upcoming deadlines

**Quick Notes:**
- `add_note` - Capture meeting notes
- `search_notes` - Find notes

**Examples:**
```
"Log a $500 gift from the Johnson Family"
"Who needs thank you letters?"
"Show donors who gave over $1000"
"Add grant prospect: Ford Foundation, $50000, deadline March 1"
"What grant deadlines are coming up?"
```

---

## Google Integration

### `calendar` - Google Calendar

**Tools:**
- `calendar_today` - Get today's events
- `calendar_create` - Create new event
- `calendar_check` - Check availability
- `calendar_free` - Find free time slots
- `calendar_delete` - Cancel event

**Examples:**
```
"What's on my calendar today?"
"Schedule a meeting for Tuesday at 2pm"
"Am I free Thursday afternoon?"
"Find me a free hour tomorrow"
"Cancel my 3pm meeting"
```

**Setup:** Google OAuth credentials required.

---

### `gdrive` - Google Drive

**Tools:**
- `drive_search` - Search files by name
- `drive_list` - List folder contents
- `drive_read` - Read Google Doc/Sheet content
- `drive_download` - Download file
- `drive_recent` - Get recently modified files

**Examples:**
```
"Find the board meeting minutes"
"What's in the Grants folder?"
"Read the Q4 budget spreadsheet"
"Download the annual report PDF"
```

**Setup:** Google OAuth credentials required.

---

## Browser Automation

### `browser` - Web Automation

**Tools:**
- `browser_navigate` - Go to URL
- `browser_login` - Log into portal (saves session)
- `browser_read_page` - Extract page text
- `browser_click` - Click element
- `browser_fill` - Fill form field
- `browser_find_elements` - Discover page elements
- `browser_find_links` - Search for links
- `browser_download` - Download file
- `browser_screenshot` - Capture page
- `browser_extract_table` - Pull table data
- `browser_close` - Save session

**Examples:**
```
"Log into the foundation portal"
"Go to networkforgood.com/reports"
"Download the donor report"
"Take a screenshot of the dashboard"
"Find links containing 'grant'"
```

**Setup:** Run `playwright install chromium`

---

## Proactive Features

### `proactive` - Briefings & Alerts

**Tools:**
- `daily_briefing` - Comprehensive summary
- `set_briefing_time` - Configure auto-briefing
- `set_deadline_alerts` - Days before to warn
- `set_quiet_hours` - No notifications period
- `check_deadlines` - Manual deadline check
- `proactive_status` - View settings

**Examples:**
```
"Give me my morning briefing"
"Set up daily briefing at 8am"
"Alert me 3 days before deadlines"
"Set quiet hours from 9pm to 8am"
```

---

## Voice

### `voice` - Speech

**Tools:**
- `speak` - Text-to-speech
- `listen` - Speech-to-text (microphone)
- `transcribe` - Audio file to text
- `voice_settings` - Configure voice

**Examples:**
```
"Read that email out loud"
"What did I just say?" (transcribes)
"Transcribe the meeting recording"
```

**Setup:** Install `pyttsx3` and optionally `SpeechRecognition`

---

## Messaging

### `messaging` - Unified Messaging

**Tools:**
- `send_message` - Auto-picks best platform
- `send_imessage` - iMessage (macOS)
- `send_whatsapp` - WhatsApp
- `send_signal` - Signal
- `check_messaging_platforms` - What's available

**Examples:**
```
"Send a message to Mom: I'll be late"
"iMessage John: meeting confirmed"
"WhatsApp the team: see you at 3"
"Signal +14155551234: documents ready"
```

---

### `sms` - Twilio SMS

**Tools:**
- `send_sms` - Send text message
- `add_sms_contact` - Save contact
- `list_sms_contacts` - View contacts
- `get_sms_messages` - Recent messages

**Examples:**
```
"Text Sarah: running late"
"Save contact Mom as +14155551234"
"Show recent text messages"
```

**Setup:** Twilio credentials required.

---

## Web & API

### `webapi` - HTTP Requests

**Tools:**
- `http_get` - GET request
- `http_post` - POST request
- `get_weather` - Weather lookup
- `shorten_url` - URL shortener

**Examples:**
```
"Get the weather in Seattle"
"Fetch data from api.example.com/status"
"Shorten this URL: https://..."
```

---

## Hardware

### `gpio` - Raspberry Pi GPIO

**Tools:**
- `gpio_setup` - Configure pin mode
- `gpio_write` - Set pin high/low
- `gpio_read` - Read pin state
- `gpio_pwm` - PWM output
- `gpio_cleanup` - Release pins

**Examples:**
```
"Turn on GPIO pin 18"
"Read the state of pin 23"
"Set pin 12 to 50% brightness"
```

**Setup:** Only works on Raspberry Pi with RPi.GPIO installed.

---

## Plugin System

### `marketplace` - Plugins

**Tools:**
- `browse_plugins` - View available plugins
- `search_plugins` - Search by keyword
- `install_plugin` - Install from registry
- `uninstall_plugin` - Remove plugin
- `update_plugins` - Update all
- `list_installed_plugins` - View installed
- `plugin_info` - Details about plugin
- `plugin_categories` - List categories

**Examples:**
```
"Browse available plugins"
"Search plugins for spotify"
"Install the home-assistant plugin"
"Update all my plugins"
"What plugins do I have?"
```

---

## Creating Custom Skills

See `python -m familiar.create_plugin my-skill` to generate a template.

Basic structure:

```python
def my_function(data: dict) -> str:
    param = data.get("param", "default")
    return f"Result: {param}"

TOOLS = [
    {
        "name": "my_tool",
        "description": "What it does",
        "input_schema": {
            "type": "object",
            "properties": {
                "param": {"type": "string"}
            },
            "required": ["param"]
        },
        "handler": my_function,
        "category": "my_category"
    }
]
```
