X-bookmark-research/skills/x-bookmark-research/references/output-format.md

Output Format Specification

Generated markdown files follow this exact structure for consistent, searchable research notes.

Filename Convention

YYYY-MM-DD-slug.md

• Date: When bookmarked (today's date for new processing)
• Slug: Kebab-case derived from title (max 50 chars)
• Examples:
  • 2026-01-30-ai-literacy-thread.md
  • 2026-01-30-specs-as-code-workflow.md

Template

---
title: [Descriptive title - not just the first line of tweet]
author: "@handle (Full Name)"
date_bookmarked: YYYY-MM-DD
original_date: YYYY-MM-DD
category: [Category / Subcategory]
tweet_url: https://x.com/user/status/ID
engagement: [#] likes, [#] replies, [#] retweets
---

## Key Insight
[1-2 sentence summary capturing WHY this is valuable. Not a description, but the insight.]

## Full Content
[Tweet text verbatim. For threads, format as:]

**1/** First tweet text

**2/** Second tweet text

[etc.]

## Author Context
[Only for --depth standard or deep]
- **[Full Name]** - [Brief description of who they are]
- [Relevant context: role, company, expertise area]
- [Why their perspective matters on this topic]

## Why This Matters
[2-3 sentences connecting this to the user's configured interests.]
Reference the specific interests/projects from config.yml to make this personal and actionable.

## Related Resources
[Optional - only if there are clear connections]
- [Link or reference to related concept]
- [Other bookmarks on similar topics]

## Action Items
- [ ] [Specific, actionable next step]
- [ ] [Another concrete action]

Frontmatter Fields

Field	Required	Format	Notes
title	Yes	String	Descriptive, not tweet's first words
author	Yes	"@handle (Full Name)"	Include both handle and display name
date_bookmarked	Yes	YYYY-MM-DD	Date of processing
original_date	Yes	YYYY-MM-DD	Tweet's creation date
category	Yes	Category / Subcategory	From standard or custom list
tweet_url	Yes	Full URL	https://x.com/user/status/ID
engagement	Yes	String	Format: N likes, N replies, N retweets

Default Category Taxonomy

These categories are used when no custom categories are configured:

AI & Machine Learning
  - LLM Applications
  - AI Philosophy
  - AI Tools

Engineering Practices
  - Documentation
  - Testing
  - Architecture
  - DevOps

Thought Leadership
  - AI Philosophy
  - Career Advice
  - Industry Trends

Product & Business
  - Strategy
  - Growth
  - Pricing

Career & Hiring
  - Job Opportunities
  - Recruiting
  - HR Tech

Tools & Automation
  - CLI Tools
  - Productivity
  - Workflows

News & Announcements
  - Product Launches
  - Company News
  - Research Papers

Users can override these by defining categories in their config.yml.

Section Guidelines

Key Insight

• One to two sentences MAX
• Focus on the insight, not description
• Answer: "What's the takeaway?"
• Bad: "This thread discusses AI literacy"
• Good: "AI literacy is cognitive, not technical - clear thinking matters more than prompt engineering"

Full Content

• Preserve exact tweet text
• For threads: number each part with **N/** format
• Include quoted tweets with > blockquote
• Preserve line breaks within tweets

Why This Matters

• Connect specifically to interests configured in config.yml
• Reference the user's actual projects and goals by name
• Be specific, not generic
• 2-3 sentences that make the bookmark actionable

Action Items

• Use checkbox format: - [ ]
• Make actionable and specific
• Typically 2-4 items
• Tie back to user's configured interests where relevant

Thread Handling

For multi-part threads:

1. Title should reflect the thread's main thesis
2. Number all parts in Full Content section
3. Key Insight summarizes the entire thread, not just tweet 1
4. Engagement may note "thread" in parenthetical

Quote Tweet Handling

## Full Content
[Main tweet text]

> **Quoted from @otheruser:**
> [Quoted tweet text]

Media Handling

Note presence of media but don't embed:

## Full Content
[Tweet text]

*[Includes: image showing X / video demonstrating Y]*