# Curated MCP-backed skill examples This directory contains example **Voxos database skills**. They are not Codex `SKILL.md` packages and are not loaded automatically. Each Markdown file is the instruction body stored for a user skill; [`catalog.toml`](https://github.com/s-block/voxos/blob/main/examples/skills/catalog.toml) provides its database fields, MCP grouping, and required tools. The collection is intentionally selective. An example belongs here only when it: - solves a recognizable real-world job rather than demonstrating tools for their own sake; - has a bounded workflow with a clear result; - uses only tools that materially improve that result; - states what must be verified, what to do when evidence is incomplete, and what the tools cannot guarantee; - treats private data and external side effects explicitly; and - can be preflighted against the tools actually discovered and allowed for the target user. Tool names and provider contracts can change. The catalog is checked against the configured MCP inventory every time an example is loaded; provider documentation remains the source of truth for usage terms, quotas, and data handling. ## Quick start List the available MCP selectors without connecting to the database: ```bash make example-skills-list ``` Check one user's configured MCPs and tool allowlists without writing anything: ```bash make example-skills-load \ USER_ID= \ MCP=openbnb \ DRY_RUN=1 ``` Load the examples for one or more selectors: ```bash make example-skills-load \ USER_ID= \ MCP=github,openbnb ``` `MCP=google-workspace` expands to both the `calendar` and `gmail` variants. `MCP=google-workspace:gmail` selects only the Gmail-owned example. Some skills also have cross-MCP dependencies: - `multimodal-journey-plan` is selected by `tripgo` and also requires Google Maps Grounding Lite. - `meeting-preparation-brief` is selected by `google-workspace:calendar` and also requires Gmail. Loading is tenant-scoped and idempotent. It blocks an example when a matching MCP is missing, disabled, untrusted, in a failed state, or lacks a discovered or allowed required tool. An untested or unauthenticated connection produces a warning so the skill can be installed but must be connected before use. The loader never changes MCP trust, authentication, tool allowlists, or agent grants, and it never overwrites an existing skill with the same slug. ## What is saved For each selected example, the loader saves all fields required by the `agent_skills` table: - `name`, `slug`, `category`, `description`, and `body_markdown` come from this directory; - `scope` is `user`, `status` is `active`, and `owner_user_id` is the supplied local Voxos user ID; and - `id`, `created_at`, and `updated_at` are generated by the application. `created_by_reflection_id` remains empty because these are curated examples, not reflection proposals. MCP selectors and required tool names are installation metadata in [`catalog.toml`](https://github.com/s-block/voxos/blob/main/examples/skills/catalog.toml); they are checked before insertion but are not columns on an `agent_skills` row. ## The examples | MCP selector | Skill | Best used for | Brief example | | --- | --- | --- | --- | | `exa` | `evidence-backed-web-research` | Current factual research with source comparison | “Compare the current official guidance on passkeys for consumer apps and identify disagreements.” | | `browserless` | `website-content-performance-audit` | A bounded content, structure, Lighthouse, and accessibility-signal review | “Audit our homepage, pricing page, and signup page; prioritize the changes most likely to reduce abandonment.” | | `github` | `github-repository-orientation` | Onboarding to an unfamiliar repository or tracing change impact | “Show me where authentication enters this repository and which tests protect it.” | | `github` | `github-pull-request-review` | Evidence-based review of a specific pull request | “Review PR 184 for authorization regressions and missing tests.” | | `google-maps-grounding-lite` | `grounded-local-day-plan` | A feasible local itinerary with verified places, weather, and route estimates | “Plan a rainy Saturday in Edinburgh for two adults, starting and ending at Waverley.” | | `tripgo` + Maps | `multimodal-journey-plan` | Door-to-door public transport and mixed-mode alternatives | “Get me from Manly to Sydney Airport by 07:00 with minimal walking and a backup route.” | | `flightradar24` | `flight-activity-brief` | A bounded operational or journalistic view of observed flight activity | “Summarize observed arrivals into Heathrow between 06:00 and 07:00 UTC; do not infer cancellations.” | | `openbnb` | `accommodation-shortlist` | Comparing a few stays against dates, guests, anchors, and nearby essentials | “Shortlist four stays in Porto for two adults, under €180 a night, within 25 minutes of Casa da Música.” | | `google-workspace:gmail` | `gmail-inbox-triage-and-drafting` | Focused inbox triage with optional confirmed label or draft creation | “Find client threads from this week that need my reply and draft responses, but do not create anything yet.” | | Calendar + Gmail | `meeting-preparation-brief` | Turning one meeting and its related email history into a prep brief | “Prepare me for tomorrow’s Acme renewal meeting: decisions, commitments, open questions, and a proposed agenda.” | | `monzo` | `personal-spending-review` | A private, read-only account and transaction review | “Compare dining and transport spending in June with May for my selected current account.” | ### Evidence-backed web research Uses Exa search for discovery and page fetch for a small set of strong sources. It is designed for questions where dates, definitions, source authority, or conflicting evidence matter. The result leads with the answer, links material claims, and separates sourced facts from inference. Required tools: `web_search_exa`, `web_fetch_exa`. Provider reference: [Exa MCP server](https://github.com/exa-labs/exa-mcp-server). ### Website content and performance audit Maps a site, samples representative templates, extracts page content, and runs targeted Lighthouse audits. It produces prioritized, evidence-backed fixes while keeping measured Lighthouse results separate from editorial, structural, and manual-accessibility observations. It is a triage workflow, not a WCAG conformance audit, penetration test, or exhaustive crawl. Required tools: `browserless_map`, `browserless_smartscraper`, `browserless_performance`. Provider reference: [Browserless REST API tools](https://docs.browserless.io/mcp/rest-api-tools). ### GitHub repository orientation Builds a compact map of an unfamiliar repository from its actual instructions, entrypoints, recent activity, related work, symbols, and tests. It traces one relevant path end to end instead of dumping the whole tree or backlog, making it useful for onboarding and change estimation. Required tools: `get_file_contents`, `list_branches`, `list_commits`, `list_issues`, `list_pull_requests`, `search_code`. ### GitHub pull request review Reviews one pull request using its metadata, diff, files, commits, checks, discussion, and surrounding code. Findings must describe a concrete failure or maintenance risk and point to a tight current line range. The workflow is read-only unless the user separately confirms a specific GitHub mutation. Required tools: `pull_request_read`, `get_file_contents`, `get_commit`. Provider reference: [official GitHub MCP server](https://github.com/github/github-mcp-server). ### Grounded local day plan Finds specific places, checks relevant weather, and tests each consecutive driving or walking leg before proposing a timed plan. It preserves returned Google Maps attribution and exposes assumptions about opening, accessibility, and availability rather than presenting them as facts. Required tools: `search_places`, `lookup_weather`, `compute_routes`. Provider reference: [Maps Grounding Lite](https://developers.google.com/maps/ai/grounding-lite). ### Multimodal journey plan Combines Google Maps place disambiguation with TripGo mixed-mode routing, near-term departures, and a shareable route link. It compares a few meaningful alternatives and distinguishes scheduled routes from live departure observations. It cannot buy tickets or guarantee accessibility or punctuality. Required tools: Maps `search_places`; TripGo `tripgo-locations`, `tripgo-routing`, `tripgo-departures`, and `tripgo-get-trip-url`. Provider reference: [TripGo MCP server](https://github.com/skedgo/tripgo-mcp-server). ### Flight activity brief Uses the least expensive light/count tools to summarize observed aircraft activity in an explicit geographic or UTC time window. It is useful for bounded airport-operations awareness or reporting, but deliberately avoids schedules, predictions, cancellation inference, safety guidance, and personal tracking. Required tools: `get_airline_info`, `get_airport_info_light`, `get_flight_summary_light`, `get_live_flights_count`, `get_live_flights_positions_light`. Provider reference: [Flightradar24 MCP server](https://fr24api.flightradar24.com/docs/mcp-server). Use requires an eligible subscription and retention compliant with the provider's current terms. ### Accommodation shortlist Searches a bounded result set, rechecks the strongest candidates with identical dates and guests, compares travel time to the user's important anchors, and looks up only relevant nearby essentials. The result is a decision-oriented shortlist, not a booking action or a guarantee of total price or availability. Required tools: `airbnb_search`, `airbnb_listing`, `maps_distance_matrix`, `maps_search_places`, `maps_place_details`. Provider reference: [OpenBnB](https://openbnb.ai/). OpenBnB is community-operated and is not affiliated with or endorsed by Airbnb or other booking platforms. ### Gmail inbox triage and drafting Uses a narrow Gmail query, opens only relevant threads, identifies actions and owners, and can propose labels or complete reply drafts. It does not delete or send mail. Any label change or draft creation requires a preview and explicit confirmation immediately before the write. Required tools: `gmail.search_threads`, `gmail.get_thread`, `gmail.list_labels`, `gmail.label_thread`, `gmail.create_draft`. ### Meeting preparation brief Anchors on one confirmed Calendar event, then searches Gmail using distinctive event topics and participants. It reconciles the event and message chronology into decisions, commitments, questions, attendee context, and a proposed agenda, without changing either Calendar or Gmail. Required tools: `calendar.list_events`, `calendar.get_event`, `gmail.search_threads`, and `gmail.get_thread`. Provider reference: [Google Workspace MCP servers](https://developers.google.com/workspace/guides/configure-mcp-servers). These services may be subject to preview availability and Workspace administrator policy. ### Personal spending review Checks the Monzo connection, requires an explicit account, and reads bounded transaction pages for a defined period. It handles minor-unit currencies, transfers, refunds, pending items, and incomplete pagination explicitly. The workflow is read-only and is not tax, investment, or comprehensive financial advice. Required tools: `monzo_connection_status`, `monzo_list_accounts`, `monzo_get_balance`, `monzo_list_pots`, `monzo_list_transactions`, `monzo_get_transaction`. Provider reference: [monzo-mcp](https://github.com/s-block/monzo-mcp). Financial data is sensitive and may be retained in Voxos chats, runs, transcripts, and tool events. ## Adding or changing an example Keep the catalog as the source of truth: 1. Add or revise one focused Markdown body. 2. Define its public fields, primary load selector, and complete tool requirements in [`catalog.toml`](https://github.com/s-block/voxos/blob/main/examples/skills/catalog.toml). 3. Use current discovered tool names, not a provider's stale marketing names. 4. Run `make example-skills-list`, a real-user dry run, the focused `tests/agent_skills` tests, and the repository validation gate. 5. Update this README so every catalog slug and cross-MCP dependency remains discoverable. Do not add an example merely because an MCP has unused tools. Prefer one strong, composable workflow over several thin wrappers around individual calls.