🌱 Trellis

Give your research something to grow on — Claude Code-native project scaffolding for quantitative social scientists

You're a quantitative social scientist using Claude Code for analysis and writing. You have survey instruments, IRB approvals, analysis scripts, manuscript drafts, reviewer reports, and meeting notes scattered across your projects. Your directory structure was already struggling to keep up with you. Now it needs to work for Claude too.

This toolkit fixes that. It provides opinionated defaults for how a research project should be organized, with clear alternatives when your situation is different. It gives you:

• /trellis:init-research-project — Scaffold a new project with a structure that both you and Claude can navigate.
• /trellis:generate-companions — Turn your PDFs, Qualtrics files, and emails into Markdown that Claude can actually read.
• /trellis:check-project — Find gaps: missing documentation, stale companions, empty directories.
• /trellis:process-reviews — Handle a new round of R&R: transcribe reviews, draft a revision strategy.
• /trellis:assemble-release — Build a clean public replication package from your private repo.

Every project you create gets CLAUDE.md files that teach Claude how your project works — not just the directory tree, but the logic of it. Where the data comes from. What the survey measures. Why the manuscript is structured the way it is.

Install

As a plugin (recommended)

claude plugin install trellis

Skills become available as /trellis:init-research-project, /trellis:generate-companions, etc. Plugin installation gives you namespacing (no conflicts with other skills) and versioned updates.

As standalone skills (fallback)

git clone https://github.com/simonfriis/trellis.git
cd trellis
bash install.sh

This copies skills directly to ~/.claude/skills/. Skills are available as /init-research-project, /generate-companions, etc. — shorter names, but no namespacing or versioning.

Your First Project in 5 Minutes

> /trellis:init-research-project

Claude will show you a proposed project structure, ask a few questions if you want to customize, and then create everything. You'll have:

• A private git repo with the full project structure
• CLAUDE.md files at every level so Claude knows what's where
• A manuscript/ directory ready for Quarto + renv
• A materials/ directory waiting for your raw files
• A docs/ wiki ready for your design rationale and decision records

Drop your Qualtrics .qsf file into materials/instruments/, then:

> /trellis:generate-companions materials/instruments

Claude reads every raw file in the directory, creates a Markdown companion next to each one, and reports what it did. Now Claude can reason about your survey instruments in every future session.

How the Template Works

Here's the mental model. Every research project has four types of stuff, and they live in four places:

1. materials/ — The Evidence Locker

Raw artifacts. The actual .qsf survey file. The PDF of your IRB approval. The email from the editor. The reviewer's report. These are the source of truth in the legal, archival sense.

Next to each raw file sits a machine-readable companion — a Markdown file that Claude can parse. The naming convention makes derivation obvious:

materials/instruments/
├── main-survey.qsf              ← The real thing
├── main-survey.qsf.md           ← What Claude reads
├── irb-approval.pdf              ← The real thing
└── irb-approval.pdf.md           ← What Claude reads

The double extension (.qsf.md) is deliberate. It's ugly, and that's the point — you can never confuse a derived file for a primary document. Every companion starts with a header that records its provenance:

<!-- DERIVED: source=main-survey.qsf, generated=2026-03-25, generator=claude -->

2. docs/ — The Project Wiki

Interpretive context. Why you chose that survey scale. Why you dropped those observations. What the reviewer was really asking and how you're going to respond. This is where you (and Claude) go to understand the project's logic, not just its artifacts.

The wiki is organized by topic, not by date. The entry point is docs/index.md, which links to everything else.

3. manuscript/ — The Reproducible Package

This is the thing that ships. A self-contained Quarto + R + renv directory that reproduces your paper from de-identified data with one command:

cd manuscript && Rscript -e 'renv::restore()' && quarto render paper.qmd

When you're ready to publish, /trellis:assemble-release extracts manuscript/ into a clean public repo, stripping all private materials.

4. .claude/ — The Agent Layer

Context for Claude that doesn't belong in the public release. Your North Star document (project framing, contribution, audience). Prompt templates for recurring tasks. Session logs for important decisions made in conversation with Claude.

The Broader Setup

A project doesn't exist in isolation. Here's the recommended architecture for your full research environment:

