How to use the factor-research agent skill (install guide)

What an agent skill is and what this one does

An agent skill is a folder of instructions and optional scripts that an AI agent loads when a task matches it. This skill is named factor-research and its main instructions live in SKILL.md.

Once installed, the agent follows a fixed workflow: compute factor values for each instrument on each date, compute forward returns, call a factor_analysis tool, and interpret the output using IC/IR statistics and quantile group backtests. It can also help combine several validated factors into one composite score.

• Single-factor validity testing (momentum, value, quality, volatility and similar)
• Choosing weights for a multi-factor combination
• Checking factor decay across different holding periods
• Comparing factor behaviour across industries and markets

Install the factor-research skill

Download the ZIP from the skill page on this site. Unzip it into one of two locations: your personal skills folder at ~/.claude/skills/, or a project-level .claude/skills/ folder inside the project you are working in. The result should be a factor-research folder containing SKILL.md.

You can also upload the ZIP in the Claude apps through Settings, then Capabilities, then Skills.

• Personal install: ~/.claude/skills/factor-research/
• Project install: .claude/skills/factor-research/ inside your project
• Apps install: Settings → Capabilities → Skills, then upload the ZIP

Check what you need before running it

The skill itself is instructions, but the work depends on three things outside it. You need a Python environment that includes the Vibe-Trading quantlib modules (src.quantlib.combination and src.quantlib.neutralization) for the optional helpers. You need a factor_analysis tool supplied by the surrounding Vibe-Trading agent framework. And you need factor and return CSV files, prepared by you or by the agent.

The skill runs scripts and does not use the network, according to its listing.

• Python environment with the Vibe-Trading quantlib modules (for optional helpers)
• A factor_analysis tool from the Vibe-Trading agent framework
• Factor CSV and return CSV data, with rows as dates and columns as instrument codes

Prepare aligned factor and return data

The factor CSV and return CSV must align exactly: same date rows and same instrument columns. Returns must be forward returns, earned after the date on which the factor was observed, to avoid look-ahead bias.

The factor_analysis tool takes three required inputs, a factor CSV path, a return CSV path and an output directory, plus an optional n_groups setting that defaults to 5. It writes ic_series.csv, ic_summary.json and group_equity.csv to the output directory.

• factor_csv: path to the factor-value CSV (required)
• return_csv: path to the return CSV (required)
• output_dir: where results are written (required)
• n_groups: number of quantile groups (optional, default 5)

How to read IC, IR and quantile backtest results

The skill sets rough thresholds. An IC mean above 0.03 suggests basic predictive power, and above 0.05 suggests strong power. An IC mean above 0.10 is unusually high and should prompt a check for look-ahead bias. An IR (IC mean divided by IC standard deviation) above 0.5 suggests a stable factor, and above 1.0 is described as very rare. A share of positive IC values above 55% suggests a stable direction, while below 50% suggests an unstable factor.

For the quantile backtest, look for monotonic group equity from Group_1 to Group_N, a large long_short_spread between the top and bottom groups, and smooth equity curves. A flat set of curves means the factor is ineffective. A persistently falling group may mean the factor works in reverse. Negative IC can still be useful, so judge by absolute value and reverse the signal direction when you use it.

• IC mean > 0.03: basic predictive power
• IC mean > 0.05: strong predictive power
• IC mean > 0.10: check for look-ahead bias
• IR > 0.5: stably effective
• Share of IC > 0 above 55%: stable direction

Combine validated factors into one score

Factors that pass their own validity tests can be combined. The skill describes equal-weight combination (standardise each factor and sum), IC-based weighting (weights proportional to absolute IC mean), and orthogonalised combination (Schmidt-style residualisation, useful when factors are highly correlated).

The optional combination module performs the equal and IC variants in one call and returns the weights it used. It estimates weights only from rows strictly before the row they apply to. The skill notes that other methods can be computed by hand and passed in as explicit weights.