Biblioteca de Skill-uri pentru Agenți

---
name: vivino-api
description: 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.
---

# Vivino API Skill for AI Agents (Claude, Codex, OpenClaw, Hermes & more)

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

## Base Guidance

- **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`

## Example Request

```bash
curl -G 'https://wine.mediashare.ro/api/wine/search' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json' \
  --data-urlencode 'q=Purcari Malbec 2020'
```

## Response Fields

The API responds with normalized wine information:

- `id` (integer) - Internal database identifier
- `name` (string) - Wine / cuvée name
- `winery` (string) - Producer / winery name
- `year` (integer|null) - Vintage year
- `score` (float) - Community average score (1.0 - 5.0)
- `reviews` (integer) - Total number of community ratings
- `url` (string) - Direct Vivino wine webpage
- `grapes` (string|null) - Grape varietal(s)
- `type` (integer|null) - Wine classification (1: Red, 2: White, 3: Sparkling, 4: Rosé, 7: Dessert, 24: Fortified)
- `avg_price` (string|null) - Computed average price
- `currency` (string|null) - Currency (e.g. `EUR`, `USD`, `RON`)

## Agent Usage & Best Practices

1. **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`).

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

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

---
name: ip-geolocation
description: Perform IP geolocation lookups, address geocoding, proxy/threat detection, and Geoname geographic hierarchy queries using the geo.mediashare.ro service. 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.
---

# IP Geolocation & Geonames Skill

This skill provides instructions and examples for interacting with the geo.mediashare.ro API service running at `https://geo.mediashare.ro`.

## Authentication & Rate Limits

- **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 <key>`) with `Accept: application/json`. Bearer token requests unlock protected features and receive higher rate limits (default 1000 req/min).

### Requesting an API Key
Need an API key for proxy detection, extended telecom intelligence, or higher rate limits?
Submit a request via the contact form at:
`https://geo.mediashare.ro/contact`

```bash
# Public keyless request (free endpoints)
curl -H "Accept: application/json" https://geo.mediashare.ro/

# Authenticated Bearer request (unlocks proxy detection & high rate limits)
curl -H "Authorization: Bearer YOUR_API_KEY" -H "Accept: application/json" https://geo.mediashare.ro/proxy?ip=8.8.8.8
```
## Endpoints & Usage

### 1. Get Visitor IP Geolocation (`GET /`)
Retrieves geolocation metadata for the caller's IP address.

**Request:**
```bash
curl -s -H "Accept: application/json" https://geo.mediashare.ro/
```

**Response Example (`200 OK`):**
```json
{
  "status": "success",
  "country": "Romania",
  "countryCode": "RO",
  "region": "B",
  "regionName": "Bucharest",
  "city": "Bucharest",
  "zip": "010001",
  "lat": 44.4323,
  "lon": 26.1063,
  "timezone": "Europe/Bucharest",
  "isp": "Example ISP",
  "org": "Example Org",
  "as": "AS12345 Example",
  "query": "1.2.3.4"
}
```

---

### 2. Advanced Proxy & Threat Detection (`GET /proxy`) - *API Key Required*
Performs multi-layered proxy, VPN, Tor, and datacenter threat analysis for an IP address.

> **Note:** The proxy detection feature requires a valid API key. Keyless requests will return `401 Unauthorized`. If you need an API key, please request one using the contact form at `https://geo.mediashare.ro/contact`.

