Skills Claude / custom instructions

À la fin de ce tutoriel Skills Claude, vous saurez distinguer custom instructions (compte + Project) et Agent Skills (SKILL.md), placer un skill sous .claude/skills/ ou ~/.claude/skills/, rédiger name + description pour le routage, et enchaîner un lab triage incident factice — sans secrets ni cluster réel.

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

Prérequis

• Hub IA pour DevOps : parcours 2026
• AI Skills : concept et catalogue
• Frère Cursor Skills : créer et partager (même format SKILL.md)
• Claude.ai (Customize → Skills) ou Claude Code en local
• Markdown / YAML frontmatter ; aucun token, kubeconfig ou mot de passe réel

Coût : selon le plan Claude (skills document pré-construits souvent sur plans payants) ; le lab fichier est gratuit.

Ce que nous allons construire

lab-claude-skills/                 (projet factice)
  ├── project-instructions.md      (simule Project instructions)
  ├── .claude/skills/incident-triage/
  │   ├── SKILL.md
  │   ├── references/CHECKLIST.md
  │   ├── scripts/parse-logs.sh
  │   └── assets/
  ├── logs/sample-app.log
  └── README.md
       → instructions = rôle / ton / FR always-on
       → Skill = procédure triage si description match
       → perso optionnel : ~/.claude/skills/

(Schéma à remplacer par Excalidraw / draw.io, alt : « Claude Skills SKILL.md vs custom instructions, .claude/skills et ~/.claude/skills ».)

Chapitre #30 Skills & agents : après Cursor (#29), même standard Agent Skills chez Anthropic, plus la couche custom instructions.

Étape 1 — Prompts, Projects, Skills, MCP

Couche	Rôle	Persistance	Exemple DevOps
Prompt	Moment-à-moment	Un message	« Résume ce terraform plan »
Custom instructions (compte)	Ton / rôle always-on	Compte Claude.ai	« Réponds en français, style runbook »
Project instructions	Contexte + règles d’un workspace	Un Project (~200K)	Runbook d’équipe, glossaire
Skills (Agent Skills)	Workflow procédural	SKILL.md chargé dynamiquement	Triage incident, revue plan TF
MCP	Outils / données	Serveurs MCP	Voir MCP servers DevOps

Instructions = qui vous êtes et comment vous parlez ; Skills = comment enchaîner une procédure ; MCP = à quels outils vous brancher. Ne mettez pas un runbook de 80 étapes dans les custom instructions.

Docs : How to create custom skills · Skills explained · anthropics/skills · agentskills.io.

Étape 2 — Custom instructions : compte et Project

Sur Claude.ai, les instructions compte fixent langue, ton et garde-fous transverses (« jamais inventer un statut vert », « citer les fichiers lus »). Gardez-les courtes.

Un Project ajoute instructions + connaissance pour un workspace (contexte large, ordre 200K). Idéal pour glossaire services, conventions FR/tableaux, fichiers runbook sans secrets. Les Project instructions ne s’appliquent que dans ce Project.

Fichier terminal CLAUDE.md : Claude Code et CLAUDE.md. Produit Projects / Artifacts : Claude Projects & Artifacts.

Custom instructions pour ton, langue, rôle SRE, règles always-on. Skill dès qu’il y a une procédure multi-étapes (triage, checklist CI, revue Terraform).

Étape 3 — Structure d’un Claude Skill

Un Agent Skill = dossier avec SKILL.md et frontmatter :

• name : minuscules / tirets ; identique au nom du dossier
• description : contrat de routage (« what + when ») — chargement si match

Progressive disclosure : SKILL.md court ; détail dans references/ ; scripts/ ; assets/ optionnels.

Emplacement	Portée
~/.claude/skills/	Personnel (Claude Code)
.claude/skills/	Projet / Git (équipe)
Claude.ai → Customize → Skills	Upload custom ; skills document pré-construits (plans payants)

Même idée que Cursor (.cursor/skills/) — tutoriel frère — chemins Claude = .claude/skills/.

Étape 4 — Lab : arborescence + Project instructions

mkdir -p ~/lab-claude-skills/.claude/skills/incident-triage/{references,scripts,assets}
mkdir -p ~/lab-claude-skills/logs
cd ~/lab-claude-skills
printf '# Lab Claude Skills — triage incident (factice)n' > README.md

Simulez les Project instructions :

cat > ~/lab-claude-skills/project-instructions.md << 'EOF'
# Project instructions — Runbook DevOps (lab)

### Rôle
Tu es un SRE junior assisté. Triage d'incidents de lab uniquement.

### Ton et langue
- Français, style runbook (listes, tableaux).
- Pas de marketing.

### Garde-fous always-on
- Aucun secret, token, kubeconfig réel.
- Ne jamais inventer « résolu » ou « cluster OK ».
- Si une info manque dans les logs, dis-le.
- Cite les fichiers lus (SKILL.md, CHECKLIST, logs).

### Contexte
Services factices : `checkout-api`, `payments-worker`. Env : `lab` uniquement.
EOF

Logs factices :

