Quartz Note Creator

This skill helps create properly formatted markdown notes for the Quartz static site generator with correct YAML frontmatter.

Helper Scripts

This skill includes Python utility scripts for reliable note creation. Always use these scripts instead of generating values manually:

• scripts/timestamp.py - Generate ISO 8601 timestamps
• scripts/filename.py - Generate and validate filenames
• scripts/frontmatter.py - Generate complete YAML frontmatter

Quick Script Usage

# Get current timestamp
python scripts/timestamp.py

# Generate filename from title
python scripts/filename.py generate "My Note Title"

# Check if file exists
python scripts/filename.py check "my-note-title.md"

# Get today's date filename
python scripts/filename.py date

# Suggest filename with existence check
python scripts/filename.py suggest "My Note Title"

# Generate complete frontmatter
python scripts/frontmatter.py --title "My Note" --tags "ai,ml" --publish true

Instructions

When the user requests to create a new note, follow these steps:

1. Generate Unique Filename

Use the filename.py script for reliable filename generation:

# For topic notes
python scripts/filename.py suggest "Note Title"

# For daily journal
python scripts/filename.py date

The script will:

• Convert the title to kebab-case (lowercase with hyphens)
• Check if the file already exists in content/notes/
• Suggest an alternative name if there's a collision
• Output: AVAILABLE: filename.md or SUGGESTED: filename-2.md

Naming conventions:

• Topic notes: Descriptive kebab-case (e.g., ai-interpretability.md)
• Daily journals: Date format YYYY-MM-DD.md (e.g., 2026-01-05.md)

2. Generate YAML Frontmatter

Use the frontmatter.py script for reliable frontmatter generation:

# Basic frontmatter
python scripts/frontmatter.py \
  --title "My Note Title" \
  --tags "ai,machine-learning" \
  --publish true

# With description
python scripts/frontmatter.py \
  --title "Daily Journal" \
  --description "Today's work log" \
  --tags "agenda" \
  --publish false

Required fields:

---
title: "Human-readable title"
description: "AI-generated 1-2 sentence description of the note"
author: "Sushant Vema"
date_created: "YYYY-MM-DDTHH:mm:ss"
date: "YYYY-MM-DDTHH:mm:ss"
publish: true
tags:
  - "tag1"
  - "tag2"
---

Field guidelines:

• title: Clear, descriptive title from user's description
• description: REQUIRED - Generate a concise 1-2 sentence AI-generated description based on the note title and topic. This should explain what the note is about or what it will cover.
• author: Always "Sushant Vema" (handled by script)
• date_created: Auto-generated by script (ISO 8601 format)
• date: Same as date_created initially (auto-generated)
• publish:
  • Default: true for most notes
  • Use false for "draft", "unpublished", or "private" notes
• tags: Extract from user's description
  • Use lowercase for tags
  • Common: "evergreen", "agenda", "AI Agent Architecture", "project"
  • Pass as comma-separated to script: --tags "ai,ml,research"

3. File Content

IMPORTANT: The note file should contain ONLY the YAML frontmatter with no additional body content. Do not add any markdown content, outlines, headers, or placeholder text after the frontmatter closing ---.

4. File Location

Always create files in: content/notes/

Full path: /Users/svema/Repos/github.com/sushantvema/sushantvema.github.io/content/notes/FILENAME.md

5. Verification

After creating the file:

1. Confirm the file was created successfully
2. Show the user the generated filename and path
3. Display the frontmatter that was generated

Complete Workflow Example

For a user request: "Create a note about AI agent architecture with tags for ai and agents"

# Step 1: Generate and check filename
FILENAME=$(python scripts/filename.py suggest "AI Agent Architecture")
# Output: AVAILABLE: ai-agent-architecture.md

# Step 2: Generate AI description based on the topic
# Create a concise 1-2 sentence description about what this note covers

# Step 3: Generate frontmatter with the AI-generated description
FRONTMATTER=$(python scripts/frontmatter.py \
  --title "AI Agent Architecture" \
  --description "An exploration of architectural patterns and design principles for building AI agents" \
  --tags "ai,agents,architecture" \
  --publish true)

# Step 4: Get full path
FILEPATH=$(python scripts/filename.py path "ai-agent-architecture.md")
# Output: /Users/svema/Repos/github.com/sushantvema/sushantvema.github.io/content/notes/ai-agent-architecture.md

# Step 5: Create the file using Write tool
# Write ONLY the FRONTMATTER to FILEPATH - no body content

Examples

Example 1: Topic Note

User request: "Create a note about progressive disclosure in UI design"

Generated file: content/notes/progressive-disclosure-ui-design.md

File contents (frontmatter only):

---
title: "Progressive Disclosure in UI Design"
description: "Exploring the principle of progressive disclosure and its applications in user interface design, including best practices and implementation strategies"
author: "Sushant Vema"
date_created: "2026-01-05T14:30:00"
date: "2026-01-05T14:30:00"
publish: true
tags:
  - "ui-design"
  - "ux"
  - "progressive-disclosure"
---

Example 2: Daily Journal

User request: "Create today's journal entry"

Generated file: content/notes/2026-01-05.md

File contents (frontmatter only):

---
title: "Sunday January 5, 2026"
description: "Daily journal entry for tracking tasks, thoughts, and reflections"
author: "Sushant Vema"
date_created: "2026-01-05T09:00:00"
date: "2026-01-05T09:00:00"
publish: false
tags:
  - "agenda"
---

Example 3: Draft Note

User request: "Create a draft note about machine learning model interpretability that I want to keep private"

Generated file: content/notes/ml-model-interpretability.md

File contents (frontmatter only):

---
title: "Machine Learning Model Interpretability"
description: "Techniques and approaches for understanding and explaining machine learning model decisions and predictions"
author: "Sushant Vema"
date_created: "2026-01-05T16:45:00"
date: "2026-01-05T16:45:00"
publish: false
tags:
  - "machine-learning"
  - "interpretability"
---

Important Notes

• Always generate an AI description based on the note title and topic - descriptions are required for all notes
• Files should contain ONLY frontmatter - do not add any body content, outlines, headers, or markdown after the closing ---
• Always use ISO 8601 format for timestamps: YYYY-MM-DDTHH:mm:ss
• Use quotes around string values in YAML frontmatter
• Tags should be an array (list with hyphens), not a comma-separated string
• The publish field controls whether the note appears on the public site
• Check existing notes in content/notes/ to avoid filename collisions
• File paths are absolute, starting with /Users/svema/Repos/github.com/sushantvema/sushantvema.github.io/

Common Patterns

Topic notes: Use descriptive kebab-case names like agent-skills.md, quartz-wishlist.md

Daily journals: Use date format YYYY-MM-DD.md and set publish: false by default

Project notes: Include "project" in filename or tags, e.g., ai-profile-summarization-project.md

Evergreen content: Add "evergreen" tag for timeless, continuously updated notes