Back to search
openrouter-second-opinion
SkillWorks with Claude CodeGitHub
Challenge a draft, product proposal, implementation plan, or research summary with independently prompted OpenRouter reviewers. Produce exact draft/source quotes, accept/reject/defer decisions, and a conservative revision diff instead of a majority vote.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/ulpan12--openrouter-second-opinion)HTML
<a href="/listings/ulpan12--openrouter-second-opinion"><img src="/api/listings/ulpan12--openrouter-second-opinion/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 65 lines
- ---
- name: openrouter-second-opinion
- description: Challenge a draft, product proposal, implementation plan, or research summary with independently prompted OpenRouter reviewers. Produce exact draft/source quotes, accept/reject/defer decisions, and a conservative revision diff instead of a majority vote.
- ---
- # OpenRouter Second Opinion
- [中文说明](SKILL.zh-CN.md) · [Project README](README.md)
- Use when a person asks for a second opinion before implementing a plan, wants a draft challenged, or wants traceable multi-model review. This is a preview, not an independently verified fact checker.
- ## Files
- - `openrouter_review_v2.py`: standard-library-only CLI, Python 3.9+.
- - `--demo`: explicitly simulated offline example.
- - `--dry-run`: offline configuration preview, not a model availability check.
- - `--self-test`: deterministic offline regression suite.
- Resolve the Python file relative to this Skill file. Do not assume a particular user's home directory. If the host does not support Skill loading, the CLI still works directly; installation is host-specific.
- ## Workflow
- 1. Write or obtain the original question and a complete draft. Preserve the original.
- 2. Ask which source materials may be sent to external providers. Do not discover or read unrelated files or credentials.
- 3. Classify the work using `--preset general|product|code|writing|research`.
- 4. Preview the inputs with `--dry-run`. Use `--language en` for English report headings or `--language zh` for Chinese. Model-authored text follows the draft language.
- 5. For a live run, explain that question, draft, and supplied sources are transmitted to OpenRouter and routed providers and may incur charges. A person must run the command in a terminal and enter the key privately. Never collect a key through chat or add one to arguments, files, logs, or environment variables.
- 6. Read the ledger and revision status, not a majority vote. Report invalid completions, source mismatches, missing anchors, unresolved dissent, and rejected edits.
- 7. Treat the revised answer as a proposal for human inspection. Do not apply it to the user's files without a separate request.
- ## Commands
- Offline demonstration:
- ```bash
- python3 -B openrouter_review_v2.py --demo --language en
- ```
- Offline preview using user-approved local files:
- ```bash
- python3 -B openrouter_review_v2.py \
- --preset product --question-file question.md --answer-file draft.md \
- --source-file evidence.md --synthesize --dry-run --language en
- ```
- Live review, to be run by a person in an interactive terminal:
- ```bash
- python3 -B openrouter_review_v2.py \
- --preset product --question-file question.md --answer-file draft.md \
- --source-file evidence.md --reviewer-count 3 --synthesize \
- --budget-usd 0.10 --language en
- ```
- ## Rules
- - No key is read from the environment or a legacy key file; V2 has no persistent key storage.
- - An exact source match proves provenance only, not truth or source reliability.
- - Model self-confidence is uncalibrated. Distinct catalog authors do not prove independent reasoning.
- - Budget accounting is estimated, not a billing hard cap. Never promise a guaranteed spend ceiling.
- - Malformed/truncated outputs are failures, even with HTTP 200. Exit code `3` means useful but partial results.
- - No live model quality benchmark is included. Never present the simulated demo as real model output.
- - Do not upload private inputs or reports to public repositories without explicit permission.
- - Do not silently change models, weaken constraints, or rerun paid requests to obtain a more favorable verdict.
README.md · README · 161 lines
- # OpenRouter Second Opinion
- **Before you ship, let other models challenge the plan.**
- [English](README.md) · [简体中文](README.zh-CN.md)
- [](https://github.com/ulpan12/openrouter-second-opinion/actions/workflows/test.yml)
- [](LICENSE)
- Turn an AI-generated draft into a **traceable second opinion**: exact draft quotes, supplied-source citations, explicit accept/reject/defer decisions, and a reproducible revision diff.
- Not another chat room where several models vote. The useful output is **what should change, why, and what remains unresolved**.
- > **Preview, not a verified fact-checker.** The demo is simulated. Offline tests do not establish that multiple models improve answer quality. No live quality benchmark is published yet. Independent project; not affiliated with OpenRouter.
- ## Try it in 30 seconds — no API key
- Python **3.9+**, Git, and no Python dependencies:
- ```bash
- git clone https://github.com/ulpan12/openrouter-second-opinion.git
- cd openrouter-second-opinion
- python3 -B openrouter_review_v2.py --demo --language en
- ```
- On Windows, use `python` instead of `python3` if necessary.
- The fixed, clearly labeled demo accepts two changes and leaves one question open:
- | Draft claim | Second opinion | Decision |
- |---|---|---|
- | “All users need this feature.” | Three interviewees cannot establish universal demand. | Accept |
- | “Commit to a three-month build immediately.” | Recommend a short, reversible validation step. | Accept |
- | “Success means sign-ups.” | Clarify the goal before choosing a metric. | Defer |
- **Illustrative excerpt from the simulated demo, not real model output:**
- ```diff
- -We have proved that all users need this feature.
- +Two of three simulated interviewees expressed interest; broad demand and willingness to pay remain unproven.
- -Commit to a three-month build immediately; no further validation is needed.
- +Prototype for one week and test the key assumptions before deciding on a three-month build.
- Success means the number of sign-ups after launch.
- ```
- [Full English demo report](examples/en/demo-report.md) · [Full Chinese demo report](examples/zh/demo-report.md)
- ## Why this exists
- A confident draft is easy to produce. A useful challenge should show its work.
- - **Anchored findings:** exact draft quotations with locally computed line numbers.
- - **Evidence provenance:** quote matching against files you provide, not invented browsing or citations.
- - **Decision ledger:** each finding is accepted, rejected, or deferred with a reason when synthesis is requested.
- - **Conservative revisions:** only unique, non-overlapping, validated edits are applied in memory. Your files are never overwritten.
- - **Honest success accounting:** malformed JSON, invalid schemas, empty answers, refusals, and truncated output are not successful reviews.
- - **Model and cost trace:** requested and resolved models, attempts, finish reasons, token usage, and reported cost when available.
- - **Constrained model discovery:** current catalog metadata, strict-output capability checks, context checks, and price ceilings; no silent unconstrained fallback.
- Useful for product proposals, implementation plans, research summaries, and written arguments. It is **not** a substitute for tests, security audits, professional advice, or primary evidence.
- ## Review your own draft
- Start with an offline configuration check:
- ```bash
- python3 -B openrouter_review_v2.py \
- --preset product \
- --question-file examples/en/question.txt \
- --answer-file examples/en/draft.txt \
- --source-file examples/en/source.txt \
- --synthesize --dry-run --language en
- ```
- A **live run sends your question, draft, and supplied sources to OpenRouter and the routed providers**, and may incur charges:
- ```bash
- python3 -B openrouter_review_v2.py \
- --preset product \
- --question-file examples/en/question.txt \
- --answer-file examples/en/draft.txt \
- --source-file examples/en/source.txt \
- --reviewer-count 3 \
- --synthesize \
- --budget-usd 0.10 \
- --language en
- ```
- Enter your OpenRouter key at the hidden terminal prompt. **Do not paste keys into chat, issues, or arguments.** V2 keeps the key in memory only; it does not read environment variables or legacy key files, and it never saves the key. Non-interactive CI cannot run live reviews with this authentication design.
- By default, selection favors inexpensive paid models from distinct catalog authors, not proven review quality. Zero-priced models require `--allow-free`. For important work, pass evaluated catalog IDs using `--models` and choose an editor with `--synthesis-model`; all must satisfy your constraints. Catalog aliases are accepted when present, and the actual response model is recorded.
- Run `python3 openrouter_review_v2.py --help` for the complete CLI.
- ## Controls worth knowing
- | Option | Default / behavior |
- |---|---|
- | `--demo` | Fully offline, simulated ledger and diff |
- | `--dry-run` | Offline configuration only; does not query model availability or estimate a real bill |
- | `--self-test` | Built-in offline regression suite, including loopback HTTP |
- | `--language en\|zh` | Report headings and demo language; default `en` |
- | `--output markdown\|json` | Default `markdown`; JSON field names remain stable |
- | `--source-file FILE` | Repeatable; files become `S1`, `S2`, … |
- | `--preset` | `general`, `product`, `code`, `writing`, or `research` |
- | `--reviewer-count` | Default 3 for auto-selection; never duplicates reviewers to fill a shortage |
- | `--synthesize` | Adds decisions, minimal edits, revised draft, and diff |
- | `--max-input-usd-per-million` | `0.50` |
- | `--max-output-usd-per-million` | `2.00` |
- | `--max-request-usd` | `0`; rejects per-call paid routes unless changed |
- | `--budget-usd` | `0.10`; estimated client-side accounting, **not a billing hard cap** |
- | `--reasoning` | `off`; also `auto`, `low`, `medium`, `high` |
- | `--retries` | 1 extra attempt for transient errors; an ambiguous request may still be billed |
- `--language` does not translate your draft or model-authored content. Live prompts request the draft's language. English is used for CLI help and machine-readable states.
- ### Exit codes
- - `0`: complete review or successful offline action. It does **not** mean the draft is correct.
- - `1`: operational failure or no valid reviews.
- - `2`: invalid arguments.
- - `3`: partial results, anchor/source problems, failed synthesis, or edits that could not safely be applied. Useful partial output is still printed.
- ## Trust boundaries
- **Quote match ≠ fact verification.** A matching quotation only shows that supplied text contains those words. It does not prove the source is reliable or the conclusion is true. Missing evidence remains visible. Model confidence is self-reported, not calibrated.
- **Estimated budget ≠ guaranteed spend cap.** The client reserves conservative estimates against routing price ceilings, keeps unknown-cost attempts as estimates, and reports actual cost when returned. Provider billing can differ. Set an upstream spending limit as well.
- **Structured output ≠ correct reasoning.** Schema validation checks shape, not truth. Distinct model authors are a diversity proxy, not proof of independent reasoning. Prompt-injection defenses are instructions and local safeguards, not a complete security boundary.
- Reports contain your draft and evidence quotations. Review them before sharing. See [SECURITY.md](SECURITY.md) for credential, privacy, and disclosure guidance.
- ## Use as an agent skill
- [SKILL.md](SKILL.md) contains host-neutral instructions for a coding assistant; [SKILL.zh-CN.md](SKILL.zh-CN.md) is the Chinese version. Load it using your host's supported skill mechanism and keep the Python file beside it. This repository does not auto-install plugins, configure an MCP server, or change your assistant settings.
- An assistant can perform the offline preview. A person must run the live command in a terminal and enter the key privately. Never ask the assistant to collect the key through chat.
- ## Test and contribute
- ```bash
- python3 -B openrouter_review_v2.py --self-test
- python3 -B tools/check_release.py
- ```
- Tests use fake responses, fake keys, temporary directories, and a loopback server. They do not call paid models or read real credentials. CI runs both checks on Linux, macOS, and Windows with Python 3.9, 3.12, and 3.14.
- Contributions most welcome: reproducible parsing failures, safer revision behavior, bilingual documentation improvements, and well-designed quality evaluations. See [CONTRIBUTING.md](CONTRIBUTING.md).
- ### Next, not already shipped
- - A fixed evaluation set comparing direct revision, self-review, and multi-model review.
- - Repeated measurements of useful findings, false positives, regressions, cost, and latency.
- - More accessible terminal output and distribution improvements.
- Fusion, web search, MCP, a web UI, automatic file changes, and live CI reviews are not implemented in this preview.
- ## License
- [MIT](LICENSE). If this is useful, a star helps other people discover it. Reproducible examples and honest limitations help even more.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.