What it does. Research across Notion and synthesize into structured documentation; use when gathering info from multiple Notion sources to produce briefs, comparisons, or reports with citations. Part of openai/skills (Skills Catalog for Codex) (openai/skills).

Upstream	openai/skills
Skill file	skills/.curated/notion-research-documentation/SKILL.md
License	MIT (skill folder LICENSE.txt)
Author	OpenAI
Fetched	2026-09-10

Install

• Codex: $skill-installer installs from this catalog ($notion-research-documentation invokes it); other agents: npx skills add openai/skills --skill notion-research-documentation.
• Raw file: curl -sL https://raw.githubusercontent.com/openai/skills/HEAD/skills/.curated/notion-research-documentation/SKILL.md

SKILL.md (verbatim)

name: notion-research-documentation
description: Research across Notion and synthesize into structured documentation; use when gathering info from multiple Notion sources to produce briefs, comparisons, or reports with citations.
metadata:
  short-description: Research Notion content and produce briefs/reports

Research & Documentation

Pull relevant Notion pages, synthesize findings, and publish clear briefs or reports (with citations and links to sources).

Quick start

1. Find sources with Notion:notion-search using targeted queries; confirm scope with the user.
2. Fetch pages via Notion:notion-fetch; note key sections and capture citations (reference/citations.md).
3. Choose output format (brief, summary, comparison, comprehensive report) using reference/format-selection-guide.md.
4. Draft in Notion with Notion:notion-create-pages using the matching template (quick, summary, comparison, comprehensive).
5. Link sources and add a references/citations section; update as new info arrives with Notion:notion-update-page.

Workflow

0) If any MCP call fails because Notion MCP is not connected, pause and set it up:

1. Add the Notion MCP:
   • codex mcp add notion --url https://mcp.notion.com/mcp
2. Enable remote MCP client:
   • Set [features].rmcp_client = true in config.toml or run codex --enable rmcp_client
3. Log in with OAuth:
   • codex mcp login notion

After successful login, the user will have to restart codex. You should finish your answer and tell them so when they try again they can continue with Step 1.

1) Gather sources

• Search first (Notion:notion-search); refine queries, and ask the user to confirm if multiple results appear.
• Fetch relevant pages (Notion:notion-fetch), skim for facts, metrics, claims, constraints, and dates.
• Track each source URL/ID for later citation; prefer direct quotes for critical facts.

2) Select the format

• Quick readout → quick brief.
• Single-topic dive → research summary.
• Option tradeoffs → comparison.
• Deep dive / exec-ready → comprehensive report.
• See reference/format-selection-guide.md for when to pick each.

3) Synthesize

• Outline before writing; group findings by themes/questions.
• Note evidence with source IDs; flag gaps or contradictions.
• Keep user goal in view (decision, summary, plan, recommendation).

4) Create the doc

• Pick the matching template in reference/ (brief, summary, comparison, comprehensive) and adapt it.
• Create the page with Notion:notion-create-pages; include title, summary, key findings, supporting evidence, and recommendations/next steps when relevant.
• Add citations inline and a references section; link back to source pages.

5) Finalize & handoff

• Add highlights, risks, and open questions.
• If the user needs follow-ups, create tasks or a checklist in the page; link any task database entries if applicable.
• Share a short changelog or status using Notion:notion-update-page when updating.

References and examples

• reference/ — search tactics, format selection, templates, and citation rules (e.g., advanced-search.md, format-selection-guide.md, research-summary-template.md, comparison-template.md, citations.md).
• examples/ — end-to-end walkthroughs (e.g., competitor-analysis.md, technical-investigation.md, market-research.md, trip-planning.md).

Other files in this skill

• LICENSE.txt
• agents/openai.yaml
• assets/notion-small.svg
• assets/notion.png
• evaluations/README.md
• evaluations/basic-research.json
• evaluations/research-to-database.json
• examples/competitor-analysis.md
• examples/market-research.md
• examples/technical-investigation.md
• examples/trip-planning.md
• reference/advanced-search.md
• reference/citations.md
• reference/comparison-format.md
• reference/comparison-template.md
• reference/comprehensive-report-format.md
• reference/comprehensive-report-template.md
• reference/format-selection-guide.md
• reference/quick-brief-format.md
• reference/quick-brief-template.md
• reference/research-summary-format.md
• reference/research-summary-template.md

evaluations/README.md (verbatim)

Research & Documentation Skill Evaluations

Evaluation scenarios for testing the Research & Documentation skill across different Codex models.

Purpose

These evaluations ensure the Research & Documentation skill:

• Searches across Notion workspace effectively
• Synthesizes information from multiple sources
• Selects appropriate research report format
• Creates comprehensive documentation with proper citations
• Works consistently across Haiku, Sonnet, and Opus

Evaluation Files

basic-research.json

Tests basic research workflow with synthesis across multiple Notion pages.

Scenario: Research Q4 product roadmap and create summary
Key Behaviors:

• Searches Notion for roadmap-related pages
• Fetches multiple relevant pages (roadmap, product docs, meeting notes)
• Synthesizes information from different sources
• Selects appropriate format (Research Summary)
• Includes citations linking back to source pages
• Creates structured document with clear sections

research-to-database.json

Tests creating research documentation in a Notion database with properties.

Scenario: Research competitor landscape and save to Research database
Key Behaviors:

• Searches for existing competitive intelligence in Notion
• Identifies Research database as target
• Fetches database schema to understand properties
• Creates page with correct property values (Research Type, Status, Date, etc.)
• Structures content with comparison format
• Includes source citations for both Notion pages and external research

Running Evaluations

1. Enable the research-documentation skill
2. Submit the query from the evaluation file
3. Verify the skill searches Notion workspace comprehensively
4. Check that multiple source pages are fetched and synthesized
5. Verify appropriate format is selected (Research Summary, Comprehensive Report, Quick Brief, Comparison)
6. Confirm citations link back to sources
7. Test with Haiku, Sonnet, and Opus

