207 — APM — installer et partager

Durée : 60 min · Complexité : ⭐⭐ · Pré-requis : Module 104 — Agents, Module 103 — Skills

Tu sais créer des skills et des agents. Mais comment les partager entre projets — ou consommer ceux publiés par d’autres ? C’est le rôle d’APM.

Pourquoi ce module

Dans les modules précédents, tu as créé des skills et des agents directement dans le dossier .agents/ de ton dépôt. Cette approche fonctionne tant que tu travailles seul sur un seul projet. Dès que tu veux réutiliser un skill dans un autre dépôt, tu te retrouves à copier-coller des fichiers manuellement — avec les problèmes classiques de synchronisation : quelle version est à jour ? Comment savoir si une nouvelle version est disponible ? Comment garantir que toute l’équipe a exactement la même configuration ?

APM (Agent Package Manager) résout ce problème. C’est un gestionnaire de dépendances pour la configuration des agents IA — pense à package.json, requirements.txt ou Cargo.toml, mais pour les primitives agentiques : instructions, skills, prompts, agents, hooks, plugins et serveurs MCP. Tu déclares les dépendances de ton projet une fois dans apm.yml, et toute personne qui clone le dépôt obtient la même configuration en une commande.

Source: https://github.com/microsoft/apm — README Citation: “Declare your project’s agentic dependencies once in apm.yml, and every developer who clones your repo gets a fully configured agent setup in seconds — with transitive dependency resolution, just like npm or pip.” Fetched: 2026-06-06

Le projet est open source, maintenu sous l’organisation microsoft/apm et créé par @danielmeppiel. Il fonctionne avec GitHub Copilot, Claude Code, Cursor, OpenCode, Codex, Gemini et Windsurf.

À la fin de ce module, tu sais :

installer la CLI APM ;
décrire la structure d’un fichier apm.yml (manifeste) et son apm.lock.yaml (lockfile) ;
installer une primitive distante et reproduire une configuration avec apm install ;
compiler ta configuration pour Copilot avec apm compile -t copilot ;
publier tes propres primitives pour qu’elles soient consommables par d’autres.

Pré-requis

Module 104 — Agents — tu dois savoir créer un agent.
Module 103 — Skills — tu dois savoir créer un skill.
VS Code avec l’extension GitHub Copilot activée.
Un dépôt Git hébergé sur GitHub.

Concepts clés

Installer APM

APM se distribue en binaire natif (macOS, Linux, Windows) ou via un gestionnaire de paquets.

# macOS / Linux — installeur officiel
curl -sSL https://aka.ms/apm-unix | sh

# Homebrew
brew install microsoft/apm/apm

# pip
pip install apm-cli

Source: https://github.com/microsoft/apm — README, section « Get Started » Citation: “curl -sSL https://aka.ms/apm-unix | sh” / “brew install microsoft/apm/apm” / “pip install apm-cli” Fetched: 2026-06-06

Le fichier `apm.yml` — le manifeste

Le fichier apm.yml se place à la racine de ton dépôt. C’est le manifeste qui décrit ton projet et ses dépendances agentiques. Contrairement à ce que tu pourrais croire, tu peux l’éditer à la main — c’est un fichier déclaratif, exactement comme un package.json.

Voici le manifeste réel de ce dépôt de documentation :

# apm.yml
name: documentation
version: 1.0.0
description: APM project for documentation
author: SebastienDegodez
dependencies:
  apm:
    - danielmeppiel/genesis/skills/genesis
  mcp: []
includes: auto
scripts: {}

Les clés importantes :

name / version / description / author — l’identité de ton package, comme dans n’importe quel manifeste.
dependencies.apm — la liste des primitives agentiques (skills, agents, prompts, plugins, packages complets). Chaque entrée est une chaîne au format <owner>/<repo>/<kind>/<name>, pas un objet.
dependencies.mcp — la liste des serveurs MCP à installer dans chaque client détecté.
includes: auto — APM scanne automatiquement le dossier .agents/ et expose les primitives locales qu’il y trouve.
scripts — des scripts nommés, exécutables avec apm run <nom>.

La convention de nommage des dépendances

Une dépendance apm se réfère à une primitive par son chemin dans un dépôt Git :

