Generates structured data dictionaries in JSON and Markdown formats by profiling tabular datasets and flagging uninterpretable coded values.
- GitHub stars
- 378
- Files
- 4
- Last commit
- Nov 10, 2026
- License
- MIT
- Allowed tools
- —
What does the generate-codebook skill do?
generate-codebook generates structured data dictionaries in JSON and Markdown formats by profiling tabular datasets and flagging uninterpretable coded values.
Summary generated from the skill's SKILL.md.
About the generate-codebook skill
Creating structured data dictionaries from raw tabular datasets is the primary function of this skill. It allows researchers and developers to transform files like CSV, Excel, Parquet, Stata, or SAS datasets into machine-readable JSON and human-readable Markdown files. By running a local Python script, the tool profiles every variable to determine its type, range, missingness, and unique counts, producing codebook.json and codebook.md as outputs.
This tool is designed to prevent the common error of guessing the meaning of coded values. Instead of inventing labels for numeric codes, it uses a deterministic profiling process to flag uninterpretable values with a [NEEDS DICTIONARY] marker. Users must manually resolve these flags by providing authoritative meanings from their own sources. This ensures the resulting codebook remains a citable and accurate artifact for downstream analysis or quality control tasks.
Developers can control the profiling behavior using flags such as --max-levels to set a categorical cutoff or --json-only to limit the output format. Because the script runs locally using pandas, data remains private and is never sent to external services.
What an agent can do with it
- 1Generate a variable profileCreate a detailed summary of a CSV file including data types, missingness, and value ranges.
- 2Identify uninterpretable coded valuesFind columns where numeric codes lack clear definitions so they can be manually labeled.
- 3Prepare data for downstream automationProduce a machine-readable JSON file to serve as the input for variable definition tools.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the generate-codebook skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the generate-codebook skill in Plugin
/plugin marketplace add Aperivue/medsci-skills /plugin install medsci-data@medsci-skills
Install the generate-codebook skill in Claude Code
~/.claude/skills/generate-codebook/SKILL.md
$ npx degit Aperivue/medsci-skills/skills/generate-codebook ~/.claude/skills/generate-codebookInstall the generate-codebook skill in Claude Code (project)
.claude/skills/generate-codebook/SKILL.md
$ npx degit Aperivue/medsci-skills/skills/generate-codebook .claude/skills/generate-codebookInstall the generate-codebook skill in Codex
~/.agents/skills/generate-codebook/SKILL.md
$ npx degit Aperivue/medsci-skills/skills/generate-codebook ~/.agents/skills/generate-codebookInstall the generate-codebook skill in Gemini CLI
~/.gemini/skills/generate-codebook/SKILL.md
$ npx degit Aperivue/medsci-skills/skills/generate-codebook ~/.gemini/skills/generate-codebookInstall the generate-codebook skill in Claude.ai
npx degit Aperivue/medsci-skills/skills/generate-codebook generate-codebook && zip -r generate-codebook.zip generate-codebook # claude.ai → Customize → Skills → + → Create skill → Upload a skill → generate-codebook.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachableaperivue/medsci-skills/skills/generate-codebook is public and reachablegithub.com/aperivue/medsci-skills/tree/HEAD/skills/generate- ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-10github.com/aperivue/medsci-skills/commits ↗Pass
- No download-and-run or credential theft in scripts1 script read; no download-and-run, remote eval, base64 execution or credential uploadPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/aperivue/medsci-skills/blob/HEAD/skills/generate- ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/aperivue/medsci-skills/blob/HEAD/skills/generate- ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 84 linesgithub.com/aperivue/medsci-skills/blob/HEAD/skills/generate- ↗Pass
SKILL.md
View on GitHubGenerate 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:
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 flaggedneeds_dictionary. - An integer-coded column with more distinct values than
--max-levelsis classedcontinuousand is not flagged. The Step 2 role review is where such columns are caught. - The same holds for a
textcolumn holding number strings: any number value (45,88) is read as a measurement, so integer codes exported as strings with more than--max-levelsvalues 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 skill
4generate-codebook skill questions
How do I install the generate-codebook skill in Claude Code?
Run npx degit Aperivue/medsci-skills/skills/generate-codebook ~/.claude/skills/generate-codebook. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the generate-codebook skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
What file formats are supported for codebook generation?
The skill supports .csv, .tsv, .xlsx, .parquet, .dta, and .sas7bdat files.
How does the tool handle coded values that it cannot interpret?
It flags these values with a [NEEDS DICTIONARY] marker instead of guessing their meaning, requiring the user to provide the authoritative definitions.
Does the script send my data to an external server?
No, the script is pandas-only, runs locally, and never sends data anywhere.