From 54ccc1695677d0aebf9e1343ffc9e3927dcd147e Mon Sep 17 00:00:00 2001
From: andrew <elkin.andr@gmail.com>
Date: Tue, 16 Jun 2026 15:17:37 +0300
Subject: [PATCH 01/19] skill md tool

---
 anton/core/memory/skill_md.py | 199 ++++++++++++++++++++++++++++++++++
 uv.lock                       |   2 +-
 2 files changed, 200 insertions(+), 1 deletion(-)
 create mode 100644 anton/core/memory/skill_md.py

diff --git a/anton/core/memory/skill_md.py b/anton/core/memory/skill_md.py
new file mode 100644
index 00000000..6fb0b088
--- /dev/null
+++ b/anton/core/memory/skill_md.py
@@ -0,0 +1,199 @@
+"""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
+      when_to_use: ...
+      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
+SkillFrontmatter exist for write/creation paths only and must be called
+explicitly via SkillFrontmatter.model_validate().
+
+Unknown top-level YAML keys are folded into `metadata` automatically.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+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) ──────────────
+
+_NAME_RE = re.compile(r"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$")
+_NAME_MAX = 64
+_DESC_MAX = 1024
+_COMPAT_MAX = 500
+
+# canonical YAML keys defined by the spec
+_SPEC_KEYS = {"name", "description", "license", "compatibility", "metadata", "allowed-tools"}
+
+
+# ─── model ────────────────────────────────────────────────────────────────────
+
+
+class SkillFrontmatter(BaseModel):
+    """In-memory representation of a SKILL.md frontmatter block.
+
+    Validators are active when you call model_validate() (write / creation
+    path).  parse_skill_md() uses model_construct() so validators are skipped.
+    """
+
+    name: 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:
+        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
+
+    @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_md(text: str, folder_name: str = "") -> tuple[SkillFrontmatter | None, str]:
+    """Parse SKILL.md text into (frontmatter, body).
+
+    No field validation is applied — accepts files created by any tool.
+    Unknown top-level YAML keys are merged into metadata.
+    Returns (None, full_text) only on structural failures (missing delimiters,
+    broken YAML, non-mapping root).
+    """
+    lines = text.split("\n")
+    if not lines or lines[0].rstrip() != "---":
+        logger.debug("parse_skill_md: no opening '---' delimiter")
+        return None, text
+
+    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, text
+
+    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, text
+
+    if not isinstance(props, dict):
+        logger.warning("parse_skill_md: frontmatter is not a YAML mapping")
+        return None, text
+
+    # 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
+
+    name = re.sub(_NAME_RE, "", name).replace("--", " - ")[:_NAME_MAX]
+    if name.startswith("-"):
+        name = name[1:]
+
+    fm = SkillFrontmatter.model_construct(
+        name=name,
+        description=str(props.get("description", ""))[:_DESC_MAX],
+        license=props.get("license"),
+        compatibility=props.get("compatibility"),
+        allowed_tools=props.get("allowed-tools"),
+        metadata=meta,
+    )
+    return fm, body
+
+
+# ─── dump ─────────────────────────────────────────────────────────────────────
+
+
+def dump_skill_md(frontmatter: SkillFrontmatter, body: str) -> str:
+    """Serialise frontmatter + body back to SKILL.md text."""
+    data: dict[str, Any] = {
+        "name": frontmatter.name,
+        "description": frontmatter.description,
+    }
+    if frontmatter.license is not None:
+        data["license"] = frontmatter.license
+    if frontmatter.compatibility is not None:
+        data["compatibility"] = frontmatter.compatibility
+    if frontmatter.allowed_tools is not None:
+        data["allowed-tools"] = frontmatter.allowed_tools
+    if frontmatter.metadata:
+        data["metadata"] = dict(frontmatter.metadata)
+
+    yaml_text = yaml.dump(
+        data,
+        default_flow_style=False,
+        allow_unicode=True,
+        sort_keys=False,
+    )
+    return f"---\n{yaml_text}---\n{body}"
+
+
+__all__ = ["SkillFrontmatter", "parse_skill_md", "dump_skill_md"]
diff --git a/uv.lock b/uv.lock
index 002d1055..08c2abc4 100644
--- a/uv.lock
+++ b/uv.lock
@@ -164,7 +164,7 @@ wheels = [
 ]
 
 [[package]]
-name = "anton"
+name = "anton-agent"
 source = { editable = "." }
 dependencies = [
     { name = "aiohttp" },

From 780f7d138804a01b1e00c9b19851c41c8a8da091 Mon Sep 17 00:00:00 2001
From: andrew <elkin.andr@gmail.com>
Date: Tue, 16 Jun 2026 16:53:04 +0300
Subject: [PATCH 02/19] update SkillStore

---
 anton/core/memory/skills.py | 377 +++++++++++++++++++++---------------
 1 file changed, 219 insertions(+), 158 deletions(-)

diff --git a/anton/core/memory/skills.py b/anton/core/memory/skills.py
index 0d0b1a87..1ea3ac59 100644
--- a/anton/core/memory/skills.py
+++ b/anton/core/memory/skills.py
@@ -2,67 +2,38 @@
 
 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.
 """
 
 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.memory.skill_md import SkillFrontmatter, dump_skill_md, parse_skill_md
+
+logger = logging.getLogger(__name__)
 
 _DEFAULT_SKILLS_ROOT = Path("~/.anton/skills").expanduser()
 
@@ -74,18 +45,9 @@
 
 @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
+    last_used: str = ""
     confidence: float = 0.0
 
 
