Notion — l'architecte

Ce skill est la couche conception au-dessus de l'API Notion. Il ne sert pas à écrire du contenu métier dans un Notion existant (ça, c'est le MCP direct ou les skills métier). Il sert à décider comment un espace Notion doit être structuré pour rester propre, lisible et pilotable, puis à le construire ou le refondre.

La mécanique brute de l'API (JSON exact des types de propriétés, types de blocs, filtres, limites) vit déjà dans le skill installé notion-api (~/.agents/skills/notion-api/references/). Ne la réinvente pas : quand tu as besoin du schéma exact d'une propriété ou d'un bloc, va le lire là-bas. Ce skill-ci se concentre sur les décisions d'architecture que l'API ne te dit pas comment prendre.

Ce que ce skill fait, et ne fait pas

Si la demande est "ajoute ce prospect dans mon CRM Notion" ou "résume cette page", ce n'est pas ce skill : redirige vers le MCP direct ou le skill métier concerné.

Règles dures

1. Exécution via le MCP Notion connecté. Utilise les outils notion-search, notion-fetch, notion-create-database, notion-create-pages, notion-update-page, notion-update-data-source, notion-create-view, notion-update-view, notion-query-database-view, notion-move-pages, notion-duplicate-page. Le CLI ntn et les appels curl directs ne sont qu'un fallback si aucun MCP Notion n'est branché (et dans ce cas ils exigent NOTION_API_TOKEN, qui n'est pas défini ici par défaut).

2. Tout ce qui modifie un schéma ou détruit de la donnée se confirme avant. Créer une base vierge sur une page de travail est sans risque. En revanche : modifier le schéma d'une base existante, archiver/supprimer des pages, renommer des propriétés en place, fusionner des bases. Pour une refonte, on propose le plan d'abord, on exécute après accord. Une seule confirmation suffit pour un lot d'opérations cohérent.

3. Agnostique. Aucune entreprise, aucun vertical, aucun ICP hardcodé. Ne suppose jamais ce que l'utilisateur stocke. Si le contexte métier compte (et qu'un skill dédié existe : exoteach, woma, avelor...), délègue-lui ; sinon, demande.

4. Pas de tiret long (em-dash —, en-dash –), nulle part. Utilise :, ,, (...), ·, ; ou ..

5. Ne réinvente pas la mécanique. Pour le JSON exact d'un type de propriété, d'un bloc, d'un filtre, ou pour les limites de l'API, lis ~/.agents/skills/notion-api/references/ (property-types.md, block-types.md, filters-and-sorts.md, rich-text.md).

Les 3 piliers d'un Notion ultra-optimisé

Toute décision de design se juge contre ces trois axes. Ils se renforcent : un modèle propre rend l'usage plus simple et l'automatisation fiable.

1. Modèle de données propre

Chaque entité (personne, entreprise, deal, projet, tâche, contenu...) vit dans une seule base, sa source unique de vérité. On ne retape jamais une donnée qui existe ailleurs : on la relie (relation) et on la remonte (rollup). On dérive plutôt que stocker (formule pour un nom complet, un score, des jours restants). Le résultat : zéro incohérence, une donnée qu'on corrige à un seul endroit.

2. Usage & lisibilité

La donnée brute n'est pas une interface. Chaque public et chaque usage a sa vue filtrée ("mes tâches", "deals à relancer cette semaine", "pipeline par étape"), et l'espace s'organise autour d'un hub qui mène à tout. La vue par défaut doit répondre à "qu'est-ce que je fais maintenant ?" sans scroll ni bruit. Couleurs de statut, icônes, callouts, dashboards : des repères visuels, pas de la déco.

3. Prêt pour l'automatisation

Un espace pilotable par API/MCP/agents : vocabulaire contrôlé (select/status, pas du texte libre) pour filtrer de façon fiable, propriétés référencées par ID (stable même si on renomme), identifiants humains stables (propriété unique_id avec préfixe), schémas cohérents entre bases similaires pour qu'un même script marche partout, dates en ISO.

Détail des patterns concrets pour chaque pilier : references/design-patterns.md.

Cadrage initial (avant de concevoir, toujours)

Concevoir sans cadrer produit des bases qu'on jette. Avant de modéliser quoi que ce soit, ces cinq points doivent être clairs (sinon, pose une question courte) :

