Skill: ivangdavila/open-router (version 1.0.0)

--- name: Open Router slug: open-router version: 1.0.0 homepage: https://clawic.com/skills/open-router description: Configure OpenRouter model routing with provider auth, model selection, fallback chains, and cost-aware defaults for stable multi-model workflows. changelog: Initial release with practical OpenRouter setup, routing rules, fallback reliability, and budget-safe operating guidance. metadata: {"clawdbot":{"emoji":"🛣️","requires":{"bins":["curl","jq"],"env":["OPENROUTER_API_KEY"]},"os":["linux","darwin","win32"]}} --- ## Setup On first use, read `setup.md` to align activation boundaries, reliability goals, and routing preferences before making configuration changes. ## When to Use Use this skill when the user wants to connect an OpenAI-compatible workflow to OpenRouter, choose models by task type, set safe fallbacks, and control cost drift over time. ## Architecture Memory lives in `~/open-router/`. See `memory-template.md` for structure. ``` ~/open-router/ ├── memory.md # Active routing profile and constraints ├── providers.md # Confirmed provider and auth choices ├── routing-rules.md # Task -> model and fallback policy ├── incidents.md # Outages, rate limits, and recovery notes └── budgets.md # Spend guardrails and optimization actions ``` ## Quick Reference Use the smallest relevant file for the current task. | Topic | File | |-------|------| | Setup and activation preferences | `setup.md` | | Memory template | `memory-template.md` | | Authentication and provider wiring | `auth-and-provider.md` | | Routing patterns by workload | `routing-playbooks.md` | | Reliability and fallback handling | `fallback-reliability.md` | | Cost controls and spend reviews | `cost-guardrails.md` | ## Core Rules ### 1. Start from Workload Classes, Not Model Hype - Classify requests first: coding, analysis, extraction, summarization, or long-context synthesis. - Map each class to a primary model and a fallback before changing any defaults. ### 2. Keep Authentication Explicit and Verifiable - Use `OPENROUTER_API_KEY` from the local environment, never pasted into logs or chat memory. - Validate auth with a minimal request before applying routing changes. ### 3. Design Fallbacks for Failure Modes, Not Convenience - Separate fallback reasons: rate limit, provider outage, latency spike, or output quality failure. - Keep at least one fallback from a different provider family for resilience. ### 4. Enforce Cost Boundaries Before Throughput Tuning - Set cost ceilings by task class and check expected token burn before broad rollout. - Route low-stakes tasks to cheaper models and reserve premium models for high-impact tasks. ### 5. Change One Layer at a Time - Modify either model selection, fallback policy, or budget limits in a single iteration. - After each change, run a quick verification prompt set and record outcome. ### 6. Record Decisions for Repeatability - Save the final routing policy, rationale, and known tradeoffs in memory. - Reuse proven policies instead of repeatedly rebuilding from scratch. ## Common Traps - Choosing one model for every task -> higher cost and unstable quality under varied workloads. - Using same-family fallback chain only -> cascading failures during provider-specific incidents. - Ignoring token limits for long inputs -> truncated responses and hidden quality loss. - Changing routing and budgets simultaneously -> unclear root cause when quality drops. - Running without verification prompts -> broken routing detected only after user-facing failures. ## External Endpoints These endpoints are used only to discover model metadata and execute routed inference requests under explicit user task intent. | Endpoint | Data Sent | Purpose | |----------|-----------|---------| | https://openrouter.ai/api/v1/models | none or auth header only | Discover current model catalog and metadata | | https://openrouter.ai/api/v1/chat/completions | user prompt content and selected model id | Execute routed inference requests | No other data is sent externally. ## Security & Privacy **Data that leaves your machine:** - Prompt text and selected model metadata sent to OpenRouter when inference is requested. **Data that stays local:** - Routing notes and preferences under `~/open-router/`. - Local environment variable references and verification logs. **This skill does NOT:** - Request raw API keys in chat. - Store plaintext secrets in skill memory files. - Modify files outside `~/open-router/` for its own state. ## Trust By using this skill, prompt content is sent to OpenRouter for model execution. Only install if you trust this service with your data. ## Related Skills Install with `clawhub install <slug>` if user confirms: - `api` — API request design, payload shaping, and response validation patterns - `auth` — credential handling and auth troubleshooting workflows - `models` — model comparison and selection guidance - `monitoring` — runtime health checks and incident tracking practices ## Feedback - If useful: `clawhub star open-router` - Stay updated: `clawhub sync`

