collaborator-onboarding

collaborator-onboarding

Synthesizes the accumulated context of an existing Carrel vault into a markdown handbook that a new collaborator can read to come up to speed on how this researcher works in this vault. Vault-specific, not Carrel-general.

When to Use

• Researcher mentions sharing the vault with someone (RA, co-author, lab member, advisor)
• The /carrel-share command is invoked
• A new lab member is joining and will work in this vault
• Periodic refresh of a shared lab handbook
• After significant changes to the vault (new tools added, sensitivity changed, automation enabled)

What This Skill Is Not

• Not /carrel-setup. Setup is for someone creating their own new Carrel environment from scratch. This skill assumes the vault already exists and has been used.
• Not /carrel-mirror. Mirror writes a self-portrait for the researcher's own awareness. This skill writes for someone else to read — different audience, different framing.
• Not Claude Code's /team-onboarding. That command generates generic Claude Code usage tips from your local session history. This skill produces a vault-specific handbook from vault content.

Source Material

Read these in order. Skip any that don't exist or are empty — degrade gracefully.

Source	Purpose
.carrel/environment.json	Researcher profile, sensitivity, configured tools, automation status, wiki status, collaborators field, team_context
CLAUDE.md (vault root)	Narrative profile, "how to work with [name]" guidance
_meta/friction_log.md	Recurring pain points the collaborator should know about
_meta/capability-log.md	Custom trackers, plugins, conventions added over time
_meta/reflections/	Recent ~5 entries — current preoccupations
_meta/mirror/	Most recent self-portrait — synthesized trajectory
notes/threads/	Active analytical threads (status: active only)
wiki/SCHEMA.md	Wiki conventions and tag taxonomy (only if wiki active)
wiki/index.md	List of wiki pages (only if wiki active)
Vault folder structure	Top-level folders that exist in this vault
_meta/cheat_sheet.md	Existing reference card — point the collaborator at it

Synthesis Approach

The handbook must answer four questions for the collaborator:

1. What does this researcher actually study and do? (substance — from CLAUDE.md, environment.json, recent reflections)
2. What are the rules and habits I need to respect? (sensitivity, naming, conventions — from CLAUDE.md, capability log, wiki schema)
3. What's currently happening? (active threads, recent work — from notes/threads/, latest reflection)
4. What should I do first? (concrete entry points — from configured tools, vault structure)

Use references/handbook-template.md for the markdown structure. Each section has a "skip if" rule for graceful degradation.

Modes

The skill has two operating modes — choose based on how the researcher framed the request.

Interactive (default)

A short brief exchange up front, then conversational refinement at the end. Use this when the researcher says "share with my RA" or "onboard Jane" without further detail.

Brief (one short exchange — don't make it a form):

• Who are they? (name, role — RA, co-author, lab member, advisor)
• What do they need to do in this vault? (read papers? add transcripts? write drafts? review?)
• How experienced are they with research workflows? (new grad student, senior PhD, faculty)

Refinement (after synthesis): show the draft, ask one focused question: "Anything missing, or anything that shouldn't go to [name]?" Apply edits, save the final.

Canonical copy (optional): offer "Want me to also save this as _meta/lab-handbook.md — your canonical 'latest version' you can update over time?" If yes, copy the file. If no, the dated handbook stands alone.

Quick mode

Skip the brief, use defaults (new lab member, general access), save the dated handbook, skip the canonical copy. Use this when the researcher says "just generate one", "quick handbook", "draft something I can edit", or otherwise signals they want a starting point rather than a conversation.

Quick mode is a behavioral shortcut. The CLI does not have a separate flag for it — it surfaces as --mode quick on the generate call.

Calling Pattern

Once mode + collaborator + sensitivity are resolved, hand off to the CLI for synthesis and the file write:

carrel vault share generate \
  --mode interactive|quick \
  --for <collaborator-slug> \
  --sensitivity low|medium|high \
  [--vault PATH]

The CLI owns: source-material reads, handbook synthesis emission, sensitivity-rule application (what gets redacted at each level), idempotent dated-filename writes under _meta/handbook/, and the optional canonical-copy write. This skill owns: mode selection, the brief (interactive), the refinement loop (interactive), and the sensitivity conversation when redaction is uncertain.

Use --explain to preview what the CLI would write — including which sources it would pull from and which sections sensitivity rules would redact — without committing.

Output

Files land at _meta/handbook/[YYYY-MM-DD]-for-[collaborator-slug].md.

• [YYYY-MM-DD] = today's date
• [collaborator-slug] = lowercase, hyphenated. Examples: jane, new-ra, co-author-cornell. If the collaborator isn't named, use lab-member.

Optionally also save as _meta/lab-handbook.md — the canonical "latest" version. Researcher chooses (interactive mode only).

Sensitivity Considerations

The --sensitivity flag controls how the CLI applies redaction; this skill resolves it with the researcher before invoking.

Default: read the researcher's sensitivity from .carrel/environment.json and pass it through. Override only when the collaborator's access is narrower than the researcher's vault-wide setting (e.g., a HIGH-sensitivity vault but the new RA only needs the public-facing project — pass --sensitivity medium with the researcher's confirmation).

Narration during synthesis (HIGH sensitivity):

• Default to project-level descriptions, not file lists
• Don't include unpublished manuscript titles or transcript filenames in the handbook
• Ask whether specific projects, papers, or threads should be redacted before sharing
• Mention sensitivity rules prominently in the handbook itself (the collaborator needs to know what they can and can't do)

Narration during synthesis (MEDIUM sensitivity):

• File lists are fine; redact only files explicitly marked sensitive (e.g., filenames starting with private- or irb-)
• Mention sensitivity rules briefly so the collaborator knows the contract

Narration during synthesis (LOW sensitivity):

• Full vault visibility; no redaction beyond the researcher's explicit asks

If the collaborator's role is unclear, default to the more restrictive interpretation and tell the researcher you've done so: "I treated their access as HIGH-sensitivity since you didn't specify their role — let me know if I should loosen it."

Anti-Patterns to Avoid

• Don't write a Carrel tutorial. The collaborator can read Carrel docs; this handbook is about THIS vault and THIS researcher.
• Don't fabricate. If the friction log is empty, write "no recurring friction recorded yet" rather than inventing pain points to fill the section.
• Don't recite raw counts. "14 papers in papers/" is not useful. "Mostly institutional theory, with a recent shift toward field-level change" is.
• Don't accumulate. Each handbook is a snapshot. Don't try to maintain a single growing document automatically — let the researcher refresh when they want to.
• Don't pretend to know the collaborator. If they haven't been described, write generic guidance and flag it: "Tailor the entry-point recommendations once you know more about [name]."

Update Cadence

The handbook is a snapshot. Refresh whenever:

• A new collaborator joins (new dated handbook for them)
• The vault has changed substantially (new tools, sensitivity shift, automation enabled, wiki activated)
• The shared lab handbook is being passed around and someone notices it's stale (overwrite the canonical lab-handbook.md)

There is no automatic refresh. The researcher decides.

Related

• Command: /carrel-share (entry point for this skill)
• Skills: vault-ops (vault structure conventions), automation (if vault has scheduled automation, surface that to the collaborator), knowledge-wiki (if wiki active, explain its conventions)
• Commands: /carrel-mirror (self-portrait — adjacent but different audience), /carrel-setup (for collaborators who need their own vault)
• Files: _meta/handbook/, _meta/lab-handbook.md (optional canonical copy)