research-repo

Name: research-repo
Author: scdenney

34stars0forks

How to install research-repo?

scdenney/open-science-skills/research-repo

$npx -y skills add scdenney/open-science-skills --skill research-repo

Installs into the current project.

Summary

Scaffold or audit an entire research project repository organized around its source library. Use when starting, structuring, organizing, or reviewing a research repo. Build sources/{og,md,unprocessed}, references.bib, a PDF-to-Markdown converter, a repo-local process-source skill

Files · 1

View on GitHub

SKILL.md

1	# Research Repository Scaffold & Audit
2
3	## Scope and organizing principle
4
5	This skill sets up a new research repository, or audits an existing one, around a single organizing principle: the source library is the spine of the project, and everything else grows from it.
6
7	A research repo is not a pile of folders. It is a knowledge base (`sources/`) with work built around it. The papers you read become a tracked, LLM-readable corpus; that corpus is keyed to a bibliography; the bibliography is what your manuscript cites; the analysis and writing folders consume the corpus and produce the outputs. Get the spine right and the rest of the repo has an obvious place to live. Get it wrong — PDFs scattered, no Markdown, a bib that does not match what you actually read — and every downstream skill (`literature-review`, `citation-check`, `fact-check`, `paper-tex`) is working on sand.
8
9	The spine has five parts:
10
11	1. `sources/og/` — original PDFs/documents. Archival, gitignored (size + copyright). You rarely read these directly.
12	2. `sources/md/` — Markdown conversions, tracked in git. This is the LLM-readable knowledge base — always read sources from here, not from the PDFs.
13	3. `sources/unprocessed/` — drop zone. New PDFs land here until they are named, converted, and filed.
14	4. `sources/references.bib` — the bibliography. One entry per source, author+year resolvable to its `md/` file, so the manuscript's `\cite` keys map to documents you have actually read.
15	5. A conversion script + an intake command — `scripts/convert-sources.sh` (OpenDataLoader PDF) turns `og/.pdf` into `md/.md`; a `process-source` command runs the per-PDF intake (identify → rename → convert → add to bib).
16
17	Everything else — `data/`, analysis `scripts/`, `manuscript/` or `paper/`, `review/` + `codebook/`, `figures/`, `tables/`, `replication/` — is built outward from that spine, conditioned on what kind of project this is.
18
19	This skill does the architecture. It does not process individual PDFs (that is `process-source`) and it does not build the public replication package (that is `replication-package`). It creates or audits the structure those skills operate inside.
20
21	## Instructions
22
23	### Step 1. Resolve the target and decide the mode
24
25	Use the path supplied with the invocation; otherwise default to the current working directory and confirm once before writing into it. Then decide the mode from what is there:
26
27	- Scaffold mode — the directory is empty, is not yet a git repo, or has no `sources/` and no manuscript. You will build the spine and the outward folders.
28	- Audit mode — the directory already has research content (a `sources/` tree, a manuscript, analysis scripts, a bib). You will read what exists, compare it against the convention, and report present / partial / missing. Never overwrite an existing file without explicit confirmation; offer to create only what is missing.
29
30	If a repo is half-built (e.g. PDFs exist but no `md/`, or an `og/` with no convert script), that is audit mode with scaffolding gaps — report the gaps and offer to fill them.
31
32	### Step 2. Identify the project archetype
33
34	The bibliography is the spine of every project; the outward folders — and whether a PDF corpus is even appropriate — depend on what the project is. Detect the archetype from concrete signals in the directory (or ask one question if it is genuinely ambiguous). Do not force a paper-centric layout onto a literature review, or a PDF corpus onto a theory paper.
35
36	\| Archetype \| Concrete signals \| Outward folders to scaffold \|
37	\|-----------\|------------------\|------------------------------\|
38	\| Literature / systematic review \| many `sources/md/` files; a coding protocol; an inventory CSV \| `review/` (inventory CSV + per-source annotations), `codebook/` (evaluation protocol), `data/` (open datasets collected) \|
39	\| Empirical analysis / paper \| data files (`.csv`, `.dta`) beside estimation scripts (`.R`, `.do`, `*.py`); a manuscript heading to a journal \| `data/`, `scripts/` (analysis), `paper/` or `manuscript/`, `figures/`, `tables/`, `replication/` \|
40	\| Corpus / digitization \| scanned images / OCR output; a large derived corpus \| `data/` (raw + derived corpus), `scripts/` (OCR/cleanup pipeline), plus `sources/` for the methods literature \|
41	\| Lightweight / theory paper \| a manuscript and a `.bib` but no archived PDFs and no large dataset \| a `paper/` or `manuscript/` folder and its `.bib`; no `sources/` PDF corpus unle

