Install guide

June 5, 2026 · View on GitHub

Prerequisites

Different tiers of skills have different runtime dependencies — install only what you need.

Required (read-tier — 12 skills)

Longbridge CLI (Rust binary, runs in-process):

# macOS / Linux — see https://github.com/longportapp/longbridge-terminal
brew install longportapp/tap/longbridge          # macOS Homebrew
# Or download a release binary onto your PATH

Verify with longbridge --version — it should print a version string.

Log in to your Longbridge account (the OAuth token is cached locally and shared with the TUI):
```
longbridge auth login
```
A browser opens for authorisation. Tick the "Trade" permission if you want the account-tier skills (positions / orders / watchlist / watchlist-admin). Quote-only access is sufficient for market-data skills. Use longbridge auth status to confirm you're signed in.

Optional (required for the analysis tier — 6 skills)

Longbridge MCP server (the analysis-tier skills valuation / fundamental / news / peer-comparison / portfolio / catalyst-radar depend entirely on this):

claude mcp add --transport http longbridge https://mcp.longbridge.com

The first MCP tool call triggers an OAuth flow in your browser. portfolio requires the Trade permission; the other four analysis skills only need the Quote permission.

Verify with claude mcp list — longbridge should appear in the output.

Optional (required for 4 skills — Python libraries)

Four skills rely on Python libraries beyond the standard library. Install only what you need:

Skill	Library	Install	Fallback if missing
`longbridge-chanlun`	czsc — 缠论形态识别	`pip install czsc`	Manual fractal detection (lower accuracy)
`longbridge-smc`	smartmoneyconcepts — BOS / FVG / Order Block	`pip install smartmoneyconcepts`	Manual BOS/FVG implementation
`longbridge-quant-stats`	statsmodels + scipy + arch — ADF / GARCH / regression diagnostics	`pip install statsmodels scipy arch`	Basic stats without GARCH/ADF
`longbridge-ml-strategy`	scikit-learn — Random Forest / Gradient Boosting	`pip install scikit-learn` (usually pre-installed)	Degrades to logistic regression
`longbridge-elliott-wave`	pandas + numpy — wave engine `scripts/signal_engine.py`	`pip install pandas numpy` (usually pre-installed)	Skill still runs; script may fail

Install all at once:

pip install czsc smartmoneyconcepts statsmodels scipy arch scikit-learn pandas numpy

Fallback behaviour: if a library is missing, the LLM falls back to a simpler implementation automatically. You will see an install prompt in the response.

All other skills use only pandas and numpy (standard) — no extra install needed.

Four install paths

Path A — `npx` / `bun` (recommended; simplest)

Install all skills:

# Global install (lands in ~/.claude/skills/, reachable from any project)
npx skills add longbridge/skills -g
bunx skills add longbridge/skills -g

# Project install (lands in <cwd>/.claude/skills/, scoped to this project only)
npx skills add longbridge/skills

Install just a few:

npx skills add longbridge/skills -g --skill longbridge-quote
npx skills add longbridge/skills -g --skill longbridge-portfolio --skill longbridge-news

⚠️ Pick scope intentionally — npx skills defaults to project scope. Without -g, the skills go into the current working directory's .claude/skills/, not the user-wide ~/.claude/skills/. This trips users up later: if you run npx skills remove from a different directory, it can't find skills installed under another project. Recommended: use -g for global install unless you specifically want project scope.

npx skills / bunx skills is a community installer that works for any Agent-Skills-compatible GitHub repo. See agentskills.io for the spec.

Path B — Claude Code plugin marketplace (carries marketplace metadata)

B1. Remote repo:

/plugin marketplace add longbridge/skills
/plugin install longbridge@longbridge-skills

B2. Local path (during development / testing):

/plugin marketplace add <path-to-the-cloned-repo>
/plugin install longbridge@longbridge-skills

longbridge is the plugin name (matches plugins[0].name in .claude-plugin/marketplace.json); longbridge-skills is the marketplace name (matches the top-level name field).

B3. Verify:

/plugin list

You should see longbridge@longbridge-skills enabled. Open a new Claude Code session and ask "NVDA 现在多少钱" to check that the skill triggers.

Path C — Symlink individual skills to `~/.claude/skills/` (cherry-pick; clone first)

Useful when you want only a few skills out of the 127. Clone the repo first, then create symlinks from your local checkout into ~/.claude/skills/.

# Clone the repo locally (anywhere is fine)
git clone https://github.com/longbridge/skills.git
cd skills
mkdir -p ~/.claude/skills

# Single skill
ln -s "$PWD/skills/longbridge-quote" ~/.claude/skills/longbridge-quote

# Or another individual skill
ln -s "$PWD/skills/longbridge-kline"  ~/.claude/skills/longbridge-kline

Batch-symlink all skills:

