Contrats de Connaissance

Les Skills MADD

Les skills injectent la connaissance à jour et définissent les critères de qualité entre agents. Chaque transition est médiatisée par un skill explicite.

Pourquoi les Skills ?

Les modèles d'IA ont des données d'entraînement qui peuvent être obsolètes. Ils ne connaissent pas :

  • Les conventions spécifiques de votre projet
  • Les versions récentes des frameworks
  • Les décisions architecturales de votre équipe
  • Les critères de qualité de votre organisation

Les skills comblent ce gap. Ce sont des documents structurés qui injectent le contexte manquant et définissent les règles du jeu.

Types de Skills

Skills Publics Documentation framework, best practices générales
Skills Projet Conventions internes, architecture, patterns maison
Skills Delta Patches temporaires de connaissance (nouvelle version, hotfix)

Skill de Spécification

Agent cible : Agent Spec

Transition : Besoin → Intention Document + Contrat

Guide la production d'Intention Documents structurés avec des requirements vérifiables.

Contenu type

# Specification Skill

## Objective
Produce structured Intention Documents and executable contracts.

## Mandatory Intention Document Structure
- Context: Business problem to solve
- Objective: What the user will be able to do
- Requirements: Numbered list (REQ-XXX)
- Validation Criteria: Minimum one per requirement
- Out of Scope: What is not included
- Dependencies: Technical prerequisites

## Rules
- Each requirement MUST have at least one validation criterion
- Criteria MUST be automatable (test, schema, assertion)
- Out of scope is MANDATORY (prevents drift)
- No "how" — only "why" and "what"

## Anti-patterns to avoid
- Vague requirements ("improve performance")
- Subjective criteria ("must be fast")
- Implicit scope (anything unsaid is out of scope)

## Output format
Structured markdown, versionable with code.

Skill de Développement

Agent cible : Agent Dev

Transition : Intention Document → Code

Définit les conventions, patterns et contraintes que l'implémentation doit respecter.

Contenu type

# Development Skill

## Tech Stack
- Framework: Next.js 14 (App Router)
- Language: TypeScript strict
- Style: Tailwind CSS
- State: Zustand
- Tests: Vitest + Playwright

## Code Conventions
- Naming: camelCase for variables, PascalCase for components
- Files: kebab-case
- Exports: Named exports only (no default)

## Mandatory Patterns
- Server Components by default, Client Components explicit
- Zod validation on all user inputs
- Error boundaries per route

## Forbidden Anti-patterns
- TypeScript any
- console.log in production
- Direct state mutations
- Relative imports beyond 2 levels (../../..)

## File Structure
/src
  /app          → Next.js routes
  /components   → Reusable components
  /lib          → Utilities and helpers
  /hooks        → Custom hooks
  /types        → TypeScript types
  /services     → Business logic

Skill d'Audit (Due Diligence)

Agent cible : Agent Audit

Transition : Code → Rapport d'Audit

Liste les critères de validation, les patterns à détecter, le format du rapport.

Contenu type

# Audit Skill (Due Diligence)

## Objective
Analyze produced code and verify alignment with intention.

## Analysis Criteria

### 1. Functional Alignment
- Is each Intention Document requirement implemented?
- Do validation criteria pass?
- Is there out-of-scope code?

### 2. Technical Quality
- Development Skill conventions respected
- Listed anti-patterns absent
- Sufficient test coverage

### 3. Security
- User input validation
- No SQL/XSS/Command injection
- No secrets exposed in code

### 4. Technical Debt
- TODO/FIXME identified and documented
- Temporary workarounds flagged
- Obsolete dependencies

## Report Format
## Audit Report - [Feature]

### Global Status: PASS | FAIL | WARNING

### Functional Alignment
- REQ-001: ✅ Implemented | ❌ Missing | ⚠️ Partial

### Critical Findings
1. [Problem description]
   - Location: file:line
   - Impact: [Security|Performance|Functional]
   - Recommendation: [Corrective action]

## Rules
- NEVER PASS if a critical finding exists
- Each finding MUST have a precise location
- Recommendations MUST be actionable

