Cursor Skills : créer et partager

À la fin de ce tutoriel Cursor Skills, vous saurez créer un Agent Skill (SKILL.md), le placer (projet vs machine), l’invoquer avec /skill-name, le scoper avec paths, et le partager via Git, marketplace équipe ou Sync Cloud Agents — lab DevOps sans secrets.

Niveau : Intermédiaire · Temps estimé : 40–50 min · Versions testées : Cursor Agent / Skills (doc 2026) · Dernière vérification : 2026-09-11

Prérequis

• Hub IA pour DevOps : parcours 2026
• AI Skills : concept et catalogue
• Cursor IDE avec Agent (pas seulement Tab)
• Dépôt Git de lab ; aucun token CI, kubeconfig ou mot de passe réel
• Bases Markdown / YAML frontmatter

Coût : 0 € (hors plan Cursor éventuel).

Ce que nous allons construire

lab-cursor-skills/
  ├── .cursor/skills/deploy-staging/
  │   ├── SKILL.md
  │   ├── scripts/smoke-check.sh
  │   └── references/CHECKLIST.md
  ├── app/README.md
  └── .git/
# optionnel : ~/.cursor/skills/commit-hygiene/

(Schéma à remplacer par une image locale Excalidraw / draw.io, alt : « Cursor Skills : SKILL.md, Git, Sync Cloud Agents, marketplace ».)

Leçon #29 : on fabrique et on distribue un skill que l’Agent auto-applique si la description matche, ou que vous forcez avec /. En équipe DevOps, c’est le moyen le plus propre de figer un runbook (staging, rollback, revue PR) sans le retaper à chaque conversation.

Un skill n’est pas un prompt jetable : c’est un artefact versionné, relisible en PR, et réutilisable par tout Agent qui ouvre le repo. L’objectif pédagogique de cette page est double — écrire un SKILL.md correct, puis choisir le bon canal de partage (Git projet, Sync Cloud Agents, ou Publish équipe).

Étape 1 — Skills vs Rules

	Rules	Skills
Rôle	Guidelines / contraintes	Workflows multi-étapes
Taille	Courte	Procédurale
Chargement	Contexte (toujours ou match)	À la demande (auto ou /nom)
Exemple	« TypeScript uniquement »	« Deploy staging : tests, build, healthcheck »

Rule = norme permanente (« pas de secrets dans le repo », « Conventional Commits »). Skill = procédure ordonnée (déploiement, audit de dépendances, checklist de merge). Les Skills suivent le standard Agent Skills : portables, versionnés, progressifs. Docs : Skills · aide.

En pratique : si la consigne tient en trois lignes et doit s’appliquer presque toujours, restez en Rule. Si vous décrivez une séquence (lire une checklist, lancer un script, résumer des preuves, ne jamais inventer un succès), passez en Skill. Mélanger les deux rôles produit soit du contexte inutile, soit des runbooks introuvables.

Étape 2 — Emplacements

Emplacement	Portée
.cursor/skills/	Projet (Git / équipe)
.agents/skills/	Projet (standard Agent Skills)
~/.cursor/skills/	Perso, machines locales
~/.agents/skills/	Perso cross-outils
.claude/skills/, .codex/skills/ (+ ~/)	Compat Claude / Codex

Sous-dossiers (catégories) et monorepo (apps/web/.cursor/skills/) : auto-scopés au sous-arbre. Le name vient du dossier qui contient SKILL.md, pas du dossier catégorie parent (shipping/, debugging/, etc.).

Cette découverte fichier-based est un avantage ops : pas de registre opaque. Vous auditez le skill comme du code. En contrepartie, un mauvais chemin ou un SKILL.md mal nommé = skill invisible — d’où les checks de l’étape validation plus bas.

Cloud Agents : seul ~/.cursor/skills/ se synchronise (Settings → Agents → Sync Skills for Cloud Agents). Les skills projet voyagent avec le repo. ~/.agents/skills/ et le local non syncé restent sur la machine ; sur self-hosted workers, préférez skills projet ou image worker.

Étape 3 — Lab projet

mkdir -p ~/lab-cursor-skills/.cursor/skills/deploy-staging/{scripts,references}
mkdir -p ~/lab-cursor-skills/app
cd ~/lab-cursor-skills
git init
printf '# Lab appn' > app/README.md

Étape 4 — Écrire SKILL.md

Le name (minuscules, tirets) = dossier parent. La description (« use this when… ») pilote l’auto-apply : déclencheurs concrets (ship, staging, health after merge). Une description vague (« helps with devops ») donne soit zéro auto-apply, soit trop d’activations.

Traitez la description comme un routeur : listez les intentions utilisateur et les moments du cycle (après merge, avant promo prod). Évitez les synonymes flous. Si le skill est dangereux (deploy réel, suppressions), ajoutez disable-model-invocation: true pour forcer l’appel explicite /skill-name.

