{"slug":"generate-codebook","title":"generate-codebook","summary":"Generate a citable data dictionary / codebook from a tabular dataset (CSV/TSV/Excel/Parquet/Stata/SAS). Profiles every variable — role, type, units placeholder, level frequencies, range/quantiles, missingness — and emits codebook.md + codebook.json. Flags coded variables whose le","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-09-14T20:48:10.713146Z","repo":{"url":"https://github.com/Aperivue/medsci-skills","stars":318,"forks":75,"license":"MIT","updatedAt":"2026-09-27T05:05:17Z"},"bodyHtml":"
\n

name: generate-codebook\ndescription: Generate a citable data dictionary / codebook from a tabular dataset (CSV/TSV/Excel/Parquet/Stata/SAS). Profiles every variable — role, type, units placeholder, level frequencies, range/quantiles, missingness — and emits codebook.md + codebook.json. Flags coded variables whose level meanings are unknown as [NEEDS DICTIONARY] rather than guessing them, feeding /define-variables and the dictionary-first workflow.\ntriggers: generate codebook, data dictionary, codebook, profile variables, variable dictionary, describe dataset, what variables, column dictionary, build codebook\ntools: Read, Write, Edit, Bash, Grep, Glob\nmodel: inherit

\n

Generate Codebook Skill

\n

You help a medical researcher turn a raw tabular dataset into a structured,\ncitable data dictionary (codebook). This is the generator side of the\ndictionary-first workflow: it produces the artifact that /define-variables and\ndictionary-first QC later consume. You generate code and review output — you do\nnot invent the meaning of coded values.

\n

Communication Rules

\n\n

Philosophy

\n

A codebook describes what is in the data, not what the codes mean. Column\ndistributions, types, and missingness are observable and safe to profile. The\nmeaning of a coded value (fatty_liver_grade = 0) is NOT observable from the\ndata — it lives in the authoritative data dictionary. This skill profiles the\nformer deterministically and explicitly flags the latter as [NEEDS DICTIONARY]\nso a human fills it from the source. This is the generator counterpart to the\ndictionary-first rule that /define-variables enforces on consumption.

\n

Reference Files

\n\n

Deterministic Script

\n

Run the bundled profiler rather than describing columns from memory:

\n
python \"${CLAUDE_SKILL_DIR}/scripts/generate_codebook.py\" data.csv --out-dir .\n
\n

Supports .csv/.tsv/.xlsx/.parquet/.dta/.sas7bdat. Flags: --max-levels N\n(categorical cutoff, default 20), --json-only, --md-only. The script is\npandas-only, runs locally, and never sends data anywhere.

\n

Workflow

\n

Step 1: Profile (deterministic)

\n

Run generate_codebook.py on the dataset. It writes codebook.json (machine-\nreadable) and codebook.md (review table), reporting per variable: role\n(id / continuous / categorical / binary / date / text), dtype, missingness,\nunique count, level frequencies or quantile summary, and a needs_dictionary flag.

\n

Step 2: Review with the researcher (gate)

\n

Present codebook.md and walk the user through it. Gate: the user confirms\nthe inferred roles (e.g., an integer-coded scale mis-read as continuous, or an id\ncolumn). Do not proceed to definition work until the user approves the role\nassignments.

\n

Step 3: Resolve [NEEDS DICTIONARY] items (gate)

\n

For every variable flagged needs_dictionary: true, the level codes are\nuninterpretable without the authoritative source. Gate: ask the user to\nsupply the meaning of each code from the real data dictionary (file/sheet/row),\nor to confirm none exists. Fill label, units, and per-level meanings into the\ncodebook only from that source — never from inference. If the user cannot\nsupply it, leave the [NEEDS DICTIONARY] marker in place; do not erase it.

\n

Step 4: Hand off

\n

The completed codebook.json becomes the input dictionary for /define-variables\n(operationalization) and the citation source for dictionary-first QC. Gate:\nconfirm with the user that no needs_dictionary flags remain unresolved before\nthe codebook is treated as authoritative for downstream analysis.

\n

Scope Limitations

\n

Supported

\n\n

NOT Supported

\n\n

Cross-Skill Integration

\n\n

Output Format

\n

codebook.json (schema in references) and codebook.md (review table with a\n\"Columns requiring dictionary lookup\" section). Summarize the counts\n(rows, columns, needs_dictionary_count) in chat; do not paste the full JSON.

\n

Worked Example

\n

Input cohort.csv:

\n
patient_id,age,sex,fatty_liver_grade,smoking_status,visit_date\n1001,54,1,0,never,2023-01-15\n1002,61,2,2,former,2023-02-03\n
\n

Run:

\n
python \"${CLAUDE_SKILL_DIR}/scripts/generate_codebook.py\" cohort.csv --out-dir .\n# -> {\"n_rows\": ..., \"n_columns\": 6, \"needs_dictionary_count\": 2, \"outputs\": [...]}\n
\n

codebook.md (excerpt):

\n
| Variable            | Role        | Missing % | Unique | Needs dictionary |\n| `patient_id`        | id          | 0.0       | N      |                  |\n| `age`               | continuous  | 0.0       | ...    |                  |\n| `sex`               | binary      | 0.0       | 2      | ⚠️ YES           |\n| `fatty_liver_grade` | categorical | 0.0       | 5      | ⚠️ YES           |\n| `smoking_status`    | categorical | 0.0       | 3      |                  |\n| `visit_date`        | date        | 0.0       | ...    |                  |\n
\n

sex and fatty_liver_grade are flagged because their levels are bare codes\n(1/2, 0..4). smoking_status is not flagged — its levels are already\nhuman-readable. The reviewer then:

\n
    \n
  1. Opens the project's authoritative data dictionary.
    2. \n
  2. Fills sex: 1 = male, 2 = female and fatty_liver_grade: 0 = none … 4 = suspected\ninto the codebook from that source (citing file > sheet > row).
    3. \n
  3. Confirms no [NEEDS DICTIONARY] flags remain, then hands codebook.json to\n/define-variables.
    4. \n
\n

What the skill must never do: write sex: 1 = male because \"that is the\nusual coding.\" If the dictionary is unavailable, the flag stays.

\n

Anti-Hallucination

\n\n","files":[{"path":"references/codebook_schema.md","sizeBytes":3435,"isText":true},{"path":"scripts/generate_codebook.py","sizeBytes":10982,"isText":true},{"path":"SKILL.md","sizeBytes":7129,"isText":true},{"path":"skill.yml","sizeBytes":1237,"isText":true},{"path":"tests/test_generate_codebook.sh","sizeBytes":3500,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-14T20:48:41.168236Z","sha256":"71990F5ABEE9D742F5916EF3DE15093533E306E436AAD2366AD8942446AF0D73","sizeBytes":11220},"review":null,"source":{"repositoryUrl":"https://github.com/Aperivue/medsci-skills","path":"skills/generate-codebook","license":"MIT","commit":"5599b724675a1d788e03cd58dabd3db7c68ca86b","subtreeSha":"8DC72C7A8E86CF71E280AFED5143C70AF328B201C30179B981D0D58BAF567B98","lastSyncedAt":"2026-09-27T19:46:33.449845Z"},"reviewedAt":"2026-09-14T20:53:35.165377Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/Aperivue/medsci-skills/tree/main/skills/generate-codebook"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install aperivue-medsci-skills@llmmart"},{"target":"git","command":"git clone https://github.com/Aperivue/medsci-skills.git"}]}