research-notes/.claude/skills/new-note.md

Creating Blog Notes

This skill documents how to create new research notes for the Maxwell blog.

Directory Structure

Each note lives in blog/content/notes/{NNN}-{slug}/:

blog/content/notes/
├── 001-picking-a-problem/
│   ├── meta.yaml         # Metadata, prompts, navigation
│   └── content.md        # Prose content
├── 002-building-the-scaffolding/
│   ├── meta.yaml
│   ├── content.md
│   └── files/            # Optional: expandable file contents
│       ├── vision.md
│       ├── architecture.md
│       └── roadmap.md
└── 003-research-planning/
    ├── meta.yaml
    └── content.md

Step 1: Create the Directory

mkdir -p blog/content/notes/{NNN}-{slug}

Use zero-padded 3-digit ID (001, 002, 003...) and kebab-case slug.

Step 2: Create meta.yaml

Required fields:

id: "003"
slug: 003-research-planning
date: "2026-02-07"
title: Research Planning
preview: "Short description shown in note list (1-2 sentences)"

prompts:
  - id: unique-id
    label: Button label shown to user
    content: |
      The actual prompt content that gets copied.
      Can be multi-line.      

  - id: another-prompt
    label: Another Prompt
    content: |
      Second prompt content here.      

filesCreated: []  # Or list of files if any

navigation:
  prev:
    slug: 002-building-the-scaffolding
    id: "002"
    title: Understanding the Project
  next: null  # Or next note reference

Optional: skillsUsed

When documenting Claude Code skills/commands used during research:

skillsUsed:
  - name: do-parallel
    command: /do-parallel
    description: Execute tasks in parallel waves with optimal agent selection and review
    usage: |
      ---
      description: Execute tasks in parallel waves...
      argument-hint: <task list or "from todo">
      allowed-tools: Task, Read, Write, Edit, Glob, Grep, Bash, TodoWrite
      ---

      Execute these tasks in parallel waves with proper review: $ARGUMENTS

      ## Instructions
      [FULL command definition from ~/.claude/commands/{command}.md]      

IMPORTANT: The usage field should contain the ACTUAL command file contents from ~/.claude/commands/, not just example usage.

Optional: filesCreated

When the note documents files that were created:

filesCreated:
  - name: vision.md
    description: Core thesis, axioms, paradoxes, and narrative
  - name: architecture.md
    description: System layers, code sketches, data structures

These files should exist in files/ subdirectory.

Step 3: Create content.md

Write the prose content in Markdown:

## The Method

Explain what you did and why.

## Section Two

More content here.

- Bullet points work
- As do **bold** and *italic*

### Subsection

Deeper explanation.

## What I Learned

Reflections on the process.

## Next Steps

What comes next in the research.

Supported Markdown features:

• Headings (h2, h3)
• Paragraphs
• Bullet lists (ul)
• Numbered lists (ol)
• Bold and italic text
• Inline code with backticks

Step 4: Add Files (Optional)

If filesCreated references files, create them in files/:

mkdir -p blog/content/notes/{NNN}-{slug}/files

Each file should be the complete content that will be shown in an expandable section.

Step 5: Update Previous Note Navigation

Edit the previous note's meta.yaml to add the next navigation:

navigation:
  prev:
    slug: 001-picking-a-problem
    id: "001"
    title: Picking a Problem
  next:
    slug: 003-research-planning
    id: "003"
    title: Research Planning  # Add this

Step 6: Verify

cd blog && npm run dev

Check:

• Note appears in list at /maxwell
• Note renders at /maxwell/notes/{slug}
• Prompts have working copy buttons
• Skills section shows with expandable usage (if skillsUsed)
• Files section shows with expandable content (if filesCreated)
• Prev/next navigation works
• Build succeeds: npm run build

Schema Reference

NoteMeta Interface

interface NoteMeta {
  id: string;
  slug: string;
  date: string;
  title: string;
  preview: string;
  prompts: Prompt[];
  skillsUsed?: SkillUsed[];
  filesCreated: FileCreated[];
  navigation: {
    prev: NavLink | null;
    next: NavLink | null;
  };
}

interface Prompt {
  id: string;
  label: string;
  content: string;
}

interface SkillUsed {
  name: string;
  command: string;
  description: string;
  usage?: string;  // Full command definition
}

interface FileCreated {
  name: string;
  description: string;
}

interface NavLink {
  slug: string;
  id: string;
  title: string;
}

Key Files

File	Purpose
blog/src/lib/content.ts	Content loaders
blog/src/app/maxwell/notes/[slug]/page.tsx	Dynamic route
blog/src/components/notes/NoteHeader.tsx	Note header
blog/src/components/notes/PromptsSection.tsx	Prompts with copy
blog/src/components/notes/SkillsSection.tsx	Skills/commands
blog/src/components/notes/FilesSection.tsx	Expandable files
blog/src/components/notes/NoteFooter.tsx	Navigation