cat > .cursor/skills/deploy-staging/SKILL.md << 'EOF'
---
name: deploy-staging
description: Deploy the app to staging. Use when the user asks to ship to staging, run a pre-prod release, or verify staging health after a merge.
paths:
  - "app/**"
  - "**/*.yml"
  - "**/*.yaml"
---

# Deploy staging

## When to use
- User asks to deploy / ship / promote to staging
- After merge to the staging branch

## Instructions
1. Read `references/CHECKLIST.md` before any command.
2. Run `scripts/smoke-check.sh` (lab : no real cluster).
3. Confirm build artifacts under `app/` (or report missing).
4. Summarize checks; never invent a green deploy.
5. Do not use production credentials. Lab only.

## Progressive disclosure
Keep this file short. Load `references/` only when needed.
EOF

cat > .cursor/skills/deploy-staging/references/CHECKLIST.md << 'EOF'
# Checklist staging (lab)
- [ ] Tests unitaires verts en local
- [ ] Artefact `app:staging-lab`
- [ ] Healthcheck HTTP factice OK
- [ ] Aucun secret en clair dans les logs Agent
EOF

cat > .cursor/skills/deploy-staging/scripts/smoke-check.sh << 'EOF'
#!/usr/bin/env bash
set -euo pipefail
echo "smoke-check: lab OK (no remote call)"
exit 0
EOF
chmod +x .cursor/skills/deploy-staging/scripts/smoke-check.sh

Champ	Effet
paths	Surfacing si fichiers matchent
disable-model-invocation: true	Slash only
icon / color	Badge Custom Mode
metadata	Clés libres

Ancien globs : fallback ; préférez paths. Détail long → references/ (chargement progressif).

Le pattern DevOps gagnant : SKILL.md = contrat court (quand / étapes / interdits), scripts/ = commandes idempotentes avec messages d’erreur clairs, references/ = checklists et procédures de repli lues seulement si le scénario l’exige. Vous économisez du contexte Agent et vous gardez une source unique pour la checklist humaine.

Étape 5 — /create-skill et migration

Dans le chat Agent, tapez /create-skill et décrivez le workflow (« checklist deploy staging, scripts smoke, references »). Cursor guide nommage et emplacement. Relisez toujours le fichier : corrigez d’abord la description (routeur d’auto-apply), puis les chemins relatifs vers scripts. Migration d’anciennes slash commands ou rules dynamiques (« Apply Intelligently ») : /migrate-to-skills (Cursor 2.4+). Les rules alwaysApply: true ou déjà scopées par globs ne migrent pas automatiquement.

Étape 6 — Invoquer

1. Rouvrir le projet (reload Agent si besoin).
2. Customize → Skills : voir deploy-staging.
3. /deploy-staging ou @ + skill.
4. Session entière : Custom Mode (Option+Enter / Alt+Enter).
5. Phrase naturelle : « prépare un déploiement staging ».

cd ~/lab-cursor-skills
test -f .cursor/skills/deploy-staging/SKILL.md
./.cursor/skills/deploy-staging/scripts/smoke-check.sh

Étape 7 — Perso vs projet

mkdir -p ~/.cursor/skills/commit-hygiene
cat > ~/.cursor/skills/commit-hygiene/SKILL.md << 'EOF'
---
name: commit-hygiene
description: Write clear conventional commits. Use when the user asks to commit, craft a commit message, or clean a messy staging area.
disable-model-invocation: true
---

# Commit hygiene
1. Run git status and git diff (staged + unstaged).
2. Propose a short subject (why, not what).
3. Never commit .env, keys, or *.pem.
4. Do not --amend unless the user explicitly asks and HEAD is theirs/unpushed.
EOF

• Projet (.cursor/skills/) : équipe via Git — chemin DevOps recommandé pour tout runbook partagé.
• Perso (~/.cursor/skills/) : vos habitudes sur tous les repos ; Cloud Agents → activer Sync Skills for Cloud Agents.
• Publish (Customize → Skills) = marketplace Default de l’équipe ; distinct du Sync (privé, vos Cloud Agents seulement).

Erreur classique : laisser un skill d’équipe uniquement sous ~/ — les collègues et la CI n’en voient rien. Inverse : publier un skill perso plein d’opinions locales sur la marketplace sans revue. Pour un staging commun, committez sous .cursor/skills/ et faites relire la description en PR.

Étape 8 — Partager avec Git

cd ~/lab-cursor-skills
git add .cursor/skills/deploy-staging app/README.md
git commit -m "Add deploy-staging Cursor skill for lab"

Tout cloneur du repo récupère le skill. C’est le mode standard pour conventions d’équipe et checklists CI/CD. Alternative : Remote Rule (GitHub) dans Customize. Passez .cursor/skills/ en code review comme un runbook : une mauvaise description se propage à toute l’équipe. Sur Teams / Enterprise, les admins peuvent couper le sync Cloud Agents au niveau org — le commit Git projet reste alors le canal fiable.

