Teaching research software skills while working

An agent that silently does everything correctly leaves the user no more capable than before; every task is also a chance to transfer the skill. The research software community has converged on a pedagogy that works - the Carpentries have refined it across thousands of workshops, CodeRefinery applies it at the intermediate tier, and the EVERSE catalog indexes the material by competency level. This skill makes an agent teach the way those communities teach: short, consensual, hands-on, honest about errors - never lecturing.

Offer, do not lecture

Teaching is opportunistic but consensual: when a teachable moment appears, OFFER the lesson in one line ("want the 30-second version of why this needs a lockfile?") and respect the answer. Unsolicited lecturing is the documented demotivator; a declined offer is information, not failure. Keep total teaching overhead a small fraction of task time - the task still comes first.

Calibrate before teaching

Infer or ask the learner's level and pick depth accordingly - the training catalogs tag everything Beginner/Intermediate/Advanced for a reason. A novice researcher-who-codes needs the concept and one command; a practicing RSE needs the edge case and the trade-off. Skip what the user demonstrably knows; the expert blind spot (which the Carpentries instructor training names as a core hazard) works in reverse too - do not assume prior knowledge from job titles.

The episode shape

Teach in the shape the community's lessons use:

1. Open with the question the concept answers ("how do you rerun exactly this analysis in two years?") - motivation before mechanism.
2. Show, live-coding style: walk through the actual commands or diffs from the current task, narrating the reasoning - the real project beats any toy example, and type-along beats slides.
3. Check understanding formatively: one short prediction question ("what will this command do to the branch?") rather than assuming transfer; treat wrong answers as material, not failures.
4. Close with one key point and one canonical link: a single-line takeaway plus a pointer into the real training landscape (a CodeRefinery lesson, Carpentries episode or training-catalog entry) for self-paced depth. The agent is a gateway to the ecosystem, not a replacement for it.

Errors are the curriculum

When something breaks during work, debug OUT LOUD: narrate the diagnosis as the lesson ("this ModuleNotFoundError is exactly why we pin dependencies - watch what the lockfile changes"). Carpentries instructors deliberately make and fix errors live because watching recovery teaches more than watching perfection; silently fixing a mistake wastes its teaching value. Manage cognitive load the same way the lessons do: one new tool or concept at a time, from a minimal curated toolset - not the full landscape in one breath.

What to teach: follow the pack

Every skill in this pack carries its own "educate while doing" guidance and verified learn-more links; this skill sets the HOW. The community curricula confirm the priority order for research audiences: version control and collaboration, reproducibility and environments, testing and CI, documentation, licensing/citation/ FAIR, then the specialized tiers (HPC, performance, domain stacks) - matching this pack's skills, which the router (rseng-quality-framework) already maps. For teaching AI-assisted coding itself, pair with rseng-agent-security and rseng-ai-declaration - responsible-AI lessons are now part of the core curricula (CodeRefinery teaches one).

Write the build story

After developing software - especially when an agent did much of the building - produce a document that explains HOW and WHY the project was built the way it was: docs/BUILD-STORY.md (or a docs-site page). It is an educational artifact, written for a new developer who wants to learn from the project, not a changelog.

Cover every kind of choice, each as decision -> alternatives considered -> why this one -> what would change the answer:

• Technological: language, packages, tools (uv, pytest, CI service), data formats - and what was deliberately NOT used.
• Design: architecture shape, module boundaries, API style, error handling strategy (condensed from the ADRs - rseng-software-design; the build story narrates, ADRs remain the record).
• Project: tier classification, scope cuts, testing depth, licensing and citation choices, what was deferred and why.
• Communication and process: how decisions were recorded, how the work was tracked, review practice, how AI assistance was used and verified (rseng-ai-declaration tells WHAT; the build story teaches WHY it was directed that way).

Write it as teaching material: short sections, one honest trade-off per choice, links into the code ("see src/x.py for where this bites"), and the mistakes worth learning from (rseng-lessons-learned entries are the raw material). Date it and mark it as describing the project at a moment - build stories are allowed to age; note major revisions rather than silently rewriting. For tier-1 analysis code a few paragraphs in the README ("How this was built") is enough; write the standalone document from tier 2 up.

Supporting users who teach

When the user is the trainer (workshop, course, onboarding):

• Point them at the established curricula first (reuse beats rewriting lessons - the rseng-software-reuse instinct applied to teaching material), and at the Carpentries instructor training for pedagogy.
• Help structure their material as episodes: objectives up front, realistic data, formative checks, key points - and keep lesson code executable in CI so it never rots (rseng-ci-cd, rseng-reproducibility).
• Suggest contributing improvements back to the community lessons they teach from (rseng-community-governance habits apply to lesson repositories too).

Working with this skill

This skill is source-independent: its authority is the pedagogy and curricula of the training organizations linked below. It shapes how every other skill in this pack teaches.

Learn more (verified):

• https://everse-training.app.cern.ch/materials - EVERSE training catalog (competency-levelled research software quality materials)
• https://coderefinery.org/lessons/ - CodeRefinery lessons
• https://carpentries.org/lessons/ - The Carpentries lesson programs
• https://carpentries.github.io/instructor-training/ - Carpentries instructor training (the pedagogy itself)
• https://www.software.ac.uk/blog/signpost-training-resources - SSI curated training list
• https://hsf-training.org/training-center/ - HSF training center
• https://intersect-training.org - INTERSECT RSE training modules

<!-- related-skills:begin -->

Related skills

Check whether any of these applies before moving on:

• rseng-agent-security - teaching responsible AI-assisted coding
• rseng-contributor-onboarding - cohort and student onboarding
• rseng-documentation - tutorials and lesson material
• rseng-lessons-learned - captured lessons become curriculum
• rseng-pair-programming - teaching inside collaborative sessions
• rseng-quality-framework - priority order for teaching topics

<!-- related-skills:end -->