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

Total time: ~1 second when config exists; ~30 seconds for first-run questionnaire.

Inputs

Required:

• Working directory — the BY project root (current directory by default).
• User input (first run only) — answers to the 3-round questionnaire (compute provider, model profile, campaign defaults).

Optional (auto-detected):

• .by/config.json — if present, skip questionnaire entirely.
• .by/environment.json — written by /by:setup; used to confirm tools and GPU.
• Environment variables — RUNPOD_API_KEY, TAMARIND_API_KEY, etc. for provider detection.
• campaigns/*/campaign_log.json — used to surface in-progress campaigns.

See references/config-schema.md for the full schema of both JSON files.

Outputs

All outputs land under .by/ in the project root.

The .by/config.json schema is canonical and downstream-critical: every BY skill that selects a compute provider reads this file. See references/config-schema.md.

Clarification Questions

⚠️ CRITICAL: ASK THIS FIRST — Confirm .by/config.json does not already exist before running the questionnaire. Re-running the questionnaire would overwrite the user's saved preferences.

1. Config file presence (ASK THIS FIRST) — Does .by/config.json already exist? If yes, skip the questionnaire and go straight to the session banner. If no, proceed to Q2. (You can check this silently — only ask the user if there's ambiguity, e.g., the file exists but is corrupted.)
2. Compute provider — Where should BY run design computations? Options: local (recommended default — uses local GPU), hpc (RunPod or other HPC target deployed via by-deploy-compute), tamarind (Tamarind Bio cloud), auto (detect best available in priority order). The default is local.
3. Local GPU tool paths (only if provider is local or auto) — Where are BoltzGen, Protenix, and PXDesign installed? Auto-detect from PATH and common locations, or accept a custom path per tool. Validate each path exists.
4. HPC target (only if provider is hpc) — Which HPC target? Default runpod. The actual deployment is handled by by-deploy-compute; this skill only records the choice and the api_key_env variable name.
5. Tamarind API key (only if provider is tamarind) — Is TAMARIND_API_KEY set in .env or the shell environment? If missing, point the user to https://tamarind.bio for a free key before continuing.
6. Model profile — Which AI model profile for sub-agents? balanced (Sonnet, recommended), quality (Opus for research/design agents), budget (Haiku where possible).
7. Default campaign tier — Default designs per campaign? preview (500, fast feasibility checks), standard (5,000, recommended), production (~20,000, thorough coverage).

See references/config-schema.md for the exact field names each answer maps to.

Standard Workflow

🚨 MANDATORY: USE THE TWO PROVIDED SCRIPTS — DO NOT WRITE INLINE PYTHON 🚨

This skill ships two scripts that codify the questionnaire and validation logic:

• scripts/init_questionnaire.py — interactive or --defaults first-run setup; writes .by/config.json.
• scripts/validate_config.py — reads .by/config.json, validates against the documented schema, prints issues.

When a script does not fit (e.g., the user wants to flip a single field), edit the JSON directly and re-run validate_config.py to confirm correctness. Do not invent a new questionnaire flow inline.

Step 1 — Detect first-run vs returning session

test -f .by/config.json && echo "returning" || echo "first-run"

✅ VERIFICATION: Output is exactly returning or first-run.

Step 2a — First-run: run the questionnaire

python3 .claude/skills/by-session/scripts/init_questionnaire.py

Or for a non-interactive default install (CI, automated scaffolding):

python3 .claude/skills/by-session/scripts/init_questionnaire.py --defaults

✅ VERIFICATION: Expect ✓ Wrote .by/config.json with provider=local (or whichever provider the user selected).

The questionnaire collects answers in three rounds (compute, profile, campaign defaults) and writes .by/config.json. The default provider is local and providers_priority is ["local", "hpc", "tamarind"]. If the user picks hpc, the skill records the HPC target (default runpod) and the env var name for the API key, but does NOT deploy anything — deployment lives in by-deploy-compute.

Step 2b — Returning session: read config + environment

python3 .claude/skills/by-session/scripts/validate_config.py .by/config.json

✅ VERIFICATION: Expect ✓ Config valid: provider=<name>, profile=<name>.

If validation fails, surface the specific field error to the user and ask before overwriting anything. Do NOT silently re-run the questionnaire.

Step 3 — Show banner

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 BY ► Protein Design Agent
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Step 4 — Check for in-progress campaigns

ls campaigns/*/campaign_log.json 2>/dev/null

Count campaigns and inspect each status field. See references/resume-protocol.md for the exact rules on what counts as "in progress" and what gets restored.

Step 5 — Display status

Build the compute line from compute.default_provider and any populated provider blocks. Examples:

