diff --git a/anton/README.md b/anton/README.md
index 484e78b2..776bf6a9 100644
--- a/anton/README.md
+++ b/anton/README.md
@@ -67,7 +67,7 @@ The high-level flow — how the executive, scratchpads, and the long-term stores
   │ (hipp.)    │  │ Buffers bad  │  │ /skill save → LLM   │
   │            │  │ cells, runs  │  │ drafts a procedure  │
   │ Episodes — │  │ post-mortem  │  │ with label + name + │
-  │ JSONL log  │  │ via LLM,     │  │ when_to_use +       │
+  │ JSONL log  │  │ via LLM,     │  │ description +       │
   │ of every   │  │ encodes new  │  │ declarative_md.     │
   │ turn.      │  │ lessons via  │  │                     │
   │            │  │ Cortex.      │  │ Future turns recall │
@@ -157,10 +157,9 @@ And the Hipocampus also is controlled as follows:
 │       └── *.md
 └── skills/                            PROCEDURAL MEMORY (striatum)
     └── <label>/                       One directory per skill
-        ├── meta.json                  label, name, when_to_use, provenance, presence flags
-        ├── declarative.md             Stage 1 — step-by-step procedure (always present)
-        ├── chunks.md                  Stage 2 — higher-level recipes/macros (optional, v2+)
-        ├── code/                      Stage 3 — runnable helper modules (optional, v2+)
+        ├── SKILL.md                   name, description, instructions (agentskills.io format)
+        ├── references/                Stage 2 — higher-level recipes/macros (optional, v2+)
+        ├── scripts/                   Stage 3 — runnable helper modules (optional, v2+)
         │   └── __init__.py
         ├── requirements.txt           Stage 3 dependencies (optional)
         └── stats.json                 Per-stage usage counters (recommended/used)