~/
├── research-data-vault/            ← NEVER in git. Encrypted backups only.
│   ├── project-alpha/
│   │   ├── raw-identifiable/       ← Survey responses with PII
│   │   ├── participant-tracking/   ← Compensation, contact info
│   │   └── credentials/            ← API keys, platform tokens
│   └── project-beta/
│       └── ...
│
├── repos/
│   ├── dataset-panel-abc/          ← Shared dataset repo (its own git repo)
│   │   ├── code/                   ← Cleaning pipeline
│   │   ├── data/                   ← DVC-tracked cleaned data
│   │   └── docs/                   ← Codebook, sampling docs
│   │
│   ├── project-alpha/              ← Research project (private repo)
│   │   ├── CLAUDE.md               ← Agent entry point
│   │   ├── manuscript/             ← Publishable replication package
│   │   ├── materials/              ← Raw artifacts + companions
│   │   └── docs/                   ← Project wiki
│   │
│   └── project-alpha-public/       ← Public replication package (public repo)
│       └── ...                     ← Output of /trellis:assemble-release
│
└── ~/.claude/
    └── plugins/                    ← This toolkit lives here (installed as plugin)

Why three layers?

The vault holds anything identifiable. It's not in any git repo — ever. If your laptop is stolen, this is the data you can't afford to lose and can't afford to expose. Back it up encrypted.

The private repo holds everything else: materials, documentation, analysis code, manuscripts. It's in git, on a private GitHub repo. You work here day-to-day.

The public repo holds the replication package: just the manuscript/ directory, stripped of private materials. Published at submission or acceptance.

Shared datasets

If multiple projects use the same dataset (say, a panel survey with multiple waves), give it its own repo. The dataset repo:

• Version-controls the cleaning pipeline
• Tracks cleaned data outputs via DVC
• Can be published independently with its own DOI
• Is consumed by project repos via DVC import or path configuration

This toolkit includes /trellis:init-research-project --dataset to scaffold a shared dataset repo.

Alternative Workflows

The setup above is opinionated. Here are alternatives for each design decision, if your situation is different.

Sensitive data handling

Approach	When to use it
Vault + config paths (recommended)	Most projects. Keeps PII completely out of git.
DVC with private remote	Large datasets. Gives you version control on data files.
Encrypted directory in repo	Solo researcher, no collaborators. Simpler but riskier.

Shared datasets

Approach	When to use it
Separate dataset repo (recommended)	Dataset evolves over time (new waves), 2+ projects use it.
Copy into each project	Dataset is frozen, only 1-2 projects.
Data vault only, no repo	No version control needed on cleaning code.

Machine-readable companions

Approach	When to use it
Double extension .qsf.md (recommended)	Most projects. Derivation is unambiguous at a glance.
Header-only convention	If you find double extensions intolerable.
Parallel directory tree	If you have hundreds of materials and want clean separation.

Public release

Approach	When to use it
Release script /trellis:assemble-release (recommended)	Most academic projects. Publish at discrete milestones.
git subtree push	If you want continuous sync between private and public.
Manual assembly	One-off publications.

Skills Reference

/trellis:init-research-project [name]

Scaffolds a new research project. In auto mode, creates the default template immediately. In interactive mode, asks about your setup.

Modes:

• Auto (default): > /trellis:init-research-project my-project
• Interactive: > /trellis:init-research-project my-project --interactive
• Dataset: > /trellis:init-research-project my-dataset --dataset

Interactive mode asks about: companion convention, shared datasets, data sensitivity level, target journal. Always previews the template before creating.

/trellis:generate-companions [directory]

Scans a directory for raw files without machine-readable companions. Spawns parallel agents to create them.

Examples:

• > /trellis:generate-companions materials/ — Process all materials
• > /trellis:generate-companions materials/instruments — Just instruments
• > /trellis:generate-companions materials/submissions/round-1 — Just this round of reviews

/trellis:check-project

Audits the project for completeness. Reports: missing companions, stale companions (source newer than .md), empty required documentation, unfilled template placeholders.

/trellis:process-reviews

Guides you through processing a new round of reviews. Creates companions for review PDFs, drafts a revision strategy, updates submission history.

/trellis:assemble-release

Builds the public replication package. Copies manuscript/ into _release/, runs PII safety checks, reports what's included and excluded.

Contributing

See CONTRIBUTING.md.

License

MIT. Your research projects are yours.