longbridge__skills/docs/install.md

# Install guide

## Prerequisites

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

### Required (read-tier — 12 skills)

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

   ```bash
   # 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.

2. **Log in to your Longbridge account** (the OAuth token is cached locally and shared with the TUI):

   ```bash
   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):

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

   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`](../skills/longbridge-chanlun) | [czsc](https://github.com/zengbin93/czsc) — 缠论形态识别 | `pip install czsc` | Manual fractal detection (lower accuracy) |
| [`longbridge-smc`](../skills/longbridge-smc) | [smartmoneyconcepts](https://github.com/joshyattridge/smart-money-concepts) — BOS / FVG / Order Block | `pip install smartmoneyconcepts` | Manual BOS/FVG implementation |
| [`longbridge-quant-stats`](../skills/longbridge-quant-stats) | [statsmodels](https://www.statsmodels.org/) + [scipy](https://scipy.org/) + [arch](https://arch.readthedocs.io/) — ADF / GARCH / regression diagnostics | `pip install statsmodels scipy arch` | Basic stats without GARCH/ADF |
| [`longbridge-ml-strategy`](../skills/longbridge-ml-strategy) | [scikit-learn](https://scikit-learn.org/) — Random Forest / Gradient Boosting | `pip install scikit-learn` (usually pre-installed) | Degrades to logistic regression |
| [`longbridge-elliott-wave`](../skills/longbridge-elliott-wave) | [pandas](https://pandas.pydata.org/) + [numpy](https://numpy.org/) — wave engine `scripts/signal_engine.py` | `pip install pandas numpy` (usually pre-installed) | Skill still runs; script may fail |

**Install all at once:**

```bash
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**:

```bash
# 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**:

```bash
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](https://agentskills.io) for the spec.

---

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

**B1. Remote repo:**

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

**B2. Local path (during development / testing):**

```text
/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:**

```text
/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 19. Clone the repo first, then create symlinks from your local checkout into `~/.claude/skills/`.

```bash
# 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**:

```bash
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:

```bash
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:

```bash
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

### 1. Real-account smoke test (only if you've installed the longbridge CLI and run `longbridge auth login`)

```bash
# 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:

```bash
# 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

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

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

```bash
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

```bash
longbridge auth logout                                # clears the local token
```

### Revoke Longbridge MCP authorisation

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

---

## FAQ

### A skill never triggers after install

1. Check that the trigger keywords cover what the user typed — see [`docs/architecture.md` §1.1](./architecture.md).
2. 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.
3. 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**:
  ```bash
  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](https://github.com/longportapp/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](./architecture.md).