Expected Skill Behaviors

Research & Documentation evaluations should verify:

Notion Search & Synthesis

• Searches workspace with relevant queries
• Fetches multiple source pages (3-5+)
• Synthesizes information across sources
• Identifies patterns and insights
• Handles conflicting information appropriately

Format Selection

• Chooses correct format based on scope and depth:
  • Research Summary: Quick overview with key findings
  • Comprehensive Report: Deep analysis with multiple sections
  • Quick Brief: Fast facts and takeaways
  • Comparison: Side-by-side analysis
• Applies format structure consistently
• Uses appropriate sections and headings

Citation & Attribution

• Includes citations for all Notion sources
• Uses mention-page tags: <mention-page url="...">
• Attributes findings to specific sources
• Distinguishes between Notion content and Codex research
• Links related documents

Document Quality

• Title clearly indicates research topic and date
• Executive summary or key findings upfront
• Organized with clear hierarchy
• Actionable insights and recommendations
• Appropriate depth for the query

Creating New Evaluations

When adding Research & Documentation evaluations:

1. Test different research types - Product research, competitive analysis, technical investigation, market research
2. Vary source count - Synthesis of 2-3 pages vs. 10+ pages
3. Test format selection - Does it choose the right format for the scope?
4. Include database targets - Not just standalone pages
5. Test citation accuracy - Are all sources properly attributed?
6. Cross-workspace search - Testing search across teamspaces if applicable

Example Success Criteria

Good (specific, testable):

• "Searches Notion for 'roadmap' and 'Q4' and 'product'"
• "Fetches at least 3 different source pages"
• "Includes citation for each key finding using mention-page tags"
• "Creates page with title format 'Research: [Topic] - [Date]'"
• "Uses Research Summary format with sections: Executive Summary → Key Findings → Details → Recommendations → Sources"

Bad (vague, untestable):

• "Searches Notion effectively"
• "Creates comprehensive research"
• "Uses sources appropriately"
• "Good documentation"

examples/competitor-analysis.md (verbatim)

Example: Competitor Analysis

User Request

"Research competitor pricing models and create a comparison document"

Workflow Execution

Step 1: Search for Competitor Information

Notion:notion-search
query: "competitor pricing"
query_type: "internal"
filters: {
  created_date_range: {
    start_date: "2024-01-01"
  }
}

Results Found:

• "Competitor Analysis - Stripe" (Product)
• "Market Research Q3 2024" (Strategy)
• "Pricing Strategy Discussion" (Product)
• "Competitor Feature Matrix" (Product)

Step 2: Fetch and Analyze

Notion:notion-fetch for each page

Extracted Information:

Stripe:

• Pay-as-you-go: 2.9% + $0.30 per transaction
• No monthly fees
• Volume discounts available

Square:

• Pay-as-you-go: 2.6% + $0.10 per transaction
• Monthly plan: $29/month with lower rates
• Hardware costs separate

PayPal:

• Standard: 3.49% + $0.49 per transaction
• Advanced: $30/month + 2.59% + $0.49
• Multi-currency fees

Adyen:

• Interchange++ pricing model
• Custom enterprise pricing
• Setup and monthly fees apply

Step 3: Create Comparison Document

Notion:notion-create-pages

pages: [{
  properties: {
    "title": "Competitor Pricing Analysis - Payment Processors"
  },
  content: "[Comparison document using template]"
}]

Output Document

# Competitor Pricing Analysis - Payment Processors

**Date**: October 14, 2025  
**Research Team**: Product Strategy

## Executive Summary

We analyzed four major payment processor competitors: Stripe, Square, PayPal, and Adyen. Pricing models vary from simple pay-as-you-go (Stripe) to complex interchange-plus (Adyen). Key insight: All competitors offer volume discounts for high-transaction merchants, with breakpoints typically at $100K/month processing volume.

## Comparison Matrix

| Feature | Stripe | Square | PayPal | Adyen |
|---------|--------|--------|--------|-------|
| **Base Rate** | 2.9% + $0.30 | 2.6% + $0.10 | 3.49% + $0.49 | Interchange++ |
| **Monthly Fee** | $0 | $0-29 | $0-30 | Custom |
| **Volume Discounts** | Yes, >$80K | Yes, >$250K | Yes, >$100K | Yes, custom |
| **Setup Fee** | $0 | $0 | $0 | $1,000-5,000 |
| **Multi-currency** | 1% extra | 3% extra | 3-4% extra | Included |
| **Chargeback Fee** | $15 | $15-25 | $20 | Custom |
| **Target Market** | Startups-Enterprise | Small-Medium | Small-Medium | Enterprise |

## Detailed Analysis

### Stripe

**Pricing Structure**:
- **Standard**: 2.9% + $0.30 per successful card charge
- **Volume discounts**: Available for businesses processing >$80,000/month
- **International cards**: +1% fee
- **Currency conversion**: 1% above market rate

**Strengths**:
- Simple, transparent pricing
- No setup fees or monthly minimums
- Excellent developer experience
- Quick onboarding

**Weaknesses**:
- Higher per-transaction fee for high volume
- Volume discounts less aggressive than Adyen

**Best for**: Startups and growth-stage companies needing quick integration

**Source**: <mention-page url="...">Competitor Analysis - Stripe</mention-page>

### Square

**Pricing Structure**:
- **Pay-as-you-go**: 2.6% + $0.10 per tap, dip, or swipe
- **Keyed-in**: 3.5% + $0.15
- **Plus plan**: $29/month for lower rates (2.5% + $0.10)
- **Premium plan**: Custom pricing

**Strengths**:
- Lowest per-transaction fee for in-person
- All-in-one hardware + software
- No long-term contracts