path: auth-and-provider.md
content: # Auth and Provider — Open Router

## Goal

Connect an OpenAI-compatible workflow to OpenRouter with explicit auth checks and zero secret leakage in notes.

## Verification Flow

1. Confirm `OPENROUTER_API_KEY` is present in the environment.
2. Run a lightweight models request to confirm auth and network path.
3. Record only pass/fail and timestamp in memory.

## Minimal Request Pattern

```bash
curl -sS https://openrouter.ai/api/v1/models \
  -H "Authorization: Bearer ${OPENROUTER_API_KEY}" \
  -H "Content-Type: application/json" | jq '.data | length'
```

## Provider Wiring Checklist

- Endpoint uses `https://openrouter.ai/api/v1`.
- Authorization header uses bearer token from environment variable.
- Client timeout and retry strategy are explicit.
- Default model is set per workload class, not globally for all tasks.

## Common Auth Failures

- Missing key in current shell session -> source environment and retry.
- Wrong header format -> enforce `Authorization: Bearer ...`.
- Silent proxy mismatch -> test direct path before debugging client wrappers.
- Expired or revoked key -> rotate key and re-run minimal verification.


path: cost-guardrails.md
content: # Cost Guardrails — Open Router

## Budget-First Operations

Set budget limits before scaling usage.

| Control | Why it matters | Suggested baseline |
|---------|----------------|--------------------|
| Monthly ceiling | Prevents surprise invoices | Hard cap with early warning at 70% |
| Per-task cap | Avoids expensive outliers | Maximum token budget by workload class |
| Premium-model gate | Protects high-cost models | Use only for high-impact tasks |

## Cost Review Cadence

Run a short review weekly:

1. Check top spend by workload class.
2. Identify low-value traffic using premium models.
3. Reassign low-stakes traffic to cheaper models.
4. Re-verify quality after each routing adjustment.

## Optimization Heuristics

- Use cheaper models for extraction, tagging, and repetitive transformations.
- Reserve premium models for ambiguous reasoning and high-risk decisions.
- Prefer deterministic prompts to reduce retries and token waste.
- Keep fallback chains short to avoid compounding token burn.

## Cost Trap

Cost spikes usually come from routing mistakes, not model list prices alone.
Always review task-model alignment before changing providers.


path: fallback-reliability.md
content: # Fallback Reliability — Open Router

## Failure Modes to Plan For

- Rate limit responses during traffic spikes.
- Provider-side outages or degraded regions.
- Latency spikes that breach user expectations.
- Quality regressions after model updates.

## Fallback Policy Design

| Trigger | Immediate Action | Follow-up |
|---------|------------------|-----------|
| Rate limit | Retry once with jitter, then fallback | Log event and adjust burst policy |
| Timeout | Fallback to lower-latency model | Record latency threshold breach |
| Repeated format failure | Switch to more deterministic model | Tighten prompt constraints |
| Provider outage | Route to different provider family | Mark incident and recovery time |

## Reliability Rules

1. Avoid infinite retries; cap attempts and fail forward.
2. Keep at least two independent routing paths for critical workloads.
3. Separate reliability fallback from cost optimization fallback.
4. Record incident fingerprints so repeated outages are recognized quickly.

## Quick Health Check

```bash
curl -sS https://openrouter.ai/api/v1/models \
  -H "Authorization: Bearer ${OPENROUTER_API_KEY}" \
  -H "Content-Type: application/json" | jq '.data[0].id'
```

