fulcra-csv

Import CSV files into Fulcra accounts as timestamped annotation events.

10|1|Updated May 21, 2026
One-click install
npx skills add https://github.com/ashfulcra/fulcra-tools --skill fulcra-csv-ashfulcra
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: fulcra-csv
Source: https://github.com/ashfulcra/fulcra-tools/tree/main/packages/csv-importer/skills/fulcra-csv
Command: npx skills add https://github.com/ashfulcra/fulcra-tools --skill fulcra-csv-ashfulcra

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Getting timestamped data from arbitrary CSV exports (wearables, spreadsheets, Pipedream/IFTTT workflows) into a Fulcra account normally requires hand-writing API calls, managing annotation definitions, and building your own dedup logic. This Skill maps CSV columns onto Fulcra annotation events with deterministic source IDs so imports are idempotent and re-runnable. ## Core Features & Use Cases - Flexible column mapping: Map timestamp, title, value, note, tag, and duration columns to Fulcra DurationAnnotation or InstantAnnotation events, with type coercion and unit support. - Three target modes: Import into user-defined annotation definitions, built-in Fulcra types like BodyMass, or generic bootstrapped definitions. - Idempotent imports with export: Deterministic source IDs plus client-side dedup readback make re-imports safe, and the export command round-trips annotations back to CSV for auditing. - Use Case: A user has a spreadsheet of daily body weights and mood scores. Bootstrap a Mood definition, import the weight CSV against the built-in BodyMass type, and verify what landed with a filtered export. ## Quick Start Ask the agent to import your CSV file into Fulcra by running a dry-run first, for example: import my weights.csv into Fulcra as BodyMass instant annotations with the date and kg columns.

Frequently Asked Questions about fulcra-csv

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I import a CSV file into Fulcra?

Run fulcra-csv import with a target flag: --definition-id for a user-defined annotation or --data-type for a built-in type like BodyMass. Map your columns with --ts-col, --value-col, and related flags, and use --dry-run first to verify parsing.

How do I create a custom Fulcra annotation definition?

Use fulcra-csv bootstrap with --name, --annotation-type, and --value-type flags; it prints the new definition UUID. Save that UUID and pass it as --definition-id on subsequent imports.

Is it safe to re-run the same CSV import twice?

Yes, re-imports are idempotent. The importer generates deterministic source IDs from each row and reads back existing source IDs before posting, skipping rows that already landed.

Why don't my imported events appear in Fulcra queries right away?

Fulcra has an ingest-to-query indexing lag of seconds to minutes for bulk imports. Wait a few minutes and re-query rather than re-running the import.

Can I export Fulcra annotations back to CSV?

Yes, fulcra-csv export reads annotations by definition ID or data type within a time window and writes selected columns to CSV. It is a one-shot read, not an ongoing sync mechanism.

What timestamp formats does the CSV importer support?

The parser uses dateparser, so ISO 8601 and most common formats work. For naive local timestamps, pass --tz with an IANA timezone like America/New_York; unparseable values raise a ValueError.