Using Tidyjs
Developmentusing-tidyjsUsing Tidyjs is an Agent Skill for development published in the pbeshai/tidy repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Write correct, idiomatic tidyjs code. Activates when the user works with @tidyjs/tidy imports, mentions tidyjs, or asks about JavaScript data wrangling in a project that uses tidyjs.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/pbeshai/tidy/blob/HEAD/skills/using-tidyjs/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/using-tidyjs, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Before writing any tidyjs code, you MUST read the relevant docs. tidyjs has a distinctive pipeline pattern and function taxonomy that differs from pandas, SQL, and lodash. Pre-training knowledge is often wrong for this library — always prefer the docs.
Locating the docs
The genai-docs should be found at one of these locations. Check in order:
- npm package:
node_modules/@tidyjs/tidy/genai-docs/
If found, use that path as DOCS_ROOT below and proceed to How to navigate.
If docs are not found locally
Fetch them from the public docs site. The AI-optimized docs are available at:
https://pbeshai.github.io/tidy/genai-docs/
The site also has llms.txt at https://pbeshai.github.io/tidy/llms.txt with a full index.
Key files to fetch:
https://pbeshai.github.io/tidy/genai-docs/mental-model.md— start herehttps://pbeshai.github.io/tidy/genai-docs/quick-reference.md— task-to-function lookuphttps://pbeshai.github.io/tidy/genai-docs/gotchas.md— common mistakes- Then fetch specific
api-*.mdfiles as needed
How to navigate
- Start: Read
DOCS_ROOT/mental-model.mdfor the pipeline pattern, accessor conventions, and function taxonomy. This is essential before writing any code. - Quick lookup: Read
DOCS_ROOT/quick-reference.mdto find which function to use for a given task. - API details: Read the relevant
api-*.mdfile for function signatures, parameters, and examples:- Core verbs (tidy, filter, mutate, arrange, select, etc.):
api-core.md - Grouping:
api-grouping.md - Summarize + aggregation functions:
api-summarize.md - Vector/cross-item operations:
api-vector.md - Joins:
api-joins.md - Pivoting:
api-pivot.md - Slicing:
api-slice.md - Column selectors:
api-selectors.md - Sequences:
api-sequences.md - Other (complete, expand, fill, TMath, etc.):
api-other.md
- Core verbs (tidy, filter, mutate, arrange, select, etc.):
- Recipes: Read
DOCS_ROOT/patterns.mdfor multi-verb composition patterns. - Avoid mistakes: Read
DOCS_ROOT/gotchas.mdbefore finalizing code.
Key principles
- Always read before writing: Read the relevant api doc for every function you use.
- Pipeline pattern: All transformations flow through
tidy(data, verb1(), verb2()). Verbs are curried functions. - Accessor functions, not strings: Use
(d) => d.columnfor field access, not string column names (except in summary functions likesum('key')and sort helpers likedesc('key')). - mutate vs mutateWithSummary:
mutateis per-item(item, index, array) => value.mutateWithSummaryreceives the full array(items[]) => value[] | value. Using summary/vector functions insidemutate()is a silent bug. Always checkgotchas.mdif unsure. - groupBy export modes: Without an export option,
groupByreturns a flat array. WithgroupBy.object(),.entries(),.map(), etc., the output shape changes. Export modes must be the last pipeline step. - Check the function taxonomy: Summary functions go inside
summarize(). Vector functions go insidemutateWithSummary(). Item functions go insidemutate(). Selectors go insideselect(). Getting this wrong produces incorrect results.