Skills as a first-class knowledge-page type: hand-authored first version, targeted delta maintenance, cautious automation

[xiaoxiaoHe-E]

Problem

Coding agents accumulate procedural knowledge — release steps, workarounds, "how we do X in this repo".
Hindsight today stores declarative knowledge very well (knowledge pages / mental models: "what this repo is"),
and always-on rules (directives). There is no home for "how to do a thing", and no lifecycle for it.

Claude Code / Hermes-style skills are the established shape for this: a short description used for
routing, a markdown body loaded only on demand. I'd like to propose skills as a knowledge-page type in
Hindsight, and I've done some local experimentation on the maintenance half. Sharing the findings first
because one of them changes where the fix belongs.

Why not just use what exists

	directive	knowledge page	skill (proposed)
Body author	human (content required)	server-synthesized from memory	human first version, server maintains deltas
How it reaches the model	force-injected into the system prompt	agent tool retrieval + coding-agents roster	roster carries name+description/summary; body read on demand
Knowledge shape	short rule	declarative — "what this is"	procedural — "how to do this"
Context cost	every reflect	full text once retrieved	one index line by default

A skill needs the directive's human authority, the knowledge page's delta maintenance, and a routing
semantic neither has. Conversely: if the body ends up unconditionally injected, a skill is just a long
directive and the concept isn't worth building. That's the load-bearing constraint.

Where whole-document rewrites actually come from

I ran a local experiment maintaining a hand-authored procedural page under mode: delta (setup and results
in the appendix). Short version: delta maintenance of hand-authored content works, but only inside a
scope that doesn't drift — feeding it topic-overlapping but semantically drifted memories rewrote the entire
document and erased every hand-written step line.

My first instinct was "delta reuses the reflect prompt, so skills need their own delta prompt." Reading the
code shows that's not where the problem is. A refresh is two stages across two independent LLM calls:

1. Synthesis leg — an agentic reflect_async(answer_as_document=True) loop, prompted with the
   bank-level reflect_mission plus a hardcoded refresh context. Produces a candidate document.
2. Delta leg — a single call with its own dedicated prompt, emitting structured ops
   (append_block / replace_block / add_section / …). Blocks no op mentions are deep-copied verbatim —
   the module comment says prose drift is "structurally impossible" here.

The delta prompt is already separate and already safe. The drift is produced in stage 1, and stage 2
faithfully merges it. The other failure path is delta not running at all and falling back to full: five
reasons, of which source_query_changed matters most for hand-authored content — changing
source_query at all makes the next refresh regenerate the whole document. Which is unfortunate, because
"tighten source_query" is exactly the fix my experiment landed on. Those two behaviours currently fight
each other.

Consequence: the fix isn't a new delta prompt. It's (a) a per-page synthesis instruction, (b) protecting
hand-authored content from the full-refresh fallbacks, (c) tighter scope.

Proposal

P0 — put description or a summary in the coding-agents page roster (small, standalone, useful now)

The session roster currently renders - <title> (<id>); the page list parser drops description even
though the API returns it. So the agent has only a title to decide whether a page is worth reading, and
description is reachable only by explicitly calling hindsight_list_knowledge_pages.

Rendering - <title> (<id>) — <description> improves routing for all knowledge pages, and is exactly the
progressive-disclosure shape skills need. This is worth doing regardless of whether the rest of the proposal
lands, and I'm happy to open it as its own PR.

P1 — hand-authored skills

• Accept a caller-supplied content on mental-model and knowledge-page create/update, across HTTP and
  MCP (MCP currently hardcodes the "Generating content..." placeholder and can't set content at all;
  update_knowledge_page has no content parameter). Skip async generation when content is supplied and
  return a null operation_id — CreateKnowledgePageResponse.operation_id is already nullable.
• Stamp last_refreshed_at / last_memory_seen_at on hand-authored creates so a fresh skill isn't
  immediately stale. Documented consequence: memories predating the skill are never auto-merged.