**Parameters:**
- `ip` *(optional)*: IP address string to analyze (defaults to caller's IP if omitted).

**Request (Authenticated):**
```bash
# Analyze a specific IP address with Bearer token
curl -s -H "Authorization: Bearer YOUR_API_KEY" -H "Accept: application/json" "https://geo.mediashare.ro/proxy?ip=8.8.8.8"

# Analyze caller's IP address with Bearer token
curl -s -H "Authorization: Bearer YOUR_API_KEY" -H "Accept: application/json" "https://geo.mediashare.ro/proxy"
```

**Response Example (`200 OK`):**
```json
{
  "ip": "8.8.8.8",
  "is_proxy": true,
  "is_vpn": false,
  "is_tor": false,
  "is_datacenter": true,
  "is_public_proxy": false,
  "is_residential_proxy": false,
  "is_relay": false,
  "is_crawler": false,
  "proxy_type": "datacenter",
  "risk_score": 60,
  "threat_level": "medium",
  "confidence": 0.85,
  "details": {
    "asn": 15169,
    "as_org": "Google LLC",
    "isp": "Google LLC",
    "country_code": "US",
    "datacenter_provider": "Google Cloud",
    "crawler_name": null,
    "matched_detectors": [
      "known_datacenter_heuristic"
    ],
    "detected_headers": {},
    "cached": false
  }
}
```

---

### 3. 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*).

**Parameters:**
- `ip` *(optional)*: IP address string to geocode (defaults to client IP if omitted).
- `addr` *(optional)*: Street address or location string to geocode (takes precedence over `ip`).
- `proxy` *(optional)*: Set to `1` or `true` to attach proxy intelligence (*requires API key; returns 401 if keyless*).

**Examples:**
```bash
# Free: Geocode an IP address (keyless)
curl -s "https://geo.mediashare.ro/get?ip=8.8.8.8"

# Free: Geocode a physical address (keyless, uses free GeoNames/GeoPlugin providers)
curl -s "https://geo.mediashare.ro/get?addr=Mountain+View,+CA"

# Protected: Geocode with attached proxy intelligence (requires API key)
curl -s -H "Authorization: Bearer YOUR_API_KEY" -H "Accept: application/json" "https://geo.mediashare.ro/get?ip=8.8.8.8&proxy=1"
```
**Response Example (`200 OK`):**
```json
{
  "city": "Mountain View",
  "county": "Santa Clara County",
  "country": "United States",
  "country_code": "US",
  "is_eu": false,
  "isEu": false,
  "languages": [
    "en-US",
    "es-US",
    "haw",
    "fr"
  ],
  "latitude": 37.3860,
  "longitude": -122.0838
}
```

---

### 4. Geoname Child Hierarchy (`GET /children`)
Fetches administrative or geographic child subdivisions for a given parent Geoname ID.

**Parameters:**
- `id` *(optional, default: `6255149`)*: Geoname ID (e.g. Earth parent ID `6255149`, continent IDs, country IDs, or administrative divisions).
- `lang` *(optional, default: `"en"`)*: Two-letter language code.

**Examples:**
```bash
# List top-level geographic regions (default parent: Earth 6255149)
curl -s "https://geo.mediashare.ro/children?id=6255149&lang=en"
```

**Response Example (`200 OK`):**
```json
[
  {
    "name": "Europe",
    "geonameId": 6255148,
    "fcodeName": "continent",
    "latitude": 48.69,
    "longitude": 9.14
  }
]
```

---

### 5. Linear Distance Calculation (`GET /distance`)
Calculates great-circle linear (Haversine) distance and compass bearing between two locations.

**Parameters:**
- `from` / `origin` *(optional)*: Origin location (coordinates `"lat,lng"`, IP address, or address string). Defaults to caller's IP address.
- `to` / `destination` *(required)*: Destination location (coordinates `"lat,lng"`, IP address, or address string).

**Examples:**
```bash
# Calculate distance between coordinate pairs
curl -s "https://geo.mediashare.ro/distance?from=44.4323,26.1063&to=45.6579,25.6012"

# Calculate distance from caller IP to an address
curl -s "https://geo.mediashare.ro/distance?to=Brasov,+Romania"
```

**Response Example (`200 OK`):**
```json
{
  "status": "success",
  "method": "haversine_great_circle",
  "origin": {
    "query": "44.4323,26.1063",
    "resolved": "44.4323, 26.1063",
    "latitude": 44.4323,
    "longitude": 26.1063
  },
  "destination": {
    "query": "45.6579,25.6012",
    "resolved": "45.6579, 25.6012",
    "latitude": 45.6579,
    "longitude": 25.6012
  },
  "distance": {
    "kilometers": 141.28,
    "miles": 87.79,
    "meters": 141280.0,
    "feet": 463517.0,
    "nautical_miles": 76.28
  },
  "bearing_degrees": 341.2
}
```


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

**Parameters:**
- `q` *(required)*: Location name, country code, or query string (e.g. `Romania`, `Paris`, `RO`).
- `lang` *(optional, default: `"en"`)*: Two-letter language code for localized results (e.g. `en`, `ro`, `de`, `fr`).
- `all` *(optional, default: `false`)*: Set to `1` or `true` to return an array of multiple matching locations.
- `limit` *(optional, default: `10`)*: Maximum number of results when `all=1`.

**Examples:**
```bash
# Search for a country
curl -s "https://geo.mediashare.ro/search?q=Romania&lang=en"

# Localized search
curl -s "https://geo.mediashare.ro/search?q=Romania&lang=ro"

# Search for a city
curl -s "https://geo.mediashare.ro/search?q=Paris&lang=en"
```

**Response Example (`200 OK`):**
```json
{
  "name": "Romania",
  "geonameId": 798549,
  "fcodeName": "independent political entity",
  "latitude": 46,
  "longitude": 25
}
```

---

## Error Handling
- `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.
  ```json
  {
    "error": "Unauthorized",
    "message": "An API key is required to access the proxy detection feature."
  }
  ```
  *(To request an API key, use the contact form at `https://geo.mediashare.ro/contact`.)*
- `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 /`.

## OpenAPI Specification
The complete OpenAPI 3.0 specification for this API is available at:
`https://geo.mediashare.ro/openapi.json`

# Romanian Finance Skill

## When to Use
Use when an agent requires official Romanian National Bank (BNR) FX rates, reference currency multipliers, or mutual-fund NAVs.

## Procedure
1. Call GET https://ro-finance.mediashare.ro/v1/fx-rates with Accept: application/json.
2. For a specific currency history, request /v1/fx-rates/{currency}/history?from=YYYY-MM-DD.
3. Verify the source field ('BNR') and the observed_at ISO timestamp.
4. Calculate conversions using the explicit ron_per_unit multiplier without rounding.

## Pitfalls
- 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
- Response contains observed_at timestamp and rates map with EUR, USD, GBP values.
- Source attribution is explicitly marked as 'BNR'.

# URL Metadata Skill

## 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
1. Validate that the target URL uses http:// or https:// schemes.
2. Send POST or GET to https://meta.mediashare.ro/v1/extract with target URL and Bearer token.
3. Check the response for title, description, og:image, and clean markdown text extraction.
4. Inspect the provenance metadata for cache freshness and extraction timestamp.

## Pitfalls
- Internal, private (RFC 1918), loopback, and cloud metadata URLs are blocked by SSRF defense layers.
- Responses exceeding maximum content length will be truncated.

## Verification
- Response contains valid extracted title and canonical URL.
- Provenance object confirms HTTP fetch status and extraction timestamp.