Skill Auto-Synthesis

Grounds on (exists today): src/gaia/agents/base/memory_store.py (MemoryStore, tool_history, knowledge, the schema migration) · src/gaia/agents/base/memory.py (the embedder, FAISS index, Mem0-style prompts, the consolidation pass) · src/gaia/agents/base/agent.py (_compose_system_prompt, _select_tools_for_turn) · src/gaia/ui/routers/memory.py (the /api/memory/* router the dashboard reads)Proposed runtime (not written yet): src/gaia/agents/base/skill_synthesis.py and the new procedures table + MemoryStore skill methods. Every such symbol is marked PROPOSED where it appears.Sibling specs: Skill Format defines the SKILL.md field grammar this spec emits; Dynamic Tool Loader Part 3 consumes the recall_skill / tools_required contract.

Component: the skill auto-synthesis pipeline — distil recurring successful tool sequences into procedural memory (issue #887).Module: gaia.agents.base.skill_synthesis — PROPOSED, greenfield. No pipeline, procedures table, or recall_skill exists in code. The contract is grounded on the live memory layer in gaia.agents.base.memory / memory_store.Status: All PROPOSED — design, pending maintainer sign-off. Nothing in this spec is implemented. PR #606 (memory v2) is merged and provides every primitive the pipeline reuses; the SKILL.md format (#691) is authored and locked, so this spec references a settled format rather than inventing one.Target agent (v1): the base MemoryMixin (so ChatAgent and any memory-bearing agent inherit it). The on-disk default model is Gemma-4-E4B-it-GGUF; the embedder is nomic-embed-text-v2-moe-GGUF (768-dim), reused unchanged.

Why this exists

PR #606 gave GAIA a memory layer modelled on CoALA — Cognitive Architectures for Language Agents (Sumers et al., 2024), which types memory into working / episodic / semantic / procedural. #606 shipped the first three: a MemoryStore over SQLite, a tool_history table that records every tool call with its outcome and latency (memory_store.py:241), and a consolidation pass that distils old conversations into durable knowledge. The procedural tier was left for a follow-up. This spec is that tier. A skill in CoALA is procedural memory: a generalized policy distilled from episodic traces. The agent already keeps the episodic trace (tool_history). The missing loop is: notice that the same multi-step goal succeeded several times, distil it into a reusable Markdown procedure, store it, and surface it the next time a similar goal appears — so the agent stops re-deriving a solved task from scratch. Two design commitments follow from putting this in the memory layer rather than a new subsystem:

It is a learning loop, not a marketplace. Synthesis creates skills from the agent’s own successful runs. Browsing, installing, and sharing skills is distribution work and stays in the marketplace track (#647). Splitting them lets the learning loop ship on the memory rails that already exist.
No new infrastructure. The same MemoryStore that holds episodic + semantic memory holds procedural memory; the same embedder clusters goals; the same Mem0-style LLM-in-the-loop pattern distils the procedure; the same memory router exposes it. GAIA’s contribution here is the integration, not a new format or a new store.

Prior art (credit before contribution)

The pipeline reuses a substantial body of public work — credited before claiming anything as GAIA’s:

Source	What it contributes
Mem0 (mem0.ai)	LLM-in-the-loop extraction with an `ADD` / `UPDATE` / `DELETE` / `NOOP` decision — reused verbatim for the distil-and-reconcile step (minus `DELETE`, which synthesis never issues).
Zep / Graphiti (getzep.com)	Fact lineage — a v2 supersedes v1. Applied to skills: a procedure with a stronger track record supersedes the weaker one via the existing `superseded_by` column.
Hindsight	Pairwise reconciliation — applied to detect two procedures for the same goal and keep the higher success rate.
ENGRAM	Memory typing — #606 already types `knowledge` by category; this extends typing to the procedural tier.
CoALA (Sumers et al., 2024)	The four-tier architecture #606 cites. This spec is its procedural tier.
Nous Research Hermes Agent (hermes-agent.nousresearch.com)	The auto-distillation-from-successful-runs paradigm, and the agentskills.io format GAIA adopts for the emitted `SKILL.md`.

GAIA’s contribution is the integration: procedural memory lives in the same MemoryStore, is distilled by the same Mem0-style pipeline, recalled through the same embedder, and exposed through the same memory router — no parallel subsystem.

Decided design

The pipeline is the maintainer’s five-step loop (#887 technical-spec comment), landing in a new module skill_synthesis.py (PROPOSED) and hooked into the existing memory maintenance pass. All five steps reuse #606 primitives — no new model, no new store engine.

┌─────────────────────────────────────────────────────────────────────┐
│  #606 memory maintenance pass — _run_memory_post_init (memory.py)    │
│  runs reconcile_memory + consolidate_old_sessions on first query     │
└───────────────────────────────┬─────────────────────────────────────┘
                                 │  NEW additive step: _synthesize_skills
                                 ▼
  1. DETECT   extract_sequences(store, since)                  PROPOSED
     walk tool_history by session; keep successful spans
     of ≥ MIN_STEPS tool calls
                                 │
                                 ▼
  2. CLUSTER  cluster_by_goal(sequences, embedder)             PROPOSED
     embed each user_goal with the #606 nomic-768 embedder;
     agglomerate at cosine ≥ SIMILARITY_TAU; keep clusters
     of ≥ MIN_OCCURRENCES
                                 │
                                 ▼
  3. DISTILL  distill_cluster(cluster, llm) → Skill | None     PROPOSED
     one low-temp LLM call per cluster (DISTILL_SYSTEM_PROMPT);
     Skill.parse() validates; literal "SKIP" → None
                                 │
                                 ▼
  4. STORE    reconcile_and_store(candidate, store)            PROPOSED
     Mem0 ADD / UPDATE / NOOP; supersede when success_count
     dominates (Zep lineage) → row in the procedures table
                                 │
                                 ▼
  5. RECALL   recall_skill(goal, top_k=2)   (live path)        PROPOSED
     vector search over procedures.embedding; inject the
     matched procedure body into the planner's system context

The synthesis pass hooks into the existing maintenance pass

#606 already runs a maintenance pass on the first process_query() of a process — _run_memory_post_init() (memory.py:1206), which calls reconcile_memory(max_pairs=20) (memory.py:1377) and consolidate_old_sessions(max_sessions=5) (memory.py:1233). Synthesis is added as one more additive step in that pass — a proposed _synthesize_skills() after consolidation. It is off the hot path and bounded by max_clusters_per_pass.

The maintainer’s pseudocode names this hook on_consolidation_pass() calling _consolidate_old_sessions / _reconcile_contradictions / _prune_stale. Those exact method names do not exist on main — the real seam is _run_memory_post_init (memory.py:1206). The pseudocode is illustrative; this spec binds the hook to the real method. See Correcting the original framing.

The proposed `procedures` table

Procedural memory gets its own table, distinct from knowledge. The rationale is in Why procedures is a separate table; the schema:

-- PROPOSED — additive v2→v3 migration in MemoryStore (mirrors the v1→v2 ADD COLUMN pattern)
CREATE TABLE IF NOT EXISTS procedures (
    id              TEXT PRIMARY KEY,
    name            TEXT NOT NULL,              -- kebab-case (→ SKILL.md frontmatter name)
    when_to_use     TEXT NOT NULL,              -- trigger; embedded for recall (→ description)
    markdown_body   TEXT NOT NULL,              -- full procedure incl. edge cases inline
    tools_required  TEXT,                       -- JSON array — the tool-loader recipe contract
    tool_sequence   TEXT,                       -- JSON — the distilled step pattern
    success_count   INTEGER NOT NULL DEFAULT 0,
    attempt_count   INTEGER NOT NULL DEFAULT 0, -- success_count / attempt_count = success rate
    provenance      TEXT,                       -- JSON {source:'synthesized', from_sessions:[...]}
    version         TEXT NOT NULL DEFAULT '1.0.0',
    enabled         INTEGER NOT NULL DEFAULT 1, -- disable without delete (AC: blocks recall)
    embedding       BLOB,                       -- over when_to_use; its OWN FAISS index
    superseded_by   TEXT,                       -- set on supersede (higher success rate)
    created_at      TEXT NOT NULL,
    last_used_at    TEXT
);

This honours the corpus name the tool-loader spec already published — procedures.embedding (tool-loader.mdx:358) — and adds a separate FAISS index over it, distinct from the knowledge embedding index (memory.py:687). Migration is additive only — a v2→v3 migration mirroring _migrate_schema_locked (memory_store.py:364), which already grew knowledge from v1→v2 with ADD COLUMN statements (memory_store.py:388) — no existing row is rewritten.

Provenance is a best-effort audit trail, not a foreign key. provenance.from_sessions is validated at synthesis time — every id resolves to a real tool_history session at the moment the procedure is distilled. It is not enforced afterward: #606’s tool_history retention may later prune a referenced session, leaving a dangling id. That is acceptable and never blocks recall — the distilled markdown_body is already self-contained. An implementer must not add a foreign-key constraint or a “verify provenance on read” check that couples recall to tool_history longevity.

`recall_skill(goal, top_k=2)` is an internal method, not a sixth tool

The issue’s Scope C calls it a “new tool”, but the design keeps it a plain MemoryMixin/MemoryStore method invoked programmatically by the planner — not a sixth LLM-facing @tool. The matched procedure’s body is injected into the system context assembled by _compose_system_prompt (agent.py:591) — the same composition seam the dynamic tool-loader’s per-turn _select_tools_for_turn hook (agent.py:786) already uses. This:

preserves the five-tool memory registry (remember, recall, update_memory, forget, search_past_conversations — memory.py:1984, :2067, :2250, :2335, :2344); the agent gains a capability without gaining a tool it must reason about choosing;
matches the tool-loader’s programmatic use — Part 3 calls recall_skill(goal) itself to union tools_required into selection (tool-loader.mdx:350), it does not wait for the model to call a tool.

Injection budget. Each matched body lands in the planner’s system prompt, so an unbounded body would both bloat the context on a small local model and defeat the tool-loader’s cache-warm seam, which recomputes the system prompt only when the tool selection changes (tool-loader.mdx:294). The spec therefore caps the injection at a default MAX_RECALL_BODY_CHARS = 1500 per body at top_k = 2 — a ≤ 3 KB worst-case prompt addition. DISTILL_SYSTEM_PROMPT already targets short, single-screen procedures, so the cap is a guardrail rather than the common path; a body over the cap is truncated at injection with an explicit … (truncated) marker while the full body stays in the procedures row. The exact value is tunable against a small-model eval at PR.

Thresholds

The five thresholds are the maintainer’s chosen constants, surfaced as config (see Open questions for the config-location decision):

Constant	Value	Meaning
`MIN_STEPS`	`3`	A span shorter than 3 tool calls is not worth distilling.
`MIN_OCCURRENCES`	`3`	Need ≥3 similar successful runs before a cluster qualifies.
`MIN_SUCCESS_RATE`	`0.80`	A cluster must be ≥80% successful.
`SIMILARITY_TAU`	`0.82`	Cosine threshold on goal embeddings, for clustering and recall match.
`max_clusters_per_pass`	`10`	Caps LLM calls per synthesis pass — bounds cost.

The format contract

The pipeline emits a SKILL.md; it does not define the format. The format is Skill Format (#691), now authored and locked. This spec references that schema and never redefines a field. The subtlety — and the single most important correctness point — is the split between what the LLM emits and what Skill.parse() injects. The guiding rule: the LLM emits only the fields it derives from the learned procedure; fixed constants are injected, never emitted. So DISTILL_SYSTEM_PROMPT asks the model for an intermediate frontmatter of four learned fields, and a deterministic Skill.parse() maps them to the canonical #691 document and adds the two constants:

Field	Origin	→ Canonical `SKILL.md` (#691)	Why
`name`	LLM (derived)	`name`	Identity, derived from the cluster. Matches the rule at `skill-format.mdx:150`.
`when_to_use`	LLM (derived)	`description`	`when_to_use` is the LLM-emitted field on purpose — it forces the model to conclude the trigger boundaries of the skill; `description` is too vague a label to constrain it. Its embedding is what `recall_skill(goal)` matches against. Maps to the required `description` (`skill-format.mdx:151`).
`tools_required` (top-level)	LLM (derived)	`metadata.gaia.tools_required`	The tool set the procedure actually used. #691 locks `tools_required` as the cross-spec recipe contract and nests it under `metadata.gaia` (`skill-format.mdx:143`, `:158`).
`markdown_body`	LLM (derived)	body	The LLM writes the *full procedure — numbered steps and* a `## Edge cases` section — inline**. `Skill.parse()` does not synthesize a separate edge-case section; the distilled body already carries it.
`license: MIT`, `version: 1.0.0`	`Skill.parse()` (fixed)	`license`, `version`	*Fixed constants, not learned content — the LLM does not* emit them.** `license` is always the repository license (`skill-format.mdx:152`); a freshly synthesised skill is always `version: 1.0.0` (SemVer — `skill-format.mdx:153`). Injecting them keeps the prompt’s output surface purely dynamic and removes any chance the model emits a wrong version.

A synthesised recipe therefore emits a bounded field set — name, description, license, version, metadata.gaia.tools_required, and the body. It does not emit security_tier, permissions, requirements, or provided tools (skill-format.mdx:154–:157): those are install-time trust and capability concerns owned by #691 / the marketplace (#647), explicitly out of #887’s scope. Each is optional in #691, so the file still validates; an omitted security_tier defaults to the most-restrictive experimental at load time. This is the one deliberate refinement of the maintainer’s pseudocode: his DISTILL_SYSTEM_PROMPT listed version: 1.0.0 inside the LLM’s required output (#887 technical-spec comment); this spec moves version (and license) to Skill.parse() injection because both are fixed, not derived. The pipeline otherwise keeps the maintainer’s prompt as written, and (a) treats the four learned fields as the intermediate shape, (b) specifies Skill.parse() as the translator to the locked schema, and (c) guarantees the emitted file validates under #691 — an explicit acceptance criterion (see Acceptance criteria traceability).

Two corpora, one format — the boundary with the loader/parser

#887 and #691 own different corpora and do not conflict:

#887 owns the internal, learned corpus. Synthesised procedures live in the procedures table, recalled via recall_skill over procedures.embedding. #887 owns the synthesize → procedures → optional SKILL.md export path.
#691 owns the external, installed corpus. The proposed gaia.skills loader (greenfield — skill-format.mdx:16) loads installed SKILL.md files from ~/.gaia/skills/<name>/ (agent-skills.mdx:193).

They meet only at the format: an exported #887 procedure is a valid #691 document, so it is installable like any other skill. They never share a table or a parser.

The tool-loader contract

Dynamic Tool Loader Part 3 is the named consumer. It is gated on #887 and returns [] cleanly until this lands, so the contract must match its already-published wording byte-for-byte:

recall_skill(goal) is “a vector search over procedures.embedding” in the same MemoryStore (tool-loader.mdx:358) — this spec’s procedures table provides exactly that column and index.
When a skill matches, the loader unions its tools_required ahead of semantic results (tool-loader.mdx:351) — this spec emits tools_required (the locked #691 field) on every recipe procedure.
The selection formula is loaded = CORE ∪ SKILL ∪ SEMANTIC ∪ escape-hatch, precedence CORE > SKILL > SEMANTIC (tool-loader.mdx:362). #887 is the producer of the SKILL input; it adds nothing to and removes nothing from that formula.

This spec is the producer side of a soft dependency. It does not modify the loader. Until #887 ships, the loader’s SKILL signal is []; once it ships, the signal is non-empty for goals that match a stored procedure. Parts 0–2 of the loader are unaffected either way.

Reuse of the memory v2 layer

Every primitive the pipeline needs already exists in #606. The table below maps each reuse to its verified file:line on main.

#	Reused primitive	`file:line`
1	`MemoryStore` over `~/.gaia/memory.db`	`memory_store.py:297`, `:300`, `:308`
2	`tool_history` (`session_id, tool_name, args, result_summary, success, error, duration_ms, timestamp`) — the episodic trace `extract_sequences` walks	`memory_store.py:241`
3	`nomic-embed-text-v2-moe-GGUF`, `EMBEDDING_DIM = 768` — reused to embed goals; no new model	`memory.py:148`, `:151`
4	FAISS `IndexFlatIP` over L2-normalized vectors = cosine — the index pattern `procedures.embedding` copies	`memory.py:687`
5	Mem0-style `_EXTRACTION_PROMPT` (ADD/UPDATE/DELETE/NOOP) — the distil-and-reconcile pattern	`memory.py:186`
6	`_CONSOLIDATION_PROMPT` / `_RECONCILIATION_PROMPT` — prior art for an LLM-in-the-loop maintenance prompt	`memory.py:222`, `:235`
7	The maintenance pass `_run_memory_post_init` → `reconcile_memory` + `consolidate_old_sessions` — the hook point	`memory.py:1206`, `:1377`, `:1233`
8	`superseded_by` column + additive `_migrate_schema_locked` — the supersede + migration patterns	`memory_store.py:227`, `:364`
9	`_compose_system_prompt` — where the matched procedure body is injected	`agent.py:591`
10	`/api/memory/*` router + `X-Gaia-UI` CSRF guard — the surface the dashboard reads procedural data through	`ui/routers/memory.py:26`, `:29`

Why procedures is a separate table

The maintainer’s tech spec left the storage shape open — “procedures (or knowledge with kind='procedure')”. This spec chooses a separate procedures table, because knowledge and procedures diverge on every lifecycle axis. knowledge (memory_store.py:209) stores atomic beliefs; procedures store generalized multi-step policies.

Axis	`knowledge` (fact / preference / note)	`procedures` (learned skill)
Origin	one conversation turn (Mem0 extraction) or the `remember()` tool	a cluster of ≥3 successful runs (`distill_cluster`), gated on occurrence + success-rate thresholds
Unit	one sentence of `content`	a whole `SKILL.md` (frontmatter + multi-step body)
Quality signal	`confidence` REAL (`memory_store.py:215`) — a belief strength	`success_count` / `attempt_count` — an empirical track record
Removal	confidence-pruned or `forget()` (deleted)	`enabled` toggle — kept, not deleted (AC: disabling blocks recall)
What’s embedded	the `content` (the fact text)	`when_to_use` (the goal/trigger) — a different corpus, for goal→procedure matching
Recipe contract	none	`tools_required` consumed by the tool-loader (#1451)
Provenance	single `source` enum (`memory_store.py:214`)	a list of `from_sessions` distilled from `tool_history`

Two consequences make a shared table actively harmful:

Embedding-corpus mismatch. recall_skill matches a goal against a trigger embedding; knowledge recall matches a query against fact-content embeddings. Mixing both in one FAISS index (memory.py:687) pollutes both result sets — procedures need their own index over procedures.embedding, exactly what the tool-loader spec promised (tool-loader.mdx:358).
category='skill' is already taken for something else. VALID_CATEGORIES already contains "skill" (memory_store.py:97), but that is a user-told skill fact (“I know vim”), not a synthesised multi-step procedure. Reusing it would conflate two unrelated concepts, and every procedure-only column (success_count, tools_required, enabled, provenance) would be NULL on all of today’s knowledge rows.

Only embedding and superseded_by echo knowledge, and even those carry different semantics (goal vs content; success-rate vs contradiction). The choice is confirm-at-PR-review, not a pre-authoring blocker (see Open questions).

Off-states as safe floors

Every degraded condition lands on a conservative floor — the pipeline produces no procedural signal, never a broken recall or a silent wrong answer. The failure-mode rows are the maintainer’s table, grounded against the real config surface.

Condition	Who triggers it	Floor behavior
Memory disabled (`GAIA_MEMORY_DISABLED=1`, `memory.py:332`)	Deliberate user setting	No store → no synthesis, no recall. `recall_skill` returns `[]`; the loader’s `SKILL` signal is `[]`. Identical to a build without this feature.
Synthesis disabled (`enabled = false`)	Deliberate user setting	The maintenance pass skips `_synthesize_skills`, logged at INFO. Already-stored procedures remain recallable.
A specific procedure disabled (`enabled = 0` on the row)	User (via the #606 dashboard track)	`recall_skill` excludes it — satisfies the AC “disabling a skill prevents it from being recalled.” The row is kept, not deleted.
Lemonade down during the distillation call	Failure	Skip the whole synthesis pass, log loudly. No silent downgrade to a smaller model.
Malformed `agentskills.io` output from the LLM	Failure	Skip that cluster, log; no truncation, no auto-fix.
Embedder fails	Failure	Re-raise — synthesis cannot proceed without embeddings (matches memory v2’s embed-failure posture).
No matching procedure at recall	Normal	`recall_skill` returns `[]`; the planner prompt is unchanged; the loader falls through to CORE + semantic.

This collapses the three user-chosen off-states (memory off, synthesis off, a disabled procedure) onto “no procedural signal” — a user can never lose a capability the agent had before — while the three failure states fail loudly per CLAUDE.md’s no-silent-fallback rule. The distinction is in the messaging (silent-and-expected vs actionable-error), not the mechanism: all of them leave the agent on its pre-synthesis behavior.

Trust boundary for injected bodies

A synthesised procedure is model-authored text that re-enters the planner’s system prompt through recall_skill → _compose_system_prompt. That makes it a trust boundary — and a self-reinforcing one: a procedure distilled from a run that itself followed an earlier weak procedure could entrench that weakness. Three rules keep the loop honest:

Internal corpus only. A body injected at planning time comes only from the local procedures table — never a network source, an imported file, or an installed ~/.gaia/skills/ document. The external corpus (#691) loads through a different path and never crosses into the injection seam (see The format contract).
No auto-export. Synthesis writes to the procedures table only; it does not auto-write a SKILL.md to disk or publish anywhere. Promoting a procedure to the installable corpus is an explicit, user-initiated action on the marketplace track (#647) — a human reviews before a synthesised procedure becomes shareable.
Empirical gate, not just plausibility. A procedure only exists because a cluster of ≥ MIN_OCCURRENCES runs cleared MIN_SUCCESS_RATE at synthesis; once its track record decays it is superseded (Zep lineage) or disabled, so a once-good policy that starts failing stops being recalled. The distiller only ever reads the agent’s own tool_history — never raw network content.

This is a content-trust statement, distinct from the install-time security_tier / permissions controls, which gate the external corpus and stay out of #887’s scope (→ #691 / #647).

Correcting the original framing

The issue body and the maintainer’s pseudocode predate #691 locking and the current code; these are the corrections an implementer must internalize.

Original framing	Reality on `main`	Consequence
`DISTILL_SYSTEM_PROMPT` emits `when_to_use` + top-level `tools_required` as the on-disk shape	#691 locks `description` + `metadata.gaia.tools_required` (`skill-format.mdx:151`, `:158`)	The prompt fields are the intermediate shape; `Skill.parse()` maps them. See The format contract.
Scope C: “New tool: `recall_skill`”	The memory registry is exactly five tools (`memory.py:1984`+) and the planner calls recall programmatically	`recall_skill` is an internal method, not a sixth `@tool`. See Decided design.
Hook is `on_consolidation_pass` → `_consolidate_old_sessions / _reconcile_contradictions / _prune_stale`	Those names don’t exist; the real pass is `_run_memory_post_init` → `reconcile_memory` + `consolidate_old_sessions` (`memory.py:1206`)	Bind `_synthesize_skills` to the real maintenance method.
Tunables in `~/.gaia/config.toml [memory.skill_synthesis]`	Memory is configured via `~/.gaia/memory_settings.json` (`memory.py:57`) + `GAIA_MEMORY_DISABLED`; there is no `config.toml` `[memory]` section	Surface the thresholds on the existing memory-settings surface, not a new TOML section — see Open questions.
Storage: `procedures` or `knowledge` with `kind='procedure'`	`knowledge` has no `kind` column and `category='skill'` already means something else (`memory_store.py:97`)	A separate `procedures` table. See Why procedures is a separate table.

Retractions — do not build against these:

The intermediate frontmatter is not the on-disk schema. A reader of the maintainer’s DISTILL_SYSTEM_PROMPT must not write when_to_use / top-level tools_required to disk. The on-disk file is the #691 schema (description, metadata.gaia.tools_required); Skill.parse() is the only bridge.
recall_skill is not an LLM tool. Do not register a sixth memory @tool; it would change the five-tool registry the rest of the system assumes.
There is no [memory.skill_synthesis] TOML section to extend — it does not exist on main. Config rides the existing memory_settings.json surface (the exact key location is an open question).

KPIs

The pipeline is judged by the acceptance criteria, gated by no-harm — a loop that synthesises garbage or breaks recall is worse than no loop.

KPI	Type	Target
Auto-synthesis fires	Headline (the issue’s first AC)	After ≥3 successful similar sequences (≥`MIN_SUCCESS_RATE`), a `SKILL.md` is created and discoverable via `recall_skill()`.
Tool-step reduction	Outcome	The 4th attempt at a matched goal uses fewer tool steps than the unmatched baseline (measured against the tool-loader baseline harness).
Format validity	Correctness / grounding	100% of synthesised `SKILL.md` validate under #691 (agentskills.io / Hermes reference parser) — round-tripped, not asserted.
No silent fallback	Safety (hard guardrail)	Lemonade down → pass skipped + logged; malformed → cluster skipped + logged; embedder down → re-raise. Never a smaller-model swap.
Recall precision	Quality	`recall_skill` returns a procedure only above `SIMILARITY_TAU`; a procedure with `enabled = 0` is never returned.
Provenance integrity	Correctness	At synthesis time, every `procedures` row’s `provenance.from_sessions` resolves to the real `tool_history` sessions it was distilled from. A best-effort audit trail, not a foreign key — later `tool_history` pruning may dangle an id, which never breaks recall.

Phased build

Ship in reviewable phases; each phase holds the prior floor and earns its place with an eval run before merge (per CLAUDE.md).

Phase 0 — `procedures` schema + additive migration (PROPOSED)

Add the procedures table and a separate FAISS index over procedures.embedding; extend MemoryStore with put_skill / search_skills / supersede_skill / iter_sessions (all PROPOSED). Migration is additive only — a v2→v3 migration mirroring the v1→v2 ADD COLUMN pattern (memory_store.py:364). Success criteria:

A fresh DB and an existing v2 DB both open after the migration; the procedures table is present; no knowledge / tool_history row is altered (verified against a copied pre-migration DB).
The procedures FAISS index is independent of the knowledge index — building one does not touch the other.

Phase 1 — Detect → cluster → distill → reconcile/store (PROPOSED)

skill_synthesis.py with extract_sequences / cluster_by_goal / distill_cluster / Skill.parse / reconcile_and_store, hooked into the maintenance pass as _synthesize_skills after consolidate_old_sessions (memory.py:1233). Reuses the nomic-768 embedder (memory.py:148). Success criteria:

After 3 successful similar sequences (≥MIN_STEPS, ≥MIN_SUCCESS_RATE), a procedures row is created with a valid distilled body and correct provenance.from_sessions.
Fail-loud verified: a stubbed Lemonade-down skips the whole pass + logs; a malformed distill output skips that cluster + logs; an embedder failure re-raises — no smaller-model fallback in any path.
Reconciliation issues ADD / UPDATE / NOOP only (never DELETE); a higher-success_count candidate supersedes via superseded_by (memory_store.py:227).
gaia eval agent shows no regression on the affected category vs the committed baseline (LLM-affecting change — eval required per CLAUDE.md).

Phase 2 — `recall_skill` + planner injection + disabled-flag (PROPOSED)

recall_skill(goal, top_k=2) as an internal method (vector search over procedures.embedding); inject the matched body into the system context via _compose_system_prompt (agent.py:591); honour enabled = 0 in the recall path; emit tools_required for the tool-loader Part 3 union. Success criteria:

A matched goal injects the procedure body and the 4th attempt shows a measurable tool-step reduction vs the unmatched baseline.
Disabling a procedure (enabled = 0) prevents it from being recalled (the issue AC) — verified directly against the recall path.
A fixture procedure’s tools_required are unioned ahead of semantic results by the tool-loader, per tool-loader.mdx:369 — and with #887 absent the loader’s SKILL signal is [] (regression test).

Deferred — Memory Dashboard “Procedures” tab (NOT #887)

The dashboard tab is explicitly out of #887 — the maintainer’s tech spec lists it under “What this issue does NOT do … part of the dashboard work in #606’s deliverables; we just expose new data.” #887 stores and exposes the procedural data (count, last-used, provenance, enabled) through the existing /api/memory/* router pattern (ui/routers/memory.py:26), following the established three-tab dashboard shape (the DashboardTab union, MemoryDashboard.tsx:267). Rendering the “Procedures” tab and the “promote this conversation to a skill” button ride #606’s dashboard track, not this issue. The two dashboard ACs are deferred accordingly (see Acceptance criteria traceability).

Examples

All examples parse as YAML and validate under Skill Format. The recipe reuses triage-support-ticket (skill-format.mdx:415) so its tools_required resolve to real registry tools.

A. The synthesised SKILL.md (Skill.parse output — the on-disk #691 document)

What Skill.parse() writes after distillation — a valid #691 document. name, description, license, version, and metadata.gaia.tools_required are all the locked schema. Each tools_required name is a real registry tool (query_documents from RAGToolsMixin, read_file from FileIOToolsMixin, remember from the tool-loader CORE set, tool-loader.mdx:269). No security_tier is emitted — skill security tiers are explicitly out of #887’s scope (→ #647); the field is optional in #691 and the loader defaults an omitted tier to the most-restrictive experimental (skill-format.mdx:154).

---
name: triage-support-ticket
description: Triage an inbound support ticket end to end. Use when the user pastes a support ticket or asks to triage one.
license: MIT
version: 1.0.0
metadata:
  gaia:
    tools_required:
      - query_documents
      - read_file
      - remember
---

# Triage a Support Ticket

1. Pull matching policy docs with `query_documents`.
2. Read any attached log with `read_file`.
3. Record the disposition with `remember` for follow-up.

## Edge cases
- If no policy doc matches, escalate rather than guessing.
- A ticket with no attached log skips step 2.

B. The intermediate DISTILL_SYSTEM_PROMPT output (before Skill.parse)

What the LLM emits — only the four learned fields: top-level name, when_to_use, tools_required, and a body that already contains the ## Edge cases section. No version, no license — those are fixed constants. Skill.parse() maps when_to_use → description, tools_required → metadata.gaia.tools_required, and injects the fixed license: MIT and version: 1.0.0 to produce example A.

---
name: triage-support-ticket
when_to_use: Triage an inbound support ticket end to end. Use when the user pastes a support ticket or asks to triage one.
tools_required: [query_documents, read_file, remember]
---

# Triage a Support Ticket

1. Pull matching policy docs with `query_documents`.
2. Read any attached log with `read_file`.
3. Record the disposition with `remember` for follow-up.

## Edge cases
- If no policy doc matches, escalate rather than guessing.
- A ticket with no attached log skips step 2.

C. A stored procedures row

The record as stored — one row of the procedures table. embedding is the 768-float BLOB over when_to_use; provenance links back to the tool_history sessions it was distilled from; success_count/attempt_count is the empirical track record; enabled = 1.

{
  "id": "proc_01J9Z4F8K2",
  "name": "triage-support-ticket",
  "when_to_use": "Triage an inbound support ticket end to end. Use when the user pastes a support ticket or asks to triage one.",
  "markdown_body": "# Triage a Support Ticket\n1. Pull matching policy docs with `query_documents`.\n2. Read any attached log with `read_file`.\n3. Record the disposition with `remember` for follow-up.\n## Edge cases\n- If no policy doc matches, escalate rather than guessing.\n- A ticket with no attached log skips step 2.",
  "tools_required": "[\"query_documents\", \"read_file\", \"remember\"]",
  "tool_sequence": "[{\"tool\": \"query_documents\"}, {\"tool\": \"read_file\"}, {\"tool\": \"remember\"}]",
  "success_count": 4,
  "attempt_count": 5,
  "provenance": "{\"source\": \"synthesized\", \"from_sessions\": [\"sess_a1\", \"sess_b2\", \"sess_c3\", \"sess_d4\"]}",
  "version": "1.0.0",
  "enabled": 1,
  "embedding": "<768-float BLOB over when_to_use>",
  "superseded_by": null,
  "created_at": "2026-06-17T12:00:00Z",
  "last_used_at": null
}

D. recall_skill at planning time (the live contract surface)

recall_skill is called programmatically at turn start. The matched procedure’s body is injected into the system context; its tools_required feed the tool-loader’s CORE ∪ SKILL ∪ SEMANTIC union ahead of semantic results.

# PROPOSED — at turn start, before tool selection (internal method, not an @tool)
matches = self.recall_skill(user_goal, top_k=2)
# matches → [
#   Skill(
#     name="triage-support-ticket",
#     when_to_use="Triage an inbound support ticket end to end. ...",
#     body="# Triage a Support Ticket\n1. ...\n## Edge cases\n- ...",
#     tools_required=["query_documents", "read_file", "remember"],
#   )
# ]   # → [] when nothing matches above SIMILARITY_TAU, or when the row is enabled=0

# 1. Planner injection — matched body added to the system context built by
#    _compose_system_prompt (agent.py:591):
#      "Past procedures: ### Relevant skill: triage-support-ticket  <body>"
#
# 2. Tool-loader Part 3 (the consumer) unions matches[i].tools_required AHEAD of
#    semantic results, per tool-loader.mdx — loaded = CORE ∪ SKILL ∪ SEMANTIC.

Open questions

No blocking forks remain — the issue owner settled the design during planning. The items below are confirm-at-PR-review, not pre-authoring blockers; the maintainer said he will “steer from the PR” (#887 comment).

Config surface for the thresholds. The maintainer’s pseudocode puts tunables in ~/.gaia/config.toml [memory.skill_synthesis], but that section does not exist — memory is configured via ~/.gaia/memory_settings.json (memory.py:57) plus GAIA_MEMORY_DISABLED. This spec proposes surfacing the five thresholds on the existing memory-settings surface (mirroring how the tool-loader dropped its proposed config.toml section for ChatAgentConfig + env, tool-loader.mdx:312). Confirm the exact key location at PR.
procedures table vs knowledge.kind. This spec chose a separate table (Why procedures is a separate table); the maintainer’s tech spec left it open. Ratify the table choice at PR.
recall_skill injection-budget tuning. The spec sets a default cap of MAX_RECALL_BODY_CHARS = 1500 per body at top_k = 2 (see Decided design), which bounds the prompt addition and protects the tool-loader’s cache-warm seam (tool-loader.mdx:294). Confirm the exact value against a small-model eval at PR — a tuning question, no longer an open design fork.
Synthesis cadence. #606’s maintenance pass runs once per process on the first query (memory.py:1206). The issue also mentions “daily background”. Confirm whether v1 piggybacks on the existing per-process pass only, or adds a scheduled cron.
Nav placement. This doc registers under Ecosystem alongside skill-format and agent-skills. Confirm it stays there given the in-flight Agent-UI / Hub restructure (a placement check, not a design fork).

Current state of the code

The memory layer it builds on is real and merged; the synthesis pipeline is entirely greenfield.

Area	Symbol / fact	`file:line`	State
Memory store	`MemoryStore`, `~/.gaia/memory.db`	`memory_store.py:297`, `:308`	Exists (#606)
Episodic trace	`tool_history` table	`memory_store.py:241`	Exists — synthesis input
Embedder	`nomic-embed-text-v2-moe-GGUF`, `EMBEDDING_DIM = 768`	`memory.py:148`, `:151`	Exists — reused, no new model
Vector index	FAISS `IndexFlatIP`	`memory.py:687`	Exists — pattern for `procedures.embedding`
Maintenance pass	`_run_memory_post_init` → `reconcile_memory` + `consolidate_old_sessions`	`memory.py:1206`, `:1377`, `:1233`	Exists — the hook point
Distillation prior art	`_EXTRACTION_PROMPT`, `_CONSOLIDATION_PROMPT`	`memory.py:186`, `:222`	Exists — Mem0 pattern
Supersede + migration	`superseded_by`, `_migrate_schema_locked`	`memory_store.py:227`, `:364`	Exists — additive pattern
Memory tools (five)	`remember`, `recall`, `update_memory`, `forget`, `search_past_conversations`	`memory.py:1984`, `:2067`, `:2250`, `:2335`, `:2344`	Exists — `recall_skill` is not one of them
Prompt composition	`_compose_system_prompt`, `_select_tools_for_turn`	`agent.py:591`, `:786`	Exists — injection seam
Memory REST + dashboard	`/api/memory/*`, `X-Gaia-UI` guard, three-tab dashboard	`ui/routers/memory.py:26`, `:29`; `MemoryDashboard.tsx:267`	Exists — exposes procedural data
`category='skill'` (a fact, not a procedure)	`VALID_CATEGORIES` includes `"skill"`	`memory_store.py:97`	Exists — different concept
`skill_synthesis.py` / `procedures` table / `extract_sequences` / `cluster_by_goal` / `distill_cluster` / `Skill.parse` / `SkillProvenance` / `reconcile_and_store` / `recall_skill` / `_synthesize_skills` / `put_skill` / `search_skills` / `supersede_skill` / `iter_sessions`	—	NOT FOUND (verified absent on `main`)	Greenfield — PROPOSED

Dependencies

Issue	Role	State	What #887 needs / gives
#606 memory v2	Blocking dependency	merged	The store, `tool_history`, the embedder, FAISS, the Mem0 pattern, the maintenance pass, the memory router — all reused (see Reuse of the memory v2 layer).
#691 Skill Format	Format contract	authored / locked	The `SKILL.md` schema #887 emits. #887 references it, never redefines a field (see The format contract).
#1451 tool-loader Part 3	Consumer (gated on #887)	open	The `recall_skill` + `tools_required` + `procedures.embedding` contract. #887 is the producer; the loader returns `[]` until #887 lands (see The tool-loader contract).
#553 self-improving agent	Consumer	open	#887 is the skill-extraction slice → partially resolves #553 (tool generation stays out of scope).
#647 marketplace	Downstream	open (v0.24.0)	A stable on-disk export path for synthesised `SKILL.md`. Marketplace UX is out of #887 scope.
#692 OpenClaw compat	Downstream	open (v0.24.0)	Format compliance only — inherited via #691.
#688 dynamic tool loading	Adjacent	open	The umbrella for the tool-loader; #1451 is its Part 3.

Acceptance-criteria traceability

Every Scope item and acceptance criterion from #887, mapped to its section and what it guarantees a consumer. Deferrals are explicit, with the track that owns them.

#887 scope / acceptance criterion	Section	Status / guarantee
Scope A — `procedures` table + additive migration	Decided design, Phase 0	Separate `procedures` table; additive v2→v3 migration (ratify at PR).
Scope B — synthesis loop on the consolidation pass (≥3 occ, ≥80%)	Decided design, Phase 1	`_synthesize_skills` after `consolidate_old_sessions`; fail-loud failure modes.
Scope C — `recall_skill(goal)` + planning injection	Decided design, Phase 2	Internal method, `top_k = 2`, injected via `_compose_system_prompt`.
Scope D — adopt the agentskills.io `SKILL.md` format	The format contract	Emits the locked #691 schema; resolves #691 by reference.
Scope E — Dashboard “Procedures” tab + provenance + promote	Phase 2 deferral	Tab build DEFERRED to #606’s dashboard track; #887 stores provenance + exposes the data.
AC — after 3 successful similar sequences, auto-create a `SKILL.md` discoverable via `recall_skill()`	KPIs, Phase 1 + Phase 2	The headline KPI.
AC — recall measurably reduces tool-step count on the 4th attempt	KPIs, Phase 2	Measured vs the tool-loader baseline.
AC — synthesised skills are valid agentskills.io documents (Hermes parser)	The format contract, Examples A–B	`Skill.parse()` round-trip; 100% validity KPI.
AC — Dashboard shows count / last-used / provenance	Phase 2 deferral	Data exposed by #887; rendering is #606’s tab.
AC — disabling a skill prevents recall	Off-states, Phase 2	The recall path honours `enabled = 0` (this is #887); the toggle UI is #606’s tab.
Out of scope — marketplace / tiers / OpenClaw shim	Dependencies	→ #647 / #692.

What's Next

Agent UI

Ecosystem

Infrastructure

Agents

Skill Auto-Synthesis

Why this exists

Prior art (credit before contribution)

Decided design

The synthesis pass hooks into the existing maintenance pass

The proposed `procedures` table

`recall_skill(goal, top_k=2)` is an internal method, not a sixth tool

Thresholds

The format contract

Two corpora, one format — the boundary with the loader/parser

The tool-loader contract

Reuse of the memory v2 layer

Why procedures is a separate table

Off-states as safe floors

Trust boundary for injected bodies

Correcting the original framing

KPIs

Phased build

Phase 0 — `procedures` schema + additive migration (PROPOSED)

Phase 1 — Detect → cluster → distill → reconcile/store (PROPOSED)

Phase 2 — `recall_skill` + planner injection + disabled-flag (PROPOSED)

Deferred — Memory Dashboard “Procedures” tab (NOT #887)

Examples

Open questions

Current state of the code

Dependencies

Acceptance-criteria traceability

​Why this exists

​Prior art (credit before contribution)

​Decided design

​The synthesis pass hooks into the existing maintenance pass

​The proposed procedures table

​recall_skill(goal, top_k=2) is an internal method, not a sixth tool

​Thresholds

​The format contract

​Two corpora, one format — the boundary with the loader/parser

​The tool-loader contract

​Reuse of the memory v2 layer

​Why procedures is a separate table

​Off-states as safe floors

​Trust boundary for injected bodies

​Correcting the original framing

​KPIs

​Phased build

​Phase 0 — procedures schema + additive migration (PROPOSED)

​Phase 1 — Detect → cluster → distill → reconcile/store (PROPOSED)

​Phase 2 — recall_skill + planner injection + disabled-flag (PROPOSED)

​Deferred — Memory Dashboard “Procedures” tab (NOT #887)

​Examples

​Open questions

​Current state of the code

​Dependencies

​Acceptance-criteria traceability

Why this exists

Prior art (credit before contribution)

Decided design

The synthesis pass hooks into the existing maintenance pass

The proposed `procedures` table

`recall_skill(goal, top_k=2)` is an internal method, not a sixth tool

Thresholds

The format contract

Two corpora, one format — the boundary with the loader/parser

The tool-loader contract

Reuse of the memory v2 layer

Why procedures is a separate table

Off-states as safe floors

Trust boundary for injected bodies

Correcting the original framing

KPIs

Phased build

Phase 0 — `procedures` schema + additive migration (PROPOSED)

Phase 1 — Detect → cluster → distill → reconcile/store (PROPOSED)

Phase 2 — `recall_skill` + planner injection + disabled-flag (PROPOSED)

Deferred — Memory Dashboard “Procedures” tab (NOT #887)

Examples

Open questions

Current state of the code

Dependencies

Acceptance-criteria traceability