MADD Skills

The Knowledge Gap

AI models are trained on data with a cutoff date. They don't know:

Your project's specific conventions and architecture
Recent framework versions and API changes
Your team's quality criteria and patterns
The current state of your codebase

Without explicit knowledge injection, agents guess. They produce code that looks correct but subtly violates your conventions, uses deprecated APIs, or ignores your architectural decisions. Skills eliminate guessing.

Anatomy of a Skill

A skill is a structured document — not prose, not a chat prompt. It has four sections that define what an agent must know and do.

Objective What this skill achieves. One sentence, no ambiguity.

Rules Directives the agent must follow. Imperative, testable, no exceptions.

Anti-patterns What the agent must never do. Explicit forbidden patterns prevent common mistakes.

Output Format The expected structure of the agent's output. Ensures consistency across cycles.

Skills are not documentation. They are executable knowledge contracts — concise, directive, and designed for machine consumption.

Three Skill Types

Skills are organized by scope and longevity:

Public Skills General knowledge shared across projects — framework documentation, language best practices, common patterns. Maintained by the community or extracted from official docs.

Project Skills Internal conventions specific to your project — naming conventions, architecture decisions, tech stack constraints, deployment requirements. Versioned with the code.

Delta Skills Temporary knowledge patches — breaking changes in a new framework version, hotfix procedures, migration guides. Short-lived and removed once the knowledge is stable.

Transition Skills

Each transition between agents is mediated by a skill that defines what knowledge the agent needs and what quality its output must meet.

Specification Skill

Architect Agent — Need → Intention Document + Contract

Guides the Architect in producing structured Intention Documents with verifiable requirements. Defines the mandatory fields, ensures validation criteria are automatable, and prevents vague or untestable requirements.

Development Skill

Maker Agent — Contract → Code

Defines the tech stack, code conventions, mandatory patterns, and forbidden anti-patterns. Ensures the Maker produces code that matches your project's standards — not generic "best practices" from training data.

Audit Skill

Breaker Agent — Code → Audit Report

Lists the validation criteria, security checks, and quality gates the Breaker must verify. Defines the audit report format with mandatory sections: status, findings, locations, and actionable recommendations.

Retro-Specification Skill

Witness Agent — Code → Retro-Specification

Guides the Witness in objective code analysis. Defines what to inventory (features, dependencies, gaps, debt), enforces factual observation over interpretation, and structures the output for the next Architect to consume.

Correction Skill

Maker Agent — Audit Report → Corrected Code

Frames how the Maker addresses audit findings. Requires root cause analysis (not just symptom fixing), mandatory regression tests for each correction, and traceability from finding to commit.

Domain Skills

The v2 innovation: instead of generalist Maker/Breaker agents, the Conductor invokes domain-specialized pairs. Each domain has a dedicated Maker skill and Breaker skill.

Domain	Maker Skill	Breaker Skill
Database	Normalization, RLS, audit logging, indexing, temporal patterns	Missing normalization, RLS, indexes, constraints, cascade risks
API	REST conventions, Zod validation, pagination, rate limiting	Missing validation, auth, CORS, N+1 queries
Frontend	Component architecture, state management, accessibility	Performance, bundle size, accessibility, XSS
Security	OIDC/JWKS, RBAC, AES-256-GCM, mTLS, headers	OWASP Top 10, privilege escalation, secrets
Infrastructure	Docker multi-stage, Compose, Terraform, secrets	Running as root, healthchecks, hardcoded secrets, SPOF

Writing Your Own Skills

The provided skills are templates. Your real skills come from your project's friction points:

Identify friction — Where does the agent regularly make mistakes? What do you keep correcting?
Document the gap — What knowledge is the agent missing? Write it as facts, not prose.
Structure as rules — Convert knowledge into imperative directives. "MUST use", "NEVER do", "ALWAYS verify".
Test and iterate — Run a cycle with the skill. If the agent still makes mistakes, the skill is incomplete. Refine.

Skill Lifecycle

Skills are living artifacts — they evolve with your project.

Version your skills with your code. They belong in the repository, not in a wiki or a shared drive. When the tech stack changes, the skills change. When conventions evolve, the skills evolve.

Directory structure

skills/
  public/         # Framework docs, language best practices
  project/        # Your conventions, architecture decisions
  delta/          # Temporary patches (new versions, hotfixes)

The MADD Boilerplates implement this structure with ready-to-use skill templates for each domain and transition.

Ready to define your Skills?

Start with the Development Skill and Audit Skill. The others will follow naturally from your project's needs.

See examples on GitHub → See a Case Study