advisor-protocol — Claude Code skill: math checks and install
The advisor-protocol Claude Code skill sends difficult mathematical reasoning to a more capable model for review. It activates when an agent is unsure how to interpret a derivation or translate it into code.
Apache-2.0 ★ 89 updated 2026-11-12
npx skills add bis-med-it/marco-BIS --skill advisor-protocol -a claude-codeWhat advisor-protocol does
The skill routes mathematical questions to a configured model when the agent cannot confidently verify a derivation or formula implementation. It covers unfamiliar priors, new identification schemes, and dense arguments from papers. Routine work such as standard OLS or GLS stays with the executing agent.
The agent reads settings from the repository-root config.yaml. The advisor is off by default; set advisor.enabled to true and configure a provider, model, and api_key_env before making a call. A fallback provider and human review can also be configured. Requests go through the provider API; the library itself does not make advisor calls.
The response can be reviewed, saved under references/, and reused during implementation. Exchanges are logged through the research-log skill. Dataset contents and proprietary information must not be sent; this is a policy instruction, not a technical filter.
What it helps with
- verify a derivation from a research paper
- interpret an unfamiliar identification scheme
- check whether code matches a formula
- turn a mathematical expression into pseudocode
- save a verified derivation for reuse
Example prompts for the agent
- Check the derivation of this formula from the paper and list its assumptions.
- Compare the implementation in
model.pywith the mathematical expression. - Interpret the notation in this identification scheme and draft pseudocode.
How to install advisor-protocol
1Skills CLI (Vercel)
npx skills add bis-med-it/marco-BIS --skill advisor-protocol -a claude-code2Manually: put the files in place
~/.claude/skills/advisor-protocol/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/advisor-protocol/
1Skills CLI (Vercel)
npx skills add bis-med-it/marco-BIS --skill advisor-protocol -a codex2Manually: put the files in place
.agents/skills/advisor-protocol/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add bis-med-it/marco-BIS --skill advisor-protocol -a cursor2Manually: put the files in place
.cursor/skills/advisor-protocol/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install bis-med-it/marco-BIS skills/advisor-protocol2Manually: put the files in place
.github/skills/advisor-protocol/SKILL.md1Skills CLI (Vercel)
npx skills add bis-med-it/marco-BIS --skill advisor-protocol -a gemini-cli2Platform CLI
gemini skills install https://github.com/bis-med-it/marco-BIS --path skills/advisor-protocolManually: put the files in place
.devin/skills/advisor-protocol/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about advisor-protocol
How do I install advisor-protocol in Claude Code?
Run npx skills add bis-med-it/marco-BIS --skill advisor-protocol -a claude-code. The skill file is installed at ~/.claude/skills/advisor-protocol/SKILL.md.
What does advisor-protocol do?
It sends complex derivations and formula checks to a configured model, then extracts verified steps, pseudocode, and assumptions. The response can go through human review and be saved for later runs.
What does advisor-protocol need to work?
The repository-root config.yaml needs a provider, model, api_key_env, and advisor.enabled: true. Requests use the provider API, and a fallback provider can be configured.
Source text
SKILL.md · Apache-2.0
--- name: advisor-protocol description: > Model-agnostic escalation protocol for complex mathematical reasoning, derivation verification, and theoretical validation. Use when the executing agent encounters dense mathematical content from a paper, unfamiliar identification schemes, non-standard prior derivations, or any situation where the agent's confidence in correctly translating mathematics to code is low. This skill routes the query to a more capable reasoning model; the specific provider and model are configurable and not hardcoded. --- # Advisor protocol ## Purpose The executing agent handles the routine workflow. When mathematical content exceeds its confidence, it asks a more capable reasoning model to check the work before proceeding, as a researcher would consult a senior colleague on a tricky derivation. ## When to escalate The executing agent should invoke the advisor when: 1. **Unfamiliar derivations.** A paper introduces notation, distributional assumptions, or algebraic steps the agent cannot confidently verify. 2. **Novel identification schemes.** Sign restrictions with complex penalty functions, narrative identification with inequality constraints, or set-identified models. 3. **Non-standard priors.** Any prior structure not covered by the `scripts/lib/bvar.py` module docstrings or `CONVENTIONS.md`. 4. **Distributional theory.** Posterior derivations involving non-conjugate cases, marginalisation over nuisance parameters, or asymptotic approximations. 5. **Ambiguous mathematical notation.** When a paper's notation is inconsistent or context-dependent and the agent is unsure of the correct interpretation. 6. **Cross-checking implementations.** After coding a complex formula, the agent can ask the advisor to verify the code matches the mathematics. **Do not escalate for:** routine matrix algebra, standard OLS/GLS, well-documented Minnesota prior computation, basic time-series transformations, or anything already covered in verified reference documents. ## Advisor configuration The advisor is off by default. Before any call, read `advisor.enabled` in the repo-root `config.yaml`. If it is not `true`, do not call the advisor: tell the user the step would normally be escalated, continue without it, and suggest checking the derivation by hand or enabling the advisor. The advisor is configured in the repo-root `config.yaml` under `advisor:` (`enabled`, provider, model, endpoint, `api_key_env`, an optional fallback provider, and settings: `max_attempts`, `timeout_seconds`, `log_all_exchanges`, `require_human_review`). The model named there is an example; set one the user has access to. Users or administrators set this once; the agent reads it at runtime. The agent sends the query through the configured provider's API; the library implements no advisor calls. ## Escalation protocol ### Step 1: Prepare the query The executing agent constructs a structured prompt for the advisor: ``` CONTEXT: I am implementing [model/method] from [paper reference]. The executing environment is [Python/R/Julia]. MATHEMATICAL CONTENT: [Extract the relevant equations, definitions, and notation from the paper. Include surrounding context so the advisor understands the setup.] SPECIFIC QUESTION: [One of:] - "Verify that the following derivation is correct: [steps]" - "Translate this mathematical expression into pseudocode: [expression]" - "This paper uses notation X for Y. Please confirm my interpretation: [interpretation]" - "I have implemented this formula as [code]. Verify it matches the mathematics." - "Derive the posterior distribution for [parameter] given [prior] and [likelihood]." CONSTRAINTS: - Provide step-by-step reasoning. - Flag any assumptions that are implicit in the paper but should be made explicit. - If the derivation has multiple valid interpretations, list them. - Express the final result in explicit matrix notation with dimensions annotated. ``` ### Step 2: Call the advisor Send the query through the configured provider's API as a standard request, with no provider-specific logic beyond API format translation. If the primary provider fails and a fallback is set, try the fallback. If no provider answers, tell the user to verify the mathematical content manually before proceeding. ### Step 3: Process the response 1. Parse the advisor's response. 2. Extract: verified derivation steps, pseudocode, flagged assumptions, and any alternative interpretations. 3. **Present to the human for review** (if `require_human_review` is true). The review happens after the call and before the response is used. 4. Log the full exchange via the research-log skill. ### Step 4: Incorporate into workflow Once the human confirms the advisor's output: 1. Save the verified derivation as a reference document in the relevant skill's `references/` directory (created on first use; e.g., `<skill-name>/references/verified_xyz_derivation.md`) or alongside the lib module that needs it (e.g., `scripts/lib/references/verified_xyz_derivation.md`). 2. Use the pseudocode to implement the formula. 3. The reference document persists, so future runs of the same method do not need to re-escalate. This creates a growing library of verified mathematical content over time. ## Cost management Advisor calls are expensive relative to routine execution. For each session, the agent records in the research log the number of advisor calls, tokens per call, and a cost estimate from the provider's published pricing. If costs are a concern, the user can: - Ask the agent to confirm with the user before each advisor call (an explicit step before invoking; `require_human_review` reviews the response after the call, so it saves no cost) - Use a local model as the advisor for cost-free but potentially lower-quality review - Pre-populate `references/` with verified content to reduce future escalations ## Institutional deployment considerations Central banks and research institutions may have: - **Air-gapped networks.** Use a locally hosted model as the advisor. - **Data confidentiality constraints.** The advisor prompt should never include proprietary data, only mathematical content from published or working papers. The skill instructs the agent to send only equations and derivations, never datasets or proprietary data. This is a policy, not a technical filter. - **Approved vendor lists.** The configurable provider system accommodates this: set only the approved provider(s) in the configuration. - **Audit requirements.** The agent logs every advisor exchange in the research log, with timestamps, prompts, responses, and human confirmation status.
© bis-med-it · Apache-2.0 · bis-med-it/marco-BIS