# advisor-claw-skill

Adopt this skill: https://proskills.md/skills/model-orchestration/sapsapshen-advisor-claw-skill

Page: https://proskills.md/skills/model-orchestration/sapsapshen-advisor-claw-skill
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 4562
upstream: https://github.com/sapsapshen/advisor-claw-skill/blob/HEAD/SKILL.md

````text
---
name: advisor-claw-skill
description: Orchestrate low-cost executor models with high-intelligence advisor models for complex or high-risk turns. Use when a task needs dynamic escalation, budget-aware planning, strategic review, or model-cost optimization without hard-coding a single provider.
emoji: "🧠"
version: "1.0.0"

dependencies:
  binaries: ["node"]
  env:
    - ANTHROPIC_API_KEY
    - OPENAI_API_KEY
    - DEEPSEEK_API_KEY

tools:
  allow:
    - read
    - write
    - exec
    - gateway
    - subagents

metadata:
  openclaw:
    category: model-orchestration
    priority: 90
    compatibility:
      min_version: "1.8.0"
    entrypoint: "scripts/index.js"
---

# Advisor Claw Skill

## Purpose

Route most work through an economical executor model and escalate to an advisor model only when the task is risky, stalled, ambiguous, or strategically complex.

After installation, the user can configure candidate models through OpenClaw conversation in either of two ways:

- reuse models already configured in OpenClaw
- add external models by supplying provider metadata and API keys

The skill should then infer role placement from model strength and cost, rather than requiring the user to hard-code advisor and executor assignments.

The skill must reject invalid model setup unless the user provides exactly 2 models.

## Trigger Guidance

Activate this skill when any of the following are true:

- The task explicitly mentions budget control, model routing, or advisor strategy.
- The task is long-running and may require mid-course review.
- The task mixes execution with architectural or quality-risk decisions.
- The user wants lower-cost models to do most of the work while preserving high-quality outcomes.

Do not activate this skill when:

- A single deterministic script is enough.
- No model-routing decision is required.
- The task is pure documentation with no execution loop or escalation policy.

## Operating Rules

1. Start with executor-first routing.
2. Reserve advisor budget before the first advisor call.
3. Sanitize and compact context before escalation.
4. Use a weighted decision score, not a single threshold.
5. Require a final review only if budget reserve is still intact.
6. Fall back cleanly if a provider is unavailable.
7. Emit a deterministic result object with cost, decisions, and review trail.

## Workflow

1. Load `config/default.yaml`, `config/roles.yaml`, and `config/strategies.yaml`.
2. Accept user-provided candidate models from OpenClaw-configured models and optional external API-key models.
3. Validate that exactly 2 models were provided.
4. Detect whether each model already exists in OpenClaw configuration.
5. Reuse OpenClaw-configured models directly; require an API key for any model not already configured.
6. Score model strength and cost, then assign advisor and executor automatically unless an explicit pin is provided.
7. Classify the task: complexity, risk, uncertainty, and expected iteration count.
8. Select strategy: `balanced`, `cost_saver`, or `quality_first`.
9. Run executor passes while recording progress, failures, spend, and command history into `out/*.md`.
10. On exceptions, retry remediation up to 5 rounds: executor first for 3 attempts, then advisor for 2 attempts.
11. Ask the decision engine whether advisor escalation is justified.
12. If escalation is allowed, build a redacted advisor brief from current task state.
13. Apply returned guidance to the next executor pass.
14. Finish with optional quality review if reserve budget remains.

## Output Contract

Return JSON with the following shape:

```json
{
  "taskId": "string",
  "strategy": "balanced",
  "status": "completed",
  "roleAssignments": {
    "executor": "gpt-4o-mini",
    "advisor": "claude-opus"
  },
  "advisorCalls": 2,
  "cost": {
    "executorUsd": 0.42,
    "advisorUsd": 0.18,
    "totalUsd": 0.60,
    "budgetRemainingUsd": 4.40
  },
  "decisionTrail": [],
  "artifacts": [],
  "warnings": [],
  "logFile": "out/20260410T101500-example-task.md"
}
```

## Notes

- Provider-specific beta headers belong in provider adapters, not the top-level skill contract.
- Model names are aliases in config and can be pinned later without changing orchestration logic.
- Execution history is persisted in Markdown under `out/` in chronological order.
- Recovery policy is fixed at 5 attempts total: 3 executor attempts, then 2 advisor attempts, then a runtime exception with stack trace.
- This skill scaffolds orchestration behavior; API wiring is intentionally isolated behind `ProviderClient`.
````

## File: README.md
upstream: https://github.com/sapsapshen/advisor-claw-skill/blob/HEAD/README.md

````text
# Advisor Claw Skill

Status: `local validation: passed` | `smoke test: ok` | `license: MIT` | `runtime: Node.js CommonJS` | `config: OpenClaw JSON5 official` | `docs: English + 中文`

Professional OpenClaw skill scaffold for a budget-aware advisor/executor workflow.

## Overview

Mission: create a research report about ai in finance during 2025-2026.

## 总览

任务：生成一份2025-2026年份有关ai在金融领域的调查报告。

<img width="1800" height="614" alt="73f666fd-0c24-47c8-9220-30d5f3b48f62" src="https://github.com/user-attachments/assets/e68648a7-9caf-4e0f-8070-f70dac12393a" />

## Navigation

### English

- [Overview](#overview)
- [What Is Actually Implemented](#what-is-actually-implemented)
- [Key Behaviors](#key-behaviors)
- [Architecture](#architecture)
- [Runtime Flow](#runtime-flow)
- [Directory Layout](#directory-layout)
- [OpenClaw Configuration Sources](#openclaw-configuration-sources)
- [Validation](#validation)
- [Notes And Precautions](#notes-and-precautions)
- [Current Scope](#current-scope)
- [How to use](#openclaw)
- [License](#license)

### 中文

- [中文部分](#中文)
- [概述](#概述)
- [已真实实现的能力](#已真实实现的能力)
- [关键行为说明](#关键行为说明)
- [架构图](#架构图)
- [运行流程简图](#运行流程简图)
- [目录结构](#目录结构)
- [OpenClaw 配置来源](#openclaw-配置来源)
- [验证方式](#验证方式)
- [使用注意事项](#使用注意事项)
- [当前范围](#当前范围)
- [如何使用](#openclaw)
- [许可证](#许可证)

---

## English

### Overview

Advisor Claw Skill is a production-oriented OpenClaw scaffold that implements a two-role orchestration pattern:

- a lower-cost executor handles the main task loop
- a stronger advisor is invoked only when task complexity, uncertainty, execution pressure, or stagnation justify the extra cost

This repository is not a mock design note anymore. It reflects the result of multiple rounds of review, correction, runtime hardening, and smoke-test validation.

### What Is Actually Implemented

The current implementation includes real, validated behavior instead of placeholder documentation:

- strict two-model workflow: the skill requires exactly 2 candidate models
- automatic role assignment: the stronger model becomes advisor, the better price/performance model becomes executor
- OpenClaw config discovery from official config surfaces
- official JSON5 config parsing for `~/.openclaw/openclaw.json`
- optional project-level merge with `openclaw.config.json`
- `$include` support within the config boundary
- configured-model reuse when a model or provider already exists in OpenClaw config
- external model support when the user explicitly provides an API key
- bounded recovery ladder: executor 3 attempts, advisor 2 attempts, then structured failure
- markdown execution logs written to `out/`
- end-of-run quality vs resource comparison in the markdown log footer
- executable smoke test covering orchestration, config loading, recovery, and logging

### Key Behaviors

#### Model Selection Rules

- Exactly 2 candidate models must be provided.
- If the candidate already exists in OpenClaw config, the skill reuses it.
- If the candidate is not configured in OpenClaw, an API key is required.
- If neither condition is met, the run fails early with a configuration error.

#### Execution Rules

- The advisor can be called at initial planning, during execution, and for final quality review.
- Advisor escalation is controlled by a weighted decision engine instead of a single threshold.
- The cost tracker records token and USD usage by role.
- The execution logger persists timeline events and a final summary.

#### Failure Rules

- Executor retries up to 3 times.
- Advisor repair attempts up to 2 more times.
- If recovery still fails, the orchestrator throws a structured `AdvisorRuntimeError` with cause and stack trace.

### Architecture

```mermaid
flowchart TD
    A[Task Input] --> B[AdvisorOrchestrator]
    B --> C[ModelRegistry]
    C --> C1[Advisor Role]
    C --> C2[Executor Role]
    B --> D[DecisionEngine]
    B --> E[ContextManager]
    B --> F[CostTracker]
    B --> G[ExecutionLogger]
    B --> H[ProviderClient]
    H --> C2
    D --> B
    E --> B
    F --> B
    G --> I[out/*.md]
```

### Runtime Flow

```mermaid
flowchart LR
    A[Load OpenClaw Config] --> B[Validate Exactly 2 Candidate Models]
    B --> C[Auto Assign Advisor / Executor]
    C --> D[Optional Initial Advisor Review]
    D --> E[Executor Pass Loop]
    E --> F{Need Advisor?}
    F -- No --> E
    F -- Yes --> G[Advisor Guidance]
    G --> E
    E --> H[Optional Final QA Review]
    H --> I[Write Markdown Log]
    I --> J[Append Quality vs Token/USD Summary]
```

### Directory Layout

```text
advisor-manager-skill/
├── SKILL.md
├── README.md
├── LICENSE
├── package.json
├── package-lock.json
├── config/
│   ├── default.yaml
│   ├── roles.yaml
│   ├── strategies.yaml
│   └── model_catalog.example.yaml
├── references/
│   ├── conversation-setup.md
│   └── design-review.md
├── scripts/
│   ├── advisor_orchestrator.js
│   ├── context_manager.js
│   ├── cost_tracker.js
│   ├── decision_engine.js
│   ├── execution_logger.js
│   ├── index.js
│   ├── model_configuration_error.js
│   ├── model_registry.js
│   ├── openclaw_config_loader.js
│   ├── provider_client.js
│   ├── runtime_error.js
│   └── smoke_test.js
└── templates/
```

### OpenClaw Configuration Sources

The runtime currently targets the official OpenClaw config layout:

- `OPENCLAW_CONFIG_PATH`
- `~/.openclaw/openclaw.json`
- project-level `openclaw.config.json`

The loader understands these official structures:

- `models.providers`
- `models.providers.*.models[]`
- `agents.defaults.models`
- `agents.defaults.model`
- `agents.list[].model`
- JSON5 comments and trailing commas
- `$include` expansion inside the config root

### Validation

Install dependencies:

```powershell
npm install
```

Run the smoke test:

```powershell
node .\scripts\smoke_test.js
```

Run syntax checks:

```powershell
node --check .\scripts\openclaw_config_loader.js
node --check .\scripts\execution_logger.js
node --check .\scripts\cost_tracker.js
node --check .\scripts\advisor_orchestrator.js
node --check .\scripts\smoke_test.js
```

### Notes And Precautions

Please read these before using the skill:

1. This repository is a hardened scaffold, not a full provider-integrated production service.
2. The skill assumes exactly 2 candidate models. Zero, one, or more than two is a hard configuration error.
3. OpenClaw-configured providers are reused only when discovery succeeds from official config structures.
4. Unconfigured external models must provide API-key metadata explicitly.
5. The generated markdown logs may contain task content, warnings, and stack traces. Do not treat `out/` as automatically sanitized public output.
6. The quality score in the log footer is an orchestration-side heuristic for runtime assessment, not a universal benchmark.
7. `$include` resolution is intentionally restricted to the config root boundary.
8. The repository currently keeps `package.json` as `private: true`; MIT licensing here expresses source usage terms, not package publication intent.

### Current Scope

Included now:

- orchestration logic
- model validation and role assignment
- official-style OpenClaw config loading
- bounded recovery
- markdown execution logging
- cost and token accounting
- bilingual documentation

Intentionally left open:

- real provider SDK integration
- persistent storage backend
- deployment packaging
- live OpenClaw gateway automation hooks

### How to use

Basically, just tell your ai platform(openclaw) to use the skill.

### License

This project is licensed under the MIT License. See `LICENSE` for details.

---

## 中文

### 概述

Advisor Claw Skill 是一个面向 OpenClaw 的生产导向型技能脚手架，实现了双角色协同模式：

- 低成本执行模型负责主要任务循环
- 只有在复杂度、不确定性、执行压力或停滞程度值得额外成本时，才调用更强的顾问模型

这个仓库现在不再只是设计草案，而是经过多轮复盘、纠偏、运行时加固和 smoke test 验证后的实际结果。

### 已真实实现的能力

当前实现的是可运行、已验证的功能，而不是占位描述：

- 严格双模型约束：技能要求且只接受 2 个候选模型
- 自动分角：更强的模型担任 advisor，更优性价比模型担任 executor
- 按 OpenClaw 官方配置结构进行模型发现
- 支持解析 `~/.openclaw/openclaw.json` 的官方 JSON5 配置
- 支持与项目级 `openclaw.config.json` 合并
- 支持配置根目录内的 `$include`
- 当模型或 provider 
````
