417 lines
9.0 KiB
Markdown
417 lines
9.0 KiB
Markdown
---
|
|
name: checking-config-compliance
|
|
description: Validates configuration compliance for Skills, Subagents and Slash Commands against best practices. Use proactively when creating or auditing configuration files.
|
|
allowed-tools: Read, Grep, Glob, WebSearch
|
|
---
|
|
|
|
# Config Compliance Checker
|
|
|
|
Valide la conformité des Skills, Subagents et Slash Commands selon les bonnes pratiques définies dans `BEST_PRACTICES_AGENTS_SKILLS.md`.
|
|
|
|
## Table des matières
|
|
|
|
- [Quand utiliser](#quand-utiliser)
|
|
- [Sources de vérité](#sources-de-vérité)
|
|
- [Checklist : Skills](#checklist--skills)
|
|
- [Checklist : Subagents](#checklist--subagents)
|
|
- [Format de Sortie Requis (CRITIQUE)](#format-de-sortie-requis-critique)
|
|
- [Checklist : Slash Commands](#checklist--slash-commands)
|
|
- [Patterns de validation](#patterns-de-validation)
|
|
- [Rapport d'audit](#rapport-daudit)
|
|
- [Workflow d'audit complet](#workflow-daudit-complet)
|
|
- [En cas de doute](#en-cas-de-doute)
|
|
|
|
## Quand utiliser
|
|
|
|
- Création d'un nouveau Skill/Subagent/Slash Command
|
|
- Audit des configurations existantes
|
|
- Avant commit de modifications de config
|
|
- Review de PR touchant `.claude/`
|
|
|
|
## Sources de vérité
|
|
|
|
**Document de référence principal :** `.claude/BEST_PRACTICES_AGENTS_SKILLS.md`
|
|
|
|
Ce skill fournit des checklists concrètes pour valider la conformité.
|
|
|
|
### Consultation de la Documentation Officielle
|
|
|
|
En cas de doute sur une règle de conformité ou une spécification exacte, consultez la documentation officielle listée dans `BEST_PRACTICES_AGENTS_SKILLS.md` via WebSearch.
|
|
|
|
**Cas d'usage pour WebSearch :**
|
|
|
|
- ✅ Vérifier les limites exactes (max 64 chars pour name, max 1024 pour description)
|
|
- ✅ Valider une règle de nommage spécifique (gérondif, kebab-case)
|
|
- ✅ Confirmer la syntaxe YAML frontmatter
|
|
- ✅ Découvrir de nouvelles best practices non encore documentées dans BEST_PRACTICES
|
|
|
|
**Ne PAS utiliser pour :**
|
|
|
|
- ❌ Remplacer la lecture de BEST_PRACTICES (toujours lire en premier)
|
|
- ❌ Copier du contenu verbatim (résumer et adapter au contexte du projet)
|
|
|
|
---
|
|
|
|
## Checklist : Skills
|
|
|
|
### 1. Frontmatter YAML
|
|
|
|
**✅ Requis :**
|
|
|
|
```yaml
|
|
---
|
|
name: skill-name
|
|
description: What it does and when to use it
|
|
---
|
|
```
|
|
|
|
**Validations :**
|
|
|
|
- [ ] `name` : kebab-case, sans guillemets, forme gérondif recommandée (-ing)
|
|
- [ ] `description` : 3ème personne, < 1024 chars, sans guillemets
|
|
- [ ] `allowed-tools` (optionnel) : liste séparée par virgules
|
|
|
|
**❌ Erreurs communes :**
|
|
|
|
```yaml
|
|
# MAUVAIS
|
|
name: "Validateur d'Accessibilité" # Guillemets inutiles, pas kebab-case
|
|
name: helper # Nom vague
|
|
description: I process files # 1ère personne
|
|
|
|
# BON
|
|
name: processing-pdfs
|
|
description: Processes PDF files and extracts structured data. Use for document automation.
|
|
```
|
|
|
|
### 2. Structure de fichier
|
|
|
|
**Recommandé :**
|
|
|
|
```
|
|
skill-name/
|
|
├── SKILL.md # < 500 lignes
|
|
├── reference/ # Fichiers de référence
|
|
│ └── patterns.md
|
|
└── scripts/ # Scripts utilitaires
|
|
└── validator.py
|
|
```
|
|
|
|
**Validations :**
|
|
|
|
- [ ] SKILL.md < 500 lignes
|
|
- [ ] Références à un niveau de profondeur max
|
|
- [ ] Scripts utilisent forward slashes (`/`)
|
|
|
|
### 3. Contenu
|
|
|
|
**Validations :**
|
|
|
|
- [ ] Focalisé sur une seule tâche
|
|
- [ ] Pas de copie de code (référence au code vivant)
|
|
- [ ] Tables des matières si > 100 lignes
|
|
- [ ] Exemples concrets (input/output)
|
|
|
|
---
|
|
|
|
## Checklist : Subagents
|
|
|
|
### 1. Frontmatter YAML
|
|
|
|
**✅ Requis :**
|
|
|
|
```yaml
|
|
---
|
|
name: agent-name
|
|
description: Expert role and when to use it
|
|
tools: Read, Write, Bash
|
|
model: inherit
|
|
---
|
|
```
|
|
|
|
**Validations :**
|
|
|
|
- [ ] `name` : kebab-case, sans guillemets
|
|
- [ ] `description` : 3ème personne, inclut "quand utiliser", mots comme "proactivement"
|
|
- [ ] `tools` : explicitement définis (principe du moindre privilège)
|
|
- [ ] `model` : `inherit` recommandé ou alias (sonnet, opus, haiku)
|
|
|
|
**❌ Erreurs communes :**
|
|
|
|
```yaml
|
|
# MAUVAIS
|
|
name: "Code Reviewer" # Guillemets inutiles, espace
|
|
tools: * # Trop permissif
|
|
description: Reviews code # Manque "quand"
|
|
|
|
# BON
|
|
name: code-reviewer
|
|
tools: Read, Grep, Glob, Bash, WebSearch
|
|
description: Expert code reviewer specializing in security and performance. Use proactively after code modifications.
|
|
model: inherit
|
|
```
|
|
|
|
### 2. Prompt système
|
|
|
|
**Validations :**
|
|
|
|
- [ ] Persona clairement définie ("Vous êtes un expert en...")
|
|
- [ ] Contexte clé du projet fourni
|
|
- [ ] Principes et workflows décrits
|
|
- [ ] Référence au code vivant
|
|
- [ ] Intégration de skills explicite si applicable
|
|
|
|
**Exemple d'intégration skill :**
|
|
|
|
```markdown
|
|
## Format de Sortie Requis (CRITIQUE)
|
|
|
|
Pour générer votre rapport, vous DEVEZ :
|
|
|
|
1. Lire le fichier `.claude/skills/report-template/SKILL.md`
|
|
2. Utiliser son contenu comme template exact
|
|
```
|
|
|
|
---
|
|
|
|
## Checklist : Slash Commands
|
|
|
|
### 1. Structure de fichier
|
|
|
|
**Localisation :**
|
|
|
|
- Personal : `~/.claude/commands/`
|
|
- Project : `.claude/commands/` (versionné)
|
|
|
|
**Format :**
|
|
|
|
```markdown
|
|
---
|
|
description: Brief description of what it does
|
|
---
|
|
|
|
Prompt content here with optional $ARGUMENTS
|
|
```
|
|
|
|
**Validations :**
|
|
|
|
- [ ] Nom fichier : kebab-case.md
|
|
- [ ] `description` claire et concise
|
|
- [ ] Arguments gérés avec `$ARGUMENTS` ou `$1`, `$2`
|
|
- [ ] Documentation du comportement
|
|
|
|
**Exemple :**
|
|
|
|
```markdown
|
|
---
|
|
description: Review code for security issues
|
|
---
|
|
|
|
Review the following code: $ARGUMENTS
|
|
|
|
Focus on:
|
|
|
|
- Security vulnerabilities
|
|
- Best practices violations
|
|
```
|
|
|
|
---
|
|
|
|
## Patterns de validation
|
|
|
|
### Validation du nom (kebab-case)
|
|
|
|
**Regex :** `^[a-z0-9]+(-[a-z0-9]+)*$`
|
|
|
|
**✅ Valides :**
|
|
|
|
- `processing-pdfs`
|
|
- `code-reviewer`
|
|
- `practicing-tdd-with-jest`
|
|
|
|
**❌ Invalides :**
|
|
|
|
- `ProcessingPDFs` (PascalCase)
|
|
- `processing_pdfs` (snake_case)
|
|
- `"processing-pdfs"` (guillemets)
|
|
- `processing pdfs` (espace)
|
|
|
|
### Validation de la description (3ème personne)
|
|
|
|
**Patterns ✅ :**
|
|
|
|
- "Processes PDF files..."
|
|
- "Validates configuration..."
|
|
- "Expert reviewer specializing in..."
|
|
|
|
**Patterns ❌ :**
|
|
|
|
- "I process files..." (1ère personne)
|
|
- "Process files..." (impératif)
|
|
- "" (vide)
|
|
|
|
### Validation allowed-tools vs tools
|
|
|
|
**Skills :**
|
|
|
|
```yaml
|
|
allowed-tools: Read, Grep # Avec tiret
|
|
```
|
|
|
|
**Subagents :**
|
|
|
|
```yaml
|
|
tools: Read, Write, Bash # Sans tiret
|
|
```
|
|
|
|
---
|
|
|
|
## Rapport d'audit
|
|
|
|
### Format recommandé
|
|
|
|
```markdown
|
|
# Audit de Conformité : [nom-du-composant]
|
|
|
|
**Type :** Skill | Subagent | Slash Command
|
|
**Fichier :** `.claude/.../nom.md`
|
|
**Date :** YYYY-MM-DD
|
|
|
|
## Score global : [X]/10
|
|
|
|
## Conformité Frontmatter
|
|
|
|
- [ ] ✅/❌ Nom conforme (kebab-case, gérondif pour skills)
|
|
- [ ] ✅/❌ Description conforme (3ème personne, < 1024 chars)
|
|
- [ ] ✅/❌ Tools/allowed-tools correctement défini
|
|
- [ ] ✅/❌ Model spécifié (subagents)
|
|
|
|
## Conformité Contenu
|
|
|
|
- [ ] ✅/❌ Structure de fichier appropriée
|
|
- [ ] ✅/❌ Taille < 500 lignes (skills)
|
|
- [ ] ✅/❌ Références au code vivant
|
|
- [ ] ✅/❌ Exemples concrets présents
|
|
|
|
## Problèmes détectés
|
|
|
|
### 🔴 Critiques
|
|
|
|
- Description non conforme
|
|
|
|
### 🟡 Avertissements
|
|
|
|
- Taille légèrement élevée (520 lignes)
|
|
|
|
### 🔵 Suggestions
|
|
|
|
- Ajouter exemples concrets
|
|
|
|
## Actions recommandées
|
|
|
|
1. Corriger le nom : `"Code Reviewer"` → `code-reviewer`
|
|
2. Réécrire description en 3ème personne
|
|
3. Définir explicitement les tools
|
|
|
|
## Diff proposé
|
|
|
|
\`\`\`diff
|
|
|
|
- name: "Code Reviewer"
|
|
|
|
* name: code-reviewer
|
|
|
|
- description: Reviews code
|
|
|
|
* description: Expert code reviewer specializing in security. Use proactively after modifications.
|
|
\`\`\`
|
|
```
|
|
|
|
---
|
|
|
|
## Workflow d'audit complet
|
|
|
|
### 1. Identifier les composants
|
|
|
|
```bash
|
|
# Skills
|
|
find .claude/skills -name "SKILL.md"
|
|
|
|
# Subagents
|
|
find .claude/agents -name "*.md"
|
|
|
|
# Slash Commands
|
|
find .claude/commands -name "*.md"
|
|
```
|
|
|
|
### 2. Auditer chaque composant
|
|
|
|
Pour chaque fichier :
|
|
|
|
1. Lire le frontmatter YAML
|
|
2. Valider chaque champ avec la checklist
|
|
3. Analyser le contenu
|
|
4. Générer le rapport
|
|
|
|
### 3. Prioriser les corrections
|
|
|
|
**🔴 Critiques (bloquer) :**
|
|
|
|
- Nom non conforme (empêche découverte)
|
|
- Description invalide
|
|
- Syntaxe YAML incorrecte
|
|
|
|
**🟡 Avertissements (corriger bientôt) :**
|
|
|
|
- Taille > 500 lignes
|
|
- Manque exemples
|
|
- Tools trop permissifs
|
|
|
|
**🔵 Suggestions (amélioration) :**
|
|
|
|
- Ajouter tables des matières
|
|
- Améliorer organisation
|
|
- Ajouter tests
|
|
|
|
### 4. Générer rapport consolidé
|
|
|
|
```markdown
|
|
# Rapport d'Audit Global
|
|
|
|
**Date :** YYYY-MM-DD
|
|
**Composants audités :** X skills, Y agents, Z commands
|
|
|
|
## Scores moyens
|
|
|
|
- Skills : 7.5/10
|
|
- Subagents : 8.2/10
|
|
- Slash Commands : 9.0/10
|
|
|
|
## Résumé des problèmes
|
|
|
|
- 🔴 Critiques : 3
|
|
- 🟡 Avertissements : 8
|
|
- 🔵 Suggestions : 12
|
|
|
|
## Top 5 corrections prioritaires
|
|
|
|
1. [skill-name] : Corriger nom et description
|
|
2. [agent-name] : Définir tools explicitement
|
|
...
|
|
```
|
|
|
|
---
|
|
|
|
## En cas de doute
|
|
|
|
**Règles absolues :**
|
|
|
|
1. Toujours consulter `.claude/BEST_PRACTICES_AGENTS_SKILLS.md`
|
|
2. Toujours valider kebab-case pour les noms
|
|
3. Toujours vérifier 3ème personne pour descriptions
|
|
4. Toujours appliquer principe du moindre privilège (tools)
|
|
|
|
**Documentation officielle :**
|
|
|
|
Consultez les liens dans `BEST_PRACTICES_AGENTS_SKILLS.md` pour les spécifications exhaustives.
|