Étape 9 — Qualité

1. Description = contrat (déclencheurs clairs).
2. SKILL.md court ; détail dans references/ / scripts/.
3. Scripts idempotents, lab sans réseau réel.
4. Un skill = un job.
5. Scoping : paths ou dossier monorepo.
6. disable-model-invocation: true pour actions destructives.
7. Suite : Évaluer la qualité d’un skill.

.cursor/skills/deploy-staging/
  ├── SKILL.md
  ├── scripts/smoke-check.sh
  ├── references/CHECKLIST.md
  └── references/ROLLBACK.md

Chargez ROLLBACK.md seulement en échec. En monorepo, skills sous apps/api/ et apps/web/ restent isolés — api-migrate ne pollue pas le contexte quand vous ne touchez que le front.

Si le skill vit à la racine mais ne doit s’activer que sur Terraform ou Helm, déclarez paths (**/*.tf, helm/**) plutôt que de l’appliquer à tout le monorepo. Moins de bruit, moins de faux positifs d’auto-apply.

Étape 10 — Validation (5 min)

1. Agent sur ~/lab-cursor-skills.
2. « Checklist deploy staging sans toucher la prod. »
3. Vérifier SKILL.md, smoke-check.sh, citation checklist.
4. Forcer /deploy-staging : même comportement.
5. Déplacer le dossier hors .cursor/skills/ : disparition dans Customize → Skills.

Si l’Agent invente un déploiement réussi sans script : resserrer « never invent a green deploy » et ajoutez un critère de succès explicite dans la checklist. Documentez aussi qui valide le go/no-go staging (humain) pour que l’Agent ne franchisse jamais seul la porte prod.

Ce mini scénario valide trois choses : découverte fichier, exécution des scripts du skill, et honnêteté du résumé. Si l’une manque, corrigez le SKILL.md avant de le partager à l’équipe.

Pièges fréquents

Symptôme	Cause	Correctif
Skill invisible	Mauvais chemin	.cursor/skills/<name>/SKILL.md
Pas d’auto-apply	description vague	« Use when… » + déclencheurs
Auto trop agressif	Description trop large	Affiner ou disable-model-invocation
name rejeté	≠ dossier	Aligner folder + frontmatter
Cloud Agent sans skill perso	Sync off	Settings → Agents → Sync Skills
Équipe sans le skill	Seulement dans ~/	Commit .cursor/skills/ ou Publish
Confusion Rule / Skill	Guideline longue en Rule	/create-skill ou /migrate-to-skills

Quiz (4 questions)

1. Où committer un skill pour toute l’équipe ?
– A. Uniquement ~/.cursor/skills/
– B. .cursor/skills/ (ou .agents/skills/) dans le repo
– C. Uniquement le marketplace public Cursor

2. Quel champ oriente surtout l’auto-apply ?
– A. icon
– B. description
– C. metadata

3. Que fait disable-model-invocation: true ?
– A. Supprime le skill
– B. Empêche l’invocation /
– C. Pas d’auto-apply ; /skill-name seulement

4. Sync Skills for Cloud Agents synchronise surtout :
– A. Tout le disque
– B. ~/.cursor/skills/
– C. Uniquement .claude/skills/

Réponses : 1‑B · 2‑B · 3‑C · 4‑B

FAQ

Skill ou Rule pour « toujours du Conventional Commits » ?
Rule courte pour la norme. Skill (commit-hygiene) pour status/diff/message + garde-fous secrets.

.cursor/skills/ ou .agents/skills/ ?
Les deux chargent au niveau projet. .agents/skills/ = standard multi-outils ; .cursor/skills/ + Git = chemin Cursor-first le plus simple.

Comment tester sans risque prod ?
Lab local, scripts sans cluster, paths serrés, disable-model-invocation sur tout deploy réel. Voir MCP servers DevOps.

Sync Cloud Agents vs Publish équipe ?
Sync copie ~/.cursor/skills/ vers vos Cloud Agents (privé). Publish = marketplace équipe. Runbook commun → commit Git projet.

Le skill n’apparaît pas après commit ?
Chemin exact, reload Agent, name = dossier. En monorepo, un skill sous apps/web/ ne surface que dans ce sous-arbre.

Pour aller plus loin

• Docs : cursor.com/docs/skills · aide Skills · agentskills.io
• Précédent : AI Skills : concept
• Suite : Skills Claude / custom instructions · Évaluer la qualité d’un skill
• Voisins : Cursor Agent / Composer 2026 · MCP servers DevOps · Routines et agents planifiés

Maillage série IA Outils 2026 — Skills & agents

← Précédent	AI Skills : concept et catalogue
→ Suite	Skills Claude / custom instructions
Hub	IA pour DevOps : parcours 2026