Skill Anatomy

Layer 1 — Domain Knowledge

Sections: When to Use, Constraints, Anti-Patterns

This layer tells the agent what the domain is about and when to activate. It answers:

• What user requests should trigger this skill?
• What rules must always be followed (e.g. "never drop more than 5% of rows without user confirmation")?
• What mistakes does the agent commonly make that must be avoided?

Domain knowledge shapes the agent's reasoning before any code is written. It is the most important layer for getting correct behaviour.

Example constraint from magic-data-cleaning:

"Never impute a column where more than 40% of values are null without surfacing this to the user first. High-null columns may indicate a structural data problem rather than missing values."

Layer 2 — Code Patterns

Sections: Reference Scripts, Seed Patterns

This layer provides concrete implementations the agent reads as starting points. Scripts are reference implementations — the agent reads them, understands the approach, and writes adapted code for your specific data.

A reference script for null imputation might look like:

# Reference: impute_nulls.py
# The agent reads this and adapts it to your actual DataFrame columns.

import pandas as pd
from sklearn.impute import SimpleImputer

def impute_numeric_columns(df: pd.DataFrame, strategy: str = "median") -> pd.DataFrame:
    numeric_cols = df.select_dtypes(include="number").columns.tolist()
    imputer = SimpleImputer(strategy=strategy)
    df[numeric_cols] = imputer.fit_transform(df[numeric_cols])
    return df

When the agent sees your data has columns revenue, units, and discount_pct, it writes a version of this function with those column names, appropriate strategies for each column's distribution, and any special cases your data requires.

Layer 3 — Procedures

Sections: Workflow, Checkpointing, Self-Healing, Handoff

This layer tells the agent how to do the work step by step. A procedure section looks like:

1. Load the most recent checkpoint from workspace/data/checkpoints/
2. Run magic-data-profiling if no profiling checkpoint exists
3. Identify null columns above the threshold
4. Select imputation strategy per column type (median for numeric, mode for categorical)
5. Apply imputation and record row-level changes
6. Write checkpoint as ckpt_\{NN\}_nulls_imputed.\{ext\}
7. Update workspace_state.md with the new checkpoint path
8. Surface a summary: columns imputed, strategy used, rows affected

Procedures make the agent's behaviour predictable and auditable — you can read the SKILL.md and know exactly what the agent will do.