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 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:

make example-skills-list

Check one user’s configured MCPs and tool allowlists without writing anything:

make example-skills-load \
  USER_ID=<local-voxos-user-id> \
  MCP=openbnb \
  DRY_RUN=1

Load the examples for one or more selectors:

make example-skills-load \
  USER_ID=<local-voxos-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; 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.

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.

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.

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.

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.

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. 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. 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. 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. 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.
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.