cat > ~/lab-claude-skills/logs/sample-app.log << 'EOF'
2026-09-11T10:01:02Z WARN checkout-api latency_ms=820 path=/cart
2026-09-11T10:01:15Z ERROR payments-worker timeout upstream=bank-sim
2026-09-11T10:01:40Z ERROR checkout-api dependency_fail service=payments-worker
2026-09-11T10:02:01Z INFO checkout-api retry attempt=2
EOF

Étape 5 — Skill incident-triage (SKILL.md)

cat > ~/lab-claude-skills/.claude/skills/incident-triage/SKILL.md << 'EOF'
---
name: incident-triage
description: Triage a lab application incident from logs. Use when the user reports an outage, error spike, checkout/payments failure, or asks to run incident triage / runbook steps on sample logs.
---

# Incident triage (lab)

## When to use
- Incident, outage, errors on checkout-api or payments-worker
- Demande de checklist triage ou hypothèse à partir de logs

## Instructions
1. Read `references/CHECKLIST.md` before conclusions.
2. Run `scripts/parse-logs.sh` on the provided log path (lab only).
3. Summarize: symptoms, blast radius, next manual checks.
4. Never claim production access or invent green status.
5. Keep answers in French if Project / custom instructions require it.

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

Référence + script :

cat > ~/lab-claude-skills/.claude/skills/incident-triage/references/CHECKLIST.md << 'EOF'
# Checklist triage incident (lab)
- [ ] Fenêtre temporelle des erreurs
- [ ] Services touchés (checkout-api, payments-worker, …)
- [ ] Distinction WARN vs ERROR
- [ ] Hypothèse sans accès prod
- [ ] Actions manuelles proposées
- [ ] Aucun secret dans la réponse
EOF

cat > ~/lab-claude-skills/.claude/skills/incident-triage/scripts/parse-logs.sh << 'EOF'
#!/usr/bin/env bash
set -euo pipefail
LOG="${1:-logs/sample-app.log}"
if [[ ! -f "$LOG" ]]; then
  echo "parse-logs: missing file $LOG (lab)"
  exit 1
fi
echo "parse-logs: scanning $LOG"
grep -E 'ERROR|WARN' "$LOG" || true
echo "parse-logs: done (no remote call)"
EOF
chmod +x ~/lab-claude-skills/.claude/skills/incident-triage/scripts/parse-logs.sh

Vérification :

cd ~/lab-claude-skills
test -f .claude/skills/incident-triage/SKILL.md
./.claude/skills/incident-triage/scripts/parse-logs.sh logs/sample-app.log

Étape 6 — Brancher instructions + Skill

1. Claude.ai : Project « Lab runbook », collez project-instructions.md, activez / uploadez le skill via Customize → Skills (ou ouvrez le repo dans Claude Code).
2. Demandez : « Erreurs checkout / payments — lance le triage sur logs/sample-app.log. »
3. Attendu : ton FR runbook (instructions) + checklist / parse-logs (Skill) si la description matche.
4. Skill perso : mkdir -p ~/.claude/skills puis copier incident-triage (portée machine, pas l’équipe).

Vs Cursor : même SKILL.md + progressive disclosure ; chemins .cursor/skills/ vs .claude/skills/ (Cursor Skills). Chez Claude, le always-on passe surtout par custom / Project instructions.

Étape 7 — Autres skills DevOps (lab) + bonnes pratiques

Skill (name)	Quand	Contenu
terraform-plan-review	Revue d’un terraform plan texte	references/TF-CHECKLIST.md
ci-failure-triage	Échec CI / logs job	scripts/summarize-ci.sh factice
incident-triage	Lab de ce tutoriel	logs + checklist

Un skill = un job.

1. description = contrat (« Use when… »).
2. name = dossier ; minuscules / tirets.
3. SKILL.md court ; détail dans references/.
4. Instructions = ton/rôle ; Skills = procédures ; MCP = outils.
5. Scripts lab sans réseau réel.
6. Qualité : Évaluer la qualité d’un skill · AI agent workflows.

Étape 8 — Mini validation (5 min)

1. Relisez project-instructions.md (rôle + FR + garde-fous).
2. Demandez un triage sur les logs sample.
3. Vérifiez citation checklist / script ; pas de « prod OK » inventé.
4. Renommez le dossier skill : la découverte fichier-based doit casser.
5. Remettez incident-triage ; retestez « pic d’erreurs payments-worker ».

Pièges fréquents

Symptôme	Cause probable	Correctif
Skill jamais chargé	description vague	Réécrire « what + when »
Invisible / rejeté	Dossier ≠ name	Aligner incident-triage
Runbook dans instructions	Confusion couches	Ton en instructions, étapes en Skill
Équipe sans le skill	Seulement ~/	Committez .claude/skills/
Statut vert inventé	Garde-fous absents	Renforcer instructions + SKILL.md
Attente d’outils dans le Skill	Confusion MCP	MCP DevOps à part
Chemins Cursor copiés	.cursor vs .claude	Adapter l’emplacement

Quiz (4 questions)