• Identify skills with the existing type:<x> tag convention plus managed (the column already exists with
  exactly the "system-owned vs hand-authored" semantic, but isn't exposed on the API). Zero migration.
  A subtype='skill' column is the alternative — it allows SQL-level isolation, but the CHECK constraint has
  already drifted between Postgres and Oracle (('structural','emergent','pinned','learned') vs
  ('directive','pinned')), and nothing reads subtype for behavior or selection today — the only read is a
  based_on context label that defaults to 'structural' — so the read path that matters (a WHERE predicate
  for isolation) would all be new. My preference is the tag first, the column only if reflect isolation demands a WHERE predicate.
• Default skill trigger: mode=delta, refresh_after_consolidation=false, exclude_mental_models=true —
  human content is not auto-rewritten unless the user opts in.
• Exclude skills from reflect by default. Note the gate is currently an unqualified
  SELECT COUNT(*) … WHERE bank_id = $1, so a single skill in a bank makes the agent's forced first step a
  search_mental_models call — that's the concrete mechanism by which skills would pollute reflect and burn
  tokens. The existing exclude_mental_models flag is all-or-nothing (it skips the count entirely, bank-wide),
  so it can't express "exclude skills only" while keeping declarative models in the loop — that isolation is
  exactly what the proposal wants to add.

The one invariant this breaks: knowledge-page bodies are currently always server-synthesized from
memory. Accepting a hand-authored content breaks that. If maintainers consider the invariant load-bearing,
skills can only live as bare mental models — at the cost of the tree, hindsight fs mount, and the roster.
That trade-off is the piece I'd most want a maintainer's read on before writing any code.

P2 — targeted maintenance (the real go/no-go gate)

• Per-page refresh_instructions, feeding the synthesis leg. Split the two concerns that
  source_query currently conflates: source_query = what to retrieve (it drives embedding + BM25, so long
  instructions pollute retrieval), refresh_instructions = how to write. Skill default would be a
  procedural-playbook instruction: exact steps, exact commands, known traps, append-only into existing
  structure.
• Protect hand-authored content from full-refresh fallbacks. For managed=false documents,
  source_query_changed and delta_ops_all_skipped should skip-and-flag rather than silently regenerate;
  full rewrite becomes explicit (force_full, or gated behind a dry-run diff).
• locked — block-level (delta ops targeting a locked block are skipped) and document-level (skip
  automatic refresh entirely).
• Acceptance must include the failing construction, not just the clean one: feed topic-overlapping,
  semantically drifted memories and verify the hand-written sections survive. Passing only on clean input is
  not a pass.

P3 — automatic skill creation (default off, drafts only)

This is the only stage that can make the value floor negative — a wrong skill actively misleads. So:
drafts only, never published without human approval; N≥2 gate (a pattern must appear in ≥2 independent
sessions); an anti-pattern blacklist (environment failures, negative claims, already-self-healed errors,
unresolved failures); update-preference order (update the loaded skill → merge into an existing sibling →
only then create); a per-bank draft quota.

Two practical notes: the coding-agents integration already has a turn-cadence mechanism, so "review every N
turns" needs no new machinery. But the transcript reader compresses tool_use into a one-line action and
discards tool_result — so "did that command actually work" isn't in the distillation input, which is
precisely the behavioural signal this stage depends on. Keeping a result code / first line (not the full
body) would likely be a prerequisite.

Also worth stating explicitly: the coding-agents tool surface deliberately does not expose page CRUD
("agents never author page structure"). Draft distillation would run server-side and keep that invariant
intact — but if maintainers read it differently, that's worth settling before any of P3. And P3 is
separable: stopping at P2 (hand-written + maintained) is a legitimate resting point that strands nothing.

Happy to split this into separate issues and start with P0 if the direction looks right.

---

Appendix — the local experiment

Setup: one hand-written procedural page (release flow: build → test → ship) with mode: delta, then
repeated "retain a related memory → refresh" rounds, diffing the body byte-for-byte each round.

Round 1 — failed. The memories I retained shared keywords with the page topic but had drifted
semantically ("release verification round N: N bug fixes confirmed" — same word "release", different
subject). The refresh rewrote the whole document into a verification-rounds table; every hand-written step
line was gone.

Round 2 — passed, 7/7. With source_query tightened to explicitly exclude the confusable topic and only
genuinely on-topic memories retained: the no-op refresh was byte-identical; new facts were appended
surgically; hand-written lines stayed byte-stable across 5 rounds; a manual edit survived the next refresh.

Two side findings from the same run: dry-run-refresh and the real refresh are two independent LLM calls, so
the preview is directional and not a contract; and a trigger.tag_groups scope silently retrieved nothing,
because TagGroupLeaf.match defaults to any_strict (which requires non-empty tags) while observations in a
shared scope carry none — two colliding defaults rather than a bug, but worth documenting.

[jimy-r]

The hand-authored-first split you propose is the load-bearing design choice, and one constraint from running it is worth building in early: make hand-authored text win conflicts by construction, not by convention. In our setup machine-maintained content lives in a fenced, subordinate block inside the skill file; the server may rewrite its own fence but never the human text, so an errant delta can't silently reword an instruction someone wrote deliberately.

Second constraint: maintenance writes follow four-operation discipline (add, update, delete, no-op) rather than append, because append-only delta streams are how a skill body accretes contradictions.

And keep an adoption gate between a proposed delta and the live page: a skill doc is effectively editable weights, and closed self-edit loops on instruction text have a measured degradation mode.

Pattern write-up: https://github.com/jimy-r/agent-workspace-architecture/blob/main/PATTERNS.md#10-a-skill-is-editable-weights--never-adopt-a-self-edit-without-a-gate

[Sanderhoff-alt]

Strong +1 on the direction — treating Skills as a first-class knowledge-page type (or extending knowledge pages to support a Skill mode) brings clear architectural value: human-authored initial baselines, progressive disclosure (name + description in the roster, body loaded on demand), and guarded delta maintenance fill a genuine gap for procedural knowledge.

One conceptual distinction worth clarifying regarding Directives:
Directives are fundamentally meta-rules / behavioral constraints injected into the system prompt to guide how the agent reasons (e.g., language selection, anti-hallucination, temporal conflict arbitration) — they were never meant to serve as document bodies or task SOPs.

The reason they surfaced as a comparison is largely an artifact of current API mechanics (where Directives happen to be the only entity accepting caller-supplied content on write, while Knowledge Pages are currently server-synthesized). Once Knowledge Pages support human-authored initial content and on-demand progressive disclosure (P0/P1), the conceptual boundaries become very clean:

• Directives: Always-on behavioral guardrails for reasoning.
• Skills: Task-specific procedural SOPs living in the Knowledge Base, routed and fetched on demand.

Looking forward to seeing P0 (description in roster) and P1 land!

[nicoloboschi]

I've been thinking about this and it makes sense somehow but not in the form you described.

One thing that would make this better would be a new type of Document that is also a Knowledge Page (or part of the tree somehow)

the reason is that we can automatically ingest it as usual and via a simple flag on the retain (like knowledge_page_tree_parent_folder_id or something) it becomes part of the tree. then all the updates/delete op are available already. it's automaticlaly available in recall and any other operation.
users can decide to set a tag to filter in/out in all the operations.

the "prefer hand-authored knowledge page" over other documents is something we can make part of the reflect/refresh mechanism so kwnoledge pages steer in that direction. although this is not that simple as knowledge pages can change.

on the skill part, I thought about it and the kwnoeldge pages api is basically already a skill so I don't see any new work here. except if if you want we coild add an "Export as Skill" but then it becomes obsolete soon and I don't see the value again.

if you could explain more your use case of "hand-authored" vs derived and what are actual, concrete, content you'd see in one and another that would be really helpful to weigh in this solution

[jimy-r]

Happy to make the split concrete from ours, since we run exactly this division daily. The OP's case may differ.

Hand-authored content is the behavior-bearing text. Procedures and their ordering, preconditions, red flags, hard constraints of the never-do-X kind, and the reasoning for why this shape was chosen over the alternatives. It changes rarely, only by deliberate human edit, and a wrong sentence in it changes what the agent does. In our skill files this is the whole body.

Derived content is the world-describing text. Status lines, rosters, counts, extracted summaries, links into source documents. It goes stale constantly, and the correct maintenance is regeneration, so it lives in a fenced machine-maintained section inside the page, subordinate to the hand-authored body. The classification test we apply to any sentence is whether being wrong would change behavior or merely describe the world stale. Behavior-bearing text goes to the human layer, world-describing to the derived layer, and world-describing text should point at its source rather than copy it, because a pointer cannot contradict the file it names.

On preferring hand-authored pages through the reflect mechanism, the one lesson we'd press is that the preference has to be structural. Steering is a convention, and a convention loses to one errant delta eventually. A fence the machine cannot cross survives every delta, and that is what makes the cautious-automation half safe to run at all.

[xiaoxiaoHe-E]

Thanks, this helps clarify the distinction I was trying to make.

My main concern is not necessarily introducing a new storage type called Skill. I care about supporting the current, widely used skill format as the user-facing model:

• a title or name;
• a short description that can be shown to all coding agents for routing;
• progressive disclosure, where the full body is loaded only when needed;
• the ability to start from hand-authored content and improve it over time based on local usage experience.

There are many procedural skills I use day to day that do not exist in historical conversations or in the code repository. This is especially important when bootstrapping a coding-agent setup for a repository.

For example, the DeepSeek Harness project has been changing frequently, so I created a local update-dsh skill that describes how to update the repository, rebuild it, verify that the required plugins are installed and working, switch the active snapshot, and restart the running service. I would like to store that skill in Hindsight so that all coding agents can discover and follow the same update process. The initial content already exists and is authored by me. After using it over time, I may want to refine it based on new failure modes or better procedures.

Another example is our internal engineering workflow. We have established procedures for creating a story, implementing it, submitting code and tests, and closing the story. These procedures are not necessarily present in the repository or in the agent's conversation history, but they are already documented as internal workflow skills. I would like to import them into the coding-agent environment and make them available to all agents.

This is why I think the ability to create a Knowledge Page with caller-supplied initial content is important. The distinction I see is:

• Hand-authored procedural content: an existing SOP, playbook, or workflow that should be treated as authoritative and preserved.
• Derived content: knowledge synthesized from retained observations or historical usage, which the server can maintain or regenerate.

The current Knowledge Page API seems primarily designed for the second case: the server synthesizes the body from memories. It does not currently provide a way to create a page with an existing, hand-authored body and then maintain it conservatively over time.

I am open to the Document + Knowledge Page/tree approach you suggested. I am not attached to Skill as the underlying database type. The important part is that the resulting Knowledge Page can be exposed in a skill-like way to coding agents: title and description in the roster, full content loaded on demand, and controlled refinement as new usage experience becomes available.

I also think updates to these pages need more specific maintenance instructions than the generic reflect/refresh prompt. Procedural skills should be updated as playbooks: preserve exact commands and deliberate instructions, add or revise steps when supported by new evidence, and avoid replacing the whole document because of memories that are semantically related to the topic but actually unrelated to the procedure. Skill updates are not expected to be very frequent, and correctness is especially important for a skill. For that reason, it should also be possible to identify and promptly correct pages that have drifted from the intended procedure over time.

Hopefully these examples make the use case and the desired lifecycle more concrete.

[jimy-r]

The authored/derived split you've landed on is, I think, the whole design. We run the same boundary under a different name: hand-authored content is authoritative, machine-derived content lives in a fenced, subordinate block, and hand-authored wins every conflict by construction.

That suggests the Knowledge Page API needs three things rather than one: caller-supplied initial body (your ask), a provenance field on the page (authored vs derived), and an update policy keyed to it. Derived pages can regenerate freely — they're a view over observations. Authored pages like your update-dsh SOP should change only through explicit, reviewed edits, never silent regeneration, because the skill is editable weights: each revision changes how every future agent behaves, so an unreviewed "improvement" is an unreviewed behaviour change.

The refine-over-time loop you describe then stays safe: the server can propose an edit to an authored page from usage evidence, but adoption is a gated diff, not a regeneration. That one distinction keeps bootstrapped SOPs trustworthy while still letting them learn.