Créer des Skills

Guide pas à pas pour ajouter de nouvelles expertises à ton projet Arc OS.

Qu'est-ce qu'un Skill

Un skill est un ensemble d'instructions portable qui enseigne à ton bot IA une capacité spécifique. Les skills vivent dans le répertoire skills/ et se composent de :

skill.md — le fichier d'instructions (requis)
<name>.evals.json — règles de validation qualité automatiques (optionnel, mais recommandé)
references/ — documents d'appui, schémas, exemples (optionnel)

skills/
├── _registry.json              ← Central registry
├── my-new-skill/
│   ├── skill.md                ← What the AI should do
│   ├── my-new-skill.evals.json ← How to validate the output
│   └── references/             ← Context documents
└── library/
    └── domain-expert.md        ← Simple single-file skills

Étape 1 : Rédiger skill.md

C'est l'instruction centrale. Claude lit ce fichier lorsque le skill est activé.

Template

# Skill Name

## Purpose
What this skill accomplishes in one sentence.

## When to Use
- Trigger condition 1
- Trigger condition 2

## Protocol
1. First action
2. Second action
3. Third action

## Output Format
What the response should look like.

## Constraints
- What NOT to do
- Safety boundaries

Bonnes pratiques

Moins de 500 mots — un skill trop long dilue le contexte
Mode impératif — "Vérifie le dépôt" plutôt que "Tu devrais vérifier"
Exemples concrets — montre les paires entrée/sortie attendues
Références d'outils précises — nomme les commandes, les API ou les patterns à utiliser

Exemple : Odoo Expert

# Odoo Expert

## Purpose
Odoo ERP module development: models, views, security, QWeb templates.

## When to Use
- Building or modifying Odoo modules
- Writing QWeb templates
- Configuring access rules and record rules
- Working with the ORM (create, write, search, browse)

## Protocol
1. Check if modifying an existing module or creating new
2. Follow Odoo 17 conventions (manifest, models/, views/, security/)
3. Use self.env['model.name'] for ORM operations
4. Always use _t() or t-call for translatable strings
5. Test with --test-tags after changes

## Constraints
- Never use cr.execute() for direct SQL — use ORM
- Never use sudo() unless security context explicitly requires it
- No inline JavaScript in QWeb templates

Étape 2 : Rédiger les evals (règles de qualité)

Les evals sont des règles déclaratives qui valident automatiquement chaque réponse. Elles s'exécutent après que Claude génère sa sortie et ajoutent des notes de bas de page si des règles échouent.

Nommage du fichier

skills/<name>/<name>.evals.json

Schéma

{
  "version": 1,
  "skill": "my-new-skill",
  "rules": [
    {
      "id": "ms-001",
      "name": "Human-readable rule description",
      "type": "rule_type",
      "value": "for string/length types",
      "pattern": "for regex types",
      "severity": "warning"
    }
  ]
}

Types de règles disponibles

Type	Ce qu'il vérifie	Champ utilisé
`string_contains`	La réponse contient un texte littéral	`value` (string)
`string_not_contains`	La réponse ne contient PAS le texte	`value` (string)
`regex_match`	La réponse correspond à la regex	`pattern` (string)
`regex_not_match`	La réponse ne correspond PAS à la regex	`pattern` (string)
`max_length`	Longueur de la réponse <= N caractères	`value` (number)
`min_length`	Longueur de la réponse >= N caractères	`value` (number)

Niveaux de sévérité

warning — Indique un problème de qualité. Affiché sous forme de ⚠️.
info — Note informative. Affichée sous forme de ℹ️.

Exemple

{
  "version": 1,
  "skill": "odoo-expert",
  "rules": [
    {
      "id": "oe-001",
      "name": "Must use ORM, not raw SQL",
      "type": "string_not_contains",
      "value": "cr.execute",
      "severity": "warning"
    },
    {
      "id": "oe-002",
      "name": "Must use translation helpers",
      "type": "regex_match",
      "pattern": "_t\\(|t-call|t-esc",
      "severity": "warning"
    },
    {
      "id": "oe-003",
      "name": "Response under 5000 chars",
      "type": "max_length",
      "value": 5000,
      "severity": "info"
    }
  ]
}

Conseils

Commence par 2-3 règles. Ajoutes-en au fur et à mesure que tu identifies des patterns à partir des corrections.
La sécurité d'abord : string_not_contains pour les commandes dangereuses, regex_not_match pour les patterns de credentials.
Convention d'ID : <skill-prefix>-<numéro> (ex. oe-001, gm-002).
Teste : Envoie un message censé déclencher le skill, vérifie que les warnings apparaissent correctement.

Étape 3 : Enregistrer dans _registry.json

Le registre informe le Context Router de l'existence de ton skill afin qu'il puisse être recommandé pour les messages pertinents.

Ajouter une entrée

{
  "name": "my-new-skill",
  "description": "One sentence (shown in SKILLS_HINT, max 80 chars).",
  "triggers": ["direct-command", "explicit-request", "пряма команда"],
  "keywords": ["broader", "semantic", "related-term"],
  "agents": ["rick"],
  "category": ["complex"],
  "phase": "21.5"
}

Triggers vs Keywords

Triggers (2 points chacun) : Signaux d'invocation directe. L'utilisateur demande explicitement ce skill.

"deploy", "review", "scaffold", "odoo", "audit"

Keywords (1 point chacun) : Termes plus larges qui suggèrent une pertinence sans être des commandes.

"OWASP", "Docker", "CI/CD", "production", "module"

Bonnes pratiques

Inclus des équivalents ukrainiens dans les triggers pour les équipes bilingues
Garde les descriptions sous 80 caractères (tronquées dans SKILLS_HINT)
5 à 8 triggers par skill (plus = matching trop bruyant)
Les keywords sont optionnels, mais améliorent significativement le routage

Étape 4 : Skills de bibliothèque (format simplifié)

Pour une expertise métier qui ne nécessite ni evals ni répertoire dédié, utilise skills/library/ :

skills/library/
├── docker-ops.md
├── postgres-pro.md
└── react-patterns.md

Ce sont des fichiers .md simples. Pas de répertoire, pas d'evals, pas de references. Idéal pour les skills riches en connaissances et pauvres en validation.

Checklist

skills/<name>/skill.md — instruction avec Purpose, Protocol, Constraints
skills/<name>/<name>.evals.json — au moins 2 règles de validation
Entrée dans skills/_registry.json — avec triggers et keywords
Le nom est cohérent partout — nom du répertoire = nom du skill dans les evals = nom dans le registre
Test : envoie un message trigger → vérifie SKILLS_HINT dans les logs
Test : déclenche intentionnellement un échec d'eval → vérifie que le warning apparaît

Ce qui se passe à l'exécution

1. Bot starts → loadRegistry() reads _registry.json
                 loadEvals() reads all .evals.json files
                 loadLearnings() reads learnings.md

2. Message arrives → routeContext() scores skills → SKILLS_HINT injected
                     formatForPrompt() adds LEARNINGS block

3. Claude responds → checkOutput() runs eval rules
                     formatEvalWarnings() appends footnotes

4. Fix It / thumbs-down → addLearning() writes to learnings.md
                          qualityTracker logs feedback

5. Nightly → findUnderperformingSkills() checks metrics
             Proposals sent to CEO for approval