@@ -101,13 +63,8 @@ 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).
     """
 
     label: str
@@ -116,26 +73,12 @@ class Skill:
     when_to_use: str
     declarative_md: str
     created_at: str
-    provenance: str  # "manual" | "consolidator" (future)
+    provenance: str  # "manual" | "consolidator"
     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 +111,126 @@ 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 hyphen-case and moves:
+      chunks.md  → references/chunks.md
+      code/      → scripts/
+
+    Returns the (possibly renamed) directory path.
+    Raises OSError on IO failures.
+    Idempotent: returns 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 = old_label.replace("_", "-")
+
+    # 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
+
+    # Build metadata dict (omit empty values)
+    meta_fields = {
+        "display_name": meta.get("name", ""),
+        "when_to_use": meta.get("when_to_use", ""),
+        "provenance": meta.get("provenance", "manual"),
+        "created_at": meta.get("created_at", ""),
+    }
+    metadata = {k: str(v) for k, v in meta_fields.items() if v}
+
+    fm = SkillFrontmatter.model_construct(
+        name=final_label,
+        description=str(meta.get("description", "")),
+        metadata=metadata,
+    )
+    skill_md_path.write_text(dump_skill_md(fm, declarative), 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 +239,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,36 +256,61 @@ def _skill_dir(self, label: str) -> Path:
     def _ensure_root(self) -> None:
         self.root.mkdir(parents=True, exist_ok=True)
 
-    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():
-            return None
-        try:
-            meta = json.loads(meta_path.read_text(encoding="utf-8"))
-        except (json.JSONDecodeError, OSError):
+    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."""
+        skill_md_path = d / "SKILL.md"
+        if not skill_md_path.is_file():
             return None
         try:
-            declarative = decl_path.read_text(encoding="utf-8")
+            text = skill_md_path.read_text(encoding="utf-8")
         except OSError:
             return None
-        stats = self._load_stats(label)
+        fm, body = parse_skill_md(text, folder_name=d.name)
+        if fm is None:
+            return None
+        label = fm.name or d.name
         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,
+            label=label,
+            name=fm.metadata.get("display_name", label),
+            description=fm.description,
+            when_to_use=fm.metadata.get("when_to_use", ""),
+            declarative_md=body,
+            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 unreadable."""
+        if not self.root.is_dir():
+            return None
+        d = self._find_dir(label)
+        if d is None:
+            return None
+
+        d = check_migrate(d, self.root)
+        if d is None:
+            return None
+
+        return self._skill_from_dir(d)
+
     def _load_stats(self, label: str) -> SkillStats:
         path = self._skill_dir(label) / "stats.json"
         if not path.is_file():
@@ -281,57 +334,75 @@ 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.
-
-        Avoids reading declarative.md for skills the LLM won't recall this turn.
-        """
+        """Lightweight listing for prompt-building — label + when_to_use only."""
         if not self.root.is_dir():
             return []
         out: 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():
+            try:
+                child = check_migrate(child, self.root)
+                if child is None:
+                    continue
+            except OSError:
+                continue
+            skill_md_path = child / "SKILL.md"
+            if not skill_md_path.is_file():
                 continue
             try:
-                meta = json.loads(meta_path.read_text(encoding="utf-8"))
-            except (json.JSONDecodeError, OSError):
+                text = skill_md_path.read_text(encoding="utf-8")
+            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_md(text, folder_name=child.name)
+            if fm is None:
+                continue
+            label = fm.name or child.name
+            out.append({
+                "label": label,
+                "name": fm.metadata.get("display_name", label),
+                "when_to_use": fm.metadata.get("when_to_use", ""),
+            })
         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()
         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,
+            "when_to_use": skill.when_to_use,
+            "provenance": skill.provenance,
+            "created_at": skill.created_at,
+        }.items() if v}
+
+        fm = SkillFrontmatter.model_construct(
+            name=skill.label,
+            description=skill.description,
+            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_md(fm, skill.declarative_md), encoding="utf-8")
+
         stats_path = d / "stats.json"
         if not stats_path.is_file():
             stats_path.write_text(
@@ -351,13 +422,7 @@ 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.
-        """
+        """Bump the per-stage `recommended` counter. Best-effort, no-ops on error."""
         d = self._skill_dir(label)
         if not d.is_dir():
             return
@@ -396,12 +461,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 +477,7 @@ def closest_match(self, bad_label: str, *, cutoff: float = 0.6) -> str | None:
     "SkillStats",
     "SkillStore",
     "StageStats",
+    "check_migrate",
     "make_unique_label",
     "slugify",
 ]

From bf19a9db35d5bad6b519498617d5f6ee04d6e6ed Mon Sep 17 00:00:00 2001
From: andrew <elkin.andr@gmail.com>
Date: Tue, 16 Jun 2026 17:28:19 +0300
Subject: [PATCH 03/19] update tests

---
 tests/test_skill_commands.py |   6 +-
 tests/test_skills_e2e.py     |  30 ++++----
 tests/test_skills_store.py   | 136 ++++++++++++++++-------------------
 3 files changed, 78 insertions(+), 94 deletions(-)

diff --git a/tests/test_skill_commands.py b/tests/test_skill_commands.py
index ee38d86f..7392d0ff 100644
--- a/tests/test_skill_commands.py
+++ b/tests/test_skill_commands.py
@@ -213,7 +213,7 @@ 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="",
@@ -237,11 +237,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"
 
diff --git a/tests/test_skills_e2e.py b/tests/test_skills_e2e.py
index f4bfb4a0..597f5dd1 100644
--- a/tests/test_skills_e2e.py
+++ b/tests/test_skills_e2e.py
@@ -112,7 +112,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 +129,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 +138,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 +146,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 +157,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..cf14bb68 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,7 +30,7 @@ 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",
@@ -53,39 +51,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,15 +97,14 @@ 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
@@ -117,14 +114,14 @@ def test_load_after_save_round_trip(self, store: SkillStore):
         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 +129,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 +162,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 +172,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.",
         }
 
     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 +195,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 +209,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 +230,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 +243,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 +273,18 @@ 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
+        assert "when_to_use:" 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

From 40746bfc0a651998b3335f7b8952ddc72547755e Mon Sep 17 00:00:00 2001
From: andrew <elkin.andr@gmail.com>
Date: Wed, 17 Jun 2026 14:24:52 +0300
Subject: [PATCH 04/19] refactor

---
 anton/core/memory/skills.py                   |  48 ++++----
 .../skill_md.py => tools/skill_format.py}     | 105 ++++++++++--------
 2 files changed, 81 insertions(+), 72 deletions(-)
 rename anton/core/{memory/skill_md.py => tools/skill_format.py} (70%)

diff --git a/anton/core/memory/skills.py b/anton/core/memory/skills.py
index 1ea3ac59..f060b7e4 100644
--- a/anton/core/memory/skills.py
+++ b/anton/core/memory/skills.py
@@ -31,7 +31,7 @@
 from datetime import datetime, timezone
 from pathlib import Path
 
-from anton.core.memory.skill_md import SkillFrontmatter, dump_skill_md, parse_skill_md
+from anton.core.tools.skill_format import AgentSkill, dump_skill, parse_skill_dir
 
 logger = logging.getLogger(__name__)
 
@@ -47,7 +47,7 @@
 class StageStats:
     recommended: int = 0
     used: int = 0
-    last_used: str = ""
+    last_used: str = ""  # ISO timestamp
     confidence: float = 0.0
 
 
@@ -65,6 +65,9 @@ class Skill:
 
     `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
@@ -157,9 +160,10 @@ def check_migrate(skill_dir: Path, store_root: Path) -> Path | None:
       chunks.md  → references/chunks.md
       code/      → scripts/
 
-    Returns the (possibly renamed) directory path.
+    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 immediately if SKILL.md already exists.
+    Idempotent: returns skill_dir immediately if SKILL.md already exists.
     """
     skill_md_path = skill_dir / "SKILL.md"
     if skill_md_path.is_file():
@@ -205,12 +209,13 @@ def check_migrate(skill_dir: Path, store_root: Path) -> Path | None:
     }
     metadata = {k: str(v) for k, v in meta_fields.items() if v}
 
