Skill reference

Every skill bundled with TVBO, what it teaches, when it fires

This page is the canonical list of every skill TVBO ships. Two flavours:

The split is by audience, not capability — user skills are still rich behavioural rules, just scoped to library usage rather than library development.

User skills

These are the five skills pip install tvbo && tvbo skills install puts on your machine.

tvbo-overview

Note

Fires when: “What is TVBO?”, “How is TVBO organised?”, “Should I use TVBO for this?”

The three-pillar mental model:

  1. LinkML datamodel — structured metadata in schema/*.yaml, generated Python types in tvbo/datamodel/ (never hand-edited).
  2. Ontology — tvbo.owl carries axioms about SimulationExperiment, SimulationStudy, Network, DynamicalSystem, Software.
  3. TVBO Python package — specifies models, loads experiments, generates code for every backend, and executes them.

Plus the Odoo platform at tvbo.charite.de as a fourth, separate management layer.

tvbo-writing-models

Note

Fires when: Editing .yaml / .yml / .py files that look like Dynamics specs.

Teaches:

  • The YAML and Python forms of a Dynamics
  • That lhs is LaTeX (not Python) — \dot{X} for time derivatives
  • That rhs is SymPy-parseable, names must match parameters/state variables
  • That parameters carry value, state variables carry equation — never both
  • That tvbo/datamodel/** is generated; don’t hand-edit it

tvbo-running-simulations

Note

Fires when: Working in .py / .ipynb files involving simulation, JAX, TVB, PyRates, or Julia.

Teaches:

  • The SimulationExperiment(dynamics).run(duration).plot() pattern
  • How to render code without executing (render_code('jax'))
  • Which extra to install per backend (tvbo[jax], tvbo[tvb], tvbo[pyrates], tvbo[julia], tvbo[neuroml], tvbo[tvboptim])
  • Intel-Mac pinning quirks (numba/llvmlite/jax)

tvbo-replicating-studies

Note

Fires when: Reproducing a published study — building a <Study>.yaml, its report.qmd, or replication plotting.

Turns a paper into one declarative, tvbo-native recipe (all or selected experiments) plus simple plotting and an honest, fully-computed report. Composes writing-models and running-simulations, then adds the replication-specific rules:

  • One <Study>.yaml for every targeted experiment — no Python drivers
  • Every reported number computed from a result container, never typed by hand
  • Backend chosen by feature-fit, not defaulted; framework gaps surfaced early
  • Replication (independent code + data) stated honestly, with a scorecard
  • Ships an assets/ dir — report/plot templates and a FAIR skeleton — installed alongside the skill

tvbo-platform

Note

Fires when: Working with tvbo.api, sharing experiments, or asking about tvbo.charite.de.

Teaches:

  • The platform is an Odoo service separate from the Python package
  • Public reads vs API-key-gated private records
  • Where each REST client module lives (tvbo/api/ontology_api.py, dynamics_api.py, experiment_api.py, network_api.py)
  • That the platform is the system of record for shared experiments — always check the stored revision when reproducing a run

Maintainer skills

These are committed to the TVBO repository under .claude/skills/ and .github/instructions/. Any AI assistant working inside a clone of tvbo gets them automatically. They are not installed by tvbo skills install unless you pass --audience maintainer or --audience all.

git

Critical

The user owns all version control. The AI assistant must never run git add, git commit, git push, or use any GitKraken write-tools.

Allowed: read-only inspection (git status, git diff, git log, git branch), branch switching when explicitly requested, fetch/pull when explicitly requested.

writing-code

Behavioural guidelines: think before coding, simplicity first, surgical changes, goal-driven execution. Designed to reduce the most common LLM coding mistakes (over-engineering, scope creep, unrequested refactors).

linkml-schema

The tvbo/datamodel/** directory is generated from schema/*.yaml by the LinkML pipeline. Hand-editing the generated dir will silently break on the next regeneration. pyproject.toml excludes it from ruff and mypy to make this explicit.

The skill encodes: where the canonical source lives, the regeneration workflow, the lint exclusions, and the LinkML 1.11+ version requirement.

codegen-templates

How TVBO compiles a Dynamics to runnable backend code:

  • tvbo/templates/ holds per-backend template trees (Mako-based).
  • tvbo/codegen/ dispatches to the right template per backend.
  • tvbo/adapters/ wraps external simulators (TVB, Julia, NeuroML, PyRates, BifurcationKit, ModelingToolkit, NetworkDynamics, openMINDS, tvboptim). Contract: tvbo/adapters/base.py.

Includes the new-backend checklist (adapter, template tree, pytest marker, dispatch, optional dependency).

tests-and-backends

The full table of backend_* pytest markers (backend_jax, backend_tvb, backend_pyrates, backend_tvboptim, backend_julia and its sub-markers, backend_neuroml), plus slow, julia, docs, the --run-slow flag, and the -n 1 --dist=loadscope default options.

grill-me

A workflow skill: instructs the assistant to interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Used for designing larger changes.

Canonical source vs adapter output

Every skill above has exactly one canonical source:

  • User skills: tvbo/skills/canonical/<name>/SKILL.md
  • Maintainer skills: skills/<name>/SKILL.md

The adapter outputs (.claude/skills/, .github/instructions/, .cursor/rules/, AGENTS.md index, raw prompt) are generated. Never edit them by hand — tvbo skills sync (or the next install) will revert your changes.

If you want to modify a skill’s content, edit the canonical source and re-run tvbo skills sync.

If you want to add a new skill, create skills/<new-name>/SKILL.md (maintainer) or tvbo/skills/canonical/<new-name>/SKILL.md (user) and run sync.

Skill frontmatter schema

---
name: my-skill                       # slug, must match the directory name
description: One-line summary used by Claude Code to pick the skill on demand.
metadata:
  audience: user                     # user | maintainer | both
  applies_to:                        # globs — used by Copilot applyTo + Cursor globs
    - "**/*.py"
    - "**/*.ipynb"
  tags: [jax, simulation]            # for filtering with --tag (future)
  requires_extras: ["jax"]           # optional — pulled into user docs
---

# Markdown body — same content across every adapter target.

audience, applies_to, tags, and requires_extras are nested under metadata: to satisfy VS Code’s SKILL.md schema linter, which only allows a known set of top-level attributes (plus a free-form metadata block). The renderer reads both forms.

Bundled assets

A skill directory may carry an assets/ sibling of its SKILL.md — helper scripts, templates, or a skeleton tree the skill tells the assistant to copy. replicating-studies is the first to use it, shipping report/plot templates and a FAIR study layout.

Only the directory-shaped claude-code target can hold assets: install and sync mirror assets/ next to the rendered SKILL.md (so an installed skill lives at ~/.claude/skills/tvbo-<name>/SKILL.md and ~/.claude/skills/tvbo-<name>/assets/), and uninstall removes it. The flat targets (Cursor, Copilot, raw prompt) carry the skill body only. Byte-compiled files (__pycache__, *.pyc) are never mirrored.