ai-notes
Manage AI notes in ~/Compost/AI-Notes - read existing notes, list recent documents, and write new implementation plans. Auto-triggers when reading from or writing to notes.
When & Why to Use This Skill
The AI Notes skill is a robust documentation management system designed to organize AI-generated insights, implementation plans, and technical specifications within a structured local environment. It automates file path generation using timestamped conventions, supports advanced search via Grep and Glob tools, and enforces professional standards for bilingual documentation (Japanese/English) and Mermaid diagrams. This skill is essential for developers and researchers looking to build a persistent, searchable, and well-organized repository of AI-assisted work.
Use Cases
- Technical Documentation & Planning: Streamline the creation of implementation plans (仕様書), design docs, and architecture specifications with automated, timestamped file organization.
- Efficient Information Retrieval: Quickly locate past insights or specific code snippets using the list, grep, and pattern-matching tools across a large volume of notes.
- Complex Project Structuring: Use the 'multiple documents' feature to generate organized directory structures for large-scale projects requiring several related technical files.
- Bilingual Workflow Management: Maintain high-quality documentation with Japanese narrative text while ensuring code comments remain in English for global technical standards.
| name | ai-notes |
|---|---|
| description | Manage AI notes in ~/Compost/AI-Notes - read existing notes, list recent documents, and write new implementation plans (仕様書, 計画書, 設計書). Auto-triggers when reading from or writing to notes, specifications, or plans. |
Notes Management Script
IMPORTANT: Use the notes.ts script for all AI notes operations.
# Script location
~/.claude/skills/ai-notes/notes.ts
Generate Output Path
Generate correct file paths for new notes:
# Single document
deno run -A ~/.claude/skills/ai-notes/notes.ts generate "<title>"
# => ~/Compost/AI-Notes/2025-12/24-0821-<title>.md
# Multiple documents (returns directory path)
deno run -A ~/.claude/skills/ai-notes/notes.ts generate "<title>" --multiple
# => ~/Compost/AI-Notes/2025-12/24-0821-<title>/
List Existing Notes
List notes ordered by file path (newest first) with H1 titles:
# List all notes
deno run -A ~/.claude/skills/ai-notes/notes.ts list
# List 10 most recent notes
deno run -A ~/.claude/skills/ai-notes/notes.ts list --limit 10
# Pagination: skip first 10, show next 10
deno run -A ~/.claude/skills/ai-notes/notes.ts list --limit 10 --offset 10
Output format: Each line shows the full path and the first H1 heading from the file:
/path/to/note.md: タイトル
Path Convention
- Base directory:
~/Compost/AI-Notes/{year}-{month}/ - Single document:
{day}-{hour}{minutes}-{title}.md - Multiple documents:
{day}-{hour}{minutes}-{title}/{number}-{title}.md
Content Requirements
- Language: Write documents in Japanese
- Code Comments: ALWAYS write code comments in English, even when the document is in Japanese
- Example code snippets should have English comments
- Inline code documentation should be in English
- Only narrative text outside code blocks should be in Japanese
- Diagrams: Use Mermaid syntax for all diagrams and flowcharts
Reading Notes
When user requests reading from notes:
- List recent notes: Use
notes.ts list --limit 20to get recent documents - Search by pattern: Use Glob tool with pattern like
~/Compost/AI-Notes/**/*{keyword}*.md - Search by content: Use Grep tool to search across note contents
- Complex searches: Use Task tool with Explore agent for multi-step exploration
Search priority:
- Start with
notes.ts listto see recent notes - For specific topics, use Grep across
~/Compost/AI-Notes - For complex queries, delegate to Explore agent