<owner>/<repo>/<kind>/<name>

Segment	Rôle	Exemple
`owner`	Propriétaire du dépôt	`danielmeppiel`, `anthropics`
`repo`	Nom du dépôt	`genesis`, `skills`
`kind`	Type de primitive	`skills`, `agents`, `prompts`, `plugins`
`name`	Nom de la primitive	`genesis`, `frontend-design`

Quelques formes acceptées, tirées de la documentation officielle :

dependencies:
  apm:
    # Un skill depuis n'importe quel dépôt
    - anthropics/skills/skills/frontend-design
    # Un plugin
    - github/awesome-copilot/plugins/context-engineering
    # Une primitive agent précise (fichier .agent.md)
    - github/awesome-copilot/agents/api-architect.agent.md
    # Un package APM complet, épinglé sur un tag
    - microsoft/apm-sample-package#v1.0.0

Source: https://github.com/microsoft/apm — README, exemple apm.yml Citation: “anthropics/skills/skills/frontend-design” / “microsoft/apm-sample-package#v1.0.0” Fetched: 2026-06-06

Le versioning se fait avec le suffixe #<tag> directement dans la chaîne de dépendance (ex. microsoft/apm-sample-package#v1.0.0). Sans suffixe, APM résout la dernière version et épingle le commit dans le lockfile (voir ci-dessous).

Le fichier `apm.lock.yaml` — le lockfile

Le lockfile fige l’arbre de dépendances résolu, exactement comme package-lock.json pour npm. C’est lui qui contient les SHA de commit, pas apm.yml. Tu ne l’édites jamais à la main.

Voici le lockfile réel de ce dépôt :

# apm.lock.yaml
lockfile_version: '1'
generated_at: '2026-05-27T06:11:02.506757+00:00'
apm_version: 0.12.4
dependencies:
  - repo_url: danielmeppiel/genesis
    host: github.com
    resolved_commit: 16a5027d6cdc23c0fd9df21f65e21fa0f681d722
    virtual_path: skills/genesis
    is_virtual: true
    package_type: claude_skill
    deployed_files:
      - .agents/skills/genesis
    content_hash: sha256:daf0921acaa8c992368b2e4d984efdc5b0f53917ac78eae33b7984f1c349fcca

Chaque entrée enregistre le commit résolu (resolved_commit), le hash d’intégrité du contenu (content_hash) et les fichiers déployés (deployed_files). C’est ce qui garantit une installation reproductible et vérifiable : APM bloque un package dont le contenu ne correspond plus à son hash.

La commande `apm install`

apm install sans argument lit apm.yml et reproduit toute la configuration — c’est la commande que lance quiconque clone ton dépôt :

git clone <org/repo> && cd <repo>
apm install     # tous les agents sont configurés

apm install <package> ajoute une dépendance et la persiste dans apm.yml :

apm install danielmeppiel/genesis/skills/genesis

Source: https://github.com/microsoft/apm — README Citation: “git clone <org/repo> && cd " / "apm install # every agent is configured" Fetched: 2026-06-06

Pour un serveur MCP, on utilise le flag --mcp :

apm install --mcp io.github.github/github-mcp-server --transport http

Source: https://github.com/microsoft/apm — README Citation: “apm install –mcp io.github.github/github-mcp-server –transport http # connects over HTTPS” Fetched: 2026-06-06

Compiler pour Copilot

APM déploie les primitives dans .agents/ (découvert par plusieurs clients). Pour générer en plus le fichier que VS Code et GitHub Copilot lisent automatiquement, tu compiles avec la cible copilot :

apm compile -t copilot     # écrit .github/copilot-instructions.md

Source: https://github.com/microsoft/apm — README Citation: “apm compile -t copilot # writes .github/copilot-instructions.md” Fetched: 2026-06-06

C’est volontairement « zéro config » : une commande, aucun réglage — VS Code lit le fichier tout seul.

Sécurité : `apm audit`

Le contexte d’un agent est exécutable de fait — un prompt est un programme pour un LLM. APM le traite comme tel. Chaque apm install scanne le contenu (Unicode caché, packages compromis) ; apm audit rejoue ces vérifications à la demande et détecte la dérive (les éditions à la main de ta configuration) en reconstruisant le contexte et en le comparant à ton arbre de travail.