People who liked this also viewed

6 picks

Type

research-repo

34stars0forks

View on GitHub

How to install research-repo?

scdenney/open-science-skills/research-repo

$npx -y skills add scdenney/open-science-skills --skill research-repo

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Research Repository Scaffold & Audit
2
3	## Scope and organizing principle
4
5	This skill sets up a new research repository, or audits an existing one, around a single organizing principle: the source library is the spine of the project, and everything else grows from it.
6
7	A research repo is not a pile of folders. It is a knowledge base (`sources/`) with work built around it. The papers you read become a tracked, LLM-readable corpus; that corpus is keyed to a bibliography; the bibliography is what your manuscript cites; the analysis and writing folders consume the corpus and produce the outputs. Get the spine right and the rest of the repo has an obvious place to live. Get it wrong — PDFs scattered, no Markdown, a bib that does not match what you actually read — and every downstream skill (`literature-review`, `citation-check`, `fact-check`, `paper-tex`) is working on sand.
8
9	The spine has five parts:
10
11	1. `sources/og/` — original PDFs/documents. Archival, gitignored (size + copyright). You rarely read these directly.
12	2. `sources/md/` — Markdown conversions, tracked in git. This is the LLM-readable knowledge base — always read sources from here, not from the PDFs.
13	3. `sources/unprocessed/` — drop zone. New PDFs land here until they are named, converted, and filed.
14	4. `sources/references.bib` — the bibliography. One entry per source, author+year resolvable to its `md/` file, so the manuscript's `\cite` keys map to documents you have actually read.
15	5. A conversion script + an intake command — `scripts/convert-sources.sh` (OpenDataLoader PDF) turns `og/.pdf` into `md/.md`; a `process-source` command runs the per-PDF intake (identify → rename → convert → add to bib).
16
17	Everything else — `data/`, analysis `scripts/`, `manuscript/` or `paper/`, `review/` + `codebook/`, `figures/`, `tables/`, `replication/` — is built outward from that spine, conditioned on what kind of project this is.
18
19	This skill does the architecture. It does not process individual PDFs (that is `process-source`) and it does not build the public replication package (that is `replication-package`). It creates or audits the structure those skills operate inside.
20
21	## Instructions
22
23	### Step 1. Resolve the target and decide the mode
24
25	Use the path supplied with the invocation; otherwise default to the current working directory and confirm once before writing into it. Then decide the mode from what is there:
26
27	- Scaffold mode — the directory is empty, is not yet a git repo, or has no `sources/` and no manuscript. You will build the spine and the outward folders.
28	- Audit mode — the directory already has research content (a `sources/` tree, a manuscript, analysis scripts, a bib). You will read what exists, compare it against the convention, and report present / partial / missing. Never overwrite an existing file without explicit confirmation; offer to create only what is missing.
29
30	If a repo is half-built (e.g. PDFs exist but no `md/`, or an `og/` with no convert script), that is audit mode with scaffolding gaps — report the gaps and offer to fill them.
31
32	### Step 2. Identify the project archetype
33
34	The bibliography is the spine of every project; the outward folders — and whether a PDF corpus is even appropriate — depend on what the project is. Detect the archetype from concrete signals in the directory (or ask one question if it is genuinely ambiguous). Do not force a paper-centric layout onto a literature review, or a PDF corpus onto a theory paper.
35
36	\| Archetype \| Concrete signals \| Outward folders to scaffold \|
37	\|-----------\|------------------\|------------------------------\|
38	\| Literature / systematic review \| many `sources/md/` files; a coding protocol; an inventory CSV \| `review/` (inventory CSV + per-source annotations), `codebook/` (evaluation protocol), `data/` (open datasets collected) \|
39	\| Empirical analysis / paper \| data files (`.csv`, `.dta`) beside estimation scripts (`.R`, `.do`, `*.py`); a manuscript heading to a journal \| `data/`, `scripts/` (analysis), `paper/` or `manuscript/`, `figures/`, `tables/`, `replication/` \|
40	\| Corpus / digitization \| scanned images / OCR output; a large derived corpus \| `data/` (raw + derived corpus), `scripts/` (OCR/cleanup pipeline), plus `sources/` for the methods literature \|
41	\| Lightweight / theory paper \| a manuscript and a `.bib` but no archived PDFs and no large dataset \| a `paper/` or `manuscript/` folder and its `.bib`; no `sources/` PDF corpus unle

People who liked this also viewed

6 picks

Type