Note Taking

Manage user's persistent note-taking system ("second brain") stored in markdown files. All operations go through notes_manager.py script.

YOU MUST ALWAYS:

• Use scripts/notes_manager.py for ALL note operations
• Pass JSON commands via stdin to the script
• Parse JSON responses and present them conversationally

YOU MUST NEVER:

• Use Read, Write, or Edit tools on note files in ~/Documents/notes/ or ~/OneDrive/Documents/notes/
• Bypass the script to manipulate .index.json or markdown files directly

Path Requirements:

• Use tilde ~/.claude/plugins/... (expands on all platforms)
• Use forward slashes / (works on Windows) - NEVER backslashes
• Use python (not python3)
• Use double quotes with escaped inner quotes

Pattern:

echo "{\"command\":\"\",\"param\":\"value\"}" | python ~/.claude/plugins/marketplaces/productivity-skills/plugins/productivity-suite/skills/note-taking/scripts/notes_manager.py

Script auto-detects notes directory (OneDrive on Windows, Documents otherwise, or $NOTES_DIR if set).

{"command":"add","heading":"Category - Brief description","content":"Note text"} {"status":"success","file":"2025/11-November.md","heading":"Work - Title","path":"/full/path.md"}

Always "Category - Description". Never "Untitled". Infer category from keywords:

• Work: "fixed", "built", "implemented", "deployed"
• Learning: "learned", "discovered", "realized"
• Meeting: "meeting", "discussed", "decided in meeting"
• Idea: "what if", "consider", "idea"
• Decision: "decided", "will", "plan to"
• Question: "how", "why", "question about"
• Reference: "record", "bookmark", "found"
• Note: "note that", "remember"

{"command":"search","query":"search terms"} [{"heading":"Work - Title","content":"Preview...","file":"2025/11-November.md","date":"2025-11-17","relevance":520}] Returns max 10 matches. Empty [] if none. Present high relevance (>=500) in full detail; multiple results by relevance with dates.

{"command":"append","searchterm":"unique term","content":"Update text"} {"status":"success","heading":"Work - Title","file":"2025/11-November.md","alternatives":[]} {"status":"notfound","query":"term","suggestion":"No matching entry found. Create a new note?"} {"status":"ambiguous","query":"term","alternatives":[{"heading":"Work - Title","relevance":45}],"message":"No strong match found."} Requires relevance >=50. If weak match, suggest alternatives or create new note.

{"command":"reindex"} {"status":"success","totalfiles":12,"totalentries":145}

{"command":"stats"} {"status":"success","total_entries":145,"categories":{...}}

{"command":"info"} {"status":"success","notesdir":"/path","onedrivedetected":true}

{"command":"validate"} {"status":"success","files_checked":12,"issues":[...]}

{"command":"clean-index"} {"status":"success","message":"Removed and rebuilt"}

{"command":"migrate","source_dir":"/path/to/source"} {"status":"success","imported":23,"skipped":2}

Add: Infer category from keywords -> extract topic -> format "Category - Description" -> execute add -> confirm

Search: Extract terms -> execute search -> parse by relevance -> present with dates -> summarize

Update: Extract search term -> execute append -> check status -> handle weak matches -> confirm with timestamp

All commands include status field. Check for:

{"status":"error","message":"Description of error"}

When errors occur, inform user clearly and suggest corrective action.

Script automatically adds **Created:** YYYY-MM-DD to new notes and **Update (YYYY-MM-DD):** to updates.

Categories: Work, Learning, Meeting, Idea, Decision, Question, Reference, Note

• Note operations complete with "success" status
• User receives conversational confirmation
• Search returns relevant results sorted by relevance score
• Updates append to correct entry with timestamp

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mcdow-webworks
• Source: mcdow-webworks/productivity-skills
• License: MIT

Install and usage instructions live in the source repository linked above.