• Compute: Local GPU ✓ (BoltzGen, Protenix, PXDesign)
• Compute: HPC ✓ (target=runpod, key=RUNPOD_API_KEY)
• Compute: Tamarind ✓ (free tier)

Full display:

Compute: Local GPU ✓ (BoltzGen, Protenix, PXDesign)
Profile: balanced | Default: standard (5,000/scaffold)
Campaigns: 3 previous, 1 active (anti-HER2 — designing 80%)

Ready:
  "Design [modality] against [target]"
  /by:plan-campaign — guided setup
  /by:status — existing campaigns

Anti-patterns

⚠️ CRITICAL — DO NOT:

• ❌ Re-run the questionnaire if .by/config.json already exists → STOP: read it instead
• ❌ Default to tamarind → the new default is local; respect providers_priority
• ❌ Silently overwrite unrelated fields in config.json → load, mutate only target field, save
• ❌ Block the session on a single failed tool check → mark ✗ with reason, continue
• ❌ Deploy HPC infrastructure here → that is by-deploy-compute's job

When Scripts Fail

Script-failure hierarchy (per the BY quality bar):

1. Fix and Retry (90%) — python3 -m pip install -e . may be needed if the project venv is stale; or set PYTHONPATH to include the templates dir. Re-run the script.
2. Modify Script (5%) — If the questionnaire flow is missing a new option (e.g., a new HPC target), add a branch to init_questionnaire.py. Keep validation in validate_config.py in sync.
3. Use as Reference (4%) — If the script's behavior is wrong for this user's edge case (e.g., heterogeneous multi-node setup), read the script and adapt the writes manually with python -c "import json; ...".
4. Write from Scratch (1%) — Only if config.json semantics have changed enough that the script is misleading; in that case, update references/config-schema.md first, then the script.

Decision Points

Default provider selection

Model profile selection

Campaign tier default

Common Issues

Best Practices

1. 🚨 CRITICAL: Always check .by/config.json existence BEFORE running the questionnaire — re-running silently overwrites user preferences.
2. ✅ REQUIRED: Use scripts/init_questionnaire.py and scripts/validate_config.py — do not write inline Python for these flows.
3. ✅ Honor providers_priority (["local", "hpc", "tamarind"]) when default_provider is auto.
4. ✅ When updating config, read-modify-write — never replace the file wholesale unless the user opts in.
5. ✅ Surface compute-provider issues but do NOT block the session — the user may want to fix them mid-session.
6. ✅ Treat .by/environment.json as advisory; the config is canonical for "which provider to use".
7. ❌ Never expose API key VALUES in the banner or logs — only present/missing.
8. ❌ Never silently fall back from local to tamarind — respect the user's explicit choice.
9. ✨ Optional: Cache the questionnaire answers in .by/.questionnaire-history.json if the user re-runs setup, so we can suggest their previous choices as defaults.

Suggested Next Steps

After the session is initialized, common next moves:

• by-design-workflow — when the user describes a target, this is the master orchestration skill that decides which design engine to invoke (it reads the compute provider from .by/config.json written here).
• by-research — if the user is starting a new campaign against an unfamiliar target, research is always step 1.
• by-campaign-manager — if the session detected an in-progress campaign, hand off to this skill for resume.
• by-deploy-compute — if the user selected hpc but the actual deployment is not yet active.
• /by:status — if the user just wants a campaign-status summary without starting work.

The chaining matters: by-session's job is to prepare the environment; downstream skills consume .by/config.json and trust it. Keep that contract clean.

Related Skills

Upstream (run before by-session): None — this skill is the entry point.

Downstream (run after by-session):

• by-design-workflow — master orchestration; reads provider from config
• by-research — first step of any new campaign
• by-campaign-manager — for resume of in-progress campaigns

Alternative / Complementary:

• by-deploy-compute — handles the deployment side of HPC; by-session only records the choice
• status (slash command skill) — read-only campaign status; does not modify config

References

Detailed documentation (references/):

• references/config-schema.md — Full JSON Schema for .by/config.json and .by/environment.json, including the post-2026-05 fields (providers_priority, compute.hpc.target, compute.hpc.api_key_env).
• references/resume-protocol.md — Detection rules for in-progress campaigns, checkpoint loading, and what is restored vs re-asked when a session reopens mid-campaign.

Scripts (scripts/):

• scripts/init_questionnaire.py — Interactive (or --defaults) first-run config flow. Asks: local GPU available? RunPod API key? Tamarind key? Writes .by/config.json with local-first defaults.
• scripts/validate_config.py — Reads .by/config.json, validates against the schema documented in references/config-schema.md, prints actionable issues.

Project context:

• templates/CLAUDE.md — the "Compute Provider Selection" section is the authoritative prose explanation of the local-first ordering this skill enforces.
• templates/.by/config.json — the canonical default config shipped with new projects.