Source: https://github.com/microsoft/apm — README, section « Secure by default » Citation: “apm install blocks compromised packages before agents read them; apm audit runs the same checks on demand” Fetched: 2026-06-06

Démonstration

Étape 1 — Installer la CLI

curl -sSL https://aka.ms/apm-unix | sh
# ou : brew install microsoft/apm/apm
apm --version

Étape 2 — Installer un skill distant

Pars d’un dépôt neuf. apm install <package> crée ou met à jour apm.yml et apm.lock.yaml automatiquement :

mkdir mon-projet-apm && cd mon-projet-apm
git init
apm install danielmeppiel/genesis/skills/genesis

Vérifie ce qui a été déployé et verrouillé :

ls .agents/skills/genesis/        # SKILL.md déployé
cat apm.yml                        # dépendance ajoutée sous dependencies.apm
cat apm.lock.yaml                  # resolved_commit + content_hash

Étape 3 — Compiler pour Copilot et tester

apm compile -t copilot             # écrit .github/copilot-instructions.md

Ouvre le dépôt dans VS Code, ouvre Copilot Chat en mode Agent, et formule une requête qui correspond à la description sémantique de genesis. Le routeur sémantique doit activer le skill.

Étape 4 — Reproduire ailleurs

Sur une autre machine (ou en CI), il suffit de cloner et d’installer — le lockfile garantit le même résultat :

git clone <ton-dépôt> && cd <ton-dépôt>
apm install

Étape 5 — Publier tes propres primitives

Pour rendre un skill installable par d’autres, pousse-le sur GitHub dans .agents/skills/<nom>/SKILL.md. Le dépôt GitHub est le registre. Marque une version stable avec un tag :

git add .agents/skills/writing-changelog/SKILL.md
git commit -m "feat: add writing-changelog skill"
git tag v1.0.0 && git push origin main --tags

N’importe qui peut alors l’installer, épinglé sur le tag :

apm install my-org/copilot-primitives/skills/writing-changelog
# ou figé : my-org/copilot-primitives#v1.0.0 dans apm.yml

Exercice ⭐⭐

Énoncé — Installe le skill genesis dans un dépôt neuf, compile pour Copilot, et reproduis l’installation depuis le lockfile.

Étapes guidées :

Installe la CLI APM (curl -sSL https://aka.ms/apm-unix | sh) et vérifie apm --version.
Crée un dépôt local : mkdir demo-apm && cd demo-apm && git init.
Installe le skill : apm install danielmeppiel/genesis/skills/genesis.
Inspecte apm.yml (la dépendance est sous dependencies.apm) et apm.lock.yaml (le resolved_commit et le content_hash).
Compile pour Copilot : apm compile -t copilot, puis vérifie .github/copilot-instructions.md.
Supprime .agents/ et relance apm install (sans argument) : la configuration se reconstruit à l’identique depuis le lockfile.

Critère de réussite : apm install se termine sans erreur, .agents/skills/genesis/SKILL.md est présent, apm.lock.yaml contient un resolved_commit, et le skill est utilisable dans Copilot.

Validation

Tu peux passer au module suivant si :

Tu as installé la CLI APM et exécuté apm --version.
Ton dépôt contient un apm.yml avec includes: auto et une dépendance sous dependencies.apm.
Tu sais que les SHA de commit vivent dans apm.lock.yaml, pas dans apm.yml.
apm compile -t copilot a généré .github/copilot-instructions.md.
Tu sais épingler une dépendance sur un tag avec le suffixe #vX.Y.Z.
Tu sais publier tes propres primitives en les poussant dans .agents/ sur GitHub.

Pour aller plus loin

Documentation officielle APM — guide complet, référence CLI, types de primitives.
CLI Reference — toutes les commandes (install, compile, audit, pack, marketplace, run).
Module 315 — Evals — vérifier que les primitives installées fonctionnent comme attendu.
Module 209 — Plugins — découvrir et installer des extensions packagées.

Sources

https://github.com/microsoft/apm — README (fetched 2026-06-06)
https://microsoft.github.io/apm/ — documentation officielle
apm.yml et apm.lock.yaml de ce dépôt