Knowledge Contracts

MADD Skills

Skills inject up-to-date knowledge and define quality criteria between agents. Each transition is mediated by an explicit skill.

Why Skills?

AI models have training data that may be outdated. They don't know:

  • Your project's specific conventions
  • Recent framework versions
  • Your team's architectural decisions
  • Your organization's quality criteria

Skills bridge this gap. They are structured documents that inject missing context and define the rules of the game.

Skill Types

Public Skills Framework documentation, general best practices
Project Skills Internal conventions, architecture, in-house patterns
Delta Skills Temporary knowledge patches (new version, hotfix)

Specification Skill

Target agent: Spec Agent

Transition: Need → Intention Document + Contract

Guides the production of structured Intention Documents with verifiable requirements.

Typical content

# 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.

Development Skill

Target agent: Dev Agent

Transition: Intention Document → Code

Defines conventions, patterns, and constraints that the implementation must respect.

Typical content

# 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

Audit Skill (Due Diligence)

Target agent: Audit Agent

Transition: Code → Audit Report

Lists validation criteria, patterns to detect, report format.

Typical content

# 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

Retro-Specification Skill

Target agent: Scribe Agent

Transition: Code → Retro-Specification

Guides objective code analysis and factual documentation production.

Typical content

# 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

Correction Skill

Target agent: Dev Agent

Transition: Audit Report → Corrected Code

Frames finding corrections with mandatory traceability.

Typical content

# 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

Create Your Own Skills

The provided skills are templates. Adapt them to your context:

  1. Identify friction points — Where does the agent regularly make mistakes?
  2. Document missing knowledge — What doesn't it know?
  3. Structure as rules — No prose, clear directives
  4. Test and iterate — A skill evolves with the project

Version your skills like code. They are part of the project's living documentation.

Implementation Notes

In practice, transition skills operate at two complementary levels:

Methodological level — How the agent executes its transition (formalize intention, audit code, document reality). This knowledge is often embedded directly in the agent definition, because the transition methodology is inseparable from the agent's identity.

Domain level — What the agent needs to know about the current project context. These are standalone files organized by type: public (framework documentation), project (internal conventions), or delta (temporary knowledge patches).

The invariant is that each transition has an explicit knowledge contract — whether that contract lives in the agent definition or in a separate skill file.

The inter-agent security barrier is enforced by access permissions (file write access, available tools), not by skill visibility. An agent that reads a skill outside its scope cannot act on it if it lacks the permissions.

The MADD Boilerplate implements this architecture with public/, project/ and delta/ directories for domain skills.

Ready to define your Skills?

Start with the Specification Skill and Development Skill. The others will follow naturally.

See examples on GitHub → See a Case Study