Trading Skills Navigator

Trading Skills Navigator

The interactive on-ramp for this repository. It turns a user's goal into a concrete recommendation: which workflow to run, which skillset (skills-index category) it belongs to, the API requirement, and the setup path for Claude Web App or Claude Code.

A new user faces 74 skills + 12 workflows with no router. This skill is that router. It is deterministic — a Python recommender (scripts/recommend.py) consumes the repo metadata; this SKILL.md narrates the result conversationally.

When to Use

• The user expresses a trading/investing goal and asks where to start or which skill/workflow to use ("どれを使えばいい", "where do I start").
• The user asks what works without paid API keys.
• The user wants the no-API vs API path separated, or a beginner path.
• The user describes a persona ("part-time swing trader", "dividend investor", "I want to short", "I want to backtest ideas") and needs routing.

Do not use this skill to execute trades, place orders, or auto-run other skills. It recommends and explains only.

Workflow

Step 1 — Capture the goal and constraints

From the user's message, extract:

• The natural-language goal (verbatim is fine).
• Optional constraints: no-API only? a daily time budget (15m/30m/60m/90m)? experience level (beginner/intermediate/advanced)?

Ask at most one brief clarifying question only if the goal is empty or has no discernible intent. Otherwise proceed — the recommender degrades gracefully.

Step 2 — Run the recommender

python3 skills/trading-skills-navigator/scripts/recommend.py \
  --query "<the user's goal, verbatim>" \
  --format json
  # optional: --no-api  --time-budget 15m|30m|60m|90m|any
  #           --experience beginner|intermediate|advanced

• In Claude Code the script reads the repo-root SSoT (skills-index.yaml + workflows/*.yaml) automatically.
• In the Claude Web App there is no repo root; the script transparently falls back to the bundled assets/metadata_snapshot.json. The recommendation is byte-identical in both environments — no behavior change for the user.

Step 3 — Narrate the result conversationally

Parse the JSON and explain, in the user's language:

• Primary workflow — display_name, cadence, ~estimated_minutes, api_profile. State plainly what it does and when to run it.
• Routing diagnostics — read routing_diagnostics.status. For ambiguous, name every candidate_personas entry and explain that the ordered first match was selected. For fallback, state that no persona matched and ask the user to rephrase; never present the beginner fallback as an exact intent match.
• Secondary workflows — if any, how they relate (e.g. "run the regime check first, then this when it allows risk").
• Skillset — the skillset.id (skills-index category). manifest_status: active means a curated skillsets/<id>.yaml bundle ships for this category (market-regime, core-portfolio, swing-opportunity, trade-memory, strategy-research) — mention it as the install bundle for the recommended workflow. manifest_status: deferred means no manifest yet (e.g. honest-gap categories); the recommendation is workflow-based only.
• No-API vs API — read no_api_path: true → the entire recommended path works without paid API keys (state this plainly); false → tell the user which paid key(s) the path needs; null → honest gap, no path. (no_api is the request flag — whether no-API mode was active — not whether the path is free; always narrate no_api_path.) If a workflow was excluded under --no-api, surface the rationale entry naming the paid integration (e.g. "swing-opportunity-daily needs FMP").
• Honest gap — if honest_gap is true there is no shipped workflow for this intent. Say so directly, then present suggested_skills from the relevant category and relay the note. Never invent a workflow.
• Backtest execution request — relay the note when the research workflow is recommended for a request containing backtest terms. It can evaluate separately measured metrics but does not execute the backtest. Its no_api_path does not describe the separate backtest tool or data.
• Operational roles — narrate the operational_roles entry for every skill in the setup bundle or honest-gap suggestion. Explain standalone rationale when present; keep enum values unchanged.
• Always read the rationale array and explain why this was recommended.