--- title: "Agent Skills Library — MediaShare" description: "Portable, client-neutral SKILL.md guides for autonomous AI agents and coding harnesses." --- # Agent Skills Library Portable, client-neutral SKILL.md guides for autonomous AI agents and coding harnesses. ## vivino-api Search and fetch wine details, community ratings, review counts, prices, and vintage information from the Vivino API using Claude, Codex, OpenClaw, Hermes, or other AI agents. - Target service: wine - Scope: wine.mediashare.ro ### When to Use Use this skill when you need to query wine information, community ratings, review counts, average prices, and vintage details from the Vivino API in any LLM assistant, coding agent, or autonomous agent workflow (Claude, Codex, OpenClaw, Hermes, Cursor, Windsurf, Pi, etc.). ### Procedure - **Primary Endpoint:** `GET /api/wine/search?q={query}` - **Authentication:** Bearer token - `Authorization: Bearer {YOUR_API_KEY}` - `Accept: application/json` - **Base URL:** `https://wine.mediashare.ro` - **OpenAPI Schema:** `/openapi/direct.json` ### Pitfalls & Edge Cases - **Constructing Search Queries:** - Include producer, wine name, and vintage year when known (e.g., `Chateau Margaux 2015`, `Catena Zapata Malbec 2019`). - For general exploration, pass the brand or appellation (e.g., `Tignanello Antinori`). - **Output Shaping for Users:** - Always highlight the wine name, winery, vintage, rating (e.g., `⭐ 4.3/5 based on 250 reviews`), average price if available, and provide the direct Vivino URL for further reading. - **Multi-Agent Setup:** - **Claude**: Upload the skill ZIP via *Customize > Skills* or place in `.claude/skills/`. - **Codex / Hermes / Pi**: Save this file as `SKILL.md` under `~/.agents/skills/vivino-api/SKILL.md`. - **OpenClaw**: Place under `~/.openclaw/skills/vivino-api/SKILL.md` or fetch raw markdown. ### Verification Steps - HTTP status is 200 OK with valid JSON structure. - Response record contains expected fields matching the query. ## ip-geolocation Perform IP geolocation lookups, address geocoding, proxy/threat detection, and Geoname geographic hierarchy queries using the geo.mediashare.ro service. - Target service: geo - Scope: geo.mediashare.ro ### When to Use Use when you need to resolve an IP address to location details, geocode street addresses, detect proxies/VPNs/Tor exit nodes, or query parent/child geoname administrative regions. ### Procedure - Get Visitor IP Geolocation (GET /): Retrieves geolocation metadata for the caller's IP address. - Advanced Proxy & Threat Detection (GET /proxy) - API Key Required: Performs multi-layered proxy, VPN, Tor, and datacenter threat analysis for an IP address. - Geocode IP or Address (GET /get): Geocodes a specific IP address or physical location/street address. Basic geocoding is free and rate-limited. Pass proxy=1 to enrich the response with proxy detection data (requires an API key). - Geoname Child Hierarchy (GET /children): Fetches administrative or geographic child subdivisions for a given parent Geoname ID. - Linear Distance Calculation (GET /distance): Calculates great-circle linear (Haversine) distance and compass bearing between two locations. - Location Search (GET /search): Performs fast location search to find any location (country, city, county, etc.) and return its details including Geoname ID, feature code description, and coordinates. Supports multiple languages and warm caching. ### Pitfalls & Edge Cases - **Documentation & Skills**: OpenAPI specification (`/openapi.json`) and agent skills (`/skills/*`) are public resources and are **not rate limited**. - **Free API Access (Keyless)**: Keyless API requests for free endpoints (`/`, `/get`, `/children`, `/distance`, `/search`) are available without an API key and are rate limited to **60 requests per minute** by client IP. Unauthenticated geocoding requests rely on free providers (GeoNames, GeoPlugin, IpInfo, local MaxMind) and never call paid upstream geocoders. - **Protected Features (API Key Required)**: The proxy & threat detection feature (`GET /proxy`, `?proxy=1`, `?check_proxy=1`), extended telecom metadata (`GET /?full=1`), and paid geocoder fallback are **not available without an API key**. Keyless requests to these features return `401 Unauthorized`. - **Private API Access (Bearer Token)**: Send your API key in the `Authorization` header (`Authorization: Bearer `) with `Accept: application/json`. Bearer token requests unlock protected features and receive higher rate limits (default 1000 req/min). - `401 Unauthorized`: Sent when accessing protected features (such as `/proxy` or `?proxy=1`) without an API key, or when an invalid/expired key is provided. - `422 Unprocessable Entity`: Sent when invalid parameters or malformed IP addresses are supplied. - `429 Too Many Requests`: Sent when request rate limits are exceeded (60 req/min for public IP access, custom/1000 req/min for API keys). - `501 Not Implemented`: Sent if external IP lookup fails for `GET /`. ### Verification Steps - HTTP GET / with header 'Accept: application/json' returns 200 OK with visitor IP geolocation. - HTTP GET /distance returns 200 OK with linear distance calculations and compass bearing. - Protected endpoints (GET /proxy, ?proxy=1) return HTTP 401 Unauthorized without an API key. - Public OpenAPI specification is accessible at https://geo.mediashare.ro/openapi.json. ## romanian-finance Query BNR official exchange rates and mutual-fund reference data. - Target service: finance - Scope: ro-finance.mediashare.ro ### When to Use Use when an agent requires official Romanian National Bank (BNR) FX rates, reference currency multipliers, or mutual-fund NAVs. ### Procedure - Call GET https://ro-finance.mediashare.ro/v1/fx-rates with Accept: application/json. - For a specific currency history, request /v1/fx-rates/{currency}/history?from=YYYY-MM-DD. - Verify the source field ('BNR') and the observed_at ISO timestamp. - Calculate conversions using the explicit ron_per_unit multiplier without rounding. ### Pitfalls & Edge Cases - BNR rates are reference rates published once per business day around 13:00 EET; they are not live tradable market quotes. - Do not execute trades or provide financial advice based on reference snapshot feeds. ### Verification Steps - Response contains observed_at timestamp and rates map with EUR, USD, GBP values. - Source attribution is explicitly marked as 'BNR'. ## url-metadata Safely extract OpenGraph tags, article text, and web page metadata. - Target service: meta - Scope: meta.mediashare.ro ### When to Use Use when an agent needs to inspect a web URL, extract article title, description, author, publication date, and OpenGraph tags safely. ### Procedure - Validate that the target URL uses http:// or https:// schemes. - Send POST or GET to https://meta.mediashare.ro/v1/extract with target URL and Bearer token. - Check the response for title, description, og:image, and clean markdown text extraction. - Inspect the provenance metadata for cache freshness and extraction timestamp. ### Pitfalls & Edge Cases - Internal, private (RFC 1918), loopback, and cloud metadata URLs are blocked by SSRF defense layers. - Responses exceeding maximum content length (e.g. 5MB) will be truncated. ### Verification Steps - Response contains valid extracted title and canonical URL. - Provenance object confirms HTTP fetch status and extraction timestamp.