fieldy
Skill0 starsChanged 3 months agoMITView on GitHub
Use when reading conversations, transcripts, summaries, or action items captured by a Fieldy AI wearable note taker, or when the user mentions Fieldy, their wearable, or wants the record of something said in person rather than on a video call. Covers API key setup, the time-window query model, pagination, and the async-processing and speaker-labelling gotchas that make naive reads report incomplete data.
- Reads credentials
In this repository36 other files it gives its agents.
- check-upstream-firstSkill
- data-verificationSkill
- deep-diveSkill
- delegation-handoffSkill
- grok-searchSkill
- is-it-really-brokenSkill
- keep-goingSkill
- learn-from-conversationsSkill
- memory-cleanupSkill
- moa-solveSkill
- mob-checkSkill
- multi-reviewSkill
- project-stewardSkill
- prove-the-setting-worksSkill
- recallSkill
- reportSkill
- robustify-doctorSkill
- skill-librarianSkill
- trust-frameworkSkill
- address-pr-commentsSkill
- diagram-renderingSkill
- find-the-real-bottleneckSkill
- live-database-maintenanceSkill
- mini-appSkill
- pr-review-sweepSkill
- scheduled-job-runnerSkill
- stop-the-noiseSkill
- upgrade-a-live-service-safelySkill
- vendor-switch-checkSkill
- writing-for-non-engineersSkill
- email-stewardSkill
- google-docsSkill
- google-sheetsSkill
- google-slidesSkill
- imessage-bluebubblesSkill
- vapi-callsSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 2 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 28
Use when the user mentions Fieldy, their wearable, or wants a real-world (non-video-call) conversation transcript, summary, or the action …
- Distinctive: line 38
If the user runs several capture devices (a meeting notetaker, a second pendant), coverage differs by device.
- Very specific: line 50
Verify: python3 scripts/fieldy.py whoami → returns {"email": "..."}.
- Very specific: line 151
Only then summarize. If the user asked what was actually _said_, do not answer from summary alone — that field is model output about the …
- Very specific: line 167
Default pageSize on conversations is 6.
- Very specific: line 188
Before any speaker profile exists, segments come back with speaker: "Unknown" and the conversation's speakers[] is empty.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Fieldy
When to Use
Use when the user mentions Fieldy, their wearable, or wants a real-world (non-video-call) conversation transcript, summary, or the action items the device captured. Also use when asked what was said in a specific in-person meeting, hallway conversation, or errand.
Fieldy is a wearable AI note taker (pendant or wrist, Bluetooth to a phone) with a companion desktop app that captures Zoom/Teams/Slack calls. It transcribes conversations and generates summaries, keywords, quotes, speaker labels, and action items. This skill reads that data over Fieldy's Public REST API.
If the user runs several capture devices (a meeting notetaker, a second pendant), coverage differs by device. A gap in Fieldy is not evidence the conversation never happened — check the other sources before concluding anything is missing.
Setup
- Open the Fieldy mobile app → Settings (gear icon) → Developer
Settings → copy the API key. It starts with
sk-fieldy-and is long-lived. The same screen exists in the desktop app. - Export it as
FIELDY_API_KEY, or put it in a0600dotenv file and pass--env-file /path/to/.env. It is a bearer token for the user's entire personal conversation history — treat it like a password. - Verify:
python3 scripts/fieldy.py whoami→ returns{"email": "..."}. A wrong key returns HTTP 401{"code":"UNAUTHORIZED"}with exit 1.
The client reads only the environment variable and an explicitly-passed
--env-file. It deliberately does not search config directories for a key:
an implicit scan on a multi-account machine can hand the caller a different
person's credential and silently return someone else's conversations. If several
agents share a host, give each one its own FIELDY_API_KEY.
API facts
Verified against the live API and its published OpenAPI 3.1.1 spec.
- Base URL:
https://api.fieldy.ai/api/public/v2 - Auth header:
Authorization: Bearer sk-fieldy-<key> - Rate limit: the API reference states 100 requests / 60s followed by a 60s
cooldown; the vendor's launch post says 30/min. Treat 30/min as the safe
budget and back off on
429. The bundled client sleeps between pages and retries429with escalating delay — but only forGET(see Pitfalls). - The API never legitimately redirects, and the client refuses redirects
outright. This is a security control, not politeness:
urllibreplays request headers on a redirect, so a302to another host would hand that host the bearer token. Verified by test. - There is no search endpoint. Every read is time-window based — pull a range
and filter locally. Do not look for a
?q=parameter; it does not exist. - Interactive docs:
https://api.fieldy.ai/docs(Scalar). The raw OpenAPI JSON is not served at/openapi.json,/docs/json, or/docs/openapi.json(all 404). It is embedded in the docs HTML asconst scalarConfig = {...}, where thecontentkey holds the whole spec as a JSON string. Extract withjson.JSONDecoder().raw_decodeon the text after that assignment, then a secondjson.loadsoncontent. A cached inventory of every endpoint, parameter, and response schema is inreferences/openapi-endpoints.md.
Endpoints
| Method | Path | Notes |
| GET | /user/me | returns {email} only — the cheapest auth probe |
| GET | /conversations | startTime+endTime required, ISO 8601; mode=starts-in-range|intersects-range, pageSize max 50 (default 6), cursor, recordingSource=wearable|phone|desktop |
| GET/PATCH/DELETE | /conversations/{id} | GET returns bare null for an unknown id, not a 404 |
| POST | /conversations | create |
| GET | /transcriptions | startTime required, endTime optional; conversationId, recordingSource, order=asc|desc, inclusive, pageSize max 1000, limit max 2000 |
| GET/POST/PATCH/DELETE | /tasks, /tasks/{id} | GET requires status (new/approved/completed/rejected/skipped/cancelled/expired) |
| GET/POST/PATCH/DELETE | /speaker-profiles, /speaker-profiles/{id} | |
| GET/POST/PATCH/DELETE | /memory-templates, /memory-templates/{id} | prompt templates that shape summaries |
| GET/POST/PATCH/DELETE | /sharables, /sharables/{id} | public share links; also GET /sharables?conversationId=, GET /sharables/resolve?idOrUrl= |
Response shapes
- Conversation:
id, title, summary, content, startTime, endTime, type(FULL|BRIEF), keywords[], speakers[], quotes[{text,context}], location{address,coordinates,city,...}, locationId, templateId, calendarEventId, updatedAt.memorySpeakersandmemoryTemplateIdare DEPRECATED aliases kept for old clients — usespeakersandtemplateId. - Transcription segment:
id, text, timestamp, speaker, speakerProfileId, start, end, createdAt, source, recordingSource.start/endare seconds offset within the recording;timestampis the absolute time. - List responses are
{items: [...], nextCursor: string|null}. Tasks return{items}with no cursor.
Usage
S=path/to/scripts/fieldy.py
python3 $S whoami # auth probe
python3 $S conversations --days 1 --text # last 24h, readable
python3 $S conversations --start 2026-05-01T00:00:00Z --end 2026-05-07T23:59:59Z
python3 $S conversation <id> # one conversation, full JSON
python3 $S transcript --conversation-id <id> --text # speaker-labelled transcript
python3 $S transcript --days 1 --source wearable --text
python3 $S tasks --status new
python3 $S speakers
python3 $S templates
python3 $S raw /sharables --param conversationId=<id> # any endpoint--text gives readable output on every subcommand; the default is JSON for
piping. --text, --verbose, and --env-file work on either side of the
subcommand.
--limit and --page-size exist only on conversations and transcript,
which are the paginated commands, and must be placed after that subcommand.
Passing them elsewhere is a hard argparse error rather than a silent no-op.
Pagination is automatic for conversations and transcript — those are the
only cursor-paginated endpoints. tasks, speakers, and templates return a
single page and do not accept --limit or --page-size. Within the paginated
commands the client follows nextCursor until the range is exhausted and never
requests a larger page than --limit needs. If it cannot
complete the walk — a repeated cursor, or the page cap — it exits nonzero
rather than printing a plausible-looking partial list. Pass --allow-partial to
accept a truncated result with a warning.
Mutating calls through raw require an explicit --yes.
Workflow: "what did I discuss about X this week"
conversations --days 7as JSON, then filter locally ontitle,summary,keywords, andquotes. There is no server-side search, so the filtering is yours to do.- For each hit,
transcript --conversation-id <id> --textto get the raw record. - Only then summarize. If the user asked what was actually said, do not
answer from
summaryalone — that field is model output about the conversation, while the transcript is the conversation. Quote the transcript.
MCP alternative
Fieldy also serves MCP at https://api.fieldy.ai/mcp (HTTP transport), offered
as a one-tap connector in Claude and ChatGPT. That path uses a browser-driven
OAuth handshake, and there is no documented way to authenticate it with a bare
sk-fieldy- key. For an agent writing code, prefer the REST API. Reach for
MCP only when the goal is Fieldy inside a chat client's connector UI.
Pitfalls
startTimeandendTimeon/conversationsare required. A bareGET /conversationsis a 400, not "everything".- Default
pageSizeon conversations is 6. An unpaginated call will happily report six conversations as though that were the whole week. Always follownextCursor. modedefaults tostarts-in-range, so a conversation that began before your window and ran into it is excluded. Useintersects-rangewhen the question is "what was happening at 3pm" rather than "what started today".- Transcripts are fetched by time range, not by conversation id alone. The
spec describes
conversationIdas "legacy client input resolved to canonical recording source". Resolve the conversation first and pass its realstartTime/endTime; do not assume the id filters on its own. Verified: a conversation-scoped fetch and a raw time-window fetch over the same interval returned identical segments. - Processing is async after a recording stops ("Sending to Private Cloud" →
"Transcribing" → "Generating Title"). A just-ended conversation can return a
null
title, nullsummary, emptyspeakers[], and zero transcript segments. That is not an API failure and not an empty conversation — retry later before reporting nothing was captured. - A recording has a 3-hour hard cap, so a long day is many conversations rather than one.
- The device only captures while transcription is running. A gap in the data means it was not recording, not that the API lost anything.
- Before any speaker profile exists, segments come back with
speaker: "Unknown"and the conversation'sspeakers[]is empty. Once a profile is created, segments label asSpeaker 1,Speaker 2, and so on. These are positional labels, not identities — a fresh account's only profile was namedUser. Do not promise "who said what" beyond what the labels support. GET /conversations/{id}with an unknown id returns HTTP 200 with a barenullbody rather than a 404. Check forNoneexplicitly or a downstreamconv["startTime"]raises an opaqueTypeError.- Transcripts are verbatim, including profanity, false starts, and whatever was said near the device by people who did not know it was recording. Treat the content as sensitive by default and do not echo more of it than the task needs.
- Partial results fail loudly. A truncated list printed with a normal
countis the worst outcome this client can produce: an agent reads it as the complete record of a week and reports that something was never discussed. Any incomplete pagination walk exits nonzero unless--allow-partialis given. Relatedly, an empty page mid-range is a hole rather than the end — the walk follows a live cursor past it. - Ids are percent-encoded before they reach the URL. Unencoded, a conversation
id of
x/../../user/metraverses to a different endpoint — verified: it returned the account profile instead of a conversation. Ids get interpolated from model output and transcript text routinely, so treat any id as untrusted. - The
rawpath argument must be a bare API path.?,#,://, and a leading//are rejected, and the rejection message deliberately does not echo the offending value, since the reason for rejecting it is that it may carry a secret. Query values go through--param. - Timestamps keep sub-second precision. Rounding
--startdown and--endup to whole seconds silently widens or narrows the window at the boundary, which changes which transcript segments come back. DELETEandPATCHmutate the user's personal record, andPOST /sharablesmints a publicly accessible link to a private conversation. They are reachable only throughraw --method ... --yes; there is no convenience subcommand for them by design. Never call one without an explicit instruction naming the target.- Only
GETis retried. A retriedPOST/PATCH/DELETEthat actually succeeded before the connection broke repeats the side effect — forPOST /sharablesthat means several public links to one private conversation. A failed mutation reportsOutcome UNKNOWNand stops; reconcile state before trying again. - Error output prints the endpoint path without the query string and redacts
anything matching
sk-..., because both can carry the key and API error bodies can quote transcript text.--verbosewidens the echoed body; use it when debugging, not in normal operation. - A time window is anchored to
--end, so--end <date> --days 7means the seven days before that date. An earlier version anchored the lookback to now, which silently producedstart > end— the API answers an inverted window with zero rows, and an agent then reports "nothing was discussed" when the query was simply malformed. Inverted or unparseable windows now exit 1.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

