Initial commit
This commit is contained in:
Zhongwei Li
416
skills/checking-config-compliance/SKILL.md
Normal file
416
skills/checking-config-compliance/SKILL.md
Normal file
@@ -0,0 +1,416 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user