@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/fr-FR/sharing.md

@@ -0,0 +1,219 @@
+---
+title: "Partage et confidentialité"
+description: "Partage de style Google Docs, intégré au framework. Chaque ressource créée par l'utilisateur (documents, tableaux de bord, conceptions, présentations, clips, enregistrements, formulaires) obtient le même modèle privé par défaut avec un partage cohérent UI."
+---
+
+# Partage et confidentialité
+
+Chaque ressource qu'un utilisateur crée dans une application native d'agent (un document, un tableau de bord, une conception, une présentation, un montage vidéo, un enregistrement d'écran, une transcription de réunion, un formulaire, un lien de réservation) est **privée par défaut pour le créateur**. Les autres personnes ne le voient que lorsque le créateur le partage explicitement ou modifie sa visibilité en `org` ou `public`.
+
+Il ressemble et fonctionne comme Google Docs. Le même bouton de partage, la même boîte de dialogue, le même modèle de visibilité à trois niveaux, les mêmes subventions par utilisateur/par organisation, dans chaque modèle, sans réinvention par application.
+
+## Pourquoi un modèle {#why}
+
+La plupart des frameworks d'applications font du partage un projet par fonctionnalité. Le résultat : chaque surface de type document se retrouve avec sa propre boîte de dialogue de partage, son propre schéma d'autorisations, ses propres bogues de contrôle d'accès. Dans l'agent natif, le partage est une **primitive de framework**. Les colonnes de schéma, les assistants de vérification d'accès, le popover de partage et le partage appelable par agent actions sont tous livrés avec le noyau. Un nouveau modèle obtient l'histoire de partage complète en ajoutant deux colonnes et une ligne d'inscription.
+
+Cela signifie également que l'agent n'a jamais besoin d'apprendre un nouveau modèle de partage par application. Dites à l'agent "Partagez ceci avec Alice en tant qu'éditeur" dans n'importe quel modèle et la même action `share-resource` se déclenche.
+
+## Les trois niveaux de visibilité {#visibility}
+
+La visibilité grossière réside dans la ressource elle-même ; les subventions à granularité fine se trouvent dans un tableau de partages compagnon.
+
+| Visibilité | Qui peut le voir                                                                                                                                |
+| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `private`  | Propriétaire + personnes explicitement accordées. **Par défaut pour chaque nouvelle ressource.**                                                |
+| `org`      | Propriétaire + subventions explicites + toute personne dans la même organisation (lecture seule).                                               |
+| `public`   | Propriétaire + subventions explicites + toute personne disposant du lien (lecture seule). N'apparaît pas dans les listes/recherches des autres. |
+
+`public` est un niveau délibérément discret : une ressource publique est accessible par lien direct, mais elle n'apparaît **pas** dans les barres latérales, les listes ou la recherche des autres utilisateurs. Cela permet de séparer le « public pour le partage du URL » du « public pour la découverte entre utilisateurs ». Les galeries et les catalogues de modèles qui souhaitent réellement une découverte multi-utilisateurs s'y inscrivent explicitement.
+
+```an-diagram title="Visibility, widening outward" summary="Coarse visibility on the resource sets the floor; explicit share grants in the companion table add named people on top."
+{
+  "html": "<div class=\"share-tiers\"><div class=\"diagram-card\"><span class=\"diagram-pill\">private</span><small class=\"diagram-muted\">owner + explicit grants only &middot; <strong>default</strong></small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">org</span><small class=\"diagram-muted\">+ anyone in the same org (read-only)</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill warn\">public</span><small class=\"diagram-muted\">+ anyone with the link (read-only) &middot; hidden from others' lists/search</small></div></div>",
+  "css": ".share-tiers{display:flex;flex-direction:column;align-items:stretch;gap:8px}.share-tiers .diagram-card{display:flex;flex-direction:column;gap:4px;padding:12px 16px}.share-tiers .diagram-arrow{text-align:center;font-size:20px;line-height:1}"
+}
+```
+
+## Rôles dans le cadre d'une attribution d'actions {#roles}
+
+Lorsque vous partagez avec un utilisateur ou une organisation spécifique, vous choisissez un rôle :
+
+- **Viewer** – lecture seule.
+- **Éditeur** — lecture + écriture.
+- **Admin** — lire + écrire + gérer les partages (peut ajouter/supprimer d'autres personnes).
+
+`admin`, NOT change-t-il de propriétaire ? Il y a toujours exactement un propriétaire par ressource, distinct des attributions de partages.
+
+## Ce qui est couvert {#covered}
+
+Chaque modèle qui stocke le travail créé par l'utilisateur utilise ce modèle. Concrètement :
+
+- **Contenu** — documents
+- **Diapositives** — présentations
+- **Conception** – conceptions et éléments
+- **Vidéo** — compositions
+- **Clips** – enregistrements d'écran (style Loom)
+- **Formulaires** — définitions de formulaire
+- **Calendrier** — événements et liens de réservation
+- **Analytics** — tableaux de bord (déploiement — voir `AGENTS.md` du modèle d'analyse)
+- **Extensions** – mini-applications en bac à sable (voir [Extensions](/docs/extensions#sharing))
+
+Chacun d'entre eux utilise le même assistant de schéma `ownableColumns()`, la même action `share-resource` et la même `<ShareButton>` UI. Passez d'un modèle à un autre et la boîte de dialogue de partage semble identique.
+
+## Ce qui n'est pas couvert {#not-covered}
+
+Quelques zones sont intentionnellement en dehors du système de partage :
+
+- **Applications de données personnelles** (courrier, macros) : conçues pour l'utilisateur. Il n'y a pas de concept « partager ma boîte de réception ».
+- **Applications externes de source de vérité** : le contrôle d'accès réside dans le système en amont, et non dans l'application native de l'agent.
+- **URL publics anonymes** — les slugs de publication de formulaire et les slugs de lien de réservation qui exposent un URL aux utilisateurs déconnectés constituent un axe distinct. Ils vivent à côté du système de partage, pas au-dessus.
+
+## Le partage UI {#share-ui}
+
+Chaque ressource partageable reçoit un bouton de partage dans son en-tête. Cliquer dessus ouvre un popover ancré au bouton (pas un modal) avec :
+
+- Sélecteur de visibilité (`Private` / `Organization` / `Public link`).
+- Saisie automatique « Ajouter des personnes ou des équipes » : recherchez des utilisateurs dans l'organisation ou collez un e-mail.
+- Une case à cocher `Notify people` de style Google Docs pour les autorisations individuelles par e-mail.
+- Une liste des subventions actuelles avec des sélecteurs de rôles et un contrôle de suppression.
+- Un bouton copier-lien qui respecte la visibilité actuelle.
+
+Le bouton de partage est une importation unique :
+
+```tsx
+import { ShareButton } from "@agent-native/core/client";
+
+<ShareButton
+  resourceType="deck"
+  resourceId={deck.id}
+  resourceTitle={deck.title}
+/>;
+```
+
+Pour les listes, déposez un `<VisibilityBadge visibility={row.visibility} />` à côté de chaque ligne afin que les utilisateurs puissent voir en un coup d'œil ce qui est privé ou partagé.
+
+## Même modèle, agent et UI {#agent-and-ui}
+
+Le framework monte automatiquement ces actions dans chaque modèle : l'agent les appelle en tant qu'outils et le UI les appelle via `useActionQuery` / `useActionMutation` :
+
+| Actions                   | Ce qu'il fait                                                                                                                              |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `share-resource`          | Accorder à un utilisateur ou à une organisation l'accès à un rôle spécifique. Le `notify` en option contrôle les notifications par e-mail. |
+| `unshare-resource`        | Révoquer l'accès d'un utilisateur ou d'une organisation.                                                                                   |
+| `list-resource-shares`    | Afficher la visibilité actuelle ainsi que toutes les autorisations explicites.                                                             |
+| `set-resource-visibility` | Passez à `private`, `org` ou `public`.                                                                                                     |
+
+Dites à l'agent "Partagez cette conception avec l'équipe marketing en tant qu'éditeurs" et il appellera `share-resource` sur le même point de terminaison que celui utilisé par UI. Le résultat apparaît dans la boîte de dialogue de partage lors du prochain rendu.
+
+## L'intégrer dans un nouveau modèle {#building}
+
+Si vous créez un modèle (voir [Creating Templates](/docs/creating-templates)), le partage de câblage est court. Deux ajouts à votre schéma :
+
+```ts
+import {
+  table,
+  text,
+  ownableColumns,
+  createSharesTable,
+} from "@agent-native/core/db/schema";
+
+export const decks = table("decks", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  data: text("data").notNull(),
+  ...ownableColumns(), // adds owner_email, org_id, visibility
+});
+
+export const deckShares = createSharesTable("deck_shares");
+```
+
+```an-schema title="Resource + companion shares table" summary="Coarse visibility lives on the resource; each fine-grained grant is a row in the shares table."
+{
+  "entities": [
+    {
+      "id": "deck",
+      "name": "decks",
+      "note": "...ownableColumns()",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true },
+        { "name": "title", "type": "text", "nullable": false },
+        { "name": "owner_email", "type": "text", "nullable": false, "note": "The single source of truth for ownership." },
+        { "name": "org_id", "type": "text", "nullable": true },
+        { "name": "visibility", "type": "enum", "nullable": false, "note": "private | org | public" }
+      ]
+    },
+    {
+      "id": "deckShare",
+      "name": "deck_shares",
+      "note": "createSharesTable() — one row per grant",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true },
+        { "name": "resource_id", "type": "text", "fk": "decks.id", "nullable": false },
+        { "name": "principal_type", "type": "enum", "note": "user | org" },
+        { "name": "principal_id", "type": "text", "note": "email (user) or org id (org)" },
+        { "name": "role", "type": "enum", "note": "viewer | editor | admin" },
+        { "name": "created_by", "type": "text" },
+        { "name": "created_at", "type": "text" }
+      ]
+    }
+  ],
+  "relations": [
+    { "from": "deckShare", "to": "deck", "kind": "n-n", "label": "grants access to" }
+  ]
+}
+```
+
+Un appel d'inscription dans `server/db/index.ts` :
+
+```ts
+import { registerShareableResource } from "@agent-native/core/sharing";
+
+registerShareableResource({
+  type: "deck",
+  resourceTable: schema.decks,
+  sharesTable: schema.deckShares,
+  displayName: "Deck",
+  titleColumn: "title",
+  getResourcePath: (deck) => `/deck/${deck.id}`,
+  getDb,
+});
+```
+
+Après cela, les requêtes de liste/lecture passent par `accessFilter()` et écrivent actions en utilisant `assertAccess()` pour appliquer les rôles.
+
+### Drapeaux de renforcement facultatifs {#hardening-flags}
+
+`registerShareableResource` accepte deux indicateurs de sécurité pour les ressources qui exécutent du code ou portent une confiance élevée :
+
+```ts
+registerShareableResource({
+  type: "extension",
+  resourceTable: schema.extensions,
+  sharesTable: schema.extensionShares,
+  // ...
+  allowPublic: false, // Reject set-resource-visibility → "public"
+  requireOrgMemberForUserShares: true, // Reject user grants to non-org emails
+});
+```
+
+`allowPublic: false` empêche tout appelant (agent ou UI) de définir la visibilité de la ressource sur `public`. `requireOrgMemberForUserShares: true` rejette les autorisations d'utilisateurs individuels vers des adresses e-mail en dehors de l'organisation du propriétaire de la ressource. Les extensions définissent les deux : le HTML d'une extension s'exécute dans une iframe qui appelle actions et DB en tant que _viewer_, donc l'accès public serait un code arbitraire avec les informations d'identification du spectateur.
+
+```an-callout
+{
+  "tone": "risk",
+  "body": "For resources that execute code or carry elevated trust (like extensions), set `allowPublic: false` and `requireOrgMemberForUserShares: true`. Otherwise a public share becomes arbitrary code running with the *viewer's* credentials."
+}
+```
+
+`getResourcePath` fournit aux e-mails de notification un lien de secours direct lorsqu'un partage est créé par l'agent ou un autre appelant non-UI. Le modèle complet (y compris l'estampillage de propriété de l'action de création et la recette de migration pour les tables existantes) réside dans la compétence d'agent `sharing` : l'agent le lit à la demande lors de la création d'une fonctionnalité prenant en charge le partage.
+
+## Garanties de sécurité {#security}
+
+Le partage s'appuie sur le modèle de portée des données plus large du framework : l'accès en liste/lecture/écriture aux tables propriétaires passe par `accessFilter()` / `resolveAccess()` / `assertAccess()`, et les ressources marquées `org_id` sont invisibles dans les organisations. Voir [Security → Data Scoping](/docs/security#data-scoping) pour le pipeline complet, la protection CI et la surface des menaces.
+
+## Voir aussi {#see-also}
+
+- [Security & Data Scoping](/docs/security) : le modèle de filtre d'accès et de propriété sur lequel repose le partage.
+- [Authentication](/docs/authentication) : sessions, organisations et manière dont l'identité circule dans le contexte de la demande.
+- [Extensions](/docs/extensions#sharing) : partage dans la surface de la mini-application en bac à sable.
+- [Creating Templates](/docs/creating-templates) — câblage de `ownableColumns` dans le schéma d'un nouveau modèle.

package/corpus/core/docs/content/locales/fr-FR/skills-guide.md

@@ -0,0 +1,281 @@
+---
+title: "Guide Skills"
+description: "Comment fonctionne skills dans l'agent natif : framework skills, domaine skills et création de skills personnalisé."
+---
+
+# Guide Skills
+
+Skills sont des fichiers Markdown qui donnent à l'agent des connaissances approfondies sur des modèles et des flux de travail spécifiques.
+
+## Que sont les skills {#what-are-skills}
+
+Skills en direct sur `.agents/skills/<name>/SKILL.md` et contient des conseils détaillés pour l'agent. Chaque compétence se concentre sur une préoccupation : comment stocker les données, comment synchroniser l'état, comment déléguer le travail au chat de l'agent.
+
+Les éléments `name` et `description` de chaque compétence sont toujours injectés dans le bloc skills de l'invite système afin que l'agent sache quels skills existent. Le corps complet des compétences est chargé à la demande lorsque l'agent décide qu'une compétence est pertinente pour la tâche (elle est également affichée via `docs-search`). C'est pourquoi il est important de garder les descriptions courtes et spécifiques au déclencheur : la description est la seule chose que l'agent lit avant de décider de charger ou non le reste.
+
+```an-diagram title="Progressive disclosure" summary="Only the name + description of every skill is always in context. The full body loads on demand when the task matches."
+{
+  "html": "<div class=\"sk-flow\"><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Always in the system prompt</span><div class=\"sk-list\"><span class=\"diagram-pill\">storing-data &mdash; <small class=\"diagram-muted\">add data models&hellip;</small></span><span class=\"diagram-pill\">real-time-sync &mdash; <small class=\"diagram-muted\">wire polling&hellip;</small></span><span class=\"diagram-pill\">create-skill &mdash; <small class=\"diagram-muted\">add a skill&hellip;</small></span></div><small class=\"diagram-muted\">just name + description (cheap)</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><small class=\"diagram-muted\">task matches a description</small><span class=\"diagram-pill accent\">load on demand</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">Full <code>SKILL.md</code> body<br><small class=\"diagram-muted\">rules, code, do/don't</small></div></div>",
+  "css": ".sk-flow{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.sk-flow .diagram-card{display:flex;flex-direction:column;gap:8px;padding:14px 16px;min-width:240px}.sk-flow .sk-list{display:flex;flex-direction:column;gap:6px}.sk-flow .center{display:flex;flex-direction:column;align-items:center;gap:6px}.sk-flow .diagram-arrow{font-size:22px}"
+}
+```
+
+## Cadre skills {#framework-skills}
+
+Il s'agit du skills fourni avec le **modèle par défaut**. L'ensemble exact disponible dans une application donnée dépend du modèle à partir duquel vous avez créé votre échafaudage : vérifiez le répertoire `.agents/skills/` de ce modèle pour savoir ce qu'il contient réellement.
+
+| Compétence             | Quand utiliser                                                                                      |
+| ---------------------- | --------------------------------------------------------------------------------------------------- |
+| `storing-data`         | Ajout de modèles de données, lecture/écriture de configuration ou d'état                            |
+| `real-time-sync`       | Synchronisation des interrogations de câblage, débogage de UI non mis à jour                        |
+| `delegate-to-agent`    | Déléguer le travail d'IA de UI ou actions à l'agent                                                 |
+| `actions`              | Création ou exécution de l'agent actions                                                            |
+| `self-modifying-code`  | Modification de la source, des composants ou des styles de l'application                            |
+| `create-skill`         | Ajout d'un nouveau skills pour l'agent                                                              |
+| `capture-learnings`    | Enregistrement des corrections et des modèles                                                       |
+| `frontend-design`      | Créer ou styliser n'importe quel site Web UI, composants ou pages                                   |
+| `adding-a-feature`     | La liste de contrôle en quatre domaines : UI, actions, skills, état de l'application                |
+| `internationalization` | Mise à jour de la copie localisée de UI, des catalogues de langues et des styles sécurisés pour RTL |
+| `shadcn-ui`            | Utilisation des primitives et des composants shadcn/ui                                              |
+| `security`             | Authentification, contrôle d'accès et gestion des secrets                                           |
+| `real-time-collab`     | Édition collaborative multi-utilisateurs                                                            |
+| `agent-engines`        | Échange ou configuration du moteur d'agent sous-jacent                                              |
+| `notifications`        | Modèles de notifications dans l'application et push                                                 |
+| `progress`             | Suivi et affichage de la progression des tâches en arrière-plan                                     |
+| `inline-embeds`        | Intégration d'applications ou d'iframes dans le chat de l'agent                                     |
+
+`context-awareness` et `a2a-protocol` sont des skills au niveau du framework disponibles dans le répertoire `.agents/skills/` à la racine du dépôt – voir le `.agents/skills/` de chaque modèle pour savoir ce dont il hérite.
+
+## Domaine skills {#domain-skills}
+
+Les modèles incluent skills spécifique à leur domaine. Ceux-ci se trouvent dans le même répertoire `.agents/skills/` mais couvrent des modèles spécifiques aux modèles. Consultez le répertoire `.agents/skills/` de chaque modèle pour la liste complète ; un échantillon représentatif :
+
+- **Modèle de courrier** — `email-drafts`, `draft-queue`
+- **Modèle de formulaires** — `form-building`, `form-publishing`, `form-responses`
+- **Modèle d'analyse** : `adhoc-analysis`, `bigquery`, `cross-source-analysis`, `dashboard-management`, `data-querying`, `provider-api`, `gong`, `hubspot`, `prometheus`
+- **Modèle de diapositives** — `create-deck`, `deck-management`, `design-systems`, `slide-editing`, `slide-images`
+
+Le domaine skills suit le même format que le framework skills. Ils codent des modèles spécifiques au modèle que l'agent doit suivre.
+
+## skills soutenu par une application {#app-backed-skills}
+
+skills basé sur une application regroupe une application native d'agent en tant qu'artefact de marché de compétences. L'ensemble peut inclure des instructions d'agent, des métadonnées de connecteur skills exportées et MCP, des instructions de lancement hébergées/locales et des surfaces UI telles que les applications MCP.
+
+> **Tous les détails ci-dessous :** les mécanismes du skills basé sur l'application (format du manifeste, commandes CLI, adaptateurs de marché, hachage de mise à jour automatique) sont couverts dans [App-backed skills — full details](#app-backed-skills-full).
+
+## Création d'un skills personnalisé {#creating-skills}
+
+Créez une compétence lorsque :
+
+- Il existe un modèle que l'agent doit suivre à plusieurs reprises
+- Un flux de travail nécessite des conseils étape par étape
+- Vous souhaitez créer des fichiers à partir d'un modèle
+
+Ne créez pas de compétence lorsque :
+
+- Les conseils existent déjà dans une autre compétence – étendez-les à la place
+- Le guide est unique : placez-le plutôt dans `AGENTS.md` ou dans la mémoire de l'espace de travail
+
+## Format de compétence {#skill-format}
+
+Chaque compétence est un fichier Markdown avec le thème principal YAML :
+
+```an-annotated-code title="Anatomy of a SKILL.md"
+{
+  "filename": ".agents/skills/project-imports/SKILL.md",
+  "language": "markdown",
+  "code": "---\nname: project-imports\ndescription: >-\n  How to import projects from the legacy CSV export. Use when the user uploads\n  a project CSV or asks to migrate projects from the old system.\n---\n\n# Project Imports\n\n## Rule\n\nAlways validate the CSV header row before writing any rows. Reject unknown\ncolumns rather than silently dropping them.\n\n## How\n\n1. Call `get-import-schema` to fetch the expected columns.\n2. Parse the first CSV row and diff against the schema.\n3. If any required columns are missing, return an error — do not proceed.\n4. Stream remaining rows through `create-project-item` in batches of 50.\n\n## Don't\n\n- Don't hold all rows in memory — stream them.\n- Don't create duplicate projects; check for an existing name first.\n\n## Related Skills\n\n- **storing-data** — SQL schema and write patterns for new rows\n- **sharing** — exposing a project to other users after import",
+  "annotations": [
+    { "lines": "2", "label": "Discovery key", "note": "The `name` matches the folder; it is how the skill is invoked as `/project-imports`." },
+    { "lines": "3-5", "label": "The trigger", "note": "This `description` is the **only** text always in context. Make it state precisely *when* the skill applies." },
+    { "lines": "9-14", "label": "Rules first", "note": "Lead with the hard rule and the why; the agent reads the body only once the task matches." },
+    { "lines": "27-30", "label": "Cross-link", "note": "Point at related skills so the agent can chain them instead of re-deriving guidance." }
+  ]
+}
+```
+
+Les frontmatters `name` et `description` sont utilisés par le système d'outils de l'agent pour la découverte de compétences. La description doit indiquer quand la compétence se déclenche – être précis sur les situations.
+
+Enregistrez le fichier sous `.agents/skills/my-skill/SKILL.md`. Le nom du répertoire doit correspondre au `name` en première page.
+
+> **Voir aussi :** [Writing Agent Instructions](/docs/writing-agent-instructions) pour savoir comment rédiger des descriptions de compétences, appliquer la divulgation progressive et maintenir `AGENTS.md` simple. Les deux pages utilisent la compétence `project-imports` comme exemple courant.
+
+## Portée des compétences : runtime vs dev {#skill-scope}
+
+Un champ frontal `scope` facultatif contrôle à quel agent une compétence est destinée :
+
+| `scope`   | Chargé par l'agent d'exécution ? | Utiliser pour                                                                                               |
+| --------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `both`    | Oui (par défaut)                 | Skills utile à l'agent intégré à l'application. Il s'agit de la valeur par défaut lorsque `scope` est omis. |
+| `runtime` | Oui                              | Skills destiné uniquement à l'agent d'exécution intégré à l'application.                                    |
+| `dev`     | Non                              | Skills destiné uniquement à l'agent de codage de l'humain (par exemple, le code Claude).                    |
+
+```markdown
+---
+name: release-checklist
+description: >-
+  Steps for cutting a release. Use when preparing or publishing a new version.
+scope: dev
+---
+```
+
+Lorsque `scope` est absent (ou défini sur une valeur non reconnue), la valeur par défaut est `both`, de sorte que chaque compétence existante continue de se charger au moment de l'exécution — ce champ est entièrement rétrocompatible. Une compétence `scope: dev` est invisible partout pour l'agent d'exécution : elle est exclue du bloc skills injecté dans l'invite système et des résultats `docs-search`.
+
+### Exposer une compétence réservée aux développeurs à votre agent de codage {#dev-only-skills}
+
+Le runtime natif de l'agent lit skills à partir de `.agents/skills/`. Le code Claude lit indépendamment skills à partir de `.claude/skills/`. Pour rendre une compétence disponible pour votre agent de codage mais masquée pour l'agent d'exécution :
+
+- Marquez-le `scope: dev` dans `.agents/skills/<name>/SKILL.md` pour que l'agent d'exécution ne le charge jamais, et/ou
+- Placez ou mettez en miroir la compétence sous `.claude/skills/<name>/SKILL.md` pour que le code Claude la récupère.
+
+Cela remplace l'ancien hack consistant à s'appuyer sur le code Claude lisant uniquement `.claude/skills` — `scope: dev` fait de la division développement/exécution un choix explicite de première classe.
+
+```an-diagram title="Which agent loads which skill" summary="scopedecides whether the in-app runtime agent sees a skill.dev skills are visible only to your coding agent."
+{
+"html": "<div class=\"sc-grid\"><div class=\"diagram-card\"><span class=\"diagram-pill\">.agents/skills/</span><div class=\"sc-row\"><span class=\"diagram-pill ok\">scope: both</span><small class=\"diagram-muted\">default</small></div><div class=\"sc-row\"><span class=\"diagram-pill ok\">scope: runtime</span></div><div class=\"sc-row\"><span class=\"diagram-pill warn\">scope: dev</span></div></div><div class=\"sc-targets\"><div class=\"diagram-box\">Runtime agent<br><small class=\"diagram-muted\">reads <code>both</code> + <code>runtime</code></small></div><div class=\"diagram-box\">Coding agent<br><small class=\"diagram-muted\">Claude Code reads <code>.claude/skills/</code> + <code>dev</code></small></div></div></div>",
+"css": ".sc-grid{display:flex;gap:24px;flex-wrap:wrap;align-items:flex-start}.sc-grid .diagram-card{display:flex;flex-direction:column;gap:8px;padding:14px 16px}.sc-grid .sc-row{display:flex;align-items:center;gap:8px}.sc-grid .sc-targets{display:flex;flex-direction:column;gap:10px}"
+}
+
+```
+
+> **Voir aussi :** [Writing Agent Instructions](/docs/writing-agent-instructions) pour savoir comment rédiger des descriptions de compétences, appliquer la divulgation progressive et maintenir `AGENTS.md` simple.
+
+## Skills contre AGENTS.md {#skills-vs-agents-md}
+
+> **AGENTS.md** — La présentation. Répertorie tous les scripts, décrit le modèle de données, explique l'architecture de l'application. L'agent lit ceci en premier pour comprendre l'application.
+>
+> **Skills** — Analyses approfondies. Chaque compétence se concentre sur un modèle avec des règles détaillées, des exemples de code et des listes de choses à faire/à ne pas faire. L'agent les lit lorsqu'il doit suivre un modèle spécifique.
+
+`AGENTS.md` indique à l'agent _ce que_ l'application fait. Skills indique à l'agent _comment_ faire des choses spécifiques correctement. Les deux sont nécessaires : `AGENTS.md` pour l'orientation, skills pour l'exécution.
+
+## Skills contre mémoire {#skills-vs-memory}
+
+> **Skills** — Guides pratiques rédigés et réutilisables. S'applique à chaque utilisateur, invoqué à la demande lorsque la tâche correspond.
+>
+> **Mémoire (`LEARNINGS.md` / `memory/MEMORY.md`)** — Apprentissages partagés du projet et mémoire structurée personnelle chargée à chaque tour.
+
+Si les connaissances s'appliquent à _tout le monde_ travaillant dans l'application (« préférez toujours les CTE aux sous-requêtes »), il s'agit d'une compétence ou d'un `LEARNINGS.md` partagé. S'il s'agit de _cet utilisateur particulier_ ("Steve aime les réponses concises"), cela appartient à `memory/MEMORY.md`. Voir [Workspace Memory](/docs/workspace#memory) pour le traitement complet.
+
+---
+
+# Avancé
+
+## skills basé sur une application — tous les détails {#app-backed-skills-full}
+
+skills basé sur une application regroupe une application native d'agent en tant qu'artefact de marché de compétences.
+Le bundle peut inclure des instructions d'agent, un connecteur skills exporté et un connecteur MCP
+métadonnées, instructions de lancement hébergées/locales et surfaces UI telles que les applications MCP.
+
+Chaque compétence basée sur l'application commence par `agent-native.app-skill.json` à la racine de l'application :
+
+```json
+{
+  "schemaVersion": 1,
+  "id": "assets",
+  "hosted": {
+    "url": "https://assets.agent-native.com",
+    "mcpUrl": "https://assets.agent-native.com/_agent-native/mcp"
+  },
+  "mcp": { "serverName": "agent-native-assets" },
+  "skills": [
+    {
+      "path": ".agents/skills/asset-generation",
+      "visibility": "both",
+      "exportAs": "assets"
+    }
+  ]
+}
+```
+
+La visibilité des compétences contrôle ce qui est expédié :
+
+| Visibilité | Signification                                                                        |
+| ---------- | ------------------------------------------------------------------------------------ |
+| `internal` | Utilisé par le propre agent de l'application, non exporté vers les places de marché. |
+| `exported` | Exporté vers les places de marché, mais non nécessaire à l'application en interne.   |
+| `both`     | Utilisé en interne et exporté.                                                       |
+
+Hosted est le chemin d’installation par défaut. Le lancement local est explicite pour la personnalisation,
+travail hors ligne ou utilisation sensible à la confidentialité.
+
+```bash
+# Happy path: exported instructions plus hosted MCP connector.
+npx @agent-native/core@latest skills add visual-plan
+npx @agent-native/core@latest skills add assets
+
+# Repo-first Content docs/blog/MDX editing.
+npx @agent-native/core@latest skills add content --mode local-files --scope project
+
+# Vercel/open Skills CLI: exported instructions only, no MCP config.
+npx skills@latest add BuilderIO/agent-native --skill assets
+
+# Register a hosted MCP connector for local agent clients.
+npx @agent-native/core@latest app-skill ensure --manifest templates/assets/agent-native.app-skill.json
+
+# Materialize and run editable local source.
+npx @agent-native/core@latest app-skill launch --manifest templates/assets/agent-native.app-skill.json --local --into ./assets-local
+
+# Build marketplace adapters: Codex plugin, Claude marketplace, Vercel skills,
+# plain/Claude skills, and MCP configs.
+npx @agent-native/core@latest app-skill pack --manifest templates/assets/agent-native.app-skill.json --out ./dist/assets-skill
+
+# Install a local exported bundle with the Vercel/open Skills CLI.
+npx skills@latest add ./dist/assets-skill --skill assets -a codex -y
+
+# Add the generated Claude Code marketplace, then install its Assets plugin.
+claude plugin marketplace add ./dist/assets-skill/adapters/claude-marketplace
+claude plugin install agent-native-assets@agent-native-apps
+```
+
+Gardez les secrets hors des fichiers de compétences. Le manifeste doit contenir le connecteur URL uniquement
+métadonnées ; La configuration de OAuth/appareil s'effectue dans l'hôte MCP ou via le mode normal de l'application
+flux des paramètres.
+
+L'adaptateur Vercel Labs `skills` est un ensemble portable `skills/<name>/SKILL.md`
+pour `npx skills@latest add ...`, mais le `skills` brut CLI installe uniquement les instructions.
+Il n'exécute pas les scripts de post-installation définis dans le référentiel et n'enregistre pas les connecteurs MCP.
+Conservez le Agent Native CLI comme chemin de documentation par défaut pour les agents locaux, car il
+enregistre également le connecteur MCP. `BuilderIO/agent-native` est un vrai GitHub
+source du référentiel pour Vercel/open Skills CLI ; `skills.sh` est une découverte et
+répertoire du classement, pas un espace de noms de package de style npm.
+
+L'adaptateur de marché Claude Code écrit
+`adapters/claude-marketplace/.claude-plugin/marketplace.json` plus un imbriqué
+répertoire du plugin contenant `skills/<name>/SKILL.md` et `.mcp.json`. Dans Claude
+Codez, ajoutez la place de marché, installez `agent-native-assets@agent-native-apps`,
+rechargez les plugins, puis authentifiez le connecteur MCP uniquement URL à partir de `/mcp`.
+
+Les manifestes de plug-in générés sont configurés pour être mis à jour automatiquement : le code Claude
+ensembles d'entrées de marché `autoUpdate: true` (avec gestion des versions commit-SHA) et
+Le plug-in Codex `version` intègre un hachage de contenu des ensembles skills et MCP
+point de terminaison, donc les plugins installés récupèrent les changements de compétences sans reconditionner. Le
+L'application Plan est publiée de cette manière en tant que marché prêt à être ajouté à la racine du dépôt –
+voir [Plan plugin & marketplace](/docs/plan-plugin) pour l'installation de bout en bout
+et flux de mise à jour automatique.
+
+Pour les utilisateurs qui installent une copie de skills via le CLI universel au lieu d'un
+Place de marché des plugins, utilisez les commandes de fraîcheur CLI :
+
+```bash
+npx @agent-native/core@latest skills status visual-plan
+npx @agent-native/core@latest skills update visual-plan
+```
+
+`skills update` analyse les projets Codex/Claude connus et les dossiers de compétences utilisateur, compare
+le dossier copié est haché dans la dernière compétence groupée et réécrit les dossiers obsolètes dans
+lieu. Les Agent Native skills nouvellement copiés incluent un `agent-native-skill.json`
+marqueur permettant à la sortie d'état future d'identifier la source et le hachage.
+
+Les applications et espaces de travail Agent Native générés incluent également le framework fourni
+skills sous `.agents/skills` (ou `packages/shared/.agents/skills` dans un
+espace de travail). Actualisez ces skills échafaudés à partir du CLI actuel/dernier avec :
+
+```bash
+npm run skills:update
+# or, without relying on the local package script:
+npx @agent-native/core@latest skills update scaffold --project
+```
+
+`AGENTS.md` et `.agents/skills` restent canoniques. La commande update répare également
+Liens de compatibilité Claude (`CLAUDE.md` et `.claude/skills`) pour que le code Claude voie
+les mêmes instructions sans conserver une deuxième copie.