WQ Alpha Research Skill
A self-evolving playbook for WorldQuant BRAIN alpha research: field lookup, expression design, backtesting, IS checks, submission, and low-correlation portfolio building in one workflow.
Credential handling shows good hygiene (env vars first, .gitignore protection, sanitization guidance); deductions: scripts can auto-submit alphas (irreversible external effect) with no user-confirmation gate or rollback, plaintext credential.txt is a weak pattern, and the self-evolution mechanism lets AI rewrite SKILL.md without a review boundary. Score 14.
Code snippets are self-consistent with useful failure feedback (429 backoff, 201 != submitted); deductions: missing imports (time) in polling loops, referenced scripts/evolve_skill.py and reference files unverified in provided evidence, unbounded polling with no timeout, and silent exception swallowing that shifts debugging cost to the user. Static evidence supports only a plausible happy path. Score 9.
Clear description, bilingual triggers, well-scoped scenarios; deductions: core function depends entirely on api.worldquantbrain.com with no disclosure of mainland-China reachability, and coverage limited to USA TOP3000 delay=1 without a documented refresh mechanism for other regions. Score 10.
README states CC BY-NC 4.0, clear structure and safety notes; deductions: no versioning or changelog, maintenance responsibility reduced to a WeChat QR code, self-evolution appending risks doc drift, and no license metadata attached to SKILL.md itself. Score 8.
The playbook is complete (decision tree, templates, checklists, diagnostics) with plausible marginal value; deductions: headline claims ('4 days zero human intervention', Gold Medal) are unverifiable marketing, failure statistics lack sourcing, and static review cannot confirm scripts produce directly usable outputs. Score 6.
Field snapshot and rules are partially samplable; deductions: key empirical claims (correlations, pass rates, medal results) lack independent reproduction, no tests or CI covering key paths, and static review cannot exceed the anchor ceiling. Score 4.
- Scripts can auto-submit alphas to WorldQuant BRAIN (irreversible external action); manually confirm every submission before use.
- The plaintext credential.txt pattern is weak; prefer environment variables and verify the file is never git-tracked.
- Core function depends on api.worldquantbrain.com; mainland-China reachability is undisclosed and may require a proxy.
- Promotional claims ('4 days zero human intervention', Gold Medal) and failure statistics have no independent evidence; treat as unverified.
- Referenced scripts/ and references/ files were not verified for existence or correctness in this static review.
- The self-evolution mechanism modifies SKILL.md; always review preview output before --apply.
- Licensed CC BY-NC 4.0 (non-commercial); not suitable for commercial use.
What does this skill do, and when should you use it?
This skill packages the WorldQuant BRAIN alpha-mining loop into a structured SKILL.md playbook covering field selection, FASTEXPR expression design, backtesting, IS failure diagnostics, submission verification, and portfolio construction. It ships with a local snapshot of all 4,367 USA TOP3000 delay=1 data fields, enabling offline search without repeated API calls. The bundled evolve_skill.py script writes new lessons from each BRAIN interaction back into the skill, making it self-evolving. The author claims it reached BRAIN Gold Medal in 4 days with zero human intervention, though this claim cannot be independently verified from the repository.
Reads local JSON/CSV field snapshots in references/ and searches USA TOP3000 fields by keyword or category; provides recommended templates and default parameters (decay, neutralization, truncation) per factor type (fundamental/analyst/technical/sentiment); authenticates against the WorldQuant BRAIN API to run simulations, fetch ACTIVE alphas, and compute daily-return correlations against existing factors; diagnoses common IS check failures (LOW_SHARPE, LOW_FITNESS, HIGH_TURNOVER) with fixes; runs scripts/evolve_skill.py to diff new/changed alphas against a local alpha_db. and generate lesson entries (--apply mode writes back to SKILL.md and alpha_db.).
- An individual WorldQuant BRAIN user who wants a templated, automatable pipeline for mining and submitting alphas
- A researcher repeatedly stuck on LOW_SHARPE or SELF_CORRELATION checks who needs systematic failure diagnostics and experience accumulation
- A new BRAIN user who wants a USA TOP3000 delay=1 field reference plus pass-rate statistics by data category as a starting point
- A user with existing ACTIVE alphas who wants daily-return correlation screening before submission to avoid wasted attempts
- A quant agent user who wants each simulation and submission result distilled into reusable research rules
What are this skill's strengths and limitations?
- Includes a local snapshot of 4,367 USA TOP3000 delay=1 fields, so field lookup works offline and saves API calls
- Templates and default parameters are backed by empirical statistics (e.g., LOW_SHARPE causes 90.7% of failures; fundamentals pass 40% of the time)
- Explicitly insists on daily-return (not cumulative PnL) correlation and explains why cumulative curves distort results
- Self-evolution script has a preview mode that modifies nothing until --apply, and enforces git-ignoring of private data (alpha_db., credential.txt)
- Warns that a 201 response is not a successful submission and requires re-checking ACTIVE status
- Covers only USA TOP3000 delay=1; other regions, universes, or delays require re-fetching fields yourself
- The "4 days to Gold Medal" claim is author-reported and cannot be independently verified from the repo
- No test suite; script quality rests on the author's personal experience and may silently break if the BRAIN API changes
- Requires a real BRAIN username and password (plaintext file or env vars), raising account-security considerations
- Most of SKILL.md is written in Chinese, reducing the experience for English users; license metadata should be verified against the CC BY-NC 4.0 notice in the README
How do you install this skill?
Clone the repository into your agent's skills directory (e.g., a Claude Code skills folder). Install Python dependencies: requests and numpy. Set BRAIN credentials: export WQ_BRAIN_USERNAME / WQ_BRAIN_PASSWORD environment variables, or place a git-ignored credential.txt in the skill directory containing a JSON array of ["username", "password"]. No one-click installer is provided; SKILL.md itself is the entry point.
How do you use this skill?
Read SKILL.md first as the operating manual. Typical flow: search fields using the local snapshot → validate a field with a simple rank(field) simulation → design expressions from the Section 4 templates and backtest → check Sharpe/Fitness/Turnover/correlation → submit via the API and re-verify status == ACTIVE. After runs, execute python scripts/evolve_skill.py to preview lesson entries, then --apply after review. Example trigger prompt: "Design a fundamental alpha on BRAIN based on operating_income/equity and check its daily-return correlation against my ACTIVE alphas."