{"id":16858,"plugin_id":"plugins_6a6a29948a7c8191ace6787d5ae074bb","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T23:13:50.372Z","digest":"31a67e854be51dd4b5704d9676b1e7726eaba72d189d1710e6b25fb6f153ece2","against":null,"payload":{"name":"jinko-protocol","description":"Design or edit multi-arm Jinkō protocol designs via the jinko-sdk. Use this skill whenever the user wants to compare doses, schedules, administration routes, treatment activation flags, or combinations of treatments by overriding model component values per arm. Protocol designs assign values to model-defined inputs; dosing functions, schedule parameterization, treatment activation logic, and administration-mode logic belong in the model. Use jinko-model when those functions or inputs do not exist yet. Use jinko-trial for running trials.","included_files":[{"relative_path":"agents/openai.yaml","size_in_bytes":260},{"relative_path":"assets/protocol.json","size_in_bytes":2371},{"relative_path":"assets/toy_protocol_arms.csv","size_in_bytes":156},{"relative_path":"assets/toy_protocol_arms.json","size_in_bytes":817},{"relative_path":"evals/evals.json","size_in_bytes":1224},{"relative_path":"references/protocol-design.md","size_in_bytes":3639},{"relative_path":"scripts/create_protocol_design.py","size_in_bytes":6622},{"relative_path":"scripts/create_protocol_design_from_csv.py","size_in_bytes":4395},{"relative_path":"scripts/edit_protocol_design_arms.py","size_in_bytes":4739},{"relative_path":"scripts/inspect_protocol_design.py","size_in_bytes":2540}],"skill_md_contents":"---\nname: jinko-protocol\ndescription: >-\n  Design or edit multi-arm Jinkō protocol designs via the jinko-sdk. Use this skill whenever the user wants to compare doses, schedules, administration routes, treatment activation flags, or combinations of treatments by overriding model component values per arm. Protocol designs assign values to model-defined inputs; dosing functions, schedule parameterization, treatment activation logic, and administration-mode logic belong in the model. Use jinko-model when those functions or inputs do not exist yet. Use jinko-trial for running trials.\ncompatibility: >-\n  Check set-up with the `jinko-sdk-setup` skill. Creating or editing protocol designs requires write access to the Jinkō project.\nmetadata:\n  author: Nova In Silico\n  requires_sdk: \">=1.8,<2.0\"\nlicense: MIT\n---\n\n# Jinkō Protocol SDK Workflows\n\nUse this skill for protocol-design mechanics through the SDK. Keep the separation of concerns explicit: the model defines treatment-regimen functions and inputs; the protocol instantiates those inputs per arm.\n\n> **PREREQUISITE:** This skill needs an initialized `jinko-sdk` connection and an\n> SDK satisfying its `metadata.requires_sdk` range. Run the `jinko-sdk-setup` skill\n> (`../jinko-sdk-setup/SKILL.md`) and proceed only once its check passes. If that\n> skill is not found, install it from `novainsilico/jinko-skills`.\n\n## Separation Of Concerns\n\n- Protocol designs only override component values, with different override values per arm.\n- Dosing functionality is defined at the model level: schedule parameterization, dose parameterization, treatment activation/deactivation through categorical parameters, route or administration mode through categorical parameters, and any formulas that interpret those inputs.\n- In the model, define the treatment-regimen function and its input components.\n- In the protocol, assign values to those inputs, as if instantiating that function for each arm.\n- If a needed override key does not exist as a model input, switch to `jinko-model` first and add the model component or dosing logic there.\n\n## Core Rules\n\n- Prefer `client.create_protocol_design(arms, model=model)` when a model is available.\n- Use `client.create_protocol_design_from_csv(csv_file_path=...)` when arms come from a spreadsheet. The CSV is posted as-is; the platform parses and validates it against its own protocol design CSV schema. This path does not accept a `model` argument; link a model with `client.create_protocol_design(...)` instead if that's required. See `assets/toy_protocol_arms.csv` for an example file and `references/protocol-design.md` for the SDK call.\n- Link protocol designs to a model when possible so the protocol design carries the model snapshot reference.\n- The override `key` must target a protocol-runnable model input, such as `Dose` or `route` in the toy model.\n- Use formulas as strings, for example `\"1.0\"`, `\"iv\"`, or `\"PT24H\"` depending on the target component.\n- Include control relationships when comparing arms; use `armControl` to identify the comparator arm.\n- Edit individual arms on an existing design with `protocol.arms` (`get`, `create`, `set_control`, `set_active`, `set_weight`, `set_override`, `delete`, `compare_overrides`), not by replacing the raw design payload.\n- Require explicit confirmation or script `--apply` before creating or updating project items.\n\n## Project Folder Hygiene\n\n- Prefer creating protocol designs inside a dedicated Jinkō folder instead of the project root. At the start of a workflow, ask for or propose a folder name, for example `YYYY-MM-DD-<experiment-name>`.\n- Reuse an existing exact-match folder when possible: `client.get_folder_by_name(name, exact_match_only=True)`.\n- If the folder does not exist, create it only after user confirmation or when a script is run with `--apply`.\n- Resolve one folder object or folder id, then pass `folder=folder` to SDK creation calls that support it.\n\n## Bundled Assets\n\n- `assets/toy_protocol_arms.json`: three arms with two routes and three doses. The `iv` route repeats across two arms.\n- `assets/toy_protocol_arms.csv`: the same three arms in CSV form, one row per arm, for use with `create_protocol_design_from_csv`.\n- `assets/protocol.json`: subset of the OpenAPI schema for protocol arm shape.\n\n## Bundled Scripts\n\n- `scripts/create_protocol_design.py`: creates a three-arm protocol design, optionally linked to a model.\n- `scripts/create_protocol_design_from_csv.py`: creates a protocol design from a CSV file of arms.\n- `scripts/edit_protocol_design_arms.py`: upserts arms and overrides on an existing protocol design via the `arms` mutator service. It retains arms and overrides omitted from the input; use explicit `protocol.arms.delete(...)` or `arm.remove_override(...)` calls for removals.\n- `scripts/inspect_protocol_design.py`: prints protocol content or a concise arm summary.\n\nExamples:\n\n```bash\npython skills/jinko-protocol/scripts/create_protocol_design.py --model-sid cm-...\npython skills/jinko-protocol/scripts/create_protocol_design.py --model-sid cm-... --apply\npython skills/jinko-protocol/scripts/create_protocol_design.py --model-sid cm-... --folder 2026-06-15-regimens --create-folder --apply\npython skills/jinko-protocol/scripts/create_protocol_design_from_csv.py --csv skills/jinko-protocol/assets/toy_protocol_arms.csv --apply\npython skills/jinko-protocol/scripts/edit_protocol_design_arms.py --protocol-design-sid pd-... --arms skills/jinko-protocol/assets/toy_protocol_arms.json --apply\npython skills/jinko-protocol/scripts/inspect_protocol_design.py --protocol-design-sid pd-... --summary\n```\n\n## Arm Shape\n\nEach arm should include:\n\n- `armName`: stable arm identifier.\n- `armOverrides`: list of `{ \"key\": \"<model-input-id>\", \"formula\": \"<arm-specific-value>\" }` entries.\n- `armIsActive`: usually `true` for active arms.\n- `armWeight`: usually `1` unless weighted simulations are intentional (for calibration).\n- `armControl`: `null` for the comparator arm, or another arm name for arms compared against a control.\n\nDefault toy arms:\n\n- `iv_low_dose`: `Dose=1.0`, `route=iv`, no control arm.\n- `po_mid_dose`: `Dose=2.0`, `route=po`, controlled by `iv_low_dose`.\n- `iv_high_dose`: `Dose=3.0`, `route=iv`, controlled by `iv_low_dose`.\n\n## Reference Routing\n\n- Read `references/protocol-design.md` for separation of concerns and SDK patterns.\n- Read `assets/protocol.json` when validating arm payload shape.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}