How to use the Alpha Zoo Explorer agent skill (alpha-zoo)

What is an agent skill, and what does alpha-zoo make the agent do?

An agent skill is a folder containing a SKILL.md file that gives an AI agent instructions for one kind of task. When a request matches the skill's description, the agent follows those instructions and uses the tools the skill names.

The alpha-zoo skill covers the prebuilt cross-sectional factor libraries: Kakushadze 101, GTJA 191, Qlib 158, and Fama-French / Carhart. It lets the agent list alphas by theme, look up the metadata of one named alpha, check whether the registry loaded correctly, and benchmark a whole zoo on a universe such as CSI 300, S&P 500 or BTC-USDT over a chosen period.

• Browse: list alphas, optionally filtered by zoo, theme or universe.
• Inspect: get metadata for a single alpha by its ID.
• Health check: report how many zoo modules loaded and any errors.
• Bench: run IC and IR statistics on one alpha or a whole zoo, producing an HTML report.
• Route: send user-supplied factor files to the separate factor_analysis tool.

Install the alpha-zoo skill

Download the skill ZIP from the directory page. You can install it in one of two ways.

For Claude Code, unzip the file into ~/.claude/skills/ to make it available for all your projects, or into a project's .claude/skills/ folder to limit it to that project.

In the Claude apps, upload the ZIP under Settings → Capabilities → Skills.

• Personal install: unzip into ~/.claude/skills/.
• Project install: unzip into the project's .claude/skills/ folder.
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP.

What you need before the skill works

The skill does not contain market data or the analysis engine on its own. It relies on the Vibe-Trading agent environment, which must provide the alpha_zoo, alpha_bench and factor_analysis tools.

You also need market data for the universe you choose. The source notes that data loaders are not yet wired for every market, so a universe that is recognised may still fail to run.

• The Vibe-Trading agent environment providing alpha_zoo, alpha_bench and factor_analysis.
• Market data for the chosen universe.
• The source does not list other software requirements, so check the environment's own documentation for setup.

How to trigger the skill with natural requests

The agent loads the skill when your request matches its description. Plain questions work well. The skill's own examples use wording such as 'which alphas exist', asking for metadata on a named alpha, or asking to run IC/IR on a whole zoo over a universe.

Mention the zoo name, theme, alpha ID, universe and period when you know them. The more specific the request, the more directly the agent maps it to a tool.

• "List all momentum alphas." The agent calls alpha_zoo to list alphas filtered by theme.
• "Show me gtja191_alpha_001." The agent calls alpha_zoo to get that alpha's metadata.
• "Bench all of GTJA 191 on CSI 300 from 2020 to 2024." The agent calls alpha_bench with that zoo, universe and period.
• "Is the registry healthy?" The agent calls alpha_zoo health to show loaded and failed modules.
• Uploading your own factor CSV and asking to evaluate it routes to factor_analysis instead.

Understand the zoos and their filters

The skill ships four zoos. Counts are nominal, so run a health check to see how many alphas are currently loaded.

Filters must match the alpha's declared metadata exactly. For example, use equity_cn rather than cn or china.

• kakushadze101: formulaic alphas from Kakushadze's 2015 paper, a mix of momentum, reversal, volume and microstructure (about 101).
• gtja191: Guotai Junan 191 alphas, focused on A-share cross-sectional factors (about 191).
• qlib158: Microsoft Qlib's 158 alpha factors, designed for ML pipelines (about 158).
• classical: Fama-French 3/5-factor and Carhart momentum (fewer than 10).

Read the benchmark output and its limits

A benchmark run reports aggregate statistics: mean, standard deviation, IR and positive ratio. The HTML report shows the top alphas by IR along with their formulas. It does not expose the underlying per-stock, per-date values, so you cannot download the raw panel through this skill.

Each run writes a single HTML file to ~/.vibe-trading/reports/ by default. The skill's guidance is to refer to that location by its shorthand rather than an absolute path.

Do not pass both alpha_id and zoo to alpha_bench. They are mutually exclusive, so choose one.

• Output: aggregate IC statistics and top-N by IR, plus formulas.
• Report location: ~/.vibe-trading/reports/.
• If a universe shows 'universe loader for X not yet implemented', that market is not yet supported.
• An empty registry (loaded=0) means zoo modules are not yet populated, not that your setup is broken.

Safety notes: scripts and network

The skill runs scripts, so it executes code in your environment as part of its tools. The skill does not use the network, according to its metadata.

alpha_zoo is read-only. alpha_bench writes one HTML file per run and no other scratch state. Review the Vibe-Trading environment's tool permissions before enabling the skill on sensitive machines.

• Runs scripts: yes.
• Uses network: no.
• alpha_zoo reads only; alpha_bench writes a single HTML report per run.

Tips for getting useful results

Start with a health check and a list call to confirm which alphas are loaded before benchmarking. Use the exact theme and universe strings from the alpha metadata.

Bench one zoo over one universe and period at a time, so results are easy to compare. Use factor_analysis when the factor is your own.

• Run "is the registry healthy" first.
• Copy filter values from alpha metadata exactly.
• Use alpha_bench with one zoo or one alpha_id, not both.
• For your own factor files, use factor_analysis.