# Notion Brief Publish Skill

> Notion Brief Publishing Skill

- Skill: `jas0nnguyen/notion-brief-publish-skill` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add jas0nnguyen/notion-brief-publish-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jas0nnguyen/notion-brief-publish-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: jas0nnguyen (https://skillmd.com/u/jas0nnguyen)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jas0nnguyen/notion-brief-publish-skill

---

# Notion Brief Publishing Skill

## Overview
This skill handles publishing approved product briefs from the `briefs/` folder to Notion with the correct structure, including inline databases for User Scenarios and Deliverables Tracker.

## When to Use This Skill
Use this skill when:
- User explicitly requests to publish a brief to Notion (e.g., "publish to Notion", "create this in Notion")
- A brief in `briefs/` folder has been approved and needs to be added to the Projects database

## Prerequisites
Before publishing, ensure:
1. Brief exists in `briefs/` folder as markdown
2. Brief content has been approved by user
3. User has confirmed:
   - **Team assignment** (which team will own this work)
   - **Product classification** (which product this feature belongs to)

**CRITICAL**: Always ask for Team and Product before publishing. Do NOT proceed without this information.

## Configuration
Read database IDs and team/product references from `.claude/config/organization.json`:
- `integrations.notion.projects_database_id` - Target database for briefs
- `integrations.notion.template_id` - Template page ID
- `teams` - Available teams
- `products` - Available products

---

## Step-by-Step Publishing Workflow

### Step 1: Ask for Required Information
Before any Notion operations, ask the user:
```
Before I publish this brief to Notion, I need to confirm:
1. Which team will own this work?
2. Which product(s) does this feature fall under?
```

### Step 2: Create Page in Projects Database
```
Use notion-create-pages with:
  parent: {"type": "data_source_id", "data_source_id": "[projects_database_id from config]"}
  pages: [{
    "properties": {
      "Project Brief": "[Brief Title]",
      "Status": "Not Started"
    },
    "content": "[Brief content in Notion markdown format]"
  }]
```

### Step 3: Set Team and Product Relations
```
Use notion-update-page with command: "update_properties"
Set Team(s) and Products relations using the page URLs
```

### Step 4: Create User Scenarios Inline Database
**CRITICAL**: The Notion API cannot create inline databases directly. You must:

1. Create the database as a child of the brief page:
```
Use notion-create-database with:
  parent: {"type": "page_id", "page_id": "[brief page ID]"}
  title: [{"type": "text", "text": {"content": "User Scenarios"}}]
  properties: {
    "Name": {"type": "title", "title": {}},
    "Scope": {
      "type": "select",
      "select": {
        "options": [
          {"name": "In Scope", "color": "green"},
          {"name": "Out of Scope", "color": "red"}
        ]
      }
    }
  }
```

2. Set database to inline display:
```
Use notion-update-database with:
  database_id: "[database ID]"
  is_inline: true
```

3. Add scenarios to the database:
```
Use notion-create-pages with:
  parent: {"type": "data_source_id", "data_source_id": "[User Scenarios collection URL]"}
  pages: [
    {
      "properties": {"Name": "Scenario title", "Scope": "In Scope"},
      "content": "[Full scenario content]"
    }
  ]
```

### Step 5: Create Deliverables Tracker Inline Database
1. Create the database:
```
Use notion-create-database with:
  parent: {"type": "page_id", "page_id": "[brief page ID]"}
  title: [{"type": "text", "text": {"content": "Deliverables tracker"}}]
  properties: {
    "Deliverable": {"type": "title", "title": {}},
    "Status": {
      "type": "select",
      "select": {
        "options": [
          {"name": "Not started", "color": "default"},
          {"name": "In progress", "color": "blue"},
          {"name": "Not needed", "color": "green"},
          {"name": "Delivered", "color": "green"}
        ]
      }
    },
    "Date": {"type": "date", "date": {}}
  }
```

**NOTE**: The Notion API does not support creating `status` type properties. Use `select` type instead with the same options.

2. Set database to inline display:
```
Use notion-update-database with:
  database_id: "[database ID]"
  is_inline: true
```

3. Add standard deliverables:
```
Use notion-create-pages with:
  parent: {"type": "data_source_id", "data_source_id": "[Deliverables Tracker collection URL]"}
  pages: [
    {"properties": {"Deliverable": "RFC's", "Status": "Not started"}},
    {"properties": {"Deliverable": "Lo-fi Designs", "Status": "Not started"}},
    {"properties": {"Deliverable": "Hi-fi Designs", "Status": "Not started"}},
    {"properties": {"Deliverable": "User Scenarios", "Status": "Delivered"}},
    {"properties": {"Deliverable": "SWAG", "Status": "Not started"}}
  ]
```

### Step 6: Reposition Databases to Correct Sections

**CRITICAL**: When databases are created as children of a page, Notion appends them to the bottom of the page content. You MUST reposition them to their correct sections.

After creating both databases and adding their content, use `notion-update-page` with `command: "replace_content"` to replace the ENTIRE page content with the databases embedded in their correct locations:

1. **User Scenarios database** must appear directly under the `## User Scenarios` header
2. **Deliverables tracker database** must appear under the `## Notes` section, before `## Resource Links`

**Database reference format:**
```
<database url="https://www.notion.so/[db-id]" inline="true" data-source-url="collection://[data-source-id]">Database Name</database>
```

---

## Standard Deliverables
Always create these rows in the Deliverables Tracker:

| Deliverable | Status |
|-------------|--------|
| RFC's | Not started |
| Lo-fi Designs | Not started |
| Hi-fi Designs | Not started |
| User Scenarios | Delivered (if scenarios are complete) |
| SWAG | Not started |

**Valid Status values**: "Not started", "In progress", "Not needed", "Delivered"

---

## User Scenarios Database Schema
- **Name** (title): Scenario name using verb + noun format
- **Scope** (select): "In Scope" (green) or "Out of Scope" (red)

Each scenario page should contain the full scenario content following the template format.

---

## Required Page Properties
When creating/updating the brief page, set these properties:
- `Project Brief` (title): The brief name
- `Status`: One of "Not Started", "In Discovery", "In Development", "In UAT", "Ready for Launch", "Done"
- `Team(s)`: Relation to team page
- `Products`: Relation to product page
- `Epic`: URL to epic (if available)

---

## Troubleshooting

### Database Not Showing as Inline
If the database appears as a child page instead of inline:
1. Use `notion-update-database` with `is_inline: true`
2. Verify by fetching the page and checking `inline="true"` in the database tag

### Status Property Issues
The Notion API does not support creating `status` type properties via API. Use `select` type instead with the same options. The visual difference is minimal.

### Database Reference Not Working
Ensure database references use the correct format without double braces:
```
<database url="https://www.notion.so/[id]" inline="true" data-source-url="collection://[id]">Name</database>
```

### Content Replacement Issues
Use `replace_content_range` with unique selection snippets. If multiple matches exist, use `replace_content` to replace entire content (but be careful to preserve database blocks).

---

## Key Reminders

1. **Always ask for Team and Product first** - Never assume
2. **Use select instead of status** - API limitation
3. **Set is_inline: true** - Databases default to child pages
4. **Add standard deliverables** - 5 standard rows every time
5. **User Scenarios need Scope property** - In Scope/Out of Scope with colors
6. **ALWAYS reposition databases** - Notion appends databases to bottom; you must use `replace_content` to move them to their correct sections