Cruncher Skill

Guides users through Crunch competition lifecycle: setup, quickstarter discovery, solution development, local testing, and submission.

Prerequisites

• - Python 3.9+ with venv module (included in standard Python)
• INLINECODE1 for package installation

Package Installation

This skill installs Python packages from PyPI into isolated virtual environments:

Package	Source	Purpose
INLINECODE2	PyPI	CrunchDAO competition CLI (setup, test, submit)
INLINECODE3

PyPI | Notebook support (optional) |
| ipykernel | PyPI | Jupyter kernel registration (optional) |
| Competition SDKs (e.g. crunch-synth, birdgame) | PyPI | Competition-specific libraries (varies) |

Agent rules for package installation:

• - Always use a virtual environment — never install into system Python
• Only install known packages listed above or referenced in competition docs (PACKAGES.md)
• Ask the user before installing any package not listed here
• All packages are from PyPI — no custom URLs, no --index-url overrides, no .whl files from unknown sources

Credentials

Submission Token (required for setup & submit)

• - How to get: User logs into CrunchDAO Hub, navigates to the competition's submit page (/competitions/<competition>/submit), and copies their token
• How it's used: Passed once via --token <TOKEN> during INLINECODE11
• Persistence: After setup, the CLI stores the token in the project's .crunch/ config directory. All subsequent commands (crunch test, crunch push, crunch download) authenticate automatically — no need to pass the token again
• If token expires: Run crunch update-token inside the project directory to refresh it

Agent rules for tokens:

• - Always ask the user to provide the token — never assume, guess, or reuse tokens from other projects
• Never write tokens into source files, scripts, notebooks, or any committed file
• Never log or echo tokens in shell output (use --token <TOKEN> placeholder in examples shown to user)
• Tokens are user-specific and project-scoped — each crunch setup call requires the user to supply one

GitHub API (optional, unauthenticated)

• - Used only for browsing quickstarter listings via api.github.com (public repo, no auth needed)
• Rate-limited to 60 requests/hour per IP; sufficient for normal use

Network Access

Operation	Requires network	Endpoint
INLINECODE20	Yes	hub.crunchdao.com
INLINECODE21

Yes | hub.crunchdao.com | | crunch download | Yes | hub.crunchdao.com | | crunch test | No | Local only | | crunch list | Yes | hub.crunchdao.com | | pip install | Yes | pypi.org | | Quickstarter browsing | Yes | api.github.com |

Quick Setup

Each competition needs its own virtual environment (dependencies can conflict).

CODEBLOCK0

For competition-specific packages and full examples, see references/competition-setup.md.

Core Workflow

1. Discover

CODEBLOCK1

2. Explain

Read the quickstarter code (main.py or notebook) and competition's SKILL.md/README.md. Provide walkthrough covering: Goal, Interface, Data flow, Approach, Scoring, Constraints, Limitations, Improvement ideas.

3. Propose Improvements

Analyze current approach, cross-reference competition docs (SKILL.md, LITERATURE.md, PACKAGES.md), generate concrete code suggestions:

• - Model: mixture densities, NGBoost, quantile regression, ensembles
• Features: volatility regimes, cross-asset correlation, seasonality
• Architecture: online learning, Bayesian updating, horizon-specific models

4. Test

CODEBLOCK2

5. Submit

CODEBLOCK3

Phrase Mapping

User says	Action
INLINECODE27	INLINECODE28
INLINECODE29

Fetch from GitHub API | | set up <competition> | Full workspace setup | | download the data | crunch download | | get the <name> quickstarter | crunch quickstarter --name | | explain this quickstarter | Structured code walkthrough | | propose improvements | Analyze and suggest code improvements | | test my solution | crunch test | | compare with baseline | Run both, side-by-side results | | submit my solution | crunch push |

Important Rules

• - Entrypoint must be main.py (default for crunch push/crunch test)
• Model files go in resources/ directory
• Respect competition interface and constraints (time limits, output format)
• Ask before installing new packages

Reference

• - CLI commands: references/cli-reference.md
• Setup examples: references/competition-setup.md