Agent skill · writing content · thebushidocollective
notetaker-fundamentals
Use when leaving structured notes, comments, and annotations in code. Covers AI note-taking patterns, TODO formats, context preservation, and development breadcrumbs for future AI assistants and human developers.
Why this skill is useful
Provides structured note-taking formats and patterns that enhance context preservation and decision documentation in codebases.
What it needs
About 7k tokens when loaded. Last updated 2026-07-19. 187 stars on the source repository.
What this skill does
Note-Taking Fundamentals for AI-Assisted Development Effective note-taking patterns for AI assistants to leave meaningful context in codebases. Philosophy When AI assistants make changes to code, they should leave breadcrumbs for future AI assistants and human developers. Notes should: Preserve context about why decisions were made Signal uncertainty where alternative approaches exist Mark incomplete work that needs follow-up Link to relevant context (issues, PRs, documentation) Explain non-obvious patterns that might confuse readers Note Formats AI Development Notes Special comment format for AI-to-AI communication: When to use: Explaining non-obvious implementation decisions Documenting alternative approaches that were considered Linking to related context (PRs, issues, discussions) Warning about subtle bugs or edge cases Preserving rationale for future refactoring decisions Structured TODO Comments Enhanced TODO format with context: TODO Format Structure: Common categories: ai/refactor - Code structure improvements ai/performance - Optimization opportunities ai/security - Security considerations ai/accessibility - A11y improvements ai/testing - Test coverage gaps ai/docs - Documentation needs ai/context - Context preservation ai/edge-case - Unhandled edge cases Decision Records Inline decision records for significant choices: When to use decision records: Choosing between competing patterns/libraries Performance trade-offs (memory vs speed, etc.) Architecture decisions affecting multiple files Security-sensitive choices Decisions that will be questioned later Context Preservation Leaving breadcrumbs for future understanding: Uncertainty Markers Signaling areas where AI is uncertain: Note Placement Guidelines Where to Place Notes Good placements: Bad placements: Proximity Rules Place notes immediately before the code they describe For file-level notes, place at the top after imports For function-level notes, place immediately before the function For inline notes, …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills thebushidocollective/note-taking-fundamentals