• Entités : de quels objets parle-t-on ? (ce sont tes futures bases)
• Utilisateurs & rôles : qui consulte, qui édite, avec quels besoins différents ? (ce sont tes futures vues)
• Décisions & actions : quelles décisions l'espace doit-il aider à prendre, quelles actions déclencher ? (ça dicte les statuts et les vues prioritaires)
• Rapports attendus : quels chiffres/agrégats on veut voir ? (ce sont tes rollups/formules)
• Automatisation : des agents, scripts ou intégrations vont-ils lire/écrire ici ? (ça durcit les contraintes du pilier 3)

Workflow — Concevoir un environnement neuf

Travaille le modèle sur papier d'abord (dans ta réponse), fais valider, puis construis. Construire avant d'avoir validé le modèle, c'est refondre tout de suite.

1. Modéliser les entités → une base par entité. Nomme les bases au pluriel (Entreprises, Deals, Tâches, Contenus).
2. Tracer les relations entre bases. Décide single vs dual property (voir design-patterns.md). Une relation, jamais une recopie.
3. Définir les rollups et formules : tout chiffre ou champ dérivable se calcule, ne se saisit pas.
4. Designer le schéma de chaque base : propriétés serrées, bons types, vocabulaire contrôlé. Une propriété de trop est une dette. Vise un schéma léger (Notion peine au-delà de ~50 KB de schéma).
5. Designer les vues par public et par usage, pas une vue fourre-tout. Filtre, trie, groupe.
6. Designer le hub / dashboard : une page d'entrée qui mène à tout, avec vues liées et KPI en callouts.
7. Construire via le MCP : crée les bases (notion-create-database), pose les propriétés, crée les vues (notion-create-view), monte la page hub (notion-create-pages). Pour les relations, crée d'abord les deux bases, puis ajoute la relation.
8. Vérifier : requête en retour (notion-query-database-view), vérifie qu'une relation résout bien, qu'un rollup affiche la bonne valeur, qu'une vue filtre comme prévu.

Workflow — Auditer / refactorer un existant

1. Cartographier : notion-search puis notion-fetch pour lister les bases, leurs schémas, leurs relations, les pages orphelines. Comprends ce qui existe avant de juger.
2. Passer la checklist d'anti-patterns : references/audit-checklist.md.
3. Prioriser : classe les problèmes par impact (incohérence de données > friction d'usage > cosmétique) et par coût de correction.
4. Proposer un plan de refonte : ce qui change, dans quel ordre, ce qui est non-destructif (ajouter une vue, une relation) vs destructif (supprimer une propriété, fusionner des bases). Le destructif passe par validation explicite.
5. Exécuter une fois validé, par lots cohérents. Préfère toujours l'ajout réversible avant la suppression.
6. Vérifier comme en conception.

Table de décision : quel outil MCP pour quoi

Pièges Notion à toujours respecter

Quelques contraintes qui cassent un design si on les ignore (liste complète et gotchas dans references/audit-checklist.md) :

• La propriété status ne se crée pas via l'API. Pour un pipeline machine-friendly créé par API, utilise select, ou crée le status à la main dans l'UI puis pilote-le.
• Limites de lot : 100 blocs par requête, 100 options par multi-select, 100 relations par page, 25 références affichées avant fetch séparé. Filtres composés : 2 niveaux d'imbrication max.
• Bases inline vs full-page : is_inline: true pour intégrer une base dans une page (hub, dashboard) ; full-page sinon.
• Data sources (API 2025-09-03+) : une base peut contenir plusieurs data sources. Le parent d'une page créée dans une base récente est un data_source_id, pas un database_id.
• Rollups de rollups peu fiables ; relations >25 réfs tronquées dans les formules. Garde les chaînes de dérivation courtes.

Références

• references/design-patterns.md : bibliothèque de patterns (hub-and-spoke, source unique de vérité, choix de type de propriété, recettes de relations/rollups/formules, conventions de nommage, recettes de vues et dashboards).
• references/audit-checklist.md : anti-patterns à détecter, processus d'audit, stratégies de refonte non-destructive, contraintes et gotchas Notion détaillés.
• ~/.agents/skills/notion-api/references/ : mécanique brute de l'API (schémas JSON exacts).