**Weaknesses**:
- Higher rates for online/keyed transactions
- Hardware costs ($49-$299)
- Less suitable for online-only businesses

**Best for**: Brick-and-mortar retail and restaurants

**Source**: <mention-page url="...">Market Research Q3 2024</mention-page>

### PayPal

**Pricing Structure**:
- **Standard**: 3.49% + $0.49 per transaction
- **Advanced**: $30/month + 2.59% + $0.49
- **Payments Pro**: Additional $30/month for direct credit card processing

**Strengths**:
- Huge customer base (PayPal checkout)
- Buyer protection increases trust
- International reach (200+ countries)

**Weaknesses**:
- Highest per-transaction fees
- Complex fee structure
- Account holds and reserves common

**Best for**: Businesses where PayPal brand trust matters (e-commerce, marketplaces)

**Source**: <mention-page url="...">Pricing Strategy Discussion</mention-page>

### Adyen

**Pricing Structure**:
- **Interchange++**: Actual interchange + scheme fees + fixed markup
- **Setup fee**: $1,000-5,000 (negotiable)
- **Monthly minimum**: Typically $10,000+ processing volume
- **Per-transaction**: Interchange + 0.6% + $0.12 (example)

**Strengths**:
- Most transparent cost structure at scale
- Lowest effective rate for high volume
- True multi-currency (100+ currencies)
- Direct connections to schemes

**Weaknesses**:
- Complex pricing requires analysis
- High minimums ($10K+/month)
- Longer integration time
- Not suitable for small businesses

**Best for**: Enterprise with $1M+/month processing volume

**Source**: <mention-page url="...">Competitor Feature Matrix</mention-page>

## Pricing Trends & Insights

### Volume-Based Discounting
All competitors offer discounts at scale:
- **Entry point**: $80K-$250K/month processing
- **Typical discount**: 10-30 basis points reduction
- **Negotiation leverage**: Begins at $500K/month+

### Hidden Costs to Consider

| Cost Type | Stripe | Square | PayPal | Adyen |
|-----------|--------|--------|--------|-------|
| Chargeback | $15 | $15-25 | $20 | $15-25 |
| Account verification | $0 | $0 | $0 | Varies |
| PCI compliance | $0 | $0 | $0 | $0 |
| Currency conversion | 1% | 3% | 3-4% | 0% |
| Refund fees | Returned | Returned | Not returned | Varies |

### Market Positioning

High Volume / Enterprise ↑ | Adyen |
| Stripe
|
| Square PayPal | └──────────────────→ Small / Simple Complex / International

## Strategic Implications

### For Startups (<$100K/month)
**Recommended**: Stripe
- Lowest friction to start
- No upfront costs
- Great documentation
- Acceptable rates at this scale

### For Growing Companies ($100K-$1M/month)
**Recommended**: Stripe or Square
- Negotiate volume discounts
- Evaluate interchange++ if international
- Consider Square if in-person dominant

### For Enterprises (>$1M/month)
**Recommended**: Adyen or Negotiated Stripe
- Interchange++ models save significantly
- Direct scheme connections
- Multi-region capabilities matter
- ROI on integration complexity

## Recommendations

1. **Immediate**: Benchmark our current 2.8% + $0.25 against Stripe's standard
2. **Short-term**: Request volume discount quote from Stripe at our current $150K/month
3. **Long-term**: Evaluate Adyen when we cross $1M/month threshold

## Next Steps

- [ ] Request detailed pricing proposal from Stripe for volume discounts
- [ ] Create pricing calculator comparing all 4 at different volume levels
- [ ] Interview customers about payment method preferences
- [ ] Analyze our transaction mix (domestic vs international, card types)

## Sources

### Primary Research
- <mention-page url="...">Competitor Analysis - Stripe</mention-page>
- <mention-page url="...">Market Research Q3 2024</mention-page>
- <mention-page url="...">Pricing Strategy Discussion</mention-page>
- <mention-page url="...">Competitor Feature Matrix</mention-page>

### External References
- Stripe.com pricing page (Oct 2025)
- Square pricing documentation
- PayPal merchant fees
- Adyen pricing transparency report

Key Success Factors

1. Structured comparison: Matrix format for quick scanning
2. Multiple dimensions: Price, features, target market
3. Strategic recommendations: Not just data, but implications
4. Visual elements: Table and positioning diagram
5. Actionable next steps: Clear recommendations
6. Comprehensive sources: Internal research + external validation

Workflow Pattern Demonstrated

• Date-filtered search (recent information only)
• Multiple competitor synthesis (4 different companies)
• Comparison template (matrix + detailed analysis)
• Strategic layer (implications and recommendations)
• Action-oriented (next steps included)

examples/market-research.md (verbatim)

Example: Market Research

User Request: "Research the current state of AI coding assistants market and create a summary document in Notion"

Workflow

1. Search

Notion:notion-search
query: "AI coding assistants market"

Found 3 relevant pages across Engineering, Strategy, and Product teamspaces.

2. Fetch & Analyze

Notion:notion-fetch (3x)

Extracted market size, competitive landscape, technology trends from source pages.

3. Create Documentation

Notion:notion-create-pages

Output (Condensed)

# AI Coding Assistants Market Research - Oct 2025

## Executive Summary
The AI coding assistant market is experiencing 150%+ YoY growth. GitHub Copilot dominates with 60% share, but specialized tools are gaining traction in specific niches.

## Key Findings

### Market Size and Growth
$800M in 2024 → $2.5B projected by 2026. Developer adoption: 23% (2023) → 47% (2024).
Source: <mention-page url="...">Market Trends Q3 2025</mention-page>

