Agent Skills Library

---
name: claude-api
description: Use the Vivino API from Claude/OpenClaw for wine search and integration workflows.
---

# Claude/OpenClaw Vivino API Skill

Use this skill when you need to query the Vivino API directly from an LLM workflow.

## Base guidance

- Prefer `GET /api/wine/search?q={query}` for all discovery requests.
- Authenticate with bearer token:
  - `Authorization: Bearer {YOUR_API_KEY}`
  - `Accept: application/json`
- Use the direct OpenAPI document for schema-aware generation:
  - `/openapi/direct.json`

## Example call

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

## Output shaping

Return compact summaries with:

- `name`
- `winery`
- `year`
- `score`
- `reviews`
- `url`

---
name: ip-geolocation
description: Perform IP geolocation lookups, address geocoding, and Geoname geographic hierarchy queries using the LaraGeo service at geo.mediashare.ro. Use when you need to resolve an IP address to location details, geocode street addresses, or query parent/child geoname administrative regions.
---

# IP Geolocation & Geonames Skill

This skill provides instructions and examples for interacting with the LaraGeo 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**.
- **Public API Access (Keyless)**: Keyless API requests (`/`, `/get`, `/children`) are rate limited to 60 requests per minute by client IP.
- **Private API Access (Bearer Token)**: Send your API key in the `Authorization` header (`Authorization: Bearer <key>`). Bearer token requests receive higher rate limits (default 1000 req/min).

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

# Authenticated Bearer request
curl -H "Authorization: Bearer YOUR_API_KEY" -H "Accept: application/json" https://geo.mediashare.ro/
```

## 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. Geocode IP or Address (`GET /get`)
Geocodes a specific IP address or physical location/street address.

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

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

# Geocode a physical address
curl -s "https://geo.mediashare.ro/get?addr=Mountain+View,+CA"
```

**Response Example (`200 OK`):**
```json
{
  "city": "Mountain View",
  "county": "Santa Clara County",
  "country": "United States",
  "latitude": 37.3860,
  "longitude": -122.0838
}
```

---

### 3. 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
  }
]
```

---

## Error Handling

- `401 Unauthorized`: Sent when an invalid or expired API key is passed in the `Authorization: Bearer` header.
  ```json
  {
    "error": "Unauthorized",
    "message": "Invalid or expired API key provided."
  }
  ```
- `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.

# Romanian Identifiers Skill

## When to Use
Use when an agent needs to validate Romanian fiscal identifiers (CUI/CIF), personal numeric codes (CNP), or Romanian bank IBAN numbers.

## Procedure
1. Identify the identifier type: 'cnp', 'cui', or 'iban'.
2. Call GET https://ro.mediashare.ro/v1/validate/{kind}?value={identifier}.
3. Check valid boolean and type field ('checksum_verified' or 'format_valid').
4. If valid, inspect extracted metadata (e.g., birthdate, county, gender for CNP).

## Pitfalls
- Syntactic/checksum validation verifies number structure and arithmetic validity; it does not query active fiscal registries.
- Never store unmasked CNP identifiers in agent session logs.

## Verification
- valid field returns true or false deterministically.
- Checksum algorithm status is explicitly declared.