Skill de Rétro-Spécification

Agent cible : Agent Scribe

Transition : Code → Rétro-Spécification

Guide l'analyse objective du code et la production de documentation factuelle.

Contenu type

# Retro-Spec Skill

## Objective
Objectively document what REALLY exists in the code.
Not what the dev says they did. What is there.

## Required Analysis

### 1. Functional Inventory
- What features are implemented?
- What endpoints/routes exist?
- What components are available?

### 2. Implementation State
- Complete vs partial features
- Commented or disabled code
- TODO/FIXME/HACK present

### 3. Dependencies
- Libraries used + versions
- External APIs called
- Third-party services integrated

### 4. Intention Gaps
- Requirements implemented differently
- Unplanned features added
- Technical limitations encountered

## Output Format
## Retro-Specification - [Date]

### Current System State

#### Features
- [Feature 1]: Complete | Partial | Stub
- [Feature 2]: ...

#### Actual Architecture
[Description of architecture as implemented]

#### Dependencies
| Package | Version | Usage |
|---------|---------|-------|
| ...     | ...     | ...   |

### Identified Gaps
| Intention | Reality | Reason |
|-----------|---------|--------|
| ...       | ...     | ...    |

## Rules
- ABSOLUTE objectivity — no embellishment
- FACTUAL — what is observed, not interpreted
- USEFUL — next Spec Agent must be able to start from here

Skill de Correction

Agent cible : Agent Dev

Transition : Rapport d'Audit → Code corrigé

Encadre la correction des findings avec traçabilité obligatoire.

Contenu type

# Correction Skill

## Objective
Fix audit findings with complete traceability.

## Mandatory Process

### For each critical finding
1. Identify root cause (not just symptom)
2. Implement correction
3. Add test that would have detected the problem
4. Document the correction

### For each minor finding
1. Fix or document why acceptable
2. If acceptable: add as explicit technical debt

## Documentation Format
## Correction - [Finding ID]

### Problem
[Finding description as identified by audit]

### Root Cause
[Why this problem existed]

### Applied Correction
[What was changed]

### Added Test
[Reference to test verifying correction]

### Impact
[Other parts of code potentially affected]

## Rules
- NEVER correct without associated test
- NEVER "fix" that breaks something else (check regression)
- Traceability finding → commit mandatory

Créer vos propres Skills

Les skills fournis sont des templates. Adaptez-les à votre contexte :

  1. Identifiez les frictions — Où l'agent se trompe régulièrement ?
  2. Documentez la connaissance manquante — Qu'est-ce qu'il ne sait pas ?
  3. Structurez en règles — Pas de prose, des directives claires
  4. Testez et itérez — Un skill évolue avec le projet

Versionnez vos skills comme du code. Ils font partie de la documentation vivante du projet.

Notes d'implémentation

En pratique, les skills de transition opèrent à deux niveaux complémentaires :

Niveau méthodologique — Comment l'agent exécute sa transition (formaliser l'intention, auditer le code, documenter la réalité). Cette connaissance est souvent embarquée directement dans la définition de l'agent, car la méthodologie de transition est inséparable de l'identité de l'agent.

Niveau domaine — Ce que l'agent doit savoir sur le contexte du projet actuel. Ces connaissances sont des fichiers standalone organisés par type : publics (documentation framework), projet (conventions internes), ou delta (patches de connaissance temporaires).

L'invariant est que chaque transition a un contrat de connaissance explicite — que ce contrat vive dans la définition de l'agent ou dans un fichier skill séparé.

La barrière de sécurité inter-agents est assurée par les permissions d'accès (écriture fichiers, outils disponibles), pas par la visibilité des skills. Un agent qui lit un skill hors de son périmètre ne peut pas agir dessus s'il n'a pas les permissions.

Le MADD Boilerplate implémente cette architecture avec des répertoires public/, project/ et delta/ pour les skills de domaine.

Prêt à définir vos Skills ?

Commencez par le Specification Skill et le Development Skill. Les autres viendront naturellement.

Voir les exemples sur GitHub → Voir un Case Study