Skip to content
Skills Library
Data & analytics · Analysis

generate-codebook

/generate-codebook

Use when a tabular dataset (CSV, Excel, Parquet, Stata, SAS) needs a data dictionary. Profiles every variable (type, levels, range, missingness) into codebook.md and codebook.json and flags coded values of unknown meaning as [NEEDS DICTIONARY] instead of guessing.

Licence
MIT
Last repository change
22.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
5
Scripts
2
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 22.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 2 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/generate_codebook.py, tests/test_generate_codebook.sh

What it does and when to use it

Use when a tabular dataset (CSV, Excel, Parquet, Stata, SAS) needs a data dictionary. Profiles every variable (type, levels, range, missingness) into codebook.md and codebook.json and flags coded values of unknown meaning as [NEEDS DICTIONARY] instead of guessing.

Original author description

Use when a tabular dataset (CSV, Excel, Parquet, Stata, SAS) needs a data dictionary. Profiles every variable (type, levels, range, missingness) into codebook.md and codebook.json and flags coded values of unknown meaning as [NEEDS DICTIONARY] instead of guessing.

How it works

  1. Deterministic Script
  2. Workflow
  3. Known limits
  4. Output Format
Original SKILL.md headings · 78 lines, 558 words
SKILL.md preview
---
name: generate-codebook
description: Use when a tabular dataset (CSV, Excel, Parquet, Stata, SAS) needs a data dictionary. Profiles every variable (type, levels, range, missingness) into codebook.md and codebook.json and flags coded values of unknown meaning as [NEEDS DICTIONARY] instead of guessing.
metadata:
  triggers: "generate codebook, data dictionary, codebook, profile variables, variable dictionary, describe dataset, what variables, column dictionary, build codebook"
---

# Generate Codebook Skill

Turn a raw tabular dataset into a structured, **citable** data dictionary (codebook). This is the
*generator* side of the dictionary-first workflow: it produces the artifact that `/define-variables`
and dictionary-first QC later consume. Distributions, types, and missingness are observable and the
bundled script profiles them; the **meaning** of a coded value (`fatty_liver_grade = 0`) is not
observable from the data and lives only in the authoritative data dictionary. You generate code and
review output — you do **not** invent the meaning of coded values.

## Deterministic Script

Run the bundled profiler rather than describing columns from memory:

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

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

## Workflow

### Step 1: Profile (deterministic)

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

### Step 2: Review with the researcher (gate)

Read `${CLAUDE_SKILL_DIR}/references/codebook_schema.md` (the codebook.json schema, the
role-inference heuristics, the `needs_dictionary` rule) before interpreting the output. Present
`codebook.md` and walk the user through it. **Gate:** role inference is a heuristic, so the user
confirms the inferred roles (e.g., an integer-coded scale mis-read as continuous, or an id column).
Do not proceed to definition work until the user approves the role assignments.

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

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

Example: in a cohort file, `sex` (levels `1/2`) and `fatty_liver_grade` (`0..4`) are flagged because
their levels are bare codes; `smoking_status` (`never/former/current`) is not. Never write
`sex: 1 = male` because "that is the usual coding" — if the dictionary is unavailable, the flag stays.

### Step 4: Hand off

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

Run `/deidentify` on the raw data before a codebook is shared externally. Cleaning or transforming
data is `/clean-data`.

## Known limits

- Codes longer than 3 characters that are not numbers (`C50.9`, `S001`) are not recognised as
  codes, so their column is not flagged `needs_dictionary`.
- An integer-coded column with more distinct values than `--max-levels` is classed `continuous`
  and is not flagged. The Step 2 role review is where such columns are caught.
- The same holds for a `text` column holding number strings: any number value
  (`45`, `88`) is read as a measurement, so integer codes exported as strings
  with more than `--max-levels` values are not flagged.

## Output Format

`codebook.json` (schema in references) and `codebook.md` (review table with a
"Columns requiring dictionary lookup" section). Summarize the counts
(rows, columns, `needs_dictionary_count`) in chat; do not paste the full JSON.
Files in this package (5)
  • SKILL.md 4 KB
  • skill.yml 1 KB
  • references/codebook_schema.md 4 KB
  • scripts/generate_codebook.py 13 KB
  • tests/test_generate_codebook.sh 7 KB

Versions

The database has no other skills named generate-codebook.

Database snapshot: 13.11.2026 · package version b049ab047c45 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100data-dictionary-creator
    Generate a data dictionary for a dataset, combining automatic profiling with the user's description of what the data represents. Use when the user wants documentation of columns — names, types, semantic meaning, units, allowed values, and nullability — for a CSV/Parquet/Excel file.
  • 100np-research-variable-dictionary
    Create a research data dictionary. Use when a researcher needs consistent definitions before combining or analysing data.
  • 100tabular-cleanup
    Use when the user has a messy tabular data dump (CSV/TSV/parquet/Excel/JSON) and wants it iteratively cleaned to an inferred data contract — a checklist of deterministic pass/fail checks, not a quality score. A single agent profiles the table, synthesizes a per-column contract…
  • 100stata-cli
    Use the local `stata-cli` command for Stata work on this machine. Trigger this skill when the user wants to bootstrap an AI-ready Stata workspace, write or debug `.do` files, inspect `.dta` data, export CSVs, or needs Stata syntax/package guidance while staying inside the local `stata-cli` workflow.
  • 90sweet
    Work on tabular data (CSV, Parquet, JSON, Excel, S3, Hugging Face datasets) in the Sweet terminal viewer through its MCP tools. Use when the user asks to explore, clean, profile, reshape, or compare data, wants to see the data while you work, or mentions Sweet.
  • 100data-dictionary
    Generate a data dictionary documenting entities, fields, and business rules. Use when the user says "data dictionary", "document the data model", "what fields are in this table", "data definitions", "field descriptions", "CRUD matrix", "entity relationship", "data catalogue",…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.