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 + 13 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, except when no-api-path is a constraint on another matched goal. For fallback, state that no persona matched and ask the user to rephrase; never present the beginner fallback as an exact intent match. unavailable means the matched goal is blocked; retain the original persona in the explanation.
Goal availability — read goal_match.workflow, runnability, and missing_requirements before describing a recommendation. eligible means metadata and specified constraints permit that workflow; it does not confirm that data or input files are ready. If alternative_workflow is present, label it by relationship: different_goal is a different-goal on-ramp; limited_alternative is a narrower offline path for the same holdings.
Secondary workflows — if any, how they relate (e.g. "run the regime check first, then this when it allows risk"). If dropped_secondary_workflows is non-empty, say which follow-on workflows were omitted under no-API mode and why; they never make the goal blocked.
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 → no usable path for the requested goal. (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 — honest_gap: true means no usable path for this goal. If goal_match.runnability is unshipped, no dedicated workflow exists and suggested_skills may help. If it is blocked, a matching workflow exists but is unavailable: explain each missing requirement. A CSV portfolio source or saved positions file selects portfolio-holdings-review, a limited offline allocation/P&L path. Relay its note: the user must supply the actual file and source --as-of; Navigator does not read or validate holdings files. Eligibility does not establish ownership, completeness, freshness or suitability for trading. Full account risk, brokerage review and reconciliation remain outside this limited path. Any CSV mention is read as the source unless it is clearly an output (export/save/send; CSVに出力) with no input wording. CSV output requests retain the full brokerage route. If loaded metadata lacks the CSV workflow, report the unsupported-capability gap instead of claiming it is runnable.
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.

Step 4 — Explain the setup path

Read references/setup_paths.md and walk the user through installing setup_bundle — the recommender's deterministic install union over the primary skillset and every secondary workflow (so nothing is dropped for a multi-workflow recommendation). Enumerate setup_bundle.required → recommended → optional, cite setup_bundle.sources to explain why each skill is needed, and name skillset.manifest.related_workflows for how the bundle is run. Narrate skillset.manifest (when present) as "what the recommended skillset is". On an honest gap install suggested_skills. Do this for whichever environment the user is in (Claude Web App .skill upload, or Claude Code folder copy); call out any paid API keys those skills need.

Step 5 — Point to the learning loop

Close by pointing the user at trader-memory-core and the trade-memory-loop / monthly-performance-review workflows so every recommended path feeds the Plan → Trade → Record → Review → Improve loop.

Output Format

The JSON the recommender emits (stable, idempotent, sort_keys):

Field	Meaning
`primary_workflow`	Recommended workflow object, or `null` on an honest gap
`secondary_workflows`	Supporting workflows (ordered, time-budget filtered)
`skillset`	`{id, source: skills-index.category, manifest_status, manifest}`. `manifest_status` is `active` when `skillsets/<id>.yaml` ships, else `deferred`. `manifest` is the 5-key view `{display_name, required_skills, recommended_skills, optional_skills, related_workflows}` when active, else `null`. Describes the primary skillset only — not the install list
`setup_bundle`	`{required, recommended, optional, sources}` — the actionable install union over the primary skillset and every secondary workflow (deterministic, tier-deduped). This is what to install. All-empty on an honest gap (use `suggested_skills`)
`suggested_skills`	Skills to use when no workflow shipped (honest gap); else `[]`
`operational_roles`	Skill id → `{type, rationale?}` for every setup-bundle skill, or every `suggested_skills` item on an honest gap
`no_api`	Request-side: was no-API constraint mode active (flag or persona)
`no_api_path`	Path-side: does the whole recommendation (primary + every secondary) work without paid API keys? `true`/`false`; `null` on an honest gap. This is the DoD's API-vs-no-API separation — narrate it explicitly
`honest_gap`	`true` when no usable workflow can serve the matched goal (`unshipped` or `blocked`)
`goal_match`	Original `{persona, workflow, runnability, missing_requirements}`; `eligible` only means metadata/constraint eligibility
`alternative_workflow`	Separate `{workflow, relationship: different_goal or limited_alternative, no_api_path, explanation}` or `null`; never substitutes for the goal
`dropped_secondary_workflows`	`[{id, reason}]` — secondary workflows removed because they need a paid API under `--no-api`; `[]` otherwise. Not a blocker: narrate it so the user knows a follow-on step was omitted
`note`	Plain-language explanation for gaps / unmapped input
`rationale`	Ordered list of why-this-was-recommended strings
`routing_diagnostics`	`{status, selected_persona, candidate_personas, explanation}`. `status` is `exact`, `ambiguous`, `fallback`, or `unavailable`; candidates are all pre-constraint persona matches in deterministic order
`setup_path_ref`	Pointer to the setup-path reference

Resources

scripts/recommend.py — the deterministic recommender (single source of truth for routing).
scripts/build_snapshot.py — regenerates assets/metadata_snapshot.json from the SSoT; --check guards drift (pre-commit + CI).
scripts/intent_benchmark.py — validates the fail-closed bilingual routing corpus, persona shadowing contracts, and metamorphic invariants.
references/intent_routing.md — the persona table, the 10-question contract, the --no-api credential rule, and scoring tie-breaks.
references/setup_paths.md — Claude Web App vs Claude Code setup steps.
assets/metadata_snapshot.json — generated SSoT digest for the Web App fallback. Never edit by hand; run build_snapshot.py.
assets/intent_benchmark_v1.json — 211 explicitly labeled EN/JA routing cases with 1.0 precision/recall and per-persona/workflow coverage gates.