| name | field-notes |
| description | User-owned external project notes in ~/.field_notes. Use when the user asks to check, search, read, save, append, update, or consult field notes; phrases include "check field notes", "look in field notes", "save to field notes", "what do field notes say", "what's next", progress notes, planning notes, external docs, cross-project memory, or docs that should live outside a repository. |
Field Notes
Field Notes are user-owned markdown notes outside any repo, stored at:
~/.field_notes
They are for cross-project memory: planning, progress, decisions, prompts, TODOs, and external docs that should not live in project repos or ~/.pi.
Rules
- Only consult Field Notes when explicitly requested or clearly implied by the user.
- Cite note paths when using them:
~/.field_notes/<file>.
- Prefer project/domain-prefixed filenames:
<project-or-domain>-<topic>.md.
- Flat files are encouraged; folders are allowed.
- Markdown is the default format.
- Do not store secrets.
- Do not overwrite notes unless the user asks. Prefer append/update by section.
Helper CLI
Use the bundled helper:
~/.agents/skills/field-notes/scripts/field-notes help
Common commands:
~/.agents/skills/field-notes/scripts/field-notes init
~/.agents/skills/field-notes/scripts/field-notes list
~/.agents/skills/field-notes/scripts/field-notes search "sample-app progress"
~/.agents/skills/field-notes/scripts/field-notes read sample-app-progress.md
~/.agents/skills/field-notes/scripts/field-notes new sample-app-progress --title "Sample App Progress"
~/.agents/skills/field-notes/scripts/field-notes append sample-app-progress.md "- Finished X"
The directory can be overridden for one command with:
FIELD_NOTES_DIR=/path/to/notes ~/.agents/skills/field-notes/scripts/field-notes list
Search workflow
When asked to check Field Notes:
- Run
field-notes init if ~/.field_notes does not exist.
- Search filenames and content with the user/project terms:
~/.agents/skills/field-notes/scripts/field-notes search "<query>"
- Read the best matching notes:
~/.agents/skills/field-notes/scripts/field-notes read <relative-path>
- Answer using only relevant excerpts and cite files.
If the query is vague, infer the current project name from cwd and include it in the search. Example from /Users/mikker/dev/acme/sample-app: search sample-app progress next tasks.
Save/update workflow
When asked to save to Field Notes:
- Pick a filename using
<project-or-domain>-<topic>.md unless the user specifies one.
- Create the note if missing.
- Append dated content unless the user asks to rewrite/replace.
- Keep notes concise and scannable.
Good headings:
# Sample App Progress
## 2026-06-19
- Done: ...
- Next: ...
- Open questions: ...
