by-session

BY Session Skill

Session initialization and configuration for BY projects. This skill defines the full session-start sequence (banner, environment check, status display) and the first-run configuration questionnaire that writes .by/config.json. It is not optional — it runs every time a new session opens in a BY project directory.

The session skill is the single source of truth for which compute provider BY will use this session. Every downstream skill (by-design-workflow, by-screening, the design engines) reads .by/config.json written here.

When to Use This Skill

Use this skill when you have:

• ✅ A new session opening in a BY project directory — the SessionStart hook fires this skill automatically
• ✅ No .by/config.json yet — run the first-run questionnaire to capture compute provider, model profile, campaign defaults
• ✅ A request to refresh environment discovery — re-scan local tools, conda envs, GPU, API keys
• ✅ A request to switch compute provider — update compute.default_provider cleanly without overwriting unrelated fields
• ✅ An in-progress campaign to detect and surface (campaigns/*/campaign_log.json with status not complete)
• ✅ Staleness checks — .by/environment.json older than 24h should prompt a refresh

Do NOT use this skill when:

• ❌ You are mid-campaign and just want status → use the status skill (it reads but does not re-questionnaire)
• ❌ You need to deploy compute on RunPod / HPC → use by-deploy-compute (this skill only records the choice of HPC)
• ❌ You are scoring designs or running design engines → use by-scoring, boltzgen, pxdesign, or protenix
• ❌ You want to inspect a specific campaign's state → use by-campaign-manager
• ❌ The user is editing .by/config.json by hand → read it back with validate_config.py, do not re-run the questionnaire

Quick Start

User opens a new terminal in a BY project directory.

Agent (by-session):
  1. Banner    → BY ► Protein Design Agent
  2. Check     → .by/config.json exists?
  3a. NO       → run init_questionnaire.py (or its inline AskUserQuestion equivalent)
                 → writes .by/config.json with local-first defaults
  3b. YES      → read config + environment, no questions asked
  4. Resume    → check campaigns/*/campaign_log.json for in-progress work
  5. Status    → print compute + profile + campaign count
  6. Done      → "Ready" prompt with suggested actions