Terminal Skills | Marketplace for AI Agent Skills

Why Notion for AI Workflows?

Notion isn't just a note-taking app — it's a flexible database that AI agents can read and write to. This makes it perfect as a source of truth for your projects, tasks, and knowledge.

🎯 Key Benefits

Structured Data — Typed properties for reliable automation
API Access — Full CRUD operations via REST API
Human Readable — You and AI see the same data
Real-time Sync — Changes reflect immediately

Database Design Patterns

1. Task Management (Kanban)

The most common use case. Design your database with these properties:

schema.json

{
  "Name": { "type": "title" },
  "Status": { 
    "type": "select",
    "options": ["Backlog", "Todo", "In Progress", "Done"]
  },
  "Project": { "type": "select" },
  "Assignee": { 
    "type": "select",
    "options": ["Human", "AI Agent"]
  },
  "Priority": { "type": "select" },
  "URL": { "type": "url" },
  "Due Date": { "type": "date" },
  "Description": { "type": "rich_text" }
}

Pro tip: Use select instead of multi_select for Status — it's easier to query and update programmatically.

2. Knowledge Base

Store documentation, SOPs, and learnings that AI can reference:

{
  "Title": { "type": "title" },
  "Category": { "type": "select" },
  "Tags": { "type": "multi_select" },
  "Content": { "type": "rich_text" },
  "Source URL": { "type": "url" },
  "Last Updated": { "type": "last_edited_time" }
}

3. Relations — The Power Feature

Link databases together for rich context:

Tasks → Projects — Each task belongs to a project
Projects → Deployments — Track deployed URLs
Notes → Tasks — Link research to work items

AI Integration Patterns

Pattern 1: Task Assignment via API

Let AI read tasks assigned to it:

query.sh

# Query tasks assigned to AI agent
curl -X POST "https://api.notion.com/v1/databases/{db_id}/query" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "and": [
        {"property": "Assignee", "select": {"equals": "AI Agent"}},
        {"property": "Status", "select": {"equals": "Todo"}}
      ]
    }
  }'

Pattern 2: Status Updates

When AI completes work, update the status:

# Mark task as done
curl -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2022-06-28" \
  -d '{
    "properties": {
      "Status": {"select": {"name": "Done"}},
      "URL": {"url": "https://deployed-app.vercel.app"}
    }
  }'

Pattern 3: Notification Webhook (ntfy)

Combine Notion with ntfy.sh for real-time notifications:

🔔 Workflow

Human assigns task to AI in Notion
Frontend sends ntfy notification
AI receives notification, queries Notion for details
AI completes work, updates Notion status
Human sees results in Notion

Code: Complete Integration

Here's a full example of an AI agent's Notion workflow:

notion-agent.ts

const NOTION_KEY = process.env.NOTION_KEY;
const DATABASE_ID = process.env.NOTION_DB;

// 1. Get assigned tasks
async function getMyTasks() {
  const res = await fetch(
    `https://api.notion.com/v1/databases/${DATABASE_ID}/query`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${NOTION_KEY}`,
        'Notion-Version': '2022-06-28',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        filter: {
          and: [
            { property: 'Assignee', select: { equals: 'AI Agent' } },
            { property: 'Status', select: { does_not_equal: 'Done' } }
          ]
        }
      })
    }
  );
  return res.json();
}

// 2. Update task status
async function updateTask(pageId: string, status: string, url?: string) {
  const properties: any = {
    Status: { select: { name: status } }
  };
  if (url) {
    properties.URL = { url };
  }
  
  await fetch(`https://api.notion.com/v1/pages/${pageId}`, {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${NOTION_KEY}`,
      'Notion-Version': '2022-06-28',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ properties })
  });
}

// 3. Create new task
async function createTask(name: string, project: string) {
  await fetch('https://api.notion.com/v1/pages', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${NOTION_KEY}`,
      'Notion-Version': '2022-06-28',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      parent: { database_id: DATABASE_ID },
      properties: {
        Name: { title: [{ text: { content: name } }] },
        Project: { select: { name: project } },
        Status: { select: { name: 'Backlog' } }
      }
    })
  });
}

Best Practices Checklist

Use Select for Status
Easier to filter and update than checkboxes
Add URL Property
Store deployed links for easy access
Use Created/Updated Time
Auto-track when tasks change
Keep Descriptions in Rich Text
AI can read and write formatted content
Use Relations for Context
Link tasks to projects, docs to tasks
Connect with ntfy.sh
Real-time notifications without polling

Conclusion

Notion becomes incredibly powerful when paired with AI agents. The key is structured data — design your databases with automation in mind, use typed properties, and create clear workflows.

Start with a simple task database, add AI as an assignee, and watch your productivity multiply. The AI handles the work, Notion tracks the progress, and you stay in control.

💡 Want to learn more?

Check out our Notion skill for Claude Code — it includes templates and automation scripts to get you started.

View Notion Skill →

Notion + AI: Best Practices for Vibe Coders