-    fm = SkillFrontmatter.model_construct(
+    fm = AgentSkill.model_construct(
         name=final_label,
         description=str(meta.get("description", "")),
+        instructions=declarative,
         metadata=metadata,
     )
-    skill_md_path.write_text(dump_skill_md(fm, declarative), encoding="utf-8")
+    skill_md_path.write_text(dump_skill(fm), encoding="utf-8")
 
     # code/ → scripts/
     code_dir = skill_dir / "code"
@@ -270,14 +275,7 @@ def _find_dir(self, label: str) -> Path | None:
 
     def _skill_from_dir(self, d: Path) -> Skill | None:
         """Build a Skill from a (already-migrated) directory."""
-        skill_md_path = d / "SKILL.md"
-        if not skill_md_path.is_file():
-            return None
-        try:
-            text = skill_md_path.read_text(encoding="utf-8")
-        except OSError:
-            return None
-        fm, body = parse_skill_md(text, folder_name=d.name)
+        fm = parse_skill_dir(d)
         if fm is None:
             return None
         label = fm.name or d.name
@@ -286,7 +284,7 @@ def _skill_from_dir(self, d: Path) -> Skill | None:
             name=fm.metadata.get("display_name", label),
             description=fm.description,
             when_to_use=fm.metadata.get("when_to_use", ""),
-            declarative_md=body,
+            declarative_md=fm.instructions,
             created_at=fm.metadata.get("created_at", ""),
             provenance=fm.metadata.get("provenance", "manual"),
             stage_1_present=True,
@@ -346,7 +344,11 @@ def list_all(self) -> list[Skill]:
         return out
 
     def list_summaries(self) -> list[dict]:
-        """Lightweight listing for prompt-building — label + when_to_use only."""
+        """Lightweight listing for prompt-building.
+
+        Returns dicts with keys: label, name, when_to_use.
+        Reads only SKILL.md frontmatter, skips the body.
+        """
         if not self.root.is_dir():
             return []
         out: list[dict] = []
@@ -359,14 +361,7 @@ def list_summaries(self) -> list[dict]:
                     continue
             except OSError:
                 continue
-            skill_md_path = child / "SKILL.md"
-            if not skill_md_path.is_file():
-                continue
-            try:
-                text = skill_md_path.read_text(encoding="utf-8")
-            except OSError:
-                continue
-            fm, _ = parse_skill_md(text, folder_name=child.name)
+            fm = parse_skill_dir(child)
             if fm is None:
                 continue
             label = fm.name or child.name
@@ -396,12 +391,13 @@ def save(self, skill: Skill) -> Path:
             "created_at": skill.created_at,
         }.items() if v}
 