@@ -477,11 +476,10 @@ Skills are intentionally distinct from engrams. **Engrams hold facts** ("CoinGec
 Each skill is a directory at `~/.anton/skills/<label>/` containing multi-stage representations that coexist (rather than graduating between stages):
 
 ```
-~/.anton/skills/csv_summary/
-├── meta.json          ← label, name, description, when_to_use, provenance, presence flags
-├── declarative.md     ← Stage 1: step-by-step procedure the LLM reads (always present)
-├── chunks.md          ← Stage 2: higher-level recipes/macros (emerges with use, v2+)
-├── code/              ← Stage 3: runnable helper modules (emerges with reliability, v2+)
+~/.anton/skills/csv-summary/
+├── SKILL.md           ← agentskills.io format: frontmatter (name, description, metadata) + body
+├── references/        ← Stage 2: higher-level recipes/macros (emerges with use, v2+)
+├── scripts/           ← Stage 3: runnable helper modules (emerges with reliability, v2+)
 │   └── __init__.py
 ├── requirements.txt   ← Stage 3 dependencies (optional)
 └── stats.json         ← per-stage usage counters
@@ -496,7 +494,7 @@ The executive picks the highest stage that's reliable enough for the current con
 
 ### Naming: `label`, not `slug`
 
-Each skill's unique identifier is its `label`. In cognitive psychology, a *label* is the declarative handle by which a procedural memory is addressed in working memory — the verbal token the executive holds when deciding to invoke a stored procedure. It's deliberately distinct from `name` (the human-readable display like "CSV Summary") and `when_to_use` (the retrieval cue describing the matching context).
+Each skill's unique identifier is its `label`. In cognitive psychology, a *label* is the declarative handle by which a procedural memory is addressed in working memory — the verbal token the executive holds when deciding to invoke a stored procedure. It's deliberately distinct from `name` (the human-readable display like "CSV Summary") and `description` (the retrieval cue describing the matching context).
 
 ### How Skills Get Created
 
@@ -510,22 +508,22 @@ anton> [opens scratchpad, loads pandas, infers schema, prints describe(), plots
 
 you> /skill save csv summary
 anton> Drafting a skill from recent work…
-       Saved skill csv_summary → ~/.anton/skills/csv_summary/
+       Saved skill csv-summary → ~/.anton/skills/csv-summary/
        Name: CSV Summary
-       When to use: User asks to explore, summarize, or describe a CSV file.
+       Description: User asks to explore, summarize, or describe a CSV file.
 ```
 
 Automatic skill extraction (the consolidator promoting recurring scratchpad patterns into skills) is a v2/v3 feature. v1 deliberately uses manual curation to learn what "good" skills look like before automating.
 
 ### How Skills Get Used
 
-On every turn, the system prompt includes a compact `## Procedural memory` section listing every available skill as one line: `- <label> — <when_to_use>`. The full procedures stay on disk. When the LLM recognizes a match, it calls the `recall_skill` tool:
+On every turn, the system prompt includes a compact `## Procedural memory` section listing every available skill as one line: `- <label> — <description>`. The full procedures stay on disk. When the LLM recognizes a match, it calls the `recall_skill` tool:
 
 ```
-{"name": "recall_skill", "input": {"label": "csv_summary"}}
+{"name": "recall_skill", "input": {"label": "csv-summary"}}
 ```
 
-The tool reads `declarative.md` and returns it as the tool result, which the LLM follows as guidance for the rest of the turn. Each successful recall increments `stats.json::stage_1::recommended` — that's the classifier signal, mechanically captured without any LLM compliance dance.
+The tool reads the SKILL.md body and returns it as the tool result, which the LLM follows as guidance for the rest of the turn. Each successful recall increments `stats.json::stage_1::recommended` — that's the classifier signal, mechanically captured without any LLM compliance dance.
 
 Brain analog: the prefrontal cortex doesn't keep every skill loaded. It has fast pattern recognition that flags "I might need skill X" and *retrieves* the skill into working memory only when it actually needs it. The `recall_skill` tool is exactly this retrieval operation.
 
@@ -540,7 +538,7 @@ Brain analog: the prefrontal cortex doesn't keep every skill loaded. It has fast
 
 ### Typo Recovery
 
-When the LLM passes a label that doesn't exist (typos, guesses), `recall_skill` uses `closest_match()` to find the nearest existing slug via difflib and returns that skill's procedure with a warning. The `recommended` counter is credited to the *resolved* label, not the input — so `recall_skill('csv_sumary')` still increments `csv_summary` in the stats. The LLM gets useful behavior even when it gets the spelling wrong.
+When the LLM passes a label that doesn't exist (typos, guesses), `recall_skill` uses `closest_match()` to find the nearest existing slug via difflib and returns that skill's procedure with a warning. The `recommended` counter is credited to the *resolved* label, not the input — so `recall_skill('csv_sumary')` still increments `csv-summary` in the stats. The LLM gets useful behavior even when it gets the spelling wrong.
 
 ## Cerebellum — Supervised Error Learning
 
@@ -890,14 +888,14 @@ Tests live at `tests/test_acc.py` (44 tests, 4 layers: pure-function detectors 
 | Method | Purpose |
 |---|---|
 | `SkillStore.list_all()` | Return every loadable skill, sorted by label. |
-| `SkillStore.list_summaries()` | Lightweight listing — `[{"label": "...", "name": "...", "when_to_use": "..."}]`. Used by the prompt builder to inject the procedural-memory section without loading any declarative content. |
-| `SkillStore.load(label)` | Read a single skill by label. Returns None if absent or malformed. |
-| `SkillStore.save(skill)` | Write the skill directory. Creates `meta.json`, `declarative.md`, `stats.json`. Never wipes accumulated counters. |
-| `SkillStore.delete(label)` | Remove a skill directory. |
-| `SkillStore.increment_recommended(label, *, stage)` | Atomic-ish bump of the per-stage `recommended` counter (called by `recall_skill`). |
-| `SkillStore.closest_match(bad_label, *, cutoff=0.6)` | Difflib-based fuzzy match for typo recovery. |
-| `make_unique_label(base, store)` | Generate a slug that doesn't collide with any existing skill (`csv_summary`, `csv_summary_2`, ...). |
-| `slugify(text)` | Normalize arbitrary text into a snake_case identifier. |
+| `SkillStore.list_summaries()` | Lightweight listing — `[{"label": "...", "name": "...", "description": "..."}]`. Used by the prompt builder to inject the procedural-memory section without loading any declarative content. |
+| `SkillStore.load(label)` | Read a single skill by label. Returns None if absent or malformed.                                                                                                                           |
+| `SkillStore.save(skill)` | Write the skill directory. Creates `SKILL.md`, `stats.json`. Never wipes accumulated counters.                                                                                               |
+| `SkillStore.delete(label)` | Remove a skill directory.                                                                                                                                                                    |
+| `SkillStore.increment_recommended(label, *, stage)` | Atomic-ish bump of the per-stage `recommended` counter (called by `recall_skill`).                                                                                                           |
+| `SkillStore.closest_match(bad_label, *, cutoff=0.6)` | Difflib-based fuzzy match for typo recovery.                                                                                                                                                 |
+| `make_unique_label(base, store)` | Generate a slug that doesn't collide with any existing skill (`csv-summary`, `csv-summary_2`, ...).                                                                                          |
+| `slugify(text)` | Normalize arbitrary text into a kebab-case identifier.                                                                                                                                       |
 
 ### `tools/recall_skill.py` — Procedural Memory Retrieval Tool
 
@@ -1060,10 +1058,10 @@ The ACC is constructed with `has_similar_lesson=_acc_has_similar`, a closure tha
 | Global lessons | ATL semantics | ~1000 tokens | Always (most recent first) |
 | Project lessons | ATL semantics | ~1000 tokens | Always (most recent first) |
 | Scratchpad wisdom | Procedural priming | ~500 tokens | Scratchpad active (tool desc). Cerebellum-generated lessons flow through here. |
-| Procedural memory list | Striatum (skill labels) | ~50 tokens per skill (compact list) | Always — when any skills are saved. Full procedures NOT loaded; only labels + when_to_use. |
+| Procedural memory list | Striatum (skill labels) | ~50 tokens per skill (compact list) | Always — when any skills are saved. Full procedures NOT loaded; only labels + description. |
 | Topic files | Cortical association | Unlimited | On demand |
 | Skill procedures | Striatum (full skills) | Variable per skill | On demand (`recall_skill` tool) — only when the LLM recognizes a match |
 | Episodic recall | MTL episodic | Variable | On demand (`recall` tool) |
 | **Total in prompt** | **Working memory** | **~5800 tokens + ~50/skill** | ~3% of 200K context |
 
-The procedural memory list scales linearly with the number of saved skills but stays cheap (~50 tokens each — slug + one-line `when_to_use`). The full skill procedures are *paid for only when retrieved*, the same way the prefrontal cortex doesn't keep every procedural memory loaded — it has fast pattern recognition that flags relevance and pulls the full procedure from storage on demand.
+The procedural memory list scales linearly with the number of saved skills but stays cheap (~50 tokens each — slug + one-line `description`). The full skill procedures are *paid for only when retrieved*, the same way the prefrontal cortex doesn't keep every procedural memory loaded — it has fast pattern recognition that flags relevance and pulls the full procedure from storage on demand.
diff --git a/anton/commands/skills.py b/anton/commands/skills.py
index 292c92ef..6f20a2c3 100644
--- a/anton/commands/skills.py
+++ b/anton/commands/skills.py
@@ -3,7 +3,7 @@
 Commands:
 
 - `/skill save [optional name hint]` — LLM reads recent scratchpad work +
-  conversation history and drafts a Skill (label, name, when_to_use,
+  conversation history and drafts a Skill (label, name, description,
   declarative procedure). Saved automatically; no interactive editing.
 - `/skills list` — show all saved skills with usage counters.
 - `/skill show <label>` — print a single skill's full procedure + stats.
@@ -54,9 +54,9 @@ class _SkillDraft(BaseModel):
     label: str = Field(
         ...,
         description=(
-            "snake_case identifier for the skill. Short (2-4 words), "
-            "captures the essence. Examples: 'csv_summary', "
-            "'web_scraping', 'api_paginated_fetch'."
+            "kebab-case identifier for the skill. Short (2-4 words), "
+            "captures the essence. Examples: 'csv-summary', "
+            "'web-scraping', 'api-paginated-fetch'."
         ),
     )
     name: str = Field(
@@ -64,10 +64,6 @@ class _SkillDraft(BaseModel):
         description="Human-readable display name (e.g. 'CSV Summary').",
     )
     description: str = Field(
-        default="",
-        description="One-sentence description of what the skill does.",
-    )
-    when_to_use: str = Field(
         ...,
         description=(
             "One sentence describing when this skill applies — what the "
@@ -229,7 +225,7 @@ async def handle_skill_save(
     name_hint_section = (
         f"The user suggested the name: {name_hint!r}. "
         "Use it as the basis for `name` and `label`, but you may refine the label "
-        "to be snake_case and short.\n"
+        "to be kebab-case and short.\n"
         if name_hint.strip()
         else ""
     )
@@ -261,7 +257,6 @@ async def handle_skill_save(
     raw_label = draft.label.strip() or slugify(name_hint or draft.name)
     name = draft.name.strip() or raw_label.replace("_", " ").title()
     description = draft.description.strip()
-    when_to_use = draft.when_to_use.strip()
     declarative_md = draft.declarative_md.strip()
 
     if not declarative_md:
@@ -278,7 +273,6 @@ async def handle_skill_save(
         label=label,
         name=name,
         description=description,
-        when_to_use=when_to_use,
         declarative_md=declarative_md,
         created_at=datetime.now(timezone.utc).isoformat(),
         provenance="manual",
@@ -290,8 +284,6 @@ async def handle_skill_save(
         f"[anton.success](anton)[/] Saved skill [bold]{label}[/bold] → {path}"
     )
     console.print(f"        [anton.muted]Name:[/] {name}")
-    if when_to_use:
-        console.print(f"        [anton.muted]When to use:[/] {when_to_use}")
     console.print(
         "        [anton.muted]Available next session — and via `recall_skill` this turn.[/]"
     )
@@ -318,7 +310,7 @@ def handle_skills_list(console: Console, store: SkillStore | None = None) -> Non
     table = Table(title="Procedural memory — saved skills", show_lines=False)
     table.add_column("Label", style="bold")
     table.add_column("Name")
-    table.add_column("When to use")
+    table.add_column("Description")
     table.add_column("Recalls", justify="right")
     table.add_column("Stages")
 
@@ -330,11 +322,11 @@ def handle_skills_list(console: Console, store: SkillStore | None = None) -> Non
             stages.append("2")
         if s.stage_3_present:
             stages.append("3")
-        when = s.when_to_use if len(s.when_to_use) <= 60 else s.when_to_use[:57] + "..."
+        desc = s.description if len(s.description) <= 60 else s.description[:57] + "..."
         table.add_row(
             s.label,
             s.name,
-            when,
+            desc,
             str(s.stats.total_recalls),
             ",".join(stages) or "-",
         )
@@ -374,8 +366,6 @@ def handle_skill_show(
     console.print(f"[anton.cyan](anton)[/] [bold]{skill.name}[/]  ([dim]{skill.label}[/])")
     if skill.description:
         console.print(f"        {skill.description}")
-    if skill.when_to_use:
-        console.print(f"        [dim]when to use:[/] {skill.when_to_use}")
     console.print()
     console.print(
         f"        [dim]recalls:[/] {skill.stats.total_recalls}  "
diff --git a/anton/config/settings.py b/anton/config/settings.py
index fc930403..7b0acdd8 100644
--- a/anton/config/settings.py
+++ b/anton/config/settings.py
@@ -64,6 +64,8 @@ class AntonSettings(CoreSettings):
     exa_api_key: str | None = None
     brave_api_key: str | None = None
 
+    skills_root: Path | None = None
+
     memory_enabled: bool = True
     # TODO: Calling this memory_dir is a bit misleading, because there are other directories that live here
     memory_dir: str = ".anton"
diff --git a/anton/core/artifacts/models.py b/anton/core/artifacts/models.py
index 9a38884b..09ef686f 100644
--- a/anton/core/artifacts/models.py
+++ b/anton/core/artifacts/models.py
@@ -56,9 +56,10 @@
 class FileEntry(BaseModel):
     """One file inside the artifact folder.
 
-    Re-derived from disk on every save (`ArtifactStore.rescan_files`)
-    rather than mutated in place. The agent never writes here
-    directly — it just creates the files; the server records them.
+    Re-derived from disk on read (`ArtifactStore._reconcile_files`, called
+    by `open()` / `list()`) rather than mutated in place. The agent never
+    populates this directly — it writes the files into the folder via the
+    scratchpad, and the store reconciles `files[]` against disk on access.
     """
 
     path: str  # relative to the artifact folder (e.g. "dashboard.html", "data/prices.csv")
diff --git a/anton/core/artifacts/store.py b/anton/core/artifacts/store.py
index dc998623..19cb4672 100644
--- a/anton/core/artifacts/store.py
+++ b/anton/core/artifacts/store.py
@@ -38,6 +38,13 @@
 
 METADATA_FILENAME = "metadata.json"
 README_FILENAME = "README.md"
+PUBLISHED_FILENAME = ".published.json"
+
+# Files the store owns or that hold publish-state — not artifact content the
+# agent authored — so they're excluded from `files[]`. Mirrors cowork-server's
+# artifacts-service housekeeping set so the agent's view and the UI agree on
+# what counts as an artifact file.
+_HOUSEKEEPING_FILES = {METADATA_FILENAME, README_FILENAME, PUBLISHED_FILENAME}
 
 # Same character whitelist projects_store uses — keeps slug shapes
 # consistent across antontron's project names AND artifact slugs.
@@ -224,14 +231,24 @@ def list(self) -> list[Artifact]:
                 continue
             artifact = self._load_silent(child.name)
             if artifact is not None:
-                out.append(artifact)
+                # Reconcile against disk so file counts are accurate even
+                # though scratchpad writes bypass the store (see _reconcile_files).
+                out.append(self._reconcile_files(artifact))
         out.sort(key=lambda a: a.updatedAt, reverse=True)
         return out
 
     def open(self, slug: str) -> Artifact | None:
-        """Load an artifact by slug. None when the folder doesn't
-        exist or the metadata file is missing/corrupt."""
-        return self._load_silent(slug)
+        """Load an artifact by slug, reconciling `files[]` against disk.
+
+        None when the folder doesn't exist or the metadata file is
+        missing/corrupt. Reconciliation (see `_reconcile_files`) is what
+        makes scratchpad-written files show up in `files[]` — the agent
+        writes them directly to the folder, bypassing the store.
+        """
+        artifact = self._load_silent(slug)
+        if artifact is None:
+            return None
+        return self._reconcile_files(artifact)
 
     # ── Provenance + per-turn updates ───────────────────────────
 
@@ -287,18 +304,39 @@ def record_turn(
         return artifact
 
     def rescan_files(self, slug: str) -> Artifact | None:
-        """Refresh `files[]` from disk. Skips `metadata.json` and
-        `README.md` — those are housekeeping, not artifact content."""
+        """Reconcile `files[]` with what's actually on disk, by slug.
+
+        Returns the (possibly refreshed) artifact, or None when the slug
+        is missing. See `_reconcile_files` for the why.
+        """
         artifact = self._load_silent(slug)
         if artifact is None:
             return None
-        folder = self.folder_for(slug)
+        return self._reconcile_files(artifact)
+
+    def _reconcile_files(self, artifact: Artifact) -> Artifact:
+        """Re-derive `files[]` from disk for an already-loaded artifact.
+
+        Scratchpad code writes artifact files straight into the folder via
+        plain ``open()``, bypassing the store — so without this, `files[]`
+        stays frozen at whatever ``create()``/``update()`` last set (usually
+        empty), and ``open()``/``list()`` report file_count 0 for artifacts
+        that are fully written on disk. The agent then concludes the file is
+        missing and burns turns in a recovery loop.
+
+        Persists (and bumps ``updatedAt``) ONLY when the on-disk file set
+        actually changed, so this is safe and cheap to call on every read —
+        no metadata/README churn and no spurious ``updatedAt`` bumps when
+        nothing moved. Skips housekeeping files (`metadata.json` /
+        `README.md` / `.published.json`).
+        """
+        folder = self.folder_for(artifact.slug)
         entries: list[FileEntry] = []
         for p in sorted(folder.rglob("*")):
             if not p.is_file() or p.is_symlink():
                 continue
             rel = str(p.relative_to(folder))
-            if rel in (METADATA_FILENAME, README_FILENAME):
+            if rel in _HOUSEKEEPING_FILES:
                 continue
             try:
                 stat = p.stat()
@@ -308,6 +346,13 @@ def rescan_files(self, slug: str) -> Artifact | None:
                 stat.st_mtime, timezone.utc
             ).isoformat(timespec="seconds")
             entries.append(FileEntry(path=rel, bytes=stat.st_size, modifiedAt=mtime_iso))
+
+        def _fingerprint(files: list[FileEntry]) -> list[tuple]:
+            return sorted((f.path, f.bytes, f.modifiedAt) for f in files)
+
+        if _fingerprint(entries) == _fingerprint(artifact.files):
+            return artifact  # nothing changed on disk — don't rewrite metadata
+
         artifact.files = entries
         artifact.updatedAt = _utc_now()
         self._save(artifact)
diff --git a/anton/core/llm/prompt_builder.py b/anton/core/llm/prompt_builder.py
index 9a4f0c0e..3c3d429d 100644
--- a/anton/core/llm/prompt_builder.py
+++ b/anton/core/llm/prompt_builder.py
@@ -67,7 +67,7 @@ def _build_procedural_memory_section(
     ) -> str:
         """Build the '## Procedural memory' section listing available skills.
 
-        Lists each skill as `- label: when_to_use` (one line) plus a short
+        Lists each skill as `- label: description` (one line) plus a short
         instruction telling the LLM to call `recall_skill(label)` to load
         the full procedure. Returns an empty string if no store is wired
         or no skills are saved — the caller skips the section entirely.
@@ -98,7 +98,7 @@ def _build_procedural_memory_section(
         ]
         for s in summaries:
             label = s.get("label", "")
-            when = s.get("when_to_use", "").strip()
+            when = s.get("description", "").strip()
             if not label:
                 continue
             if when:
diff --git a/anton/core/memory/skills.py b/anton/core/memory/skills.py
index 0d0b1a87..92121672 100644
--- a/anton/core/memory/skills.py
+++ b/anton/core/memory/skills.py
@@ -2,67 +2,52 @@
 
 A *skill* is one concept with multiple representations that coexist:
 
-  - Stage 1 (declarative.md) — step-by-step procedure the LLM reads. Always present.
-  - Stage 2 (chunks.md)      — higher-level recipes/macros. Emerges from use. (v2+)
-  - Stage 3 (code/)          — runnable helper modules. Emerges from reliability. (v2+)
+  - Stage 1 (SKILL.md body)  — step-by-step procedure the LLM reads. Always present.
+  - Stage 2 (references/)    — higher-level recipes/macros. Emerges from use.
+  - Stage 3 (scripts/)       — runnable helper modules. Emerges from reliability.
 
 Each skill lives at `~/.anton/skills/<label>/` as a directory:
 
-    ~/.anton/skills/csv_summary/
-    ├── meta.json          # label, name, description, when_to_use, provenance, presence flags
-    ├── declarative.md     # Stage 1 — required
-    ├── chunks.md          # Stage 2 — optional
-    ├── code/              # Stage 3 — optional
-    │   └── __init__.py
-    ├── requirements.txt   # Stage 3 deps — optional
-    └── stats.json         # per-stage usage counters
-
-This module is the storage layer only — read/write/search. The classifier
-(`recall_skill` tool) and the LLM-driven save command live elsewhere.
-
-Brain analogue: cortico-striatal procedural memory. The executive (PFC)
-recognizes a familiar pattern in the user's request, retrieves the
-matching procedure from the striatum, and executes it. Stages coexist
-rather than graduating — the executive picks the highest stage that's
-reliable enough for the current context.
-
-Relationship to `Engram` (anton/core/memory/hippocampus.py):
-    `Engram` is the unit of *declarative* memory in Anton — a single
-    fact, rule, or lesson stored as a flat bullet in rules.md / lessons.md /
-    profile.md. Engrams are loaded into every prompt unconditionally because
-    they're cheap (one line each). The brain-region analogue is the
-    hippocampus → neocortex consolidation pathway.
-
-    `Skill` is the unit of *procedural* memory in Anton — a multi-step
-    workflow stored as a directory of staged representations. Skills are
-    NOT loaded into every prompt; the LLM sees only their compact label +
-    when_to_use line and explicitly retrieves the full procedure via the
-    `recall_skill` tool when it recognizes a match. The brain-region
-    analogue is the hippocampus → striatum / cerebellum pathway.
-
-    Both systems coexist in the brain (declarative and procedural memory
-    are dissociable — H.M. lost the former but kept the latter), and they
-    coexist in Anton. Engrams hold facts; Skills hold procedures.
-
-Naming note:
-    The unique identifier for a skill is called its `label`. In cognitive
-    psychology this is the declarative handle by which a procedural
-    memory is addressed in working memory — the verbal token the
-    executive holds when deciding to invoke a stored procedure. It is
-    deliberately distinct from `name` (the human-readable display) and
-    `when_to_use` (the retrieval cue describing the matching context).
+    ~/.anton/skills/csv-summary/
+    ├── SKILL.md           # agentskills.io format: frontmatter + declarative body
+    ├── references/        # Stage 2 — optional
+    ├── scripts/           # Stage 3 — optional
+    └── stats.json         # per-stage usage counters (internal sidecar)
+
+Legacy format (meta.json + declarative.md) is migrated transparently on first
+read via check_migrate().
+
+Labels use hyphens (e.g. `my-cat`), not underscores.
+
+Relationship to Engram (anton/core/memory/hippocampus.py):
+    Engram is the unit of *declarative* memory — a single fact, rule, or
+    lesson stored as a flat bullet in rules.md / lessons.md / profile.md.
+    Engrams are loaded into every prompt unconditionally because they're cheap.
+
+    Skill is the unit of *procedural* memory — a multi-step workflow stored
+    as a directory of staged representations. Skills are NOT loaded into every
+    prompt; the LLM sees only a compact label + description line and explicitly
+    retrieves the full procedure via `recall_skill` when it recognizes a match.
+
+    Both systems coexist the way they do in the brain — declarative and
+    procedural memory are dissociable (H.M. lost the former but kept the
+    latter). Engrams hold facts; Skills hold procedures.
 """
 
 from __future__ import annotations
 
 import difflib
 import json
+import logging
 import re
 import shutil
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from pathlib import Path
 
+from anton.core.tools.skill_format import AgentSkill, dump_skill, parse_skill_dir, normalize_name, DESC_MAX
+
+logger = logging.getLogger(__name__)
 
 _DEFAULT_SKILLS_ROOT = Path("~/.anton/skills").expanduser()
 
@@ -74,15 +59,6 @@
 
 @dataclass
 class StageStats:
-    """Per-stage usage tracking.
-
-    `recommended` increments every time the classifier (recall_skill tool)
-    pulls this stage into context. `used` increments when scratchpad code
-    actually imports a Stage 3 helper — Stage 1 and Stage 2 only have a
-    `recommended` signal because there's no mechanical way to detect
-    whether the LLM "followed" a markdown procedure.
-    """
-
     recommended: int = 0
     used: int = 0
     last_used: str = ""  # ISO timestamp
@@ -101,41 +77,25 @@ class SkillStats:
 class Skill:
     """In-memory representation of a skill directory.
 
-    Always carries the metadata. The Stage 1 markdown is loaded eagerly
-    because it's small and almost always needed. Stage 2 and Stage 3
-    content (when present) is loaded on demand by callers.
-
-    The `label` is the declarative handle for this procedural memory —
-    the snake_case identifier the LLM uses when it calls
-    `recall_skill(label)`. It is the directory name on disk.
+    `label` is the hyphen-case identifier (= SKILL.md `name` field = dir name).
+    `name` is the human-readable display name (metadata.display_name).
+    `stage_*_present` flags are derived from directory presence on disk, not
+    stored explicitly: stage_1 is always True, stage_2 requires `references/`,
+    stage_3 requires `scripts/`.
     """
 
     label: str
     name: str
     description: str
-    when_to_use: str
     declarative_md: str
     created_at: str
-    provenance: str  # "manual" | "consolidator" (future)
+    provenance: str  # "manual" | "consolidator"
+    when_to_use: str = ""
     stage_1_present: bool = True
     stage_2_present: bool = False
     stage_3_present: bool = False
     stats: SkillStats = field(default_factory=SkillStats)
 
-    def to_meta_dict(self) -> dict:
-        """Serialize the meta.json payload (excludes declarative content + stats)."""
-        return {
-            "label": self.label,
-            "name": self.name,
-            "description": self.description,
-            "when_to_use": self.when_to_use,
-            "created_at": self.created_at,
-            "provenance": self.provenance,
-            "stage_1_present": self.stage_1_present,
-            "stage_2_present": self.stage_2_present,
-            "stage_3_present": self.stage_3_present,
-        }
-
     def to_stats_dict(self) -> dict:
         return {
             "total_recalls": self.stats.total_recalls,
@@ -168,40 +128,130 @@ def _stage_stats_from_dict(d: dict) -> StageStats:
 # ─────────────────────────────────────────────────────────────────────────────
 
 
-_SLUG_RE = re.compile(r"[^a-z0-9_]+")
+_SLUG_RE = re.compile(r"[^a-z0-9-]+")
 
 
 def slugify(text: str) -> str:
-    """Normalize arbitrary text into a snake_case identifier.
+    """Normalize arbitrary text into a hyphen-case label.
 
-    Strips non-alphanumerics, lowercases, collapses runs of underscores.
-    Empty input becomes 'skill'. Used to produce path/URL-safe labels;
-    the term "slugify" refers to the formatting operation, not to the
-    semantic role of the result (which we call a `label`).
+    Strips non-alphanumerics (except hyphens), lowercases, collapses runs.
+    Empty input becomes 'skill'.
     """
-    s = text.strip().lower().replace("-", "_").replace(" ", "_")
-    s = _SLUG_RE.sub("_", s)
-    s = re.sub(r"_+", "_", s).strip("_")
+    s = text.strip().lower().replace("_", "-").replace(" ", "-")
+    s = _SLUG_RE.sub("-", s)
+    s = re.sub(r"-+", "-", s).strip("-")
     return s or "skill"
 
 
 def make_unique_label(base: str, store: "SkillStore") -> str:
     """Return a label that doesn't collide with any existing skill.
 
-    If `base` (after slugify normalization) is already unique, return it
-    as-is. Otherwise append `_2`, `_3`, ... until a free slot is found.
+    Appends `-2`, `-3`, ... until a free slot is found.
     """
     candidate = slugify(base)
     if store.load(candidate) is None:
         return candidate
     n = 2
     while True:
-        next_candidate = f"{candidate}_{n}"
+        next_candidate = f"{candidate}-{n}"
         if store.load(next_candidate) is None:
             return next_candidate
         n += 1
 
 
+# ─────────────────────────────────────────────────────────────────────────────
+# Migration
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def check_migrate(skill_dir: Path, store_root: Path) -> Path | None:
+    """Migrate a legacy skill directory to SKILL.md format in place.
+
+    Old format: meta.json + declarative.md
+    New format: SKILL.md (agentskills.io spec)
+
+    Also renames the directory from snake_case to kebab-case and moves:
+      code/      → scripts/
+
+    Returns the (possibly renamed) directory path, or None if the directory
+    contains neither legacy files nor a SKILL.md (unrecognised dir, skip it).
+    Raises OSError on IO failures.
+    Idempotent: returns skill_dir immediately if SKILL.md already exists.
+    """
+    skill_md_path = skill_dir / "SKILL.md"
+    if skill_md_path.is_file():
+        return skill_dir
+
+    meta_path = skill_dir / "meta.json"
+    decl_path = skill_dir / "declarative.md"
+    if not meta_path.is_file() and not decl_path.is_file():
+        return None
+
+    # Load legacy data
+    meta: dict = {}
+    if meta_path.is_file():
+        try:
+            meta = json.loads(meta_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    declarative = decl_path.read_text(encoding="utf-8") if decl_path.is_file() else ""
+
+    old_label = skill_dir.name
+    new_label = normalize_name(old_label)
+
+    # Resolve collision when renaming
+    final_label = new_label
+    if new_label != old_label:
+        target = store_root / new_label
+        if target.exists():
+            n = 2
+            while True:
+                candidate = f"{new_label}-{n}"
+                if not (store_root / candidate).exists():
+                    final_label = candidate
+                    break
+                n += 1
+
+    description = str(meta.get("description", "")).strip()
+    when_to_use = str(meta.get("when_to_use", "")).strip()
+    if when_to_use:
+        description = f"{description}. {when_to_use}" if description else when_to_use
+    description = description[:DESC_MAX]
+
+    metadata = {k: str(v) for k, v in {
+        "display_name": meta.get("name", ""),
+        "provenance": meta.get("provenance", "manual"),
+        "created_at": meta.get("created_at", ""),
+    }.items() if v}
+
+    fm = AgentSkill.model_construct(
+        name=final_label,
+        description=description,
+        instructions=declarative,
+        metadata=metadata,
+    )
+    skill_md_path.write_text(dump_skill(fm), encoding="utf-8")
+
+    # code/ → scripts/
+    code_dir = skill_dir / "code"
+    scripts_dir = skill_dir / "scripts"
+    if code_dir.is_dir() and not scripts_dir.exists():
+        shutil.move(str(code_dir), str(scripts_dir))
+
+    # Remove legacy files
+    meta_path.unlink(missing_ok=True)
+    decl_path.unlink(missing_ok=True)
+
+    # Rename directory
+    if final_label != old_label:
+        final_dir = store_root / final_label
+        skill_dir.rename(final_dir)
+        return final_dir
+
+    return skill_dir
+
+
 # ─────────────────────────────────────────────────────────────────────────────
 # Store
 # ─────────────────────────────────────────────────────────────────────────────
@@ -210,17 +260,16 @@ def make_unique_label(base: str, store: "SkillStore") -> str:
 class SkillStore:
     """File-backed store of skills under `~/.anton/skills/` (by default).
 
-    Each skill is a directory whose name is its `label` (the snake_case
-    declarative handle). The store is stateless — it reads from disk on
-    demand. Callers should not cache Skill instances long-term, since
-    stats are mutated through the store's increment helpers and a stale
-    in-memory copy will drift.
+    Each skill is a directory whose name is its `label` (hyphen-case).
+    The store is stateless — reads from disk on demand.
+    Legacy directories (meta.json + declarative.md) are migrated transparently
+    on first access via check_migrate().
     """
 
     def __init__(self, root: Path | None = None) -> None:
         self.root = Path(root) if root is not None else _DEFAULT_SKILLS_ROOT
 
-    # ── reading ─────────────────────────────────────────────────────
+    # ── internal helpers ─────────────────────────────────────────────
 
     def _skill_dir(self, label: str) -> Path:
         return self.root / label
@@ -228,35 +277,52 @@ def _skill_dir(self, label: str) -> Path:
     def _ensure_root(self) -> None:
         self.root.mkdir(parents=True, exist_ok=True)
 
+    def _find_dir(self, label: str) -> Path | None:
+        """Locate the directory for a label, tolerating legacy underscore names."""
+        norm = label.replace("_", "-")
+        d = self.root / norm
+        if d.is_dir():
+            return d
+        if norm != label:
+            old = self.root / label
+            if old.is_dir():
+                return old
+        return None
+
+    def _skill_from_dir(self, d: Path) -> Skill | None:
+        """Build a Skill from a (already-migrated) directory."""
+        fm = parse_skill_dir(d)
+        if fm is None:
+            return None
+
+        return Skill(
+            label=fm.name,
+            name=fm.metadata.get("display_name", fm.name),
+            description=fm.description,
+            declarative_md=fm.instructions,
+            created_at=fm.metadata.get("created_at", ""),
+            provenance=fm.metadata.get("provenance", "manual"),
+            stage_1_present=True,
+            stage_2_present=(d / "references").is_dir(),
+            stage_3_present=(d / "scripts").is_dir(),
+            stats=self._load_stats(d.name),
+        )
+
+    # ── reading ─────────────────────────────────────────────────────
+
     def load(self, label: str) -> Skill | None:
-        """Read a single skill by label. Returns None if absent or malformed."""
-        d = self._skill_dir(label)
-        meta_path = d / "meta.json"
-        decl_path = d / "declarative.md"
-        if not meta_path.is_file() or not decl_path.is_file():
+        """Read a single skill by label. Returns None if absent or unreadable."""
+        if not self.root.is_dir():
             return None
-        try:
-            meta = json.loads(meta_path.read_text(encoding="utf-8"))
-        except (json.JSONDecodeError, OSError):
+        d = self._find_dir(label)
+        if d is None:
             return None
-        try:
-            declarative = decl_path.read_text(encoding="utf-8")
-        except OSError:
+
+        d = check_migrate(d, self.root)
+        if d is None:
             return None
-        stats = self._load_stats(label)
-        return Skill(
-            label=str(meta.get("label", label)),
-            name=str(meta.get("name", label)),
-            description=str(meta.get("description", "")),
-            when_to_use=str(meta.get("when_to_use", "")),
-            declarative_md=declarative,
-            created_at=str(meta.get("created_at", "")),
-            provenance=str(meta.get("provenance", "manual")),
-            stage_1_present=bool(meta.get("stage_1_present", True)),
-            stage_2_present=bool(meta.get("stage_2_present", False)),
-            stage_3_present=bool(meta.get("stage_3_present", False)),
-            stats=stats,
-        )
+
+        return self._skill_from_dir(d)
 
     def _load_stats(self, label: str) -> SkillStats:
         path = self._skill_dir(label) / "stats.json"
@@ -281,15 +347,22 @@ def list_all(self) -> list[Skill]:
         for child in sorted(self.root.iterdir()):
             if not child.is_dir():
                 continue
-            skill = self.load(child.name)
+            try:
+                child = check_migrate(child, self.root)
+                if child is None:
+                    continue
+            except OSError:
+                continue
+            skill = self._skill_from_dir(child)
             if skill is not None:
                 out.append(skill)
         return out
 
     def list_summaries(self) -> list[dict]:
-        """Lightweight listing for prompt-building — label + when_to_use only.
+        """Lightweight listing for prompt-building.
 
-        Avoids reading declarative.md for skills the LLM won't recall this turn.
+        Returns dicts with keys: label, name, description.
+        Reads only SKILL.md frontmatter, skips the body.
         """
         if not self.root.is_dir():
             return []
@@ -297,41 +370,56 @@ def list_summaries(self) -> list[dict]:
         for child in sorted(self.root.iterdir()):
             if not child.is_dir():
                 continue
-            meta_path = child / "meta.json"
-            if not meta_path.is_file():
-                continue
             try:
-                meta = json.loads(meta_path.read_text(encoding="utf-8"))
-            except (json.JSONDecodeError, OSError):
+                child = check_migrate(child, self.root)
+                if child is None:
+                    continue
+            except OSError:
                 continue
-            out.append(
-                {
-                    "label": str(meta.get("label", child.name)),
-                    "name": str(meta.get("name", child.name)),
-                    "when_to_use": str(meta.get("when_to_use", "")),
-                }
-            )
+            fm = parse_skill_dir(child)
+            if fm is None:
+                continue
+
+            out.append({
+                "label": fm.name,
+                "name": fm.metadata.get("display_name", fm.name),
+                "description": fm.description,
+            })
         return out
 
     # ── writing ─────────────────────────────────────────────────────
 
     def save(self, skill: Skill) -> Path:
-        """Write the skill directory to disk. Overwrites in place.
+        """Write the skill directory to disk. Overwrites SKILL.md in place.
 
-        Returns the directory path. Creates the parent root if needed.
-        Stage 2 and Stage 3 files are NOT touched here — they have their
-        own writers (consolidator, future).
+        Returns the directory path. Stage 2/3 files are not touched here.
+        stats.json is only initialized if it doesn't already exist.
         """
         self._ensure_root()
+
+        skill.label = normalize_name(skill.label)
         d = self._skill_dir(skill.label)
         d.mkdir(parents=True, exist_ok=True)
-        (d / "meta.json").write_text(
-            json.dumps(skill.to_meta_dict(), indent=2) + "\n",
-            encoding="utf-8",
+
+        metadata = {k: v for k, v in {
+            "display_name": skill.name,
+            "provenance": skill.provenance,
+            "created_at": skill.created_at,
+        }.items() if v}
+
+        description = skill.description
+        if skill.when_to_use:
+            description = f"{description}. {skill.when_to_use}" if description else skill.when_to_use
+        description = description[:DESC_MAX]
+
+        fm = AgentSkill.model_construct(
+            name=skill.label,
+            description=description,
+            instructions=skill.declarative_md,
+            metadata=metadata,
         )
-        (d / "declarative.md").write_text(skill.declarative_md, encoding="utf-8")
-        # Only initialize stats.json if it doesn't already exist — we
-        # never want save() to wipe accumulated counts.
+        (d / "SKILL.md").write_text(dump_skill(fm), encoding="utf-8")
+
         stats_path = d / "stats.json"
         if not stats_path.is_file():
             stats_path.write_text(
@@ -351,17 +439,11 @@ def delete(self, label: str) -> bool:
     # ── stats updates ───────────────────────────────────────────────
 
     def increment_recommended(self, label: str, *, stage: int = 1) -> None:
-        """Atomic-ish bump of the per-stage `recommended` counter.
-
-        Reads the existing stats.json, mutates the right field, writes
-        back. Best-effort — if the skill doesn't exist or the file is
-        unwritable, silently no-ops. Concurrent writers may race; that's
-        acceptable for a counter that's used for guidance, not billing.
-        """
-        d = self._skill_dir(label)
-        if not d.is_dir():
+        """Bump the per-stage `recommended` counter. Best-effort, no-ops on error."""
+        d = self._find_dir(label)
+        if d is None:
             return
-        stats = self._load_stats(label)
+        stats = self._load_stats(d.name)
         stats.total_recalls += 1
         target = self._stage_for(stats, stage)
         target.recommended += 1
@@ -396,12 +478,7 @@ def _stage_for(stats: SkillStats, stage: int) -> StageStats:
     # ── search ──────────────────────────────────────────────────────
 
     def closest_match(self, bad_label: str, *, cutoff: float = 0.6) -> str | None:
-        """Find the existing label closest to `bad_label`, or None.
-
-        Used by the recall_skill tool to recover from typos and guesses.
-        Cutoff is intentionally generous — we'd rather suggest a wrong
-        match the LLM can reject than return nothing.
-        """
+        """Find the existing label closest to `bad_label`, or None."""
         bad = slugify(bad_label)
         candidates = [s["label"] for s in self.list_summaries()]
         if not candidates:
@@ -417,6 +494,7 @@ def closest_match(self, bad_label: str, *, cutoff: float = 0.6) -> str | None:
     "SkillStats",
     "SkillStore",
     "StageStats",
+    "check_migrate",
     "make_unique_label",
     "slugify",
 ]
diff --git a/anton/core/session.py b/anton/core/session.py
index 742ee377..5bc18c12 100644
--- a/anton/core/session.py
+++ b/anton/core/session.py
@@ -212,7 +212,7 @@ def __init__(self, config: ChatSessionConfig) -> None:
         # Procedural memory: brain-inspired skills (Stage 1 = declarative).
         # Lives at ~/.anton/skills/<label>/. The recall_skill tool retrieves
         # entries on demand and increments per-stage usage counters.
-        self._skill_store = SkillStore()
+        self._skill_store = SkillStore(root=getattr(s, "skills_root", None))
         # Cerebellum: supervised error learning over scratchpad cells.
         # Buffers errored/warning cells across the turn, runs one diff
         # call at end-of-turn, and encodes lessons via cortex.encode().
diff --git a/anton/core/tools/recall_skill.py b/anton/core/tools/recall_skill.py
index 290e5af1..6e1438c2 100644
--- a/anton/core/tools/recall_skill.py
+++ b/anton/core/tools/recall_skill.py
@@ -42,7 +42,7 @@
         "label": {
             "type": "string",
             "description": (
-                "The skill label to recall, e.g. 'csv_summary'. Must come from "
+                "The skill label to recall, e.g. 'csv-summary'. Must come from "
                 "the procedural memory list in your system prompt."
             ),
         },
@@ -113,7 +113,7 @@ async def handle_recall_skill(session: "ChatSession", tc_input: dict) -> str:
         )
 
     # Increment the recommended counter for the *resolved* label, not the
-    # input. If the LLM typo'd 'csv_sumary', we credit 'csv_summary'.
+    # input. If the LLM typo'd 'csv-sumary', we credit 'csv-summary'.
     store.increment_recommended(skill.label, stage=1)
 
     return _format_skill_response(skill, warning=warning)
diff --git a/anton/core/tools/skill_format.py b/anton/core/tools/skill_format.py
new file mode 100644
index 00000000..5b2ff010
--- /dev/null
+++ b/anton/core/tools/skill_format.py
@@ -0,0 +1,210 @@
+"""Parsing and serialisation of the agentskills.io SKILL.md format.
+
+SKILL.md layout:
+    ---
+    name: my-cat
+    description: Short description (1-1024 chars)
+    license: MIT                        # optional
+    compatibility: requires network     # optional
+    allowed-tools: read_file write_file # optional, space-separated
+    metadata:
+      display_name: My Cat
+      provenance: manual
+      created_at: "2026-06-15T15:20:42+00:00"
+    ---
+    Step-by-step body (= former declarative.md content)
+
+Parsing is intentionally lenient — no field validation is applied when
+reading, since files may be authored by external tools.  Validators on
+AgentSkill exist for write/creation paths only and must be called
+explicitly via AgentSkill.model_validate().
+
+Unknown top-level YAML keys are folded into `metadata` automatically.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import BaseModel, Field, field_validator
+
+logger = logging.getLogger(__name__)
+
+# ─── spec constraints (used by validators, not enforced on read) ──────────────
+
+SKILL_FILE = "SKILL.md"
+DESC_MAX = 1024
+_NAME_RE = re.compile(r"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$")
+_NAME_MAX = 64
+_COMPAT_MAX = 500
+
+# canonical YAML keys defined by the spec
+_SPEC_KEYS = {"name", "description", "license", "compatibility", "metadata", "allowed-tools"}
+
+
+# ─── model ────────────────────────────────────────────────────────────────────
+
+def validate_name(v: str) -> str:
+    if len(v) > _NAME_MAX:
+        raise ValueError(f"name exceeds {_NAME_MAX} chars")
+    if "--" in v:
+        raise ValueError("name must not contain '--'")
+    if not _NAME_RE.match(v):
+        raise ValueError(
+            f"name {v!r} must match {_NAME_RE.pattern}"
+        )
+    return v
+
+
+def normalize_name(value: str) -> str:
+    slug = value.strip().lower()
+    slug = re.sub(r"[^a-z0-9]+", "-", slug)  # non-alnum runs -> single hyphen
+    slug = re.sub(r"-{2,}", "-", slug).strip("-")
+
+    return slug[:_NAME_MAX].rstrip("-")
+
+
+class AgentSkill(BaseModel):
+    """In-memory representation of a SKILL.md file (frontmatter + body).
+
+    Validators are active when you call model_validate() (write / creation
+    path).  parse_skill_dir() uses model_construct() so validators are skipped.
+    """
+
+    name: str = ""
+    instructions: str
+    description: str = ""
+    license: str | None = None
+    compatibility: str | None = None
+    allowed_tools: str | None = Field(None, alias="allowed-tools")
+    metadata: dict[str, str] = {}
+
+    # ── validators (write / creation path only) ───────────────────────
+
+    @field_validator("name")
+    @classmethod
+    def _validate_name(cls, v: str) -> str:
+        return validate_name(v)
+
+    @field_validator("description")
+    @classmethod
+    def _validate_description(cls, v: str) -> str:
+        if not v:
+            raise ValueError("description must not be empty")
+        if len(v) > DESC_MAX:
+            raise ValueError(f"description exceeds {DESC_MAX} chars")
+        return v
+
+    @field_validator("compatibility")
+    @classmethod
+    def _validate_compatibility(cls, v: str | None) -> str | None:
+        if v is not None and len(v) > _COMPAT_MAX:
+            raise ValueError(f"compatibility exceeds {_COMPAT_MAX} chars")
+        return v
+
+    @field_validator("metadata", mode="before")
+    @classmethod
+    def _coerce_metadata(cls, v: Any) -> dict[str, str]:
+        if not isinstance(v, dict):
+            return {}
+        return {str(k): str(val) for k, val in v.items()}
+
+
+# ─── parse ────────────────────────────────────────────────────────────────────
+
+
+def parse_skill_dir(skill_dir: Path) -> AgentSkill | None:
+    """Read ``<skill_dir>/SKILL.md`` into a ``Skill``"""
+    folder_name = skill_dir.name
+    md_path = skill_dir / "SKILL.md"
+
+    try:
+        text = md_path.read_text(encoding="utf-8")
+    except OSError:
+        return None
+
+    lines = text.split("\n")
+    if not lines or lines[0].rstrip() != "---":
+        logger.debug("parse_skill_md: no opening '---' delimiter")
+        return None
+
+    close_idx: int | None = None
+    for i, line in enumerate(lines[1:], 1):
+        if line.rstrip() == "---":
+            close_idx = i
+            break
+
+    if close_idx is None:
+        logger.debug("parse_skill_md: no closing '---' delimiter")
+        return None
+
+    yaml_text = "\n".join(lines[1:close_idx])
+    body = "\n".join(lines[close_idx + 1 :])
+
+    try:
+        props = yaml.safe_load(yaml_text)
+    except yaml.YAMLError as exc:
+        logger.warning("parse_skill_md: YAML error: %s", exc)
+        return None
+
+    if not isinstance(props, dict):
+        logger.warning("parse_skill_md: frontmatter is not a YAML mapping")
+        return None
+
+    # Collect metadata from the spec field, then fold in unknown top-level keys
+    meta: dict[str, str] = {}
+    spec_meta = props.get("metadata")
+    if isinstance(spec_meta, dict):
+        meta = {str(k): str(v) for k, v in spec_meta.items()}
+    for k, v in props.items():
+        if k not in _SPEC_KEYS:
+            meta.setdefault(str(k), str(v))
+
+    # check name
+    name = props.get("name")
+    if not name:
+        name = folder_name
+
+    return AgentSkill.model_construct(
+        name=normalize_name(name),
+        instructions=body,
+        description=str(props.get("description", "")),
+        license=props.get("license"),
+        compatibility=props.get("compatibility"),
+        allowed_tools=props.get("allowed-tools"),
+        metadata=meta,
+    )
+
+
+# ─── dump ─────────────────────────────────────────────────────────────────────
+
+
+def dump_skill(skill: AgentSkill) -> str:
+    """Serialize an AgentSkill back to SKILL.md text."""
+    data: dict[str, Any] = {
+        "name": skill.name,
+        "description": skill.description,
+    }
+    if skill.license is not None:
+        data["license"] = skill.license
+    if skill.compatibility is not None:
+        data["compatibility"] = skill.compatibility
+    if skill.allowed_tools is not None:
+        data["allowed-tools"] = skill.allowed_tools
+    if skill.metadata:
+        data["metadata"] = dict(skill.metadata)
+
+    yaml_text = yaml.dump(
+        data,
+        default_flow_style=False,
+        allow_unicode=True,
+        sort_keys=False,
+    )
+    return f"---\n{yaml_text}---\n{skill.instructions}"
+
+
+__all__ = ["AgentSkill", "parse_skill_dir", "dump_skill"]
diff --git a/docs/docs/developer/architecture.md b/docs/docs/developer/architecture.md
index f8611b5c..77f67e2e 100644
--- a/docs/docs/developer/architecture.md
+++ b/docs/docs/developer/architecture.md
@@ -57,7 +57,7 @@ At the highest level there are three layers:
   │ (hipp.)    │  │ Buffers bad  │  │ /skill save → LLM   │
   │            │  │ cells, runs  │  │ drafts a procedure  │
   │ Episodes — │  │ post-mortem  │  │ with label + name + │
-  │ JSONL log  │  │ via LLM,     │  │ when_to_use +       │
+  │ JSONL log  │  │ via LLM,     │  │ description +       │
   │ of every   │  │ encodes new  │  │ declarative_md.     │
   │ turn.      │  │ lessons via  │  │                     │
   │            │  │ Cortex.      │  │ Future turns recall │
diff --git a/docs/docs/developer/brain-mapping.md b/docs/docs/developer/brain-mapping.md
index 29d1b48d..9fa3cce7 100644
--- a/docs/docs/developer/brain-mapping.md
+++ b/docs/docs/developer/brain-mapping.md
@@ -64,10 +64,9 @@ Two scopes: **global** (cross-project, under the home directory) and
 │       └── *.md
 └── skills/                            PROCEDURAL MEMORY (striatum)
     └── <label>/                       One directory per skill
-        ├── meta.json                  label, name, when_to_use, provenance, presence flags
-        ├── declarative.md             Stage 1 — step-by-step procedure (always present)
-        ├── chunks.md                  Stage 2 — higher-level recipes/macros (optional, v2+)
-        ├── code/                      Stage 3 — runnable helper modules (optional, v2+)
+        ├── SKILL.md                   name, description, instructions (agentskills.io format)
+        ├── references/                Stage 2 — higher-level recipes/macros (optional, v2+)
+        ├── scripts/                   Stage 3 — runnable helper modules (optional, v2+)
         │   └── __init__.py
         ├── requirements.txt           Stage 3 dependencies (optional)
         └── stats.json                 Per-stage usage counters (recommended/used)
diff --git a/docs/docs/developer/skills-internals.md b/docs/docs/developer/skills-internals.md
index de91f096..157251d4 100644
--- a/docs/docs/developer/skills-internals.md
+++ b/docs/docs/developer/skills-internals.md
@@ -29,11 +29,10 @@ Each skill is a directory at `~/.anton/skills/<label>/` containing multi-stage
 representations that **coexist** (rather than graduating between stages):
 
 ```
-~/.anton/skills/csv_summary/
-├── meta.json          ← label, name, description, when_to_use, provenance, presence flags
-├── declarative.md     ← Stage 1: step-by-step procedure the LLM reads (always present)
-├── chunks.md          ← Stage 2: higher-level recipes/macros (emerges with use, v2+)
-├── code/              ← Stage 3: runnable helper modules (emerges with reliability, v2+)
+~/.anton/skills/csv-summary/
+├── SKILL.md           ← agentskills.io format: frontmatter (name, description, metadata) + body
+├── references/        ← Stage 2: higher-level recipes/macros (emerges with use, v2+)
+├── scripts/           ← Stage 3: runnable helper modules (emerges with reliability, v2+)
 │   └── __init__.py
 ├── requirements.txt   ← Stage 3 dependencies (optional)
 └── stats.json         ← per-stage usage counters
@@ -52,16 +51,16 @@ The executive picks the highest stage reliable enough for the current context.
 **v1 only ships Stage 1**; the directory format pre-allocates the other slots so
 consolidation can fill them later without a migration.
 
-## Naming: `label` vs `name` vs `when_to_use`
+## Naming: `label` vs `name` vs `description`
 
-A skill's unique identifier is its **`label`** (snake_case slug, e.g.
-`csv_summary`). In cognitive psychology, a *label* is the declarative handle by
+A skill's unique identifier is its **`label`** (hyphen-case slug, e.g.
+`csv-summary`). In cognitive psychology, a *label* is the declarative handle by
 which a procedural memory is addressed in working memory — the verbal token the
 executive holds when deciding to invoke a stored procedure. It is deliberately
 distinct from:
 
 - **`name`** — the human-readable display ("CSV Summary"),
-- **`when_to_use`** — the retrieval cue describing the matching context. This
+- **`description`** — the retrieval cue describing the matching context. This
   is the most important field: it's the one line the LLM sees in every prompt.
 
 ## Creation: `/skill save` and `_SkillDraft`
@@ -76,10 +75,9 @@ LLM's instructions:
 
 | Field | Required | Guidance baked into the schema |
 |---|---|---|
-| `label` | yes | snake_case, 2-4 words, captures the essence |
+| `label` | yes | hyphen-case, 2-4 words, captures the essence |
 | `name` | yes | Human-readable display name |
-| `description` | no | One sentence on what the skill does |
-| `when_to_use` | yes | One sentence on when it applies — "what the classifier shows to the LLM next time" |
+| `description` | yes | One sentence on when it applies — "what the classifier shows to the LLM next time" |
 | `declarative_md` | yes | Numbered steps, specific decisions, written as instructions for a future agent — not a retrospective |
 
 The result is saved via `SkillStore.save()`, with `make_unique_label()` avoiding
@@ -92,7 +90,7 @@ v2/v3 feature — v1 deliberately uses manual curation.
 On every turn, the prompt builder (`_build_procedural_memory_section` in
 `anton/core/llm/prompt_builder.py`) injects a compact
 `## Procedural memory (skills available)` section: one line per skill —
-`` `label` — when_to_use `` — built from `SkillStore.list_summaries()` without
+`` `label` — description `` — built from `SkillStore.list_summaries()` without
 loading any declarative content (~50 tokens per skill). The full procedures
 stay on disk.
 
@@ -123,9 +121,9 @@ increments `csv_summary`.
 | Method | Purpose |
 |---|---|
 | `list_all()` | Every loadable skill, sorted by label |
-| `list_summaries()` | Lightweight listing — label, name, when_to_use only. Used by the prompt builder |
+| `list_summaries()` | Lightweight listing — label, name, description only. Used by the prompt builder |
 | `load(label)` | Read one skill. Returns None if absent or malformed |
-| `save(skill)` | Write the directory: `meta.json`, `declarative.md`, `stats.json`. Never wipes accumulated counters |
+| `save(skill)` | Write the directory: `SKILL.md`, `stats.json`. Never wipes accumulated counters |
 | `delete(label)` | Remove a skill directory |
 | `increment_recommended(label, *, stage)` | Atomic-ish bump of the per-stage `recommended` counter (called by `recall_skill`) |
 | `closest_match(bad_label, *, cutoff=0.6)` | Difflib fuzzy match for typo recovery |
diff --git a/tests/test_artifacts.py b/tests/test_artifacts.py
index 9753c25a..cdf478fd 100644
--- a/tests/test_artifacts.py
+++ b/tests/test_artifacts.py
@@ -264,6 +264,62 @@ def test_rescan_excludes_metadata_and_readme(store: ArtifactStore):
     assert paths == {"real-file.md"}
 
 
+# ─── Reconcile-on-read (ENG-372) ────────────────────────────────────────────
+# Scratchpad code writes artifact files straight into the folder via plain
+# open(), bypassing the store. open()/list() must reconcile files[] against
+# disk so the agent never sees file_count 0 for a fully-written artifact.
+
+
+def test_open_reflects_scratchpad_written_files(store: ArtifactStore):
+    artifact = store.create(name="Dash", description="x", type="html-app")
+    assert artifact.files == []  # create starts empty
+    folder = store.folder_for(artifact.slug)
+    (folder / "dashboard.html").write_text("<html>" + "x" * 1000 + "</html>")
+    opened = store.open(artifact.slug)
+    assert [f.path for f in opened.files] == ["dashboard.html"]
+    assert opened.files[0].bytes > 1000
+
+
+def test_list_reflects_scratchpad_written_files(store: ArtifactStore):
+    artifact = store.create(name="Dash", description="x", type="html-app")
+    (store.folder_for(artifact.slug) / "dashboard.html").write_text("<html></html>")
+    match = next(a for a in store.list() if a.slug == artifact.slug)
+    assert {f.path for f in match.files} == {"dashboard.html"}
+
+
+def test_reconcile_excludes_published_json(store: ArtifactStore):
+    """.published.json is publish-state housekeeping, not artifact content."""
+    artifact = store.create(name="Dash", description="x", type="html-app")
+    folder = store.folder_for(artifact.slug)
+    (folder / "dashboard.html").write_text("<html></html>")
+    (folder / ".published.json").write_text("{}")
+    opened = store.open(artifact.slug)
+    assert {f.path for f in opened.files} == {"dashboard.html"}
+
+
+def test_reconcile_on_read_is_idempotent(store: ArtifactStore):
+    """A read with no on-disk change must not re-save or bump updatedAt."""
+    artifact = store.create(name="Dash", description="x", type="html-app")
+    (store.folder_for(artifact.slug) / "dashboard.html").write_text("<html></html>")
+    first = store.open(artifact.slug)   # reconciles + persists
+    second = store.open(artifact.slug)  # no disk change → no re-save
+    assert {f.path for f in second.files} == {"dashboard.html"}
+    assert second.updatedAt == first.updatedAt
+
+
+def test_reconcile_re_saves_and_persists_when_files_change(store: ArtifactStore):
+    """A changed on-disk file set must reconcile AND persist to metadata.json."""
+    artifact = store.create(name="Dash", description="x", type="html-app")
+    folder = store.folder_for(artifact.slug)
+    (folder / "a.html").write_text("<html></html>")
+    assert {f.path for f in store.open(artifact.slug).files} == {"a.html"}
+    # A second file lands on disk → next read reconciles and persists it.
+    (folder / "b.html").write_text("<html></html>")
+    assert {f.path for f in store.open(artifact.slug).files} == {"a.html", "b.html"}
+    on_disk = json.loads(store.metadata_path(artifact.slug).read_text())
+    assert {f["path"] for f in on_disk["files"]} == {"a.html", "b.html"}
+
+
 # ─── README rendering ───────────────────────────────────────────────────────
 
 
diff --git a/tests/test_prompt_builder_skills.py b/tests/test_prompt_builder_skills.py
index 0dbc6009..433868a6 100644
--- a/tests/test_prompt_builder_skills.py
+++ b/tests/test_prompt_builder_skills.py
@@ -18,7 +18,7 @@ def empty_store(tmp_path: Path) -> SkillStore:
 @pytest.fixture()
 def populated_store(tmp_path: Path) -> SkillStore:
     s = SkillStore(root=tmp_path / "skills_populated")
-    for label, when in [
+    for label, desc in [
         ("csv_summary", "User asks to explore or summarize a CSV file."),
         ("web_scraping", "User asks to scrape data from a website."),
         ("api_fetcher", "User asks to fetch data from a JSON API."),
@@ -27,8 +27,7 @@ def populated_store(tmp_path: Path) -> SkillStore:
             Skill(
                 label=label,
                 name=label.replace("_", " ").title(),
-                description="",
-                when_to_use=when,
+                description=desc,
                 declarative_md="step 1\nstep 2",
                 created_at="2026-04-10T12:00:00+00:00",
                 provenance="manual",
@@ -64,10 +63,10 @@ def test_populated_store_renders_section(self, populated_store: SkillStore):
         prompt = _build_prompt(builder, skill_store=populated_store)
         assert "## Procedural memory" in prompt
         # All labels are listed
-        assert "`csv_summary`" in prompt
-        assert "`web_scraping`" in prompt
-        assert "`api_fetcher`" in prompt
-        # And their when_to_use
+        assert "`csv-summary`" in prompt
+        assert "`web-scraping`" in prompt
+        assert "`api-fetcher`" in prompt
+        # And their description
         assert "explore or summarize a CSV" in prompt
         assert "scrape data from a website" in prompt
         assert "fetch data from a JSON API" in prompt
@@ -113,14 +112,13 @@ def test_section_is_compact(self, populated_store: SkillStore):
         # Three skills, header + intro + bullets — keep it under ~600 chars
         assert len(section) < 1000
 
-    def test_handles_skill_without_when_to_use(self, tmp_path: Path):
+    def test_handles_skill_without_description(self, tmp_path: Path):
         s = SkillStore(root=tmp_path / "skills_partial")
         s.save(
             Skill(
                 label="bare",
                 name="Bare",
                 description="",
-                when_to_use="",
                 declarative_md="x",
                 created_at="2026-04-10T12:00:00+00:00",
                 provenance="manual",
@@ -129,7 +127,7 @@ def test_handles_skill_without_when_to_use(self, tmp_path: Path):
         builder = ChatSystemPromptBuilder()
         prompt = _build_prompt(builder, skill_store=s)
         assert "`bare`" in prompt
-        # No crash, even with no when_to_use
+        # No crash, even with no description
 
     def test_skip_section_when_store_raises(self, tmp_path: Path, monkeypatch):
         """If the store blows up at read time, the section is omitted gracefully."""
diff --git a/tests/test_recall_skill.py b/tests/test_recall_skill.py
index 2f53d693..15c5db4e 100644
--- a/tests/test_recall_skill.py
+++ b/tests/test_recall_skill.py
@@ -27,7 +27,6 @@ def store(tmp_path: Path) -> SkillStore:
             label="csv_summary",
             name="CSV Summary",
             description="Load a CSV, infer schema, compute summary stats.",
-            when_to_use="User asks to explore, summarize, or describe a CSV file.",
             declarative_md="1. Load the CSV.\n2. Infer types.\n3. Print summary.",
             created_at="2026-04-10T12:00:00+00:00",
             provenance="manual",
@@ -38,7 +37,6 @@ def store(tmp_path: Path) -> SkillStore:
             label="web_scraping",
             name="Web Scraping",
             description="Fetch and parse HTML to extract structured data.",
-            when_to_use="User asks to scrape or extract data from a webpage.",
             declarative_md="1. Fetch the URL.\n2. Parse with BeautifulSoup.\n3. Select elements.",
             created_at="2026-04-10T12:00:00+00:00",
             provenance="manual",
@@ -49,7 +47,6 @@ def store(tmp_path: Path) -> SkillStore:
             label="api_fetcher",
             name="API Fetcher",
             description="Call a REST API and normalize the response.",
-            when_to_use="User asks to fetch data from a JSON API.",
             declarative_md="1. Identify auth.\n2. Call endpoint.\n3. Normalize.",
             created_at="2026-04-10T12:00:00+00:00",
             provenance="manual",
@@ -139,7 +136,7 @@ async def test_typo_returns_closest_match(self, store: SkillStore):
         session = _session_with(store)
         result = await handle_recall_skill(session, {"label": "csv_sumary"})
         assert "⚠" in result
-        assert "csv_summary" in result
+        assert "csv-summary" in result
         # The full procedure is still included after the warning
         assert "Load the CSV" in result
 
@@ -154,8 +151,8 @@ async def test_typo_credits_resolved_label_not_input(self, store: SkillStore):
     @pytest.mark.asyncio
     async def test_dash_to_underscore_recovered(self, store: SkillStore):
         session = _session_with(store)
-        result = await handle_recall_skill(session, {"label": "web-scraping"})
-        assert "web_scraping" in result
+        result = await handle_recall_skill(session, {"label": "web__scraping"})
+        assert "web-scraping" in result
         # Could match exactly via slugify, in which case there's no warning,
         # or via fuzzy match. Either way the procedure should be returned.
         assert "BeautifulSoup" in result
@@ -175,9 +172,9 @@ async def test_unrelated_returns_no_match_with_listing(
         result = await handle_recall_skill(session, {"label": "xyzzy_quark"})
         assert "NO MATCH" in result
         # Should mention all available labels
-        assert "csv_summary" in result
-        assert "web_scraping" in result
-        assert "api_fetcher" in result
+        assert "csv-summary" in result
+        assert "web-scraping" in result
+        assert "api-fetcher" in result
 
     @pytest.mark.asyncio
     async def test_unrelated_does_not_increment_counters(
@@ -185,7 +182,7 @@ async def test_unrelated_does_not_increment_counters(
     ):
         session = _session_with(store)
         await handle_recall_skill(session, {"label": "xyzzy_quark"})
-        for label in ("csv_summary", "web_scraping", "api_fetcher"):
+        for label in ("csv-summary", "web-scraping", "api-fetcher"):
             loaded = store.load(label)
             assert loaded is not None
             assert loaded.stats.stage_1.recommended == 0
diff --git a/tests/test_session_skills_init.py b/tests/test_session_skills_init.py
index e542a61f..c6806b1b 100644
--- a/tests/test_session_skills_init.py
+++ b/tests/test_session_skills_init.py
@@ -29,8 +29,7 @@ def store_with_one_skill(tmp_path: Path) -> SkillStore:
         Skill(
             label="csv_summary",
             name="CSV Summary",
-            description="Load a CSV, infer schema, compute stats.",
-            when_to_use="User asks to explore or summarize a CSV file.",
+            description="User asks to explore or summarize a CSV file.",
             declarative_md="1. Load CSV\n2. Describe\n3. Plot",
             created_at="2026-04-10T12:00:00+00:00",
             provenance="manual",
@@ -73,7 +72,7 @@ def test_section_appears_when_store_passed(
             skill_store=store_with_one_skill,
         )
         assert "## Procedural memory" in prompt
-        assert "csv_summary" in prompt
+        assert "csv-summary" in prompt
 
     def test_section_omitted_when_no_store(self):
         builder = ChatSystemPromptBuilder()
diff --git a/tests/test_skill_commands.py b/tests/test_skill_commands.py
index ee38d86f..bbb87bf3 100644
--- a/tests/test_skill_commands.py
+++ b/tests/test_skill_commands.py
@@ -72,8 +72,7 @@ def _draft(
     *,
     label: str = "csv_summary",
     name: str = "CSV Summary",
-    description: str = "",
-    when_to_use: str = "When summarizing CSV files.",
+    description: str = "When summarizing CSV files.",
     declarative_md: str = "1. Load.\n2. Describe.",
 ) -> _SkillDraft:
     """Convenience constructor for test drafts."""
@@ -81,7 +80,6 @@ def _draft(
         label=label,
         name=name,
         description=description,
-        when_to_use=when_to_use,
         declarative_md=declarative_md,
     )
 
@@ -177,8 +175,7 @@ async def test_happy_path(self, console, store):
             draft=_draft(
                 label="csv_summary",
                 name="CSV Summary",
-                description="Load and summarize a CSV.",
-                when_to_use="User asks to summarize a CSV file.",
+                description="User asks to summarize a CSV file.",
                 declarative_md="1. Load.\n2. Describe.\n3. Plot.",
             ),
             cells=[_fake_cell("import pandas as pd; df = pd.read_csv('x.csv')")],
@@ -190,7 +187,6 @@ async def test_happy_path(self, console, store):
         loaded = store.load("csv_summary")
         assert loaded is not None
         assert loaded.name == "CSV Summary"
-        assert loaded.when_to_use == "User asks to summarize a CSV file."
         assert "Load." in loaded.declarative_md
         assert loaded.provenance == "manual"
         assert loaded.created_at  # ISO timestamp set
@@ -213,10 +209,9 @@ async def test_label_collision_appends_number(self, console, store):
         # Pre-existing skill with the label the LLM will return
         store.save(
             Skill(
-                label="csv_summary",
+                label="csv-summary",
                 name="Existing",
                 description="",
-                when_to_use="",
                 declarative_md="prior",
                 created_at="2026-04-09T00:00:00+00:00",
                 provenance="manual",
@@ -226,8 +221,7 @@ async def test_label_collision_appends_number(self, console, store):
             draft=_draft(
                 label="csv_summary",
                 name="New CSV Summary",
-                description="",
-                when_to_use="User asks for CSV stats.",
+                description="User asks for CSV stats.",
                 declarative_md="step 1",
             ),
             cells=[_fake_cell("x")],
@@ -237,11 +231,11 @@ async def test_label_collision_appends_number(self, console, store):
         await handle_skill_save(console, session, store=store)
 
         # Original is unchanged
-        original = store.load("csv_summary")
+        original = store.load("csv-summary")
         assert original is not None
         assert original.declarative_md == "prior"
         # New one was saved with a unique label
-        new = store.load("csv_summary_2")
+        new = store.load("csv-summary-2")
         assert new is not None
         assert new.declarative_md == "step 1"
 
@@ -251,7 +245,7 @@ async def test_name_hint_is_passed_to_llm(self, console, store):
             draft=_draft(
                 label="data_loader",
                 name="Data Loader",
-                when_to_use="User asks to load data.",
+                description="User asks to load data.",
             ),
             cells=[_fake_cell("x")],
             history=[{"role": "user", "content": "go"}],
@@ -272,7 +266,7 @@ async def test_empty_procedure_refuses_save(self, console, store):
             draft=_draft(
                 label="empty",
                 name="Empty",
-                when_to_use="x",
+                description="x",
                 declarative_md="",  # blank — refuse
             ),
             cells=[_fake_cell("x")],
@@ -338,8 +332,7 @@ def test_list_with_skills(self, console, store):
             Skill(
                 label="csv_summary",
                 name="CSV Summary",
-                description="",
-                when_to_use="When the user asks about a CSV",
+                description="When the user asks about a CSV",
                 declarative_md="step",
                 created_at="2026-04-10T00:00:00+00:00",
                 provenance="manual",
@@ -348,7 +341,7 @@ def test_list_with_skills(self, console, store):
         handle_skills_list(console, store=store)
         # Sanity-check that the rendered output mentions the label
         out = console.export_text()
-        assert "csv_summary" in out
+        assert "CSV Summary" in out
 
     def test_show_existing(self, console, store):
         store.save(
@@ -356,7 +349,6 @@ def test_show_existing(self, console, store):
                 label="csv_summary",
                 name="CSV Summary",
                 description="A CSV utility.",
-                when_to_use="when needed",
                 declarative_md="1. Load\n2. Describe",
                 created_at="2026-04-10T00:00:00+00:00",
                 provenance="manual",
@@ -370,10 +362,9 @@ def test_show_existing(self, console, store):
     def test_show_unknown_suggests_closest(self, console, store):
         store.save(
             Skill(
-                label="csv_summary",
+                label="csv-summary",
                 name="CSV",
                 description="",
-                when_to_use="",
                 declarative_md="x",
                 created_at="2026-04-10T00:00:00+00:00",
                 provenance="manual",
@@ -381,7 +372,7 @@ def test_show_unknown_suggests_closest(self, console, store):
         )
         handle_skill_show(console, "csv_sumary", store=store)  # typo
         out = console.export_text()
-        assert "csv_summary" in out
+        assert "csv-summary" in out
 
     def test_show_no_args(self, console, store):
         handle_skill_show(console, "", store=store)
@@ -394,7 +385,6 @@ def test_remove_existing(self, console, store):
                 label="zap",
                 name="Zap",
                 description="",
-                when_to_use="",
                 declarative_md="x",
                 created_at="2026-04-10T00:00:00+00:00",
                 provenance="manual",
diff --git a/tests/test_skills_e2e.py b/tests/test_skills_e2e.py
index f4bfb4a0..9be0eba3 100644
--- a/tests/test_skills_e2e.py
+++ b/tests/test_skills_e2e.py
@@ -94,8 +94,7 @@ async def test_full_skills_loop(console, store_root):
     draft = _SkillDraft(
         label="csv_summary",
         name="CSV Summary",
-        description="Load a CSV with pandas, print shape/describe/dtypes, plot a histogram.",
-        when_to_use="User asks to explore, summarize, or describe a CSV file.",
+        description="User asks to explore, summarize, or describe a CSV file.",
         declarative_md=(
             "1. Use `pandas.read_csv()` to load the file.\n"
             "2. Print `df.shape` and `df.dtypes`.\n"
@@ -112,7 +111,7 @@ async def test_full_skills_loop(console, store_root):
     skills = store.list_all()
     assert len(skills) == 1
     saved = skills[0]
-    assert saved.label == "csv_summary"
+    assert saved.label == "csv-summary"
     assert saved.name == "CSV Summary"
     assert "pandas.read_csv" in saved.declarative_md
     assert saved.stats.stage_1.recommended == 0  # no recalls yet
@@ -129,7 +128,7 @@ async def test_full_skills_loop(console, store_root):
         skill_store=fresh_store,
     )
     assert "## Procedural memory" in prompt
-    assert "`csv_summary`" in prompt
+    assert "`csv-summary`" in prompt
     assert "explore, summarize, or describe a CSV" in prompt
 
     # ── Step 3: LLM "decides" to recall the skill via the tool registry ─
@@ -138,7 +137,7 @@ async def test_full_skills_loop(console, store_root):
     fresh_session = SimpleNamespace(_skill_store=fresh_store)
 
     result = await registry.dispatch_tool(
-        fresh_session, "recall_skill", {"label": "csv_summary"}
+        fresh_session, "recall_skill", {"label": "csv-summary"}
     )
 
     assert "CSV Summary" in result
@@ -146,7 +145,7 @@ async def test_full_skills_loop(console, store_root):
     assert "describe" in result
 
     # Counter incremented to 1
-    after_recall_1 = fresh_store.load("csv_summary")
+    after_recall_1 = fresh_store.load("csv-summary")
     assert after_recall_1 is not None
     assert after_recall_1.stats.stage_1.recommended == 1
     assert after_recall_1.stats.total_recalls == 1
@@ -157,31 +156,25 @@ async def test_full_skills_loop(console, store_root):
         fresh_session, "recall_skill", {"label": "csv_sumary"}  # missing 'm'
     )
     assert "⚠" in typo_result
-    assert "csv_summary" in typo_result
+    assert "csv-summary" in typo_result
     assert "pandas.read_csv" in typo_result  # full procedure still returned
 
     # Counter is now 2 (typo credited to the resolved label)
-    after_recall_2 = fresh_store.load("csv_summary")
+    after_recall_2 = fresh_store.load("csv-summary")
     assert after_recall_2 is not None
     assert after_recall_2.stats.stage_1.recommended == 2
     assert after_recall_2.stats.total_recalls == 2
 
     # ── Step 5: Disk verification ───────────────────────────────────────
-    skill_dir = store_root / "csv_summary"
+    skill_dir = store_root / "csv-summary"
     assert skill_dir.is_dir()
-    assert (skill_dir / "meta.json").is_file()
-    assert (skill_dir / "declarative.md").is_file()
+    assert (skill_dir / "SKILL.md").is_file()
     assert (skill_dir / "stats.json").is_file()
 
+    skill_md_text = (skill_dir / "SKILL.md").read_text()
+    assert "name: csv-summary" in skill_md_text
+    assert "pandas.read_csv" in skill_md_text
+
     stats_on_disk = json.loads((skill_dir / "stats.json").read_text())
     assert stats_on_disk["total_recalls"] == 2
     assert stats_on_disk["stage_1"]["recommended"] == 2
-
-    meta_on_disk = json.loads((skill_dir / "meta.json").read_text())
-    assert meta_on_disk["label"] == "csv_summary"
-    assert meta_on_disk["stage_1_present"] is True
-    assert meta_on_disk["stage_2_present"] is False
-    assert meta_on_disk["stage_3_present"] is False
-
-    declarative_on_disk = (skill_dir / "declarative.md").read_text()
-    assert "pandas.read_csv" in declarative_on_disk
diff --git a/tests/test_skills_store.py b/tests/test_skills_store.py
index f843ce1f..4de11a55 100644
--- a/tests/test_skills_store.py
+++ b/tests/test_skills_store.py
@@ -9,9 +9,7 @@
 
 from anton.core.memory.skills import (
     Skill,
-    SkillStats,
     SkillStore,
-    StageStats,
     make_unique_label,
     slugify,
 )
@@ -32,12 +30,11 @@ def store(store_root: Path) -> SkillStore:
     return SkillStore(root=store_root)
 
 
-def _make_skill(label: str = "csv_summary", **overrides) -> Skill:
+def _make_skill(label: str = "csv-summary", **overrides) -> Skill:
     base = dict(
         label=label,
         name="CSV Summary",
         description="Load a CSV, infer schema, compute summary stats.",
-        when_to_use="User asks to explore, summarize, or describe a CSV file.",
         declarative_md="1. Load the CSV.\n2. Infer types.\n3. Print summary.\n",
         created_at="2026-04-10T12:00:00+00:00",
         provenance="manual",
@@ -53,39 +50,39 @@ def _make_skill(label: str = "csv_summary", **overrides) -> Skill:
 
 class TestSlugify:
     def test_simple_lowercase(self):
-        assert slugify("CSV Summary") == "csv_summary"
+        assert slugify("CSV Summary") == "csv-summary"
 
     def test_strips_special_chars(self):
-        assert slugify("Web Scraping (v2)!") == "web_scraping_v2"
+        assert slugify("Web Scraping (v2)!") == "web-scraping-v2"
 
-    def test_collapses_underscores(self):
-        assert slugify("foo___bar") == "foo_bar"
+    def test_collapses_hyphens(self):
+        assert slugify("foo---bar") == "foo-bar"
 
     def test_trims_leading_trailing(self):
-        assert slugify("__hello__") == "hello"
+        assert slugify("--hello--") == "hello"
 
     def test_empty_input_falls_back(self):
         assert slugify("") == "skill"
         assert slugify("   ") == "skill"
         assert slugify("!@#$") == "skill"
 
-    def test_dash_to_underscore(self):
-        assert slugify("api-data-fetcher") == "api_data_fetcher"
+    def test_hyphen_preserved(self):
+        assert slugify("api-data-fetcher") == "api-data-fetcher"
 
 
 class TestMakeUniqueLabel:
     def test_returns_base_when_unique(self, store: SkillStore):
-        assert make_unique_label("Brand New", store) == "brand_new"
+        assert make_unique_label("Brand New", store) == "brand-new"
 
     def test_appends_number_on_collision(self, store: SkillStore):
-        store.save(_make_skill(label="csv_summary"))
-        assert make_unique_label("CSV Summary", store) == "csv_summary_2"
+        store.save(_make_skill(label="csv-summary"))
+        assert make_unique_label("CSV Summary", store) == "csv-summary-2"
 
     def test_chains_numbers(self, store: SkillStore):
-        store.save(_make_skill(label="csv_summary"))
-        store.save(_make_skill(label="csv_summary_2"))
-        store.save(_make_skill(label="csv_summary_3"))
-        assert make_unique_label("CSV Summary", store) == "csv_summary_4"
+        store.save(_make_skill(label="csv-summary"))
+        store.save(_make_skill(label="csv-summary-2"))
+        store.save(_make_skill(label="csv-summary-3"))
+        assert make_unique_label("CSV Summary", store) == "csv-summary-4"
 
 
 # ─────────────────────────────────────────────────────────────────────────────
@@ -99,32 +96,30 @@ def test_save_creates_directory_with_required_files(
     ):
         skill = _make_skill()
         path = store.save(skill)
-        assert path == store_root / "csv_summary"
-        assert (path / "meta.json").is_file()
-        assert (path / "declarative.md").is_file()
+        assert path == store_root / "csv-summary"
+        assert (path / "SKILL.md").is_file()
         assert (path / "stats.json").is_file()
 
     def test_load_after_save_round_trip(self, store: SkillStore):
         original = _make_skill()
         store.save(original)
-        loaded = store.load("csv_summary")
+        loaded = store.load("csv-summary")
         assert loaded is not None
         assert loaded.label == original.label
         assert loaded.name == original.name
         assert loaded.description == original.description
-        assert loaded.when_to_use == original.when_to_use
         assert loaded.declarative_md == original.declarative_md
         assert loaded.provenance == "manual"
 
     def test_load_unknown_returns_none(self, store: SkillStore):
-        assert store.load("does_not_exist") is None
+        assert store.load("does-not-exist") is None
 
-    def test_load_with_corrupt_meta_returns_none(
+    def test_load_with_corrupt_skill_md_returns_none(
         self, store: SkillStore, store_root: Path
     ):
         store.save(_make_skill())
-        (store_root / "csv_summary" / "meta.json").write_text("not json{")
-        assert store.load("csv_summary") is None
+        (store_root / "csv-summary" / "SKILL.md").write_text("not yaml: [\nbad")
+        assert store.load("csv-summary") is None
 
     def test_save_does_not_wipe_existing_stats(
         self, store: SkillStore, store_root: Path
@@ -132,11 +127,11 @@ def test_save_does_not_wipe_existing_stats(
         # First save initializes stats.json with zeroes.
         store.save(_make_skill())
         # Simulate accumulated counters.
-        store.increment_recommended("csv_summary", stage=1)
-        store.increment_recommended("csv_summary", stage=1)
+        store.increment_recommended("csv-summary", stage=1)
+        store.increment_recommended("csv-summary", stage=1)
         # Saving again (e.g., editing the procedure) must NOT zero them.
         store.save(_make_skill(declarative_md="updated procedure"))
-        loaded = store.load("csv_summary")
+        loaded = store.load("csv-summary")
         assert loaded is not None
         assert loaded.stats.stage_1.recommended == 2
         assert loaded.declarative_md == "updated procedure"
@@ -165,7 +160,7 @@ def test_list_summaries_skips_malformed(
         self, store: SkillStore, store_root: Path
     ):
         store.save(_make_skill(label="good"))
-        # Create a directory with no meta.json — should be skipped.
+        # Create a directory with no SKILL.md — should be skipped.
         (store_root / "broken").mkdir()
         summaries = store.list_summaries()
         assert [s["label"] for s in summaries] == ["good"]
@@ -175,16 +170,16 @@ def test_list_summaries_lightweight_shape(self, store: SkillStore):
         summaries = store.list_summaries()
         assert len(summaries) == 1
         assert summaries[0] == {
-            "label": "csv_summary",
+            "label": "csv-summary",
             "name": "CSV Summary",
-            "when_to_use": "User asks to explore, summarize, or describe a CSV file.",
+            "description": "Load a CSV, infer schema, compute summary stats.",
         }
 
     def test_delete_removes_directory(self, store: SkillStore, store_root: Path):
         store.save(_make_skill())
-        assert (store_root / "csv_summary").is_dir()
-        assert store.delete("csv_summary") is True
-        assert not (store_root / "csv_summary").exists()
+        assert (store_root / "csv-summary").is_dir()
+        assert store.delete("csv-summary") is True
+        assert not (store_root / "csv-summary").exists()
 
     def test_delete_unknown_returns_false(self, store: SkillStore):
         assert store.delete("nope") is False
@@ -198,12 +193,12 @@ def test_delete_unknown_returns_false(self, store: SkillStore):
 class TestStatsIncrement:
     def test_increment_unknown_skill_is_noop(self, store: SkillStore):
         # Should not raise.
-        store.increment_recommended("not_a_skill", stage=1)
+        store.increment_recommended("not-a-skill", stage=1)
 
     def test_increment_stage_1(self, store: SkillStore):
         store.save(_make_skill())
-        store.increment_recommended("csv_summary", stage=1)
-        loaded = store.load("csv_summary")
+        store.increment_recommended("csv-summary", stage=1)
+        loaded = store.load("csv-summary")
         assert loaded is not None
         assert loaded.stats.stage_1.recommended == 1
         assert loaded.stats.stage_1.last_used  # set to a timestamp
@@ -212,18 +207,18 @@ def test_increment_stage_1(self, store: SkillStore):
     def test_increment_multiple_times(self, store: SkillStore):
         store.save(_make_skill())
         for _ in range(5):
-            store.increment_recommended("csv_summary", stage=1)
-        loaded = store.load("csv_summary")
+            store.increment_recommended("csv-summary", stage=1)
+        loaded = store.load("csv-summary")
         assert loaded is not None
         assert loaded.stats.stage_1.recommended == 5
         assert loaded.stats.total_recalls == 5
 
     def test_increment_per_stage_independent(self, store: SkillStore):
         store.save(_make_skill())
-        store.increment_recommended("csv_summary", stage=1)
-        store.increment_recommended("csv_summary", stage=1)
-        store.increment_recommended("csv_summary", stage=2)
-        loaded = store.load("csv_summary")
+        store.increment_recommended("csv-summary", stage=1)
+        store.increment_recommended("csv-summary", stage=1)
+        store.increment_recommended("csv-summary", stage=2)
+        loaded = store.load("csv-summary")
         assert loaded is not None
         assert loaded.stats.stage_1.recommended == 2
         assert loaded.stats.stage_2.recommended == 1
@@ -233,7 +228,7 @@ def test_increment_per_stage_independent(self, store: SkillStore):
     def test_invalid_stage_raises(self, store: SkillStore):
         store.save(_make_skill())
         with pytest.raises(ValueError):
-            store.increment_recommended("csv_summary", stage=4)
+            store.increment_recommended("csv-summary", stage=4)
 
 
 # ─────────────────────────────────────────────────────────────────────────────
@@ -246,28 +241,28 @@ def test_empty_store_returns_none(self, store: SkillStore):
         assert store.closest_match("anything") is None
 
     def test_exact_match(self, store: SkillStore):
-        store.save(_make_skill(label="csv_summary"))
-        assert store.closest_match("csv_summary") == "csv_summary"
+        store.save(_make_skill(label="csv-summary"))
+        assert store.closest_match("csv-summary") == "csv-summary"
 
     def test_typo_one_char(self, store: SkillStore):
-        store.save(_make_skill(label="csv_summary"))
-        assert store.closest_match("csv_sumary") == "csv_summary"
+        store.save(_make_skill(label="csv-summary"))
+        assert store.closest_match("csv-sumary") == "csv-summary"
 
-    def test_dash_vs_underscore(self, store: SkillStore):
-        store.save(_make_skill(label="web_scraping"))
-        assert store.closest_match("web-scraping") == "web_scraping"
+    def test_underscore_normalized_to_hyphen(self, store: SkillStore):
+        store.save(_make_skill(label="web-scraping"))
+        assert store.closest_match("web_scraping") == "web-scraping"
 
     def test_completely_unrelated_returns_none(self, store: SkillStore):
-        store.save(_make_skill(label="csv_summary"))
-        assert store.closest_match("xyzzy_quark") is None
+        store.save(_make_skill(label="csv-summary"))
+        assert store.closest_match("xyzzy-quark") is None
 
     def test_picks_closer_of_two_candidates(self, store: SkillStore):
-        store.save(_make_skill(label="csv_summary"))
-        store.save(_make_skill(label="api_fetcher"))
-        # Closer to csv_summary
-        assert store.closest_match("csv_summery") == "csv_summary"
-        # Closer to api_fetcher
-        assert store.closest_match("api_fecher") == "api_fetcher"
+        store.save(_make_skill(label="csv-summary"))
+        store.save(_make_skill(label="api-fetcher"))
+        # Closer to csv-summary
+        assert store.closest_match("csv-summery") == "csv-summary"
+        # Closer to api-fetcher
+        assert store.closest_match("api-fecher") == "api-fetcher"
 
 
 # ─────────────────────────────────────────────────────────────────────────────
@@ -276,25 +271,17 @@ def test_picks_closer_of_two_candidates(self, store: SkillStore):
 
 
 class TestDiskFormat:
-    def test_meta_json_has_expected_keys(self, store: SkillStore, store_root: Path):
+    def test_skill_md_has_expected_fields(self, store: SkillStore, store_root: Path):
         store.save(_make_skill())
-        meta = json.loads((store_root / "csv_summary" / "meta.json").read_text())
-        assert set(meta.keys()) >= {
-            "label",
-            "name",
-            "description",
-            "when_to_use",
-            "created_at",
-            "provenance",
-            "stage_1_present",
-            "stage_2_present",
-            "stage_3_present",
-        }
-        assert meta["label"] == "csv_summary"
+        text = (store_root / "csv-summary" / "SKILL.md").read_text()
+        assert text.startswith("---\n")
+        assert "name: csv-summary" in text
+        assert "description:" in text
+        assert "display_name:" in text
 
     def test_stats_json_initial_shape(self, store: SkillStore, store_root: Path):
         store.save(_make_skill())
-        stats = json.loads((store_root / "csv_summary" / "stats.json").read_text())
+        stats = json.loads((store_root / "csv-summary" / "stats.json").read_text())
         assert stats["total_recalls"] == 0
         for stage_key in ("stage_1", "stage_2", "stage_3"):
             assert stage_key in stats