If this fails consistently, avoid changing routing policy until connectivity and auth are confirmed.


path: memory-template.md
content: # Memory Template — Open Router

Create `~/open-router/memory.md` with this structure:

```markdown
# Open Router Memory

## Status
status: ongoing
version: 1.0.0
last: YYYY-MM-DD
integration: pending | complete | paused | never_ask

## Activation
- Auto-activate when:
- Explicit-only topics:
- Never activate for:

## Stack Context
- Client type:
- Provider wiring:
- Auth mode:
- Region or latency constraints:

## Routing Policy
- Workload class:
- Primary model:
- Fallback model:
- Trigger for fallback:

## Budget Guardrails
- Monthly budget:
- Per-task budget:
- Escalation threshold:

## Incident Log
- Date:
- Failure mode:
- Impact:
- Fix applied:

## Notes
- Decision:
- Follow-up:

---
*Updated: YYYY-MM-DD*
```

## Status Values

| Value | Meaning | Behavior |
|-------|---------|----------|
| `ongoing` | Context still evolving | Continue learning from real routing events |
| `complete` | Baseline policy is stable | Minimize setup questions and execute directly |
| `paused` | User paused setup prompts | Use existing policy without asking for new setup details |
| `never_ask` | User declined setup | Never request setup details again |

## Principles

- Keep memory concise and operational.
- Store decisions and outcomes, not raw secrets.
- Update `last` after meaningful routing changes.
- Record incidents in terms of failure mode and verified fix.


path: routing-playbooks.md
content: # Routing Playbooks — Open Router

## Workload Classes

Define routing by workload first, then select models.

| Workload | Primary Objective | Suggested Routing Strategy |
|----------|-------------------|----------------------------|
| Short coding tasks | Fast turnaround | Lower-latency model with code reliability baseline |
| Deep analysis | Reasoning quality | Higher-capability model with fallback for rate limits |
| Long-context synthesis | Context capacity | Long-context model plus fallback with similar context window |
| Extraction and formatting | Deterministic output | Stable, lower-cost model with strict prompt templates |
| Brainstorming | Creative breadth | Mid-tier model with cheaper fallback for iterative cycles |

## Decision Sequence

1. Identify workload class and acceptable latency.
2. Choose primary model for that class.
3. Assign fallback from a different family when possible.
4. Define trigger: timeout, rate limit, or quality threshold.
5. Validate with a small prompt set before rollout.

## Verification Prompt Set

Use 3-5 representative prompts per workload class:

- One typical case
- One edge case with long or noisy input
- One strict-format output case

Track success rate, latency, and output consistency before finalizing policy.

## Anti-Pattern

Using one "best model" for every workflow causes avoidable cost spikes and weak reliability when task shapes change.


path: setup.md
content: # Setup — Open Router

Read this when `~/open-router/` does not exist or is empty.

## Your Attitude

Be practical and reliability-first. Help the user get working routing quickly, then improve resilience and cost control with small, reversible steps.

## Priority Order

### 1. First: Integration

In the first 2-3 exchanges, define when this skill should activate.

- Ask whether to activate automatically for model selection and routing requests.
- Ask whether to be proactive when rate limits or quality drift are mentioned.
- Ask which contexts should never trigger this skill.

### 2. Then: Understand Their Current Stack

Collect only details that change routing decisions.

- Current provider entry point and client compatibility assumptions.
- Main workload types and expected latency or quality targets.
- Reliability constraints: acceptable errors, retries, and failover tolerance.

### 3. Finally: Budget and Operating Style

Capture constraints that avoid runaway cost and unstable behavior.

- Monthly or per-task budget boundary.
- Preference for conservative reliability versus aggressive savings.
- Preferred answer style for operations: short commands or detailed guidance.

## What to Capture Internally

Keep compact notes in `~/open-router/memory.md`.

- Activation boundaries and proactive behavior preferences.
- Current routing map and fallback chain.
- Verified models for each workload class.
- Budget ceilings and recent incidents.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)