-        fm = SkillFrontmatter.model_construct(
+        fm = AgentSkill.model_construct(
             name=skill.label,
             description=skill.description,
+            instructions=skill.declarative_md,
             metadata=metadata,
         )
-        (d / "SKILL.md").write_text(dump_skill_md(fm, skill.declarative_md), encoding="utf-8")
+        (d / "SKILL.md").write_text(dump_skill(fm), encoding="utf-8")
 
         stats_path = d / "stats.json"
         if not stats_path.is_file():
diff --git a/anton/core/memory/skill_md.py b/anton/core/tools/skill_format.py
similarity index 70%
rename from anton/core/memory/skill_md.py
rename to anton/core/tools/skill_format.py
index 6fb0b088..c18a881e 100644
--- a/anton/core/memory/skill_md.py
+++ b/anton/core/tools/skill_format.py
@@ -17,8 +17,8 @@
 
 Parsing is intentionally lenient — no field validation is applied when
 reading, since files may be authored by external tools.  Validators on
-SkillFrontmatter exist for write/creation paths only and must be called
-explicitly via SkillFrontmatter.model_validate().
+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.
 """
@@ -27,6 +27,7 @@
 
 import logging
 import re
+from pathlib import Path
 from typing import Any
 
 import yaml
@@ -47,15 +48,36 @@
 
 # ─── 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
 
-class SkillFrontmatter(BaseModel):
-    """In-memory representation of a SKILL.md frontmatter block.
+
+def normalize_name(value: str) -> str:
+    slug = value.strip().lower()
+    slug = re.sub(_NAME_RE, "-", 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_md() uses model_construct() so validators are skipped.
+    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
@@ -67,15 +89,7 @@ class SkillFrontmatter(BaseModel):
     @field_validator("name")
     @classmethod
     def _validate_name(cls, 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
+        return validate_name(v)
 
     @field_validator("description")
     @classmethod
@@ -104,18 +118,21 @@ def _coerce_metadata(cls, v: Any) -> dict[str, str]:
 # ─── parse ────────────────────────────────────────────────────────────────────
 
 
-def parse_skill_md(text: str, folder_name: str = "") -> tuple[SkillFrontmatter | None, str]:
-    """Parse SKILL.md text into (frontmatter, body).
+def parse_skill_dir(skill_dir: Path) -> AgentSkill:
+    """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 as e:
+        return None
 
-    No field validation is applied — accepts files created by any tool.
-    Unknown top-level YAML keys are merged into metadata.
-    Returns (None, full_text) only on structural failures (missing delimiters,
-    broken YAML, non-mapping root).
-    """
     lines = text.split("\n")
     if not lines or lines[0].rstrip() != "---":
         logger.debug("parse_skill_md: no opening '---' delimiter")
-        return None, text
+        return None
 
     close_idx: int | None = None
     for i, line in enumerate(lines[1:], 1):
@@ -125,7 +142,7 @@ def parse_skill_md(text: str, folder_name: str = "") -> tuple[SkillFrontmatter |
 
     if close_idx is None:
         logger.debug("parse_skill_md: no closing '---' delimiter")
-        return None, text
+        return None
 
     yaml_text = "\n".join(lines[1:close_idx])
     body = "\n".join(lines[close_idx + 1 :])
@@ -134,11 +151,11 @@ def parse_skill_md(text: str, folder_name: str = "") -> tuple[SkillFrontmatter |
         props = yaml.safe_load(yaml_text)
     except yaml.YAMLError as exc:
         logger.warning("parse_skill_md: YAML error: %s", exc)
-        return None, text
+        return None
 
     if not isinstance(props, dict):
         logger.warning("parse_skill_md: frontmatter is not a YAML mapping")
-        return None, text
+        return None
 
     # Collect metadata from the spec field, then fold in unknown top-level keys
     meta: dict[str, str] = {}
@@ -154,38 +171,34 @@ def parse_skill_md(text: str, folder_name: str = "") -> tuple[SkillFrontmatter |
     if not name:
         name = folder_name
 
-    name = re.sub(_NAME_RE, "", name).replace("--", " - ")[:_NAME_MAX]
-    if name.startswith("-"):
-        name = name[1:]
-
-    fm = SkillFrontmatter.model_construct(
-        name=name,
+    return AgentSkill.model_construct(
+        name=normalize_name(name),
+        instructions=body,
         description=str(props.get("description", ""))[:_DESC_MAX],
         license=props.get("license"),
         compatibility=props.get("compatibility"),
         allowed_tools=props.get("allowed-tools"),
         metadata=meta,
     )
-    return fm, body
 
 
 # ─── dump ─────────────────────────────────────────────────────────────────────
 
 
-def dump_skill_md(frontmatter: SkillFrontmatter, body: str) -> str:
-    """Serialise frontmatter + body back to SKILL.md text."""
+def dump_skill(skill: AgentSkill) -> str:
+    """Serialise an AgentSkill back to SKILL.md text."""
     data: dict[str, Any] = {
-        "name": frontmatter.name,
-        "description": frontmatter.description,
+        "name": skill.name,
+        "description": skill.description,
     }
-    if frontmatter.license is not None:
-        data["license"] = frontmatter.license
-    if frontmatter.compatibility is not None:
-        data["compatibility"] = frontmatter.compatibility
-    if frontmatter.allowed_tools is not None:
-        data["allowed-tools"] = frontmatter.allowed_tools
-    if frontmatter.metadata:
-        data["metadata"] = dict(frontmatter.metadata)
+    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,
@@ -193,7 +206,7 @@ def dump_skill_md(frontmatter: SkillFrontmatter, body: str) -> str:
         allow_unicode=True,
         sort_keys=False,
     )
-    return f"---\n{yaml_text}---\n{body}"
+    return f"---\n{yaml_text}---\n{skill.instructions}"
 
 
-__all__ = ["SkillFrontmatter", "parse_skill_md", "dump_skill_md"]
+__all__ = ["AgentSkill", "parse_skill_dir", "dump_skill"]

From 3c9fdd34a5ae648f3d4bf969f2fd978279746ee1 Mon Sep 17 00:00:00 2001
From: andrew <elkin.andr@gmail.com>
Date: Wed, 17 Jun 2026 16:54:52 +0300
Subject: [PATCH 05/19] when_to_use moved to description

---
 anton/commands/skills.py            | 18 ++++--------------
 anton/core/llm/prompt_builder.py    |  4 ++--
 anton/core/tools/skill_format.py    |  7 +++----
 tests/test_prompt_builder_skills.py | 12 +++++-------
 tests/test_recall_skill.py          |  3 ---
 tests/test_session_skills_init.py   |  3 +--
 tests/test_skill_commands.py        | 24 +++++++-----------------
 tests/test_skills_e2e.py            |  3 +--
 tests/test_skills_store.py          |  5 +----
 9 files changed, 24 insertions(+), 55 deletions(-)

diff --git a/anton/commands/skills.py b/anton/commands/skills.py
index 292c92ef..87af7111 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.
@@ -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 "
@@ -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/core/llm/prompt_builder.py b/anton/core/llm/prompt_builder.py
index 9d50a80c..49e92d7d 100644
--- a/anton/core/llm/prompt_builder.py
+++ b/anton/core/llm/prompt_builder.py
@@ -65,7 +65,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.
@@ -96,7 +96,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/tools/skill_format.py b/anton/core/tools/skill_format.py
index c18a881e..3154dcc6 100644
--- a/anton/core/tools/skill_format.py
+++ b/anton/core/tools/skill_format.py
@@ -9,7 +9,6 @@
     allowed-tools: read_file write_file # optional, space-separated
     metadata:
       display_name: My Cat
-      when_to_use: ...
       provenance: manual
       created_at: "2026-06-15T15:20:42+00:00"
     ---
@@ -37,6 +36,7 @@
 
 # ─── spec constraints (used by validators, not enforced on read) ──────────────
 
+SKILL_FILE = "SKILL.md"
 _NAME_RE = re.compile(r"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$")
 _NAME_MAX = 64
 _DESC_MAX = 1024
@@ -62,7 +62,7 @@ def validate_name(v: str) -> str:
 
 def normalize_name(value: str) -> str:
     slug = value.strip().lower()
-    slug = re.sub(_NAME_RE, "-", slug)  # non-alnum runs -> single hyphen
+    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("-")
@@ -118,12 +118,11 @@ def _coerce_metadata(cls, v: Any) -> dict[str, str]:
 # ─── parse ────────────────────────────────────────────────────────────────────
 
 
-def parse_skill_dir(skill_dir: Path) -> AgentSkill:
+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 as e:
diff --git a/tests/test_prompt_builder_skills.py b/tests/test_prompt_builder_skills.py
index 0dbc6009..6c583804 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",
@@ -67,7 +66,7 @@ def test_populated_store_renders_section(self, populated_store: SkillStore):
         assert "`csv_summary`" in prompt
         assert "`web_scraping`" in prompt
         assert "`api_fetcher`" in prompt
-        # And their when_to_use
+        # 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..11f52f39 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",
diff --git a/tests/test_session_skills_init.py b/tests/test_session_skills_init.py
index e542a61f..f5a1853e 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",
diff --git a/tests/test_skill_commands.py b/tests/test_skill_commands.py
index 7392d0ff..642aa0fa 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
@@ -216,7 +212,6 @@ async def test_label_collision_appends_number(self, console, store):
                 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")],
@@ -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",
@@ -373,7 +365,6 @@ def test_show_unknown_suggests_closest(self, console, store):
                 label="csv_summary",
                 name="CSV",
                 description="",
-                when_to_use="",
                 declarative_md="x",
                 created_at="2026-04-10T00:00:00+00:00",
                 provenance="manual",
@@ -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 597f5dd1..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"
diff --git a/tests/test_skills_store.py b/tests/test_skills_store.py
index cf14bb68..4de11a55 100644
--- a/tests/test_skills_store.py
+++ b/tests/test_skills_store.py
@@ -35,7 +35,6 @@ def _make_skill(label: str = "csv-summary", **overrides) -> Skill:
         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",
@@ -109,7 +108,6 @@ def test_load_after_save_round_trip(self, store: SkillStore):
         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"
 
@@ -174,7 +172,7 @@ def test_list_summaries_lightweight_shape(self, store: SkillStore):
         assert summaries[0] == {
             "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):
@@ -280,7 +278,6 @@ def test_skill_md_has_expected_fields(self, store: SkillStore, store_root: Path)
         assert "name: csv-summary" in text
         assert "description:" in text
         assert "display_name:" in text
-        assert "when_to_use:" in text
 
     def test_stats_json_initial_shape(self, store: SkillStore, store_root: Path):
         store.save(_make_skill())

From 3e3044b4feeb0ffaa9be9da040e0576d1c36e522 Mon Sep 17 00:00:00 2001
From: andrew <elkin.andr@gmail.com>
Date: Wed, 17 Jun 2026 17:00:33 +0300
Subject: [PATCH 06/19] when_to_use to description

---
 anton/README.md                         | 32 ++++++++++-----------
 anton/core/memory/skills.py             | 37 ++++++++++++-------------
 docs/docs/developer/architecture.md     |  2 +-
 docs/docs/developer/brain-mapping.md    |  7 ++---
 docs/docs/developer/skills-internals.md | 28 +++++++++----------
 5 files changed, 50 insertions(+), 56 deletions(-)

diff --git a/anton/README.md b/anton/README.md
index 484e78b2..c16fdad8 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
 
@@ -512,14 +510,14 @@ you> /skill save csv summary
 anton> Drafting a skill from recent work…
        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"}}
@@ -890,9 +888,9 @@ 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.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 `meta.json`, `declarative.md`, `stats.json`. Never wipes accumulated counters. |
+| `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. |
@@ -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/core/memory/skills.py b/anton/core/memory/skills.py
index f060b7e4..c91685c8 100644
--- a/anton/core/memory/skills.py
+++ b/anton/core/memory/skills.py
@@ -31,7 +31,7 @@
 from datetime import datetime, timezone
 from pathlib import Path
 
-from anton.core.tools.skill_format import AgentSkill, dump_skill, parse_skill_dir
+from anton.core.tools.skill_format import AgentSkill, dump_skill, parse_skill_dir, normalize_name
 
 logger = logging.getLogger(__name__)
 
@@ -73,7 +73,6 @@ class Skill:
     label: str
     name: str
     description: str
-    when_to_use: str
     declarative_md: str
     created_at: str
     provenance: str  # "manual" | "consolidator"
@@ -185,7 +184,7 @@ def check_migrate(skill_dir: Path, store_root: Path) -> Path | None:
     declarative = decl_path.read_text(encoding="utf-8") if decl_path.is_file() else ""
 
     old_label = skill_dir.name
-    new_label = old_label.replace("_", "-")
+    new_label = normalize_name(old_label)
 
     # Resolve collision when renaming
     final_label = new_label
@@ -200,18 +199,20 @@ def check_migrate(skill_dir: Path, store_root: Path) -> Path | None:
                     break
                 n += 1
 
-    # Build metadata dict (omit empty values)
-    meta_fields = {
+    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
+
+    metadata = {k: str(v) for k, v in {
         "display_name": meta.get("name", ""),
-        "when_to_use": meta.get("when_to_use", ""),
         "provenance": meta.get("provenance", "manual"),
         "created_at": meta.get("created_at", ""),
-    }
-    metadata = {k: str(v) for k, v in meta_fields.items() if v}
+    }.items() if v}
 
     fm = AgentSkill.model_construct(
         name=final_label,
-        description=str(meta.get("description", "")),
+        description=description,
         instructions=declarative,
         metadata=metadata,
     )
@@ -278,12 +279,11 @@ def _skill_from_dir(self, d: Path) -> Skill | None:
         fm = parse_skill_dir(d)
         if fm is None:
             return None
-        label = fm.name or d.name
+
         return Skill(
-            label=label,
-            name=fm.metadata.get("display_name", label),
+            label=fm.metadata.get("display_name", fm.name),
+            name=fm.name,
             description=fm.description,
-            when_to_use=fm.metadata.get("when_to_use", ""),
             declarative_md=fm.instructions,
             created_at=fm.metadata.get("created_at", ""),
             provenance=fm.metadata.get("provenance", "manual"),
@@ -346,7 +346,7 @@ def list_all(self) -> list[Skill]:
     def list_summaries(self) -> list[dict]:
         """Lightweight listing for prompt-building.
 
-        Returns dicts with keys: label, name, when_to_use.
+        Returns dicts with keys: label, name, description.
         Reads only SKILL.md frontmatter, skips the body.
         """
         if not self.root.is_dir():
@@ -364,11 +364,11 @@ def list_summaries(self) -> list[dict]:
             fm = parse_skill_dir(child)
             if fm is None:
                 continue
-            label = fm.name or child.name
+
             out.append({
-                "label": label,
-                "name": fm.metadata.get("display_name", label),
-                "when_to_use": fm.metadata.get("when_to_use", ""),
+                "label": fm.metadata.get("display_name", fm.name),
+                "name": fm.name,
+                "description": fm.description,
             })
         return out
 
@@ -386,7 +386,6 @@ def save(self, skill: Skill) -> Path:
 
         metadata = {k: v for k, v in {
             "display_name": skill.name,
-            "when_to_use": skill.when_to_use,
             "provenance": skill.provenance,
             "created_at": skill.created_at,
         }.items() if v}
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 |

From be04feefb353fdee6e93a6b69f378500788fc258 Mon Sep 17 00:00:00 2001
From: andrew <elkin.andr@gmail.com>
Date: Wed, 17 Jun 2026 17:14:36 +0300
Subject: [PATCH 07/19] label - is skill name name - is visible name

---
 anton/core/memory/skills.py | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/anton/core/memory/skills.py b/anton/core/memory/skills.py
index c91685c8..9b5b5339 100644
--- a/anton/core/memory/skills.py
+++ b/anton/core/memory/skills.py
@@ -281,8 +281,8 @@ def _skill_from_dir(self, d: Path) -> Skill | None:
             return None
 
         return Skill(
-            label=fm.metadata.get("display_name", fm.name),
-            name=fm.name,
+            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", ""),
@@ -366,8 +366,8 @@ def list_summaries(self) -> list[dict]:
                 continue
 
             out.append({
-                "label": fm.metadata.get("display_name", fm.name),
-                "name": fm.name,
+                "label": fm.name,
+                "name": fm.metadata.get("display_name", fm.name),
                 "description": fm.description,
             })
         return out

From e567b12db1ecf6b3edabebb58c7665ffa1ce08b9 Mon Sep 17 00:00:00 2001
From: andrew <elkin.andr@gmail.com>
Date: Wed, 17 Jun 2026 18:07:53 +0300
Subject: [PATCH 08/19] check len on migration

---
 anton/core/memory/skills.py      | 3 ++-
 anton/core/tools/skill_format.py | 8 ++++----
 2 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/anton/core/memory/skills.py b/anton/core/memory/skills.py
index 9b5b5339..688d36e2 100644
--- a/anton/core/memory/skills.py
+++ b/anton/core/memory/skills.py
@@ -31,7 +31,7 @@
 from datetime import datetime, timezone
 from pathlib import Path
 
-from anton.core.tools.skill_format import AgentSkill, dump_skill, parse_skill_dir, normalize_name
+from anton.core.tools.skill_format import AgentSkill, dump_skill, parse_skill_dir, normalize_name, DESC_MAX
 
 logger = logging.getLogger(__name__)
 
@@ -203,6 +203,7 @@ def check_migrate(skill_dir: Path, store_root: Path) -> Path | None:
     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", ""),
diff --git a/anton/core/tools/skill_format.py b/anton/core/tools/skill_format.py
index 3154dcc6..c3d9914b 100644
--- a/anton/core/tools/skill_format.py
+++ b/anton/core/tools/skill_format.py
@@ -37,9 +37,9 @@
 # ─── 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
-_DESC_MAX = 1024
 _COMPAT_MAX = 500
 
 # canonical YAML keys defined by the spec
@@ -96,8 +96,8 @@ def _validate_name(cls, v: str) -> str:
     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")
+        if len(v) > DESC_MAX:
+            raise ValueError(f"description exceeds {DESC_MAX} chars")
         return v
 
     @field_validator("compatibility")
@@ -173,7 +173,7 @@ def parse_skill_dir(skill_dir: Path) -> AgentSkill | None:
     return AgentSkill.model_construct(
         name=normalize_name(name),
         instructions=body,
-        description=str(props.get("description", ""))[:_DESC_MAX],
+        description=str(props.get("description", "")),
         license=props.get("license"),
         compatibility=props.get("compatibility"),
         allowed_tools=props.get("allowed-tools"),

From bb33a63fb74f8e83e46161658706630eaaf986ec Mon Sep 17 00:00:00 2001
From: andrew <elkin.andr@gmail.com>
Date: Thu, 18 Jun 2026 11:08:49 +0300
Subject: [PATCH 09/19] setting for skill root

---
 anton/config/settings.py | 2 ++
 anton/core/session.py    | 2 +-
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/anton/config/settings.py b/anton/config/settings.py
index 27476c89..b357d9a1 100644
--- a/anton/config/settings.py
+++ b/anton/config/settings.py
@@ -51,6 +51,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/session.py b/anton/core/session.py
index 58abf956..58419f4d 100644
--- a/anton/core/session.py
+++ b/anton/core/session.py
@@ -185,7 +185,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().

From 9ef6f5d7d8362e94a424f62498660c8730e2f4ab Mon Sep 17 00:00:00 2001
From: andrew <elkin.andr@gmail.com>
Date: Thu, 18 Jun 2026 16:07:12 +0300
Subject: [PATCH 10/19] fix tests

---
 tests/test_recall_skill.py | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/tests/test_recall_skill.py b/tests/test_recall_skill.py
index 11f52f39..0060f3b4 100644
--- a/tests/test_recall_skill.py
+++ b/tests/test_recall_skill.py
@@ -172,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(
@@ -182,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

From 77374c53214d4feb7d1c32207b49ccf054c659d9 Mon Sep 17 00:00:00 2001
From: andrew <elkin.andr@gmail.com>
Date: Thu, 18 Jun 2026 16:21:30 +0300
Subject: [PATCH 11/19] fix tests

---
 anton/commands/skills.py         | 8 ++++----
 anton/core/memory/skills.py      | 4 +++-
 anton/core/tools/recall_skill.py | 4 ++--
 tests/test_recall_skill.py       | 2 +-
 4 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/anton/commands/skills.py b/anton/commands/skills.py
index 87af7111..6f20a2c3 100644
--- a/anton/commands/skills.py
+++ b/anton/commands/skills.py
@@ -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(
@@ -225,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 ""
     )
diff --git a/anton/core/memory/skills.py b/anton/core/memory/skills.py
index 688d36e2..13ec9fa8 100644
--- a/anton/core/memory/skills.py
+++ b/anton/core/memory/skills.py
@@ -155,7 +155,7 @@ def check_migrate(skill_dir: Path, store_root: Path) -> Path | None:
     Old format: meta.json + declarative.md
     New format: SKILL.md (agentskills.io spec)
 
-    Also renames the directory from snake_case to hyphen-case and moves:
+    Also renames the directory from snake_case to kebab-case and moves:
       chunks.md  → references/chunks.md
       code/      → scripts/
 
@@ -382,6 +382,8 @@ def save(self, skill: Skill) -> Path:
         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)
 
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/tests/test_recall_skill.py b/tests/test_recall_skill.py
index 0060f3b4..e971fc4a 100644
--- a/tests/test_recall_skill.py
+++ b/tests/test_recall_skill.py
@@ -152,7 +152,7 @@ async def test_typo_credits_resolved_label_not_input(self, store: SkillStore):
     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
+        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

From e833cb79eaea986a5ab55f1cbfde036f4182bf46 Mon Sep 17 00:00:00 2001
From: andrew <elkin.andr@gmail.com>
Date: Thu, 18 Jun 2026 16:33:34 +0300
Subject: [PATCH 12/19] fix tests

---
 tests/test_prompt_builder_skills.py | 6 +++---
 tests/test_recall_skill.py          | 4 ++--
 tests/test_session_skills_init.py   | 2 +-
 tests/test_skill_commands.py        | 4 ++--
 4 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/tests/test_prompt_builder_skills.py b/tests/test_prompt_builder_skills.py
index 6c583804..433868a6 100644
--- a/tests/test_prompt_builder_skills.py
+++ b/tests/test_prompt_builder_skills.py
@@ -63,9 +63,9 @@ 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
+        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
diff --git a/tests/test_recall_skill.py b/tests/test_recall_skill.py
index e971fc4a..15c5db4e 100644
--- a/tests/test_recall_skill.py
+++ b/tests/test_recall_skill.py
@@ -136,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
 
@@ -151,7 +151,7 @@ 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"})
+        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.
diff --git a/tests/test_session_skills_init.py b/tests/test_session_skills_init.py
index f5a1853e..c6806b1b 100644
--- a/tests/test_session_skills_init.py
+++ b/tests/test_session_skills_init.py
@@ -72,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 642aa0fa..bbb87bf3 100644
--- a/tests/test_skill_commands.py
+++ b/tests/test_skill_commands.py
@@ -362,7 +362,7 @@ 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="",
                 declarative_md="x",
@@ -372,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)

From a8532fc9c7aeeeac9eb0d1184514d13a2e006e32 Mon Sep 17 00:00:00 2001
From: andrew <elkin.andr@gmail.com>
Date: Thu, 18 Jun 2026 16:50:49 +0300
Subject: [PATCH 13/19] update readme

---
 anton/README.md | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/anton/README.md b/anton/README.md
index c16fdad8..776bf6a9 100644
--- a/anton/README.md
+++ b/anton/README.md
@@ -508,7 +508,7 @@ 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
        Description: User asks to explore, summarize, or describe a CSV file.
 ```
@@ -520,10 +520,10 @@ Automatic skill extraction (the consolidator promoting recurring scratchpad patt
 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.
 
@@ -538,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
 
@@ -889,13 +889,13 @@ Tests live at `tests/test_acc.py` (44 tests, 4 layers: pure-function detectors 
 |---|---|
 | `SkillStore.list_all()` | Return every loadable skill, sorted by label. |
 | `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 snake_case identifier. |
+| `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
 

From 4d02d69a2e454354dc96dbd9713e55c88eeb068b Mon Sep 17 00:00:00 2001
From: andrew <elkin.andr@gmail.com>
Date: Thu, 18 Jun 2026 16:53:09 +0300
Subject: [PATCH 14/19] uv lock

---
 uv.lock | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/uv.lock b/uv.lock
index 08c2abc4..002d1055 100644
--- a/uv.lock
+++ b/uv.lock
@@ -164,7 +164,7 @@ wheels = [
 ]
 
 [[package]]
-name = "anton-agent"
+name = "anton"
 source = { editable = "." }
 dependencies = [
     { name = "aiohttp" },

From 8a369824e470a8cfb738b15df43a89615ac4d89f Mon Sep 17 00:00:00 2001
From: andrew <elkin.andr@gmail.com>
Date: Thu, 18 Jun 2026 16:57:31 +0300
Subject: [PATCH 15/19] rollback part of the doc

---
 anton/core/memory/skills.py | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/anton/core/memory/skills.py b/anton/core/memory/skills.py
index 13ec9fa8..edb293de 100644
--- a/anton/core/memory/skills.py
+++ b/anton/core/memory/skills.py
@@ -18,6 +18,20 @@
 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

From fa386340ae9333f4d78dfb323ce841c553213484 Mon Sep 17 00:00:00 2001
From: andrew <elkin.andr@gmail.com>
Date: Thu, 18 Jun 2026 18:00:10 +0300
Subject: [PATCH 16/19] fixes

---
 anton/core/memory/skills.py      | 7 +++----
 anton/core/tools/skill_format.py | 5 ++---
 2 files changed, 5 insertions(+), 7 deletions(-)

diff --git a/anton/core/memory/skills.py b/anton/core/memory/skills.py
index edb293de..39491990 100644
--- a/anton/core/memory/skills.py
+++ b/anton/core/memory/skills.py
@@ -170,7 +170,6 @@ def check_migrate(skill_dir: Path, store_root: Path) -> Path | None:
     New format: SKILL.md (agentskills.io spec)
 
     Also renames the directory from snake_case to kebab-case and moves:
-      chunks.md  → references/chunks.md
       code/      → scripts/
 
     Returns the (possibly renamed) directory path, or None if the directory
@@ -435,10 +434,10 @@ def delete(self, label: str) -> bool:
 
     def increment_recommended(self, label: str, *, stage: int = 1) -> None:
         """Bump the per-stage `recommended` counter. Best-effort, no-ops on error."""
-        d = self._skill_dir(label)
-        if not d.is_dir():
+        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
diff --git a/anton/core/tools/skill_format.py b/anton/core/tools/skill_format.py
index c3d9914b..5b2ff010 100644
--- a/anton/core/tools/skill_format.py
+++ b/anton/core/tools/skill_format.py
@@ -68,7 +68,6 @@ def normalize_name(value: str) -> str:
     return slug[:_NAME_MAX].rstrip("-")
 
 
-
 class AgentSkill(BaseModel):
     """In-memory representation of a SKILL.md file (frontmatter + body).
 
@@ -125,7 +124,7 @@ def parse_skill_dir(skill_dir: Path) -> AgentSkill | None:
 
     try:
         text = md_path.read_text(encoding="utf-8")
-    except OSError as e:
+    except OSError:
         return None
 
     lines = text.split("\n")
@@ -185,7 +184,7 @@ def parse_skill_dir(skill_dir: Path) -> AgentSkill | None:
 
 
 def dump_skill(skill: AgentSkill) -> str:
-    """Serialise an AgentSkill back to SKILL.md text."""
+    """Serialize an AgentSkill back to SKILL.md text."""
     data: dict[str, Any] = {
         "name": skill.name,
         "description": skill.description,

From 194b407ebdd6ddb4136a25c1d7b286a6412fe846 Mon Sep 17 00:00:00 2001
From: Alejandro Cantu <alecantu7@gmail.com>
Date: Thu, 18 Jun 2026 12:41:48 -0700
Subject: [PATCH 17/19] Reconcile artifact files[] against disk on read
 (ENG-372)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Scratchpad code writes artifact files straight into the folder via plain
open(), bypassing the store — so files[] stayed frozen at the empty state
create() wrote, and open_artifact()/list_artifacts() reported file_count 0
for fully-written artifacts. The agent read that as "file missing" and
burned turns in a recovery loop.

The store already had a rescan_files() primitive but nothing ever called it
(dead code). Wire reconciliation into open() and list() via a new
_reconcile_files(), which:
  - re-derives files[] from disk, and
  - persists (+ bumps updatedAt) ONLY when the on-disk set actually changed,
    so it's idempotent and cheap to call on every read (no metadata/README
    churn, no spurious updatedAt bumps).

Also add .published.json to the housekeeping skip set (was metadata.json /
README.md only) to match cowork-server's artifacts service, so publish-state
isn't miscounted as an artifact file.

Scope: agent-facing only. cowork-server's UI already scans disk directly, so
the user-facing artifact list/preview was never affected.

Tests: open()/list() now reflect a scratchpad-written file; .published.json
excluded; reconcile-on-read is idempotent (no re-save when unchanged).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 anton/core/artifacts/models.py |  7 ++--
 anton/core/artifacts/store.py  | 61 +++++++++++++++++++++++++++++-----
 tests/test_artifacts.py        | 43 ++++++++++++++++++++++++
 3 files changed, 100 insertions(+), 11 deletions(-)

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/tests/test_artifacts.py b/tests/test_artifacts.py
index 9753c25a..0aee4ee7 100644
--- a/tests/test_artifacts.py
+++ b/tests/test_artifacts.py
@@ -264,6 +264,49 @@ 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
+
+
 # ─── README rendering ───────────────────────────────────────────────────────
 
 

From 91f9a279ba4dea056523530d20724324b6c4f318 Mon Sep 17 00:00:00 2001
From: Alejandro Cantu <alecantu7@gmail.com>
Date: Thu, 18 Jun 2026 12:50:33 -0700
Subject: [PATCH 18/19] test: reconcile re-saves and persists when the file set
 changes (ENG-372)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adversarial-review gap: idempotency (no re-save when unchanged) was covered,
but not the inverse — that a changed on-disk file set actually reconciles AND
persists to metadata.json. Add it.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 tests/test_artifacts.py | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/tests/test_artifacts.py b/tests/test_artifacts.py
index 0aee4ee7..cdf478fd 100644
--- a/tests/test_artifacts.py
+++ b/tests/test_artifacts.py
@@ -307,6 +307,19 @@ def test_reconcile_on_read_is_idempotent(store: ArtifactStore):
     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 ───────────────────────────────────────────────────────
 
 

From 8b1446dbe329713be34b75d2d1e2d40f01d10d5b Mon Sep 17 00:00:00 2001
From: andrew <elkin.andr@gmail.com>
Date: Fri, 19 Jun 2026 16:56:51 +0300
Subject: [PATCH 19/19] rollback when_to_use for back compatibility with old
 cowork version

---
 anton/core/memory/skills.py | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/anton/core/memory/skills.py b/anton/core/memory/skills.py
index 39491990..92121672 100644
--- a/anton/core/memory/skills.py
+++ b/anton/core/memory/skills.py
@@ -90,6 +90,7 @@ class Skill:
     declarative_md: str
     created_at: str
     provenance: str  # "manual" | "consolidator"
+    when_to_use: str = ""
     stage_1_present: bool = True
     stage_2_present: bool = False
     stage_3_present: bool = False
@@ -406,9 +407,14 @@ def save(self, skill: Skill) -> Path:
             "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=skill.description,
+            description=description,
             instructions=skill.declarative_md,
             metadata=metadata,
         )