1. Où placer un skill Claude partagé via Git ?
– A. Uniquement ~/.claude/skills/
– B. .claude/skills/<name>/SKILL.md dans le repo
– C. Uniquement les custom instructions du compte

2. Quel champ oriente surtout le chargement dynamique ?
– A. icon
– B. description
– C. La taille du Project (200K)

3. À quoi servent surtout custom / Project instructions ?
– A. Remplacer MCP
– B. Ton, rôle, règles always-on (compte ou Project)
– C. Exécuter des scripts shell automatiquement

4. Progressive disclosure recommande de :
– A. Tout mettre dans SKILL.md
– B. Garder SKILL.md court et détailler dans references/
– C. Stocker les secrets dans assets/

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

Compléments opérationnels

Standard de brief réutilisable

Pour claude-skills-instructions, adoptez un brief unique partagé par l’équipe. Il contient toujours cinq champs : objectif mesurable, contexte borné (lab/staging), liste blanche de fichiers ou ressources, interdits explicites (secrets, réseau, prod), et definition of done exécutable (commande de test ou checklist). Sans ces champs, l’outil improvisera — parfois avec élégance, souvent hors périmètre.

Stockez les briefs gagnants sous briefs/claude-skills-instructions/ dans un dépôt de documentation interne. Chaque brief cite le commit de référence et le modèle utilisé. Au troisième succès comparable, ouvrez une PR qui transforme le brief en rule, Skill ou slash command. Voir ai-skills-concept, claude-skills-instructions et evaluer-qualite-skill.

Revue de diff comme compétence P0

La vitesse d’un agent n’a aucune valeur si personne ne sait lire un diff. Instituez une règle simple : aucun apply massif sans parcours hunk par hunk. Posez-vous trois questions : ce changement est-il demandé ? est-il testé ? est-il réversible ? Si une réponse est non, refusez ou exigez un plan plus petit.

En atelier, faites commenter un diff à voix haute pendant cinq minutes. Les juniors apprennent ainsi le vocabulaire du refus. Reliez cette pratique à ai-code-review-pr et aux workflows ai-agent-workflows.

Sécurité continue

Les surfaces claude-skills-instructions multiplient les occasions d’injection et de fuite. Traitez tickets, README upstream, logs et ressources MCP comme des données non fiables. Séparez instructions et données. Allowlist tools. Confirmation humaine avant mutation. Guide : ai-prompt-injection-securite, mcp-servers-devops, claude-code-mcp.

Secrets : variables d’environnement de session, gestionnaire d’équipe, rotation, jamais de commit. Si un secret fuit dans un chat vendor, supposez-le compromis et rotatez.

Coûts, modèles et mode dégradé

Documentez un mapping fast/strong et un soft-cap mensuel dans la stack perso. OpenRouter peut aider à basculer — openrouter-multi-modeles. Le local (ollama-llm-locaux + continue-dev) sert de mode dégradé ou de bac à sable confidentialité.

Surveillez les changements silencieux de modèle par défaut : une régression de qualité est souvent un routing vendor, pas « l’équipe qui a oublié comment prompter ».

Ancrage parcours

claude-skills-instructions n’est qu’une étape du parcours IA DevOps 2026. Tronc commun d’abord (prompts, injection, skills), puis surface spécialisée, puis industrialisation (routines, MCP, RAG). Hub de navigation : /ia/. Comparatifs utiles : claude-vs-gpt-code, codex-vs-claude-code, claude-vs-cursor-vs-copilot.

FAQ

Custom instructions ou Skill pour « toujours en français style runbook » ?
Custom / Project instructions. Le Skill sert à une procédure (triage, checklist CI), pas seulement au ton.

Claude.ai et Claude Code : mêmes dossiers ?
Claude Code : ~/.claude/skills/ (perso) et .claude/skills/ (projet). Claude.ai : Customize → Skills (upload / pré-construits). Le format SKILL.md reste le pont (agentskills.io).

Comment éviter les secrets dans un Project ?
Lab et exemples seulement ; pas de clés dans assets/ ni dans les instructions. Outils réels via MCP / vaults, pas dans le Markdown du skill.

Skill Claude ou CLAUDE.md ?
CLAUDE.md = contexte permanent Claude Code. Skill = procédure déclenchée via description. Complémentaires : Claude Code et CLAUDE.md.

Upload Claude.ai ou commit .claude/skills/ ?
Commit .claude/skills/ pour l’équipe. Upload Customize → Skills pour usage perso multi-projets. Une seule source de vérité.

Pour aller plus loin

• Docs : custom skills · Skills explained · anthropics/skills · agentskills.io
• Précédent : Cursor Skills : créer et partager · Concept : AI Skills
• Voisins : Claude Projects & Artifacts · Claude Code et CLAUDE.md · MCP servers DevOps · Évaluer la qualité d’un skill · AI agent workflows

Maillage série IA Outils 2026 — Skills & agents

← Précédent	Cursor Skills : créer et partager
→ Suite	Évaluer la qualité d’un skill
Hub	IA pour DevOps : parcours 2026