for d in "$PWD"/skills/*; do
  ln -sfn "$d" "$HOME/.claude/skills/$(basename "$d")"
done
ls -la ~/.claude/skills/ | grep longbridge

Why symlink and not cp? The repo itself is the live source — edits to a SKILL.md take effect immediately, with no redeploy. For production distribution, swap ln -s for cp -R.

⚠️ Special case: the mutating skill

longbridge-watchlist-admin modifies the user's watchlist state. The batch script above will install it; the SKILL.md enforces a dry-run + confirm protocol, so it's safe by default. If you'd rather audit it before enabling, install all others first and skip this one:

for d in "$PWD"/skills/*; do
  slug=$(basename "$d")
  [[ "$slug" == "longbridge-watchlist-admin" ]] && continue
  ln -sfn "$d" "$HOME/.claude/skills/$slug"
done

Run a separate ln -s for longbridge-watchlist-admin once you're ready.

Path D — Other agent products

Skills are pure Markdown + Python and portable to any Agent-Skills-compatible product. Only the install directory differs:

Agent product	Default skill directory
Claude Code	`~/.claude/skills/`
Gemini CLI	`~/.gemini/skills/`
OpenCode	`~/.opencode/skills/`
OpenAI Codex	see vendor docs

Example (Gemini CLI), assuming the repo is cloned locally:

mkdir -p ~/.gemini/skills
for d in "$PWD"/skills/*; do
  ln -sfn "$d" "$HOME/.gemini/skills/$(basename "$d")"
done

Different products implement different parts of the spec — compatibility and allowed-tools are experimental. Every field used in this repo is part of the canonical Agent Skills spec, so cross-product portability should be safe.

Verify

# Quote
longbridge quote NVDA.US --format json

# 5 daily candles
longbridge kline NVDA.US --period day --count 5 --format json

# Watchlist
longbridge watchlist --format json

Each call should return JSON. If you're unsure of an exact flag, run longbridge <subcommand> --help first — every subcommand self-documents.

2. End-to-end through Claude Code

Open a new session and try one prompt per skill family:

Prompt	Expected skill
"NVDA 现在多少钱"	`longbridge-quote`
"特斯拉过去一年走势"	`longbridge-kline`
"700.HK 盘口"	`longbridge-depth`
"我的自选股"	`longbridge-watchlist`
"NVDA 估值贵不贵"	`longbridge-valuation` (analysis tier — needs MCP)

Each reply should include "Source: Longbridge Securities" / "数据来源:长桥证券".

Uninstall

Path A (npx / bun) installs

npx skills remove expects the installed skill name (e.g. longbridge-quote), not the GitHub repo path used at install. It also operates against the same scope as the install:

Global installs (-g) → use npx skills remove -g <name> or npx skills ls -g
Project installs (no flag) → run from the project root where you originally installed

List first, then remove by name:

# Inspect what's installed (add -g for global)
npx skills list
npx skills list -g

# Remove one (add -g if globally installed)
npx skills remove longbridge-quote
npx skills remove -g longbridge-quote

# Remove several at once
npx skills remove -g longbridge longbridge-quote longbridge-kline longbridge-depth ...

# Remove all longbridge-* skills in one shot
npx skills list -g 2>/dev/null | grep -E '^longbridge(-|$)' | xargs -r npx skills remove -g

If npx skills remove ever misbehaves, the cleanest fallback is plain rm — see Path C below.

Path B (plugin marketplace) installs

/plugin uninstall longbridge@longbridge-skills
/plugin marketplace remove longbridge-skills          # optional — drop the marketplace registration

Path C (symlink) installs / fallback when other methods misbehave

rm -rf ~/.claude/skills/longbridge ~/.claude/skills/longbridge-*
ls ~/.claude/skills/                                  # verify

This works regardless of how the skills were originally installed (npx / bun / marketplace / manual symlink) since they all live under ~/.claude/skills/.

Revoke Longbridge CLI authorisation

longbridge auth logout                                # clears the local token

Revoke Longbridge MCP authorisation

claude mcp logout longbridge                          # revoke the OAuth scope
claude mcp remove longbridge                          # remove the MCP registration

FAQ

A skill never triggers after install

Check that the trigger keywords cover what the user typed — see docs/architecture.md §1.1.
Check that the directory name is a valid lowercase ASCII slug (matches ^[a-z0-9]+(-[a-z0-9]+)*$) and equals the name: field in SKILL.md frontmatter.
Claude Code scans ~/.claude/skills/ once per session start. Restart the session if you installed while a session was open.

`auth_expired`

Read-tier market-data skills (quote / kline / depth / …) only need the Quote permission at longbridge auth login.

Account-tier skills (positions / orders / watchlist) require the Trade permission:

longbridge auth logout && longbridge auth login   # re-authorise; tick "Trade" in the browser

MCP behaves the same — claude mcp logout longbridge and re-authorise on the next MCP tool call.

`command not found: longbridge`

The shell cannot locate the longbridge binary. Two fixes:

Recommended: install longbridge-terminal.
Alternative: install MCP (claude mcp add ...) so the LLM falls back automatically.

`Only US market is supported for security-list`

Expected. The longbridge security-list endpoint exposes only the US Overnight category. For non-US listed-stock lookups, ask the LLM about a specific symbol (it will route to longbridge-quote).

Analysis-tier skill says "this skill has no CLI fallback"

Expected. The five analysis-tier skills (valuation / fundamental / news / peer-comparison / portfolio) are prompt-only and MCP-only. Run claude mcp add longbridge ... and authorise — portfolio needs Trade scope, the other four only need Quote scope.

For the design rationale, see docs/architecture.md §2 — CLI vs MCP tool selection.