How to use the Multi-Factor Stock Ranking agent skill

What is an agent skill and what does this one do?

An agent skill is a folder of instructions and optional scripts that an AI agent can load when a task matches it. This skill, named multi-factor, covers multi-factor cross-sectional stock ranking. On any given date it computes several factor values for each stock in a group, standardizes them, sums them into a composite score, and marks the top N stocks for a long portfolio.

The skill follows four steps: calculate factors for each stock, apply Z-score normalization across the cross-section (subtract the mean, divide by the standard deviation), sum the factors with equal weights or custom weights, then rank and select the TopN names with weight 1/N each. Its built-in factors are momentum, reversal, volatility and volume_ratio. Momentum and volume_ratio are scored higher-is-better, while volatility and reversal are scored lower-is-better, and the directions are aligned before standardization.

• Default parameters: momentum_window 20, vol_window 20, top_n 3, rebalance_freq 20 trading days.
• If extra fields such as PE, PB and ROE are supplied (China A-shares), value and quality factors pe_factor, pb_factor and roe_factor can be added.
• The newer Zoo engine can compose pre-built factors from the Alpha Zoo library and supports long-only, short-only or long-short signals.

How do you install the multi-factor skill?

Download the ZIP for the skill from this page and unzip it. For a personal setup, place the unzipped folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder. Alternatively, in the Claude apps you can upload the skill under Settings → Capabilities → Skills.

The skill package contains three files: SKILL.md (the instructions the agent reads), example_signal_engine.py (the legacy per-symbol engine) and zoo_signal_engine.py (the newer panel-based engine). Install the Python dependencies the skill names before running any code.

What do you need before you run it?

You need Python with pandas and numpy, plus price or volume data for many instruments. The method needs at least 3 stocks on each date, because Z-scores are meaningless with fewer names. The basic factors work from the price and volume data you provide.

The Zoo engine needs more: the Vibe-Trading Registry and Alpha Zoo modules (src.factors.registry) and a panel of price data as a dict of DataFrames, such as close and volume. Value and quality factors also need optional extra fields for China A-shares (PE, PB, ROE).

• Python, pandas, numpy
• For the Zoo engine: Vibe-Trading Registry and Alpha Zoo modules (src.factors.registry) and a panel of price data
• Optional PE, PB and ROE fields for China A-shares

How do you trigger the skill with natural requests?

You do not need special syntax. Describe the portfolio task in plain language and mention that it spans several stocks, so the agent picks the cross-sectional ranking method. Naming factors such as momentum or volatility, or asking for a TopN portfolio, makes the match more likely.

If you want to compose specific alphas from the Alpha Zoo, name the factor IDs or ask for the Zoo engine. The skill's documentation points the agent to the zoo_signal_engine.py file for new work and to example_signal_engine.py only for legacy per-symbol workflows.

• Build a top 10 long-only portfolio from my 50-stock price panel using momentum and volatility.
• Rank these stocks each date by volume_ratio and reversal, hold the top 5 equal-weight, and rebalance every 20 days.
• Using the Alpha Zoo, combine alpha101_001 and alpha101_012 into a long-short signal with 10 longs and 10 shorts.

What does the Zoo engine look like in code?

The Zoo engine works on wide panels, where the input is a dict of DataFrames in the same shape the registry uses. It redistributes weights if an alpha fails or is skipped, and it supports long-only (top_n), short-only (bottom_n) and long-short (top_n plus bottom_n) modes. It also exposes a generate(data_map) method so it can plug into existing run_backtest pipelines. The skill notes that you can browse candidate alphas with registry.list(theme=...), which is covered in the alpha-zoo skill.

What mistakes should you avoid?

The skill lists several pitfalls. Keep the previous signal unchanged between rebalance dates instead of reranking every day. Align factor directions before standardizing, because momentum and volatility point in opposite directions. Normalize portfolio weights so each TopN stock gets 1/N and every other stock gets 0.

Use the legacy example_signal_engine.py only for existing per-symbol workflows that compute factors from raw OHLCV. For new code the skill recommends zoo_signal_engine.py, which adds registry-level NaN and inf guardrails and per-alpha skip isolation.

• Never rerank between rebalance dates.
• Check that each date has at least 3 stocks.
• Confirm factor directions are aligned before standardizing.
• Check that TopN weights sum to 1 and all others are 0.

What safety points should you know?

The skill runs scripts but does not use the network, according to its listing. The code does not place orders. Its output, however, is meant to feed trading decisions, so bad data or logic can cause real losses. Treat rankings as research output to review, not as instructions to trade.

Backtested results can mislead. A ranking that looked strong on historical data may not hold up in live markets, and the skill only computes rankings from the data you supply. It is not investment advice and does not guarantee returns.

• Runs scripts: yes. Uses network: no.
• Review data quality and logic before acting on output.
• Do not treat backtest results as a forecast.