trading-skills-navigator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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 72 skills + 11 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.

本仓库的交互式入门工具。它可将用户的目标转化为具体推荐：应运行哪个workflow、所属的skillset（技能索引分类）、API要求，以及针对Claude Web App或Claude Code的设置路径。

新用户面对72项技能+11个工作流时，往往缺乏引导工具。本技能就是这样一个引导器。它是确定性的——由一个Python推荐器（

scripts/recommend.py

）读取仓库元数据；本SKILL.md以对话式语言呈现推荐结果。

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.

用户表达交易/投资目标，并询问从何处入手或应使用哪种技能/工作流（例如“どれを使えばいい”、“where do I start”）。
用户询问哪些功能无需付费API密钥即可使用。
用户希望区分无API路径与需API路径，或需要入门路径推荐。
用户描述自身角色（如“兼职波段交易者”、“股息投资者”、“我想做空”、“我想回测交易思路”）并需要引导。

请勿使用本技能执行交易、下单或自动运行其他技能。它仅提供推荐和说明。

Workflow

工作流程

Step 1 — Capture the goal and constraints

步骤1 — 捕捉目标与约束

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.

从用户的消息中提取：

自然语言表述的目标（直接引用原文即可）。
可选约束条件：是否仅使用无API模式？每日时间预算（15分钟/30分钟/60分钟/90分钟）？经验水平（初级/中级/高级）？

仅当目标为空或无明确意图时，最多提出一个简短的澄清问题。否则直接进行下一步——推荐器会自动适配模糊的输入。

Step 2 — Run the recommender

步骤2 — 运行推荐器

bash

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.

bash

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

在Claude Code中，脚本会自动读取仓库根目录下的单一可信数据源（
```
skills-index.yaml
```
+
```
workflows/*.yaml
```
）。
在Claude Web App中没有仓库根目录，脚本会自动回退到内置的
```
assets/metadata_snapshot.json
```
文件。两种环境下的推荐结果完全一致——用户体验无差异。

Step 3 — Narrate the result conversationally

步骤3 — 以对话式语言呈现结果

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.
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) — 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.
Always read the
```
rationale
```
array and explain why this was recommended.

解析JSON结果，并用用户使用的语言进行说明：

主工作流 — 说明其
```
display_name
```
（显示名称）、
```
cadence
```
（执行频率）、
```
~estimated_minutes
```
（预估耗时）和
```
api_profile
```
（API配置）。清晰说明该工作流的功能及运行时机。
辅助工作流 — 若存在，说明它们与主工作流的关系（例如：“先运行市场状态检查工作流，当允许承担风险时再运行此工作流”）。
技能集 — 说明
```
skillset.id
```
（技能集ID，即技能索引分类）。
```
manifest_status: active
```
表示该分类有经过整理的
```
skillsets/<id>.yaml
```
捆绑包（如market-regime、core-portfolio、swing-opportunity、trade-memory）——需提及此捆绑包是推荐工作流的安装包。
```
manifest_status: deferred
```
表示目前尚无清单文件（如实缺分类）；此时仅基于工作流进行推荐。
无API vs 需API — 查看
```
no_api_path
```
字段：
```
true
```
→ 整个推荐路径无需付费API密钥即可使用（直接说明）；
```
false
```
→ 告知用户该路径需要哪些付费密钥；
```
null
```
→ 如实缺，无对应路径。（
```
no_api
```
是请求端标志——表示是否启用无API模式，而非路径是否免费；务必说明
```
no_api_path
```
的结果。）若在
```
--no-api
```
模式下排除了某个工作流，需说明
```
rationale
```
中提及的付费集成（例如：“swing-opportunity-daily需要FMP密钥”）。
如实缺 — 若
```
honest_gap
```
为
```
true
```
，表示目前无可用工作流匹配该需求。直接告知用户，然后展示相关分类下的
```
suggested_skills
```
（建议技能）并传达
```
note
```
（说明）。切勿虚构工作流。
务必读取
```
rationale
```
数组并解释为何推荐该方案。

Step 4 — Explain the setup path

步骤4 — 说明设置路径

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.

读取

references/setup_paths.md

文件，引导用户安装**

setup_bundle

**（推荐器针对主技能集及所有辅助工作流生成的确定性安装合集，确保多工作流推荐时无遗漏）。按

setup_bundle.required

（必需）→

recommended

（推荐）→

optional

（可选）的顺序列出技能，引用

setup_bundle.sources

说明每项技能的必要性，并提及

skillset.manifest.related_workflows

说明该捆绑包的运行方式。若存在

skillset.manifest

，需说明“推荐的技能集是什么”。若为如实缺场景，则安装

suggested_skills

（建议技能）。根据用户所处的环境（Claude Web App上传

.skill

文件，或Claude Code复制文件夹）进行引导；务必指出这些技能所需的付费API密钥（若有）。

Step 5 — Point to the learning loop

步骤5 — 引导至学习循环

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.

最后引导用户关注

trader-memory-core

以及

trade-memory-loop

monthly-performance-review

工作流，确保每条推荐路径都能融入“计划→交易→记录→复盘→改进”的循环。

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 `[]`
`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 workflow exists for the intent
`note`	Plain-language explanation for gaps / unmapped input
`rationale`	Ordered list of why-this-was-recommended strings
`setup_path_ref`	Pointer to the setup-path reference

推荐器输出的JSON（稳定、幂等、已排序

sort_keys

）：

字段	含义
`primary_workflow`	推荐的工作流对象；若为如实缺场景则为 `null`
`secondary_workflows`	辅助工作流（已排序，按时间预算过滤）
`skillset`	`{id, source: skills-index.category, manifest_status, manifest}` 。当 `skillsets/<id>.yaml` 可用时， `manifest_status` 为 `active` ，否则为 `deferred` 。当状态为 `active` 时， `manifest` 包含5个字段： `{display_name, required_skills, recommended_skills, optional_skills, related_workflows}` ，否则为 `null` 。仅描述主技能集——不包含安装列表
`setup_bundle`	`{required, recommended, optional, sources}` — 针对主技能集及所有辅助工作流生成的可执行安装合集（确定性、按层级去重）。这是需要安装的内容。如实缺场景下所有字段为空（此时使用 `suggested_skills` ）
`suggested_skills`	无可用工作流时（如实缺场景）推荐使用的技能；否则为 `[]`
`no_api`	请求端标志：是否启用无API约束模式（通过标志或角色设置）
`no_api_path`	路径端标志：整个推荐路径（主工作流+所有辅助工作流）是否无需付费API密钥即可使用？取值为 `true` / `false` ；如实缺场景下为 `null` 。这是区分需API与无API路径的核心依据——务必明确说明
`honest_gap`	当无匹配需求的工作流时为 `true`
`note`	针对缺漏/未匹配输入的平实说明
`rationale`	按顺序排列的推荐理由字符串列表
`setup_path_ref`	设置路径参考文档的指针

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).

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

```
scripts/recommend.py
```
— 确定性推荐器（路由逻辑的单一可信数据源）。
```
scripts/build_snapshot.py
```
— 从单一可信数据源重新生成
```
assets/metadata_snapshot.json
```
；
```
--check
```
参数用于防止数据偏差（预提交+持续集成）。
```
references/intent_routing.md
```
— 包含角色表、10项问题约定、
```
--no-api
```
凭证规则及评分平局处理方式。
```
references/setup_paths.md
```
— Claude Web App与Claude Code的设置步骤说明。
```
assets/metadata_snapshot.json
```
— 为Web App回退机制生成的单一可信数据源摘要。切勿手动编辑；请运行
```
build_snapshot.py
```
生成。