Invest Setup

Invest Setup Skill

Single responsibility: turn an empty openInvest deployment into a working one. Triggers only on the user's first-time setup — run once, then step aside (the invest skill takes over all day-to-day interaction).

When to Use

• User explicitly says "set up invest" / "initialize invest" / "帮我初始化 invest"
• The invest skill's doctor returns status: "needs_setup" (memory / user_profile missing)
• User wants a full reconfiguration (explicitly says "reset" / "重新配置"; requires --force)
• v1 → v2 schema migration (the user's portfolio.md is in the old format)

When NOT to Use

• User is already onboarded (doctor returns status: "ready") → switch to the invest skill
• User wants to view holdings / P&L / run the committee → use the invest skill
• User wants to track a new asset but is already onboarded → the invest skill's POST /api/holdings endpoint
• User wants to commit / push code → that's a git operation, unrelated to setup

If you (the agent) entered this skill by mistake, exit immediately and tell the user to use the invest skill instead.

Two onboarding paths

| Path | Scenario | Flow | |------|------|------| | A. Fresh deployment (default) | User's first time with openInvest; data lives on this machine | "Flow (4 steps)" below | | B. Connect to an existing hub | User already runs openInvest on another machine (a server) and wants this machine to share the same data (multi-device) | "Path B" below, 2 minutes |

Phrasings that trigger Path B: "connect to my hub / 连接我的 hub" / "it's already installed on my server / 我服务器上已经装好了" / "share one portfolio across machines / 多台电脑共用持仓" / "connect to my existing deployment".

Path B: connect to an existing hub (no init)

1. Ask two questions:

• Hub address? (e.g. https://invest.example.com or http://10.0.0.6:8765)
• Does the hub have auth enabled? A token (INVEST_API_TOKEN) or a Cloudflare

Access service token (CF_ACCESS_CLIENT_ID/SECRET)? Skip if not enabled.

1. Write the answers into $INVEST_HOME/.env (only these two or three lines are

needed; no DeepSeek key / Gmail / 5-question flow — those all live on the hub): ``env INVEST_API_BASE=https://invest.example.com INVEST_API_TOKEN=... # optional ``

1. Verify: run run.sh doctor → it should return status: "ready" plus a remote

section (api_base / auth method). If it can't connect, the error JSON's hint tells you whether the problem is the address, the token, or the hub service not running.

1. Done — hand over to the invest skill.

Note: Path B must not run init (init is disabled in remote mode and will error); no memory/ is created on this machine — all data stays on the hub.

Flow (4 steps)

1. Run doctor first to confirm setup is really needed

~/.claude/skills/invest-setup/scripts/run.sh doctor

Returns status: "ready" → exit immediately and tell the user "you're already onboarded — just use the invest skill".

Returns status: "needs_setup" → go to step 2.

2. Ask the user 5 questions (use AskUserQuestion on the Coordinator path, your conversational tool on the Direct path)

| # | Ask | Notes | |---|------|------| | Q1 | What should we call you? | display name; Anonymous if they'd rather not say | | Q2 | Risk tolerance? | Conservative / Balanced / Aggressive | | Q3 | Monthly income / monthly expenses / FX working buffer (CNY)? | three numbers; all can be 0 to skip | | Q4 | What do you currently hold? (free-form description) | natural language, see below | | Q5 | DeepSeek API key & Gmail App Password? | Optional. Not needed on the Coordinator path |

Q4 natural language (key change 2026-05)

Do not ask field by field. Let the user describe their holdings in one sentence:

> "510300 CSI 300 ETF, 3000 shares at 4.2 CNY; 80k in CMB Zhaozhaobao; 50 grams of ICBC gold accumulation at 750 average cost" > "AAPL 100 shares at 150 USD cost, 0.3 BTC, 50k CNY cash" > "Nothing at all, just 10k CNY"

When the backend cmd_init sees a holdings_description field it calls DeepSeek to parse it into the v2 schema. Without a DeepSeek key it falls back to v1 fields (only cashcny / audcash get written into the portfolio) — tell the user about this.

Boundary rules to tell the user (not enforced):

• For A-shares, just say the code (510300) — no .SS suffix needed
• For HK / US stocks, say the ticker (0700.HK or "Tencent")
• For crypto, just say the coin (BTC / ETH)
• Yu'ebao / Zhaozhaobao / money-market funds → the parser routes them into cash, not holdings

3. wealth_context (optional but recommended)

If the user reveals "this account is pocket money" / "I have an emergency reserve" / "family backup" → ask one more question:

> Do you have an emergency fund / family backup outside this portfolio? Roughly how > much? (Family funds cannot be used for investing — they only serve to prevent > the "low cash = high risk" misjudgment.)

Record it into wealth_context:

wealth_context:
  emergency_buffer_cny: 200000  # or whatever number the user gives
  family_backup_available: true
  account_purpose: "pocket-money account"  # the user's own words
  lifestyle_notes: "..."

See docs/wiki/12-verification.md claim 7 (WealthContextOfficer) for details.

4. Assemble the payload + run init

echo '{
  "display_name": "...",
  "risk_tolerance": "Balanced",
  "monthly_income_cny": 30000,
  "monthly_expense_cny": 15000,
  "exchange_buffer_cny": 10000,
  "holdings_description": "",
  "wealth_context": { ... },   # optional
  "deepseek_api_key": "...",   # optional
  "gmail_app_password": "..."  # optional
}' | ~/.claude/skills/invest-setup/scripts/run.sh init --from-stdin

Returns JSON:

{
  "status": "ok",
  "holdings_parse_note": "...",  // natural-language parse result, **show it to the user**
  "memory_root": "/path/...",
  "next_step": "run status via the invest skill to view holdings"
}

5. Confirm + hand over

After it finishes:

1. Render holdings_parse_note to the user (so they can confirm the parse is correct)
2. Run doctor again to confirm status: "ready"
3. Tell the user: "✓ Onboarding complete. Next time you say 'show portfolio' /

'analyze X', the invest skill kicks in automatically. To reconfigure, say 'reset invest'."

Error handling

• DeepSeek parse timeout: report the error to the user and have them re-enter using v1 fields (aud / cny / ndqunits / goldgrams)
• schema validation fail: usually a wrong field type — check the error field in the init response
• user_profile.json already exists: refuse to overwrite; have the user add --force to confirm explicitly

FAQ

Q: I swapped DeepSeek for Qwen / Zhipu and it doesn't work

A: When editing .env, the model name must change too:

LLM_API_KEY=...
LLM_BASE_URL=...
LLM_MODEL=qwen-max         # ← don't forget this

Changing only the API key + base_url while the model stays deepseek-chat → the upstream returns 400 "model not found". Every provider names its models differently — check the provider's own site.

Q: The committee decision replay is blank after a run

A: Check whether the memory/.committee//.md file was generated. If not, something failed during the call — run run.sh doctor and see which item's hint is red.

Q: The code seems older than the demo site

A: Run run.sh update (pulls the latest release from PyPI). openInvest is still iterating quickly.

References

The detailed 5-step flow lives in the original references/onboarding.md (179 lines). This SKILL.md is the condensed agent-trigger guide.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: longsizhuo
• Source: longsizhuo/openInvest
• License: MIT
• Homepage: https://openInvest.involutionhell.com

Install and usage instructions live in the source repository linked above.