### Competitive Landscape
- GitHub Copilot: 60% (strong IDE integration)
- Cursor: 15% (rapid growth, full IDE)
- Tabnine: 10% (enterprise, on-premise)
- Cody: 5% (codebase-aware)
- CodeWhisperer: 8% (AWS integration)
Source: <mention-page url="...">AI Tools Competitive Analysis</mention-page>

### Technology Trends
Key differentiators: context awareness, customization, multi-modal interfaces, code verification.
Source: <mention-page url="...">Developer Tools Landscape</mention-page>

## Next Steps
1. Monitor Cursor growth and feature releases
2. Evaluate Cody's codebase-aware capabilities
3. Document enterprise security/compliance requirements
4. Track pricing trends

Key Takeaways

• Found relevant pages across multiple teamspaces
• Synthesized competitive, market, and technical perspectives
• Used proper citations linking to source pages
• Created actionable recommendations

examples/technical-investigation.md (verbatim)

Example: Technical Investigation

User Request

"Research our current caching strategy and create a technical summary"

Workflow Execution

Step 1: Search for Caching Information

Notion:notion-search
query: "caching strategy architecture"
query_type: "internal"
teamspace_id: "engineering-teamspace-id"

Results Found:

• "System Architecture Overview" (Engineering)
• "Redis Implementation Guide" (Backend Docs)
• "Performance Optimization - Q3 2024" (Engineering)
• "API Caching Decision Record" (Architecture)

Step 2: Fetch Relevant Pages

Notion:notion-fetch
id: "system-architecture-page-url"

Extracted: Current caching architecture uses Redis for API responses, Memcached for session storage.

Notion:notion-fetch
id: "redis-implementation-guide-url"

Extracted: Implementation details, TTL settings, invalidation strategies.

Notion:notion-fetch
id: "api-caching-decision-record-url"

Extracted: Why Redis was chosen over alternatives, trade-offs considered.

Step 3: Synthesize Findings

Key findings identified:

• Two-tier caching: Redis (API responses) + Memcached (sessions)
• TTL strategy: 5 minutes for dynamic data, 1 hour for static
• Invalidation: Event-driven for critical updates
• Performance impact: 75% reduction in database load
• Known issues: Cache stampede on popular endpoints

Step 4: Create Technical Summary

Notion:notion-create-pages

parent: { page_id: "engineering-docs-parent-id" }

pages: [{
  properties: {
    "title": "Technical Summary: Caching Strategy - Oct 2025"
  },
  content: "[Structured technical summary using template]"
}]

Output Document

# Technical Summary: Caching Strategy - Oct 2025

## Executive Summary

Our caching infrastructure uses a two-tier approach with Redis for API response caching and Memcached for session management. This strategy has reduced database load by 75% and improved API response times from 200ms to 50ms average.

## Architecture Overview

### Layer 1: API Response Caching (Redis)
**Technology**: Redis 7.0 cluster (3 nodes)
**Purpose**: Cache GET endpoint responses
**TTL Strategy**:
- Dynamic content: 5 minutes
- Static content: 1 hour
- User-specific: 15 minutes

**Source**: <mention-page url="...">System Architecture Overview</mention-page>

### Layer 2: Session Storage (Memcached)
**Technology**: Memcached 1.6
**Purpose**: User session data, temporary state
**TTL**: 24 hours (session lifetime)

## Implementation Details

### Cache Key Format

api:v1:{endpoint}:{params_hash} session:{user_id}:{session_id}

### Invalidation Strategy
- **Event-driven**: Critical data changes trigger immediate invalidation
- **Time-based**: TTL expiration for non-critical data
- **Manual**: Admin tools for emergency cache clear

**Source**: <mention-page url="...">Redis Implementation Guide</mention-page>

## Decision Rationale

### Why Redis for API Caching?

**Pros**:
- Advanced data structures (sorted sets, hashes)
- Built-in TTL with automatic eviction
- Pub/sub for cache invalidation events
- Persistence options for durability

**Cons**:
- Higher memory usage than Memcached
- More complex cluster management

**Decision**: Chosen for flexibility and rich feature set needed for API caching.

**Source**: <mention-page url="...">API Caching Decision Record</mention-page>

### Why Memcached for Sessions?

**Pros**:
- Simpler, lighter weight
- Excellent for key-value storage
- Lower memory footprint

**Cons**:
- No persistence
- Limited data structures

**Decision**: Perfect fit for ephemeral session data where simplicity is valued.

## Performance Impact

| Metric | Before Caching | After Caching | Improvement |
|--------|----------------|---------------|-------------|
| Avg Response Time | 200ms | 50ms | 75% faster |
| Database Load | 100% | 25% | 75% reduction |
| Cache Hit Rate | - | 85% | - |
| Peak RPS Handled | 1,000 | 4,000 | 4x increase |

**Source**: <mention-page url="...">Performance Optimization - Q3 2024</mention-page>

## Known Issues & Limitations

### Cache Stampede
**Issue**: When popular cache entries expire, multiple requests hit database simultaneously

**Mitigation**: Implemented probabilistic early expiration and request coalescing

**Status**: Reduced by 90% but not eliminated

### Stale Data Risk
**Issue**: Cached data can be up to TTL duration stale

**Mitigation**: Event-driven invalidation for critical data paths

**Status**: Acceptable trade-off for performance gains

## Monitoring & Observability

**Metrics tracked**:
- Cache hit/miss rates per endpoint
- Memory usage and eviction rates
- Response time distributions
- Invalidation event frequency

**Tools**: DataDog dashboards, CloudWatch alarms

## Future Considerations

1. **Edge Caching**: Evaluate CDN integration for static assets
2. **Cache Warming**: Pre-populate cache for predictable traffic spikes
3. **Adaptive TTLs**: Adjust TTLs based on data change frequency
4. **Regional Caching**: Multi-region cache replication for global performance

## Related Documentation

- <mention-page url="...">System Architecture Overview</mention-page>
- <mention-page url="...">Redis Implementation Guide</mention-page>
- <mention-page url="...">API Caching Decision Record</mention-page>
- <mention-page url="...">Performance Optimization - Q3 2024</mention-page>

## Appendix: Configuration Examples

### Redis Configuration
```yaml
maxmemory: 8gb
maxmemory-policy: allkeys-lru
tcp-keepalive: 60

Common Cache Operations

# Set with TTL
cache.set(key, value, ttl=300)

# Get with fallback
value = cache.get(key) or fetch_from_db(key)

# Invalidate pattern
cache.delete_pattern("api:v1:users:*")

## Key Success Factors

1. **Multiple source integration**: Combined architecture docs, implementation guides, and decision records
2. **Technical depth**: Included configuration, code examples, metrics
3. **Decision context**: Explained why choices were made, not just what
4. **Practical focus**: Real performance numbers and known issues
5. **Future-looking**: Noted areas for improvement
6. **Well-cited**: Every major point links back to source material

## Workflow Pattern Demonstrated

This example shows the complete research workflow:
- **Scoped search** (teamspace filter for engineering)
- **Multi-page synthesis** (4 different sources)
- **Technical template** (architecture-focused format)
- **Proper placement** (under engineering docs)
- **Comprehensive citations** (links to all sources)

## examples/trip-planning.md (verbatim)

# Example: Group Trip Research & Planning

**User Request**: "Research and plan our friends' trip to Japan in March - we're 6 people looking for 10 days"

## Workflow

### 1. Search Existing Notes

Notion:notion-search query: "Japan travel"

Found: Japan Travel Guide (from friend), Tokyo Restaurants, Kyoto Temple Guide

### 2. Fetch & Extract Tips

Notion:notion-fetch (3x)

**Key info from previous travelers:**
- Best time: March-April (cherry blossoms)
- Must-see: Tokyo, Kyoto, Osaka
- Budget: $200-300/day (mid-range)
- Book accommodations 3 months ahead
- Get JR Pass before arrival
- Top restaurants: Sushi Dai, Ichiran Ramen, Tsunahachi Tempura

### 3. Research & Synthesize
Combined previous traveler insights with:
- Flight options and prices
- Accommodation types (hotels/ryokans/Airbnb)
- Transportation (JR Pass essential)
- 10-day itinerary structure
- Budget breakdown

### 4. Create Comprehensive Plan

Notion:notion-create-pages parent: { page_id: "travel-plans-parent-id" } pages: [{ properties: { title: "Japan Trip 2026 - March 15-25 (10 Days)" }, content: "[Full trip plan with itinerary, budget, tips...]" }]

## Output Sample

```markdown
# Japan Trip 2026 - March 15-25 (10 Days)

## Trip Overview
**Dates**: March 15-25, 2026 (Cherry Blossom Season 🌸)
**Group**: 6 people | **Budget**: $3,000-4,000/person

## Itinerary Summary

**Days 1-3: Tokyo**
- Arrive, explore Shibuya, Harajuku, Shinjuku
- Visit Tsukiji Market, Imperial Palace, Sensoji Temple
- Experience Tokyo nightlife, teamLab Borderless

**Days 4-5: Hakone**  
- Day trip from Tokyo
- Hot springs, Mt. Fuji views, Lake Ashi cruise

**Days 6-8: Kyoto**
- Bullet train from Tokyo
- Fushimi Inari, Kinkaku-ji, Arashiyama Bamboo Grove
- Geisha district (Gion), traditional tea ceremony

**Days 9-10: Osaka + Depart**
- Osaka Castle, Dotonbori food district
- Nara day trip (deer park, Todai-ji Temple)
- Return flight from Osaka (KIX)

## Budget Breakdown (per person)
- **Flights**: $900-1,200 (round-trip)
- **Accommodations**: $700-1,000 (9 nights)
- **JR Pass**: $280 (7-day pass)
- **Food**: $500-700 ($50-70/day)
- **Activities**: $300-400
- **Local transport**: $100
**Total**: $2,780-3,680

## Key Bookings
- **Flights**: Book 3-4 months ahead
- **Hotels**: Book now (cherry blossom season)
  - Tokyo: Shinjuku area (2 nights) + Asakusa (1 night)
  - Kyoto: Gion area (3 nights)
  - Osaka: Namba area (2 nights)
- **JR Pass**: Order 2-3 weeks before travel
- **Restaurants**: Reserve 1 week ahead (Sushi Dai, high-end spots)

## Essential Tips
Source: <mention-page url="...">Japan Travel Guide</mention-page>
- Get pocket WiFi or eSIM on arrival
- Download: Google Translate, Hyperdia (train routes), Tabelog (restaurants)
- Cash-heavy country - withdraw at 7-Eleven ATMs
- Shoes off in temples, ryokans, some restaurants
- Trains extremely punctual - don't be late
- Learn basic phrases: arigatou, sumimasen, itadakimasu

## Packing List
- Comfortable walking shoes (10k+ steps/day)
- Light jacket (March 55-65°F)
- Backpack for day trips
- Cash pouch
- Portable charger

## Next Steps
- [ ] Book flights (target: <$1,100/person)
- [ ] Order JR Passes
- [ ] Book hotels (Tokyo → Kyoto → Osaka)
- [ ] Create shared expense tracker
- [ ] Schedule group planning call

## Sources
- <mention-page url="...">Japan Travel Guide</mention-page> (Sarah's 2024 trip)
- <mention-page url="...">Tokyo Restaurant Recommendations</mention-page>
- <mention-page url="...">Kyoto Temple Guide</mention-page>

Key Takeaways

• Leveraged previous traveler notes from Notion
• Combined personal insights with research
• Created actionable itinerary with budget breakdown
• Included practical tips from experienced travelers
• Set clear next steps for group coordination

reference/advanced-search.md (verbatim)

Advanced Search Techniques

Search Filtering

By Date Range

Use created_date_range to find recent content:

filters: {
  created_date_range: {
    start_date: "2024-01-01",
    end_date: "2025-01-01"
  }
}

When to use:

• Finding recent updates on a topic
• Focusing on current information
• Excluding outdated content

By Creator

Use created_by_user_ids to find content from specific people:

filters: {
  created_by_user_ids: ["user-id-1", "user-id-2"]
}

When to use:

• Research from subject matter experts
• Team-specific information
• Attribution tracking

Combined Filters

Stack filters for precision:

filters: {
  created_date_range: {
    start_date: "2024-10-01"
  },
  created_by_user_ids: ["expert-user-id"]
}

Scoped Searches

Teamspace Scoping

Restrict search to specific teamspace:

teamspace_id: "teamspace-uuid"

When to use:

• Project-specific research
• Department-focused information
• Reducing noise from irrelevant results

Page Scoping

Search within a specific page and its subpages:

page_url: "https://notion.so/workspace/Page-Title-uuid"

When to use:

• Research within a project hierarchy
• Documentation updates
• Focused investigation

Database Scoping

Search within a database's content:

data_source_url: "collection://data-source-uuid"

When to use:

• Task/project database research
• Structured data investigation
• Finding specific entries

Search Strategies

Broad to Narrow

1. Start with general search term
2. Review results for relevant teamspaces/pages
3. Re-search with scope filters
4. Fetch detailed content from top results

Example:

Search 1: query="API integration" → 50 results across workspace
Search 2: query="API integration", teamspace_id="engineering" → 12 results
Fetch: Top 3-5 most relevant pages

Multi-Query Approach

Run parallel searches with related terms:

Query 1: "API integration"
Query 2: "API authentication"
Query 3: "API documentation"

Combine results to build comprehensive picture.

Temporal Research

Search across time periods to track evolution:

Search 1: created_date_range 2023 → Historical context
Search 2: created_date_range 2024 → Recent developments
Search 3: created_date_range 2025 → Current state

Result Processing

Identifying Relevant Results

Look for:

• High semantic match: Result summary closely matches query intent
• Recent updates: Last-edited date is recent
• Authoritative sources: Created by known experts or in official locations
• Comprehensive content: Result summary suggests detailed information

Prioritizing Fetches

Fetch pages in order of relevance:

1. Primary sources: Direct documentation, official pages
2. Recent updates: Newly edited content
3. Related context: Supporting information
4. Historical reference: Background and context

Don't fetch everything - be selective based on research needs.

Handling Too Many Results

If search returns 20+ results:

1. Add filters: Narrow by date, creator, or teamspace
2. Refine query: Use more specific terms
3. Use page scoping: Search within relevant parent page
4. Sample strategically: Fetch diverse results (recent, popular, authoritative)

Handling Too Few Results

If search returns < 3 results:

1. Broaden query: Use more general terms
2. Remove filters: Search full workspace
3. Try synonyms: Alternative terminology
4. Search in related areas: Adjacent teamspaces or pages

Search Quality

Effective Search Queries

Good queries (specific, semantic):

• "Q4 product roadmap"
• "authentication implementation guide"
• "customer feedback themes"

Weak queries (too vague):

• "roadmap"
• "guide"
• "feedback"

Over-specific queries (too narrow):

• "Q4 2024 product roadmap for mobile app version 3.2 feature X"

User Context

Always use available user context:

• Query should match their terminology
• Scope to their relevant teamspaces
• Consider their role/department
• Reference their recent pages

Connected Sources

Notion Integrations

Search extends beyond Notion pages to:

• Slack messages (if connected)
• Google Drive documents (if connected)
• GitHub issues/PRs (if connected)
• Jira tickets (if connected)

Be aware results may come from these sources.

Source Attribution

When citing results from connected sources:

• Note the source type in documentation
• Use appropriate mention format
• Verify user has access to the source system

reference/citations.md (verbatim)

Citation Styles

Basic Page Citation

Always cite sources using Notion page mentions:

<mention-page url="https://notion.so/workspace/Page-Title-uuid">Page Title</mention-page>

The URL must be provided. The title is optional but improves readability:

<mention-page url="https://notion.so/workspace/Page-Title-uuid"/>

Inline Citations

Cite immediately after referenced information:

The Q4 revenue increased by 23% quarter-over-quarter (<mention-page url="...">Q4 Financial Report</mention-page>).

Multiple Sources

When information comes from multiple sources:

Customer satisfaction has improved across all metrics (<mention-page url="...">Q3 Survey Results</mention-page>, <mention-page url="...">Support Analysis</mention-page>).

Section-Level Citations

For longer sections derived from one source:

### Engineering Priorities

According to the <mention-page url="...">Engineering Roadmap 2025</mention-page>:

- Focus on API scalability
- Improve developer experience
- Migrate to microservices architecture

Sources Section

Always include a "Sources" section at document end:

## Sources

- <mention-page url="...">Strategic Plan 2025</mention-page>
- <mention-page url="...">Market Analysis Report</mention-page>
- <mention-page url="...">Competitor Research: Q3</mention-page>
- <mention-page url="...">Customer Interview Notes</mention-page>

Group by category for long lists:

## Sources

### Primary Sources
- <mention-page url="...">Official Roadmap</mention-page>
- <mention-page url="...">Strategy Document</mention-page>

### Supporting Research
- <mention-page url="...">Market Trends</mention-page>
- <mention-page url="...">Customer Feedback</mention-page>

### Background Context
- <mention-page url="...">Historical Analysis</mention-page>

Quoting Content

When quoting directly from source:

The product team noted: "We need to prioritize mobile experience improvements" (<mention-page url="...">Product Meeting Notes</mention-page>).

For block quotes:

> We need to prioritize mobile experience improvements to meet our Q4 goals. This includes performance optimization and UI refresh.
>
> — <mention-page url="...">Product Meeting Notes - Oct 2025</mention-page>

Data Citations

When presenting data, cite the source:

| Metric | Q3 | Q4 | Change |
|--------|----|----|--------|
| Revenue | $2.3M | $2.8M | +21.7% |
| Users | 12.4K | 15.1K | +21.8% |

Source: <mention-page url="...">Financial Dashboard</mention-page>

Database Citations

When referencing database content:

Based on analysis of the <mention-database url="...">Projects Database</mention-database>, 67% of projects are on track.

User Citations

When attributing information to specific people:

<mention-user url="...">Sarah Chen</mention-user> noted in <mention-page url="...">Architecture Review</mention-page> that the microservices migration is ahead of schedule.

Citation Frequency

Over-citing (every sentence):

The revenue increased (<mention-page url="...">Report</mention-page>). 
Costs decreased (<mention-page url="...">Report</mention-page>). 
Margin improved (<mention-page url="...">Report</mention-page>).

Under-citing (no attribution):

The revenue increased, costs decreased, and margin improved.

Right balance (grouped citation):

The revenue increased, costs decreased, and margin improved (<mention-page url="...">Q4 Financial Report</mention-page>).

Outdated Information

Note when source information might be outdated:

The original API design (<mention-page url="...">API Spec v1</mention-page>, last updated January 2024) has been superseded by the new architecture in <mention-page url="...">API Spec v2</mention-page>.

Cross-References

Link to related research documents:

## Related Research

This research builds on previous findings:
- <mention-page url="...">Market Analysis - Q2 2025</mention-page>
- <mention-page url="...">Competitor Landscape Review</mention-page>

For implementation details, see:
- <mention-page url="...">Technical Implementation Guide</mention-page>

Citation Validation

Before finalizing research:

✓ Every key claim has a source citation ✓ All page mentions have valid URLs ✓ Sources section includes all cited pages ✓ Outdated sources are noted as such ✓ Direct quotes are clearly marked ✓ Data sources are attributed

Citation Style Consistency

Choose one citation style and use throughout:

Inline style (lightweight):

Revenue grew 23% (Financial Report). Customer count increased 18% (Metrics Dashboard).

Formal style (full mentions):

Revenue grew 23% (<mention-page url="...">Q4 Financial Report</mention-page>). Customer count increased 18% (<mention-page url="...">Metrics Dashboard</mention-page>).

Recommend formal style for most research documentation as it provides clickable navigation.

reference/comparison-format.md (verbatim)

Comparison Format

When to use:

• Evaluating multiple options
• Tool/vendor selection
• Approach comparison
• Decision support

Characteristics

Length: 800-1200 words typically

Structure:

• Overview of what's being compared
• Comparison matrix table
• Detailed analysis per option (pros/cons)
• Clear recommendation with rationale
• Sources

Template

See comparison-template.md for the full template.

Best For

• Decision support with multiple options
• Tool or vendor selection
• Comparing different technical approaches
• Evaluating trade-offs between alternatives

Example Use Cases

• "Compare the three database options discussed in our tech docs"
• "What are the pros and cons of each deployment approach?"
• "Compare the vendor proposals"
• "Evaluate the different authentication methods we've documented"

reference/comparison-template.md (verbatim)

Comparison Template

Use when researching multiple options or alternatives. See comparison-format.md for when to use this format.

# [Topic] Comparison

## Overview
[Brief introduction to what's being compared and why]

## Comparison Matrix

| Criteria | Option A | Option B | Option C |
|----------|----------|----------|----------|
| [Criterion 1] | [Rating/Details] | [Rating/Details] | [Rating/Details] |
| [Criterion 2] | [Rating/Details] | [Rating/Details] | [Rating/Details] |

## Detailed Analysis

### Option A
**Pros**:
- [Advantage]
- [Advantage]

**Cons**:
- [Disadvantage]
- [Disadvantage]

**Best for**: [Use case]

**Source**: <mention-page url="...">Source Page</mention-page>

[Repeat for each option]

## Recommendation

**Selected option**: [Choice]

**Rationale**: [Why this option is best given the context]

## Sources
[List all consulted pages]

reference/comprehensive-report-format.md (verbatim)

Comprehensive Report Format

When to use:

• Formal documentation requirements
• Strategic decision support
• Complex topics requiring extensive analysis
• Multiple stakeholders need alignment

Characteristics

Length: 1500+ words

Structure:

• Executive summary
• Background & context
• Methodology
• Detailed findings with subsections
• Data & evidence section
• Implications (short and long-term)
• Prioritized recommendations
• Appendix

Template

See comprehensive-report-template.md for the full template.

Best For

• Deep analysis and strategic decisions
• Formal documentation requirements
• Complex topics with multiple facets
• When stakeholders need extensive context
• Board presentations or executive briefings

Example Use Cases

• "Create a comprehensive analysis of our market position"
• "Document the full technical investigation of the database migration"
• "Prepare an in-depth report on vendor options for executive review"
• "Analyze the pros and cons of different architectural approaches"

reference/comprehensive-report-template.md (verbatim)

Comprehensive Report Template

Use for in-depth research requiring extensive analysis. See comprehensive-report-format.md for when to use this format.

# [Report Title]

## Executive Summary
[One paragraph summarizing the entire report]

## Background & Context
[Why this research was conducted, what questions it addresses]

## Methodology
- Sources consulted: [number] Notion pages across [teamspaces]
- Time period: [if relevant]
- Scope: [what was included/excluded]

## Key Findings

### [Major Theme 1]
**Summary**: [One sentence]

**Details**:
- [Supporting point with evidence]
- [Supporting point with evidence]
- [Supporting point with evidence]

**Sources**: [Page mentions]

### [Major Theme 2]
[Repeat structure]

## Data & Evidence

[Tables, quotes, specific data points]

## Implications

### Short-term
[Immediate implications]

### Long-term
[Strategic implications]

## Recommendations

### Priority 1: [High priority action]
- **What**: [Specific action]
- **Why**: [Rationale]
- **How**: [Implementation approach]

### Priority 2: [Medium priority action]
[Repeat structure]

## Appendix

### Additional Resources
- [Related pages]

### Open Questions
- [Unanswered questions for future research]

reference/format-selection-guide.md (verbatim)

Format Selection Guide

Choose the right output format for your research needs.

Decision Tree

Is this comparing multiple options?
  ├─ YES → Use Comparison Format
  └─ NO ↓

Is this time-sensitive or simple?
  ├─ YES → Use Quick Brief
  └─ NO ↓

Does this require formal/extensive documentation?
  ├─ YES → Use Comprehensive Report
  └─ NO → Use Research Summary (default)

Format Overview

Format	Length	When to Use	Template
Research Summary	500-1000 words	Most research requests (default)	Template
Comprehensive Report	1500+ words	Formal docs, strategic decisions	Template
Quick Brief	200-400 words	Time-sensitive, simple topics	Template
Comparison	800-1200 words	Evaluating options	Template

Formatting Guidelines

Headings

• Use # for title
• Use ## for major sections
• Use ### for subsections
• Keep heading hierarchy consistent

Lists

• Use - for bullet points
• Use 1. for numbered lists
• Keep list items parallel in structure

Emphasis

• Use **bold** for key terms and section labels
• Use *italic* for emphasis
• Use sparingly for maximum impact

Citations

• Always use <mention-page url="...">Page Title</mention-page> for source pages
• Include citation immediately after referenced information
• Group all sources in a "Sources" section at the end

Tables

• Use for structured data comparison
• Keep columns to 3-5 for readability
• Include header row
• Align content appropriately

Code Blocks

Use when including:

• Technical specifications
• Configuration examples
• Command examples

Example code or configuration here

Content Guidelines

Executive Summaries

• Lead with the most important finding
• Include 1-2 key implications
• Make it standalone (reader gets value without reading further)
• Target 2-3 sentences for summaries, 1 paragraph for reports

Key Findings

• Start with a clear headline
• Support with specific evidence
• Include relevant data points or quotes
• Cite source immediately
• Focus on actionable insights

Recommendations

• Make them specific and actionable
• Explain the "why" behind each recommendation
• Prioritize clearly (Priority 1, 2, 3 or High/Medium/Low)
• Include implementation hints when relevant

Source Citations

• Link to original pages using mentions
• Note if information is outdated (check last-edited dates)
• Credit specific sections when quoting
• Group related sources together

reference/quick-brief-format.md (verbatim)

Quick Brief Format

When to use:

• Time-sensitive requests
• Simple topics
• Status updates
• Quick reference needs

Characteristics

Length: 200-400 words

Structure:

• 3-4 sentence summary
• 3-5 bullet key points
• Short action items list
• Brief source list

Template

See quick-brief-template.md for the full template.

Best For

• Fast turnaround requests
• Simple, straightforward topics
• Quick status updates
• When time is more important than depth
• Initial exploration before deeper research

Example Use Cases

• "Quick summary of what's in our API docs"
• "Fast brief on the meeting notes from yesterday"
• "What are the key points from that spec?"
• "Give me a quick overview of the project status"

reference/quick-brief-template.md (verbatim)

Quick Brief Template

Use for fast turnaround requests or simple topics. See quick-brief-format.md for when to use this format.

# [Topic] - Quick Brief

**Date**: [Current date]

## Summary
[3-4 sentences covering the essentials]

## Key Points
- **Point 1**: [Details]
- **Point 2**: [Details]
- **Point 3**: [Details]

## Action Items
1. [Immediate next step]
2. [Follow-up action]

## Sources
[Brief list of pages consulted]

reference/research-summary-format.md (verbatim)

Research Summary Format

When to use: General research requests, most common format

Characteristics

Length: 500-1000 words typically

Structure:

• Executive summary (2-3 sentences)
• 3-5 key findings with supporting evidence
• Detailed analysis section
• Conclusions and next steps
• Source citations

Template

See research-summary-template.md for the full template.

Best For

• Most general-purpose research requests
• Standard documentation needs
• Balanced depth and readability
• When you need comprehensive but accessible information

Example Use Cases

• "Research our authentication options"
• "What does our project documentation say about the API redesign?"
• "Summarize the team's discussion about mobile strategy"
• "Compile information about our deployment process"

reference/research-summary-template.md (verbatim)

Research Summary Template

Use this for most research requests. See research-summary-format.md for when to use this format.

# [Topic Name]

## Executive Summary
[2-3 sentence overview of key findings and implications]

## Key Findings

### Finding 1: [Clear headline]
[Details and supporting evidence]
- Source: <mention-page url="...">Original Page</mention-page>

### Finding 2: [Clear headline]
[Details and supporting evidence]
- Source: <mention-page url="...">Original Page</mention-page>

### Finding 3: [Clear headline]
[Details and supporting evidence]
- Source: <mention-page url="...">Original Page</mention-page>

## Detailed Analysis

### [Section 1]
[In-depth discussion of first major theme]

### [Section 2]
[In-depth discussion of second major theme]

## Conclusions

[Summary of implications and insights]

## Next Steps

1. [Actionable recommendation]
2. [Actionable recommendation]
3. [Actionable recommendation]

## Sources

- <mention-page url="...">Page Title</mention-page>
- <mention-page url="...">Page Title</mention-page>
- <mention-page url="...">Page Title</mention-page>

Back to openai/skills (Skills Catalog for Codex) or Agent skills.