Agents Memory, Skills and Tools

P Three forms of retained capability. Memory records what is known, with evidence and limits. A skill describes how to accomplish a domain task: when it applies, the procedure, tools, judgement points and proof. A tool is runnable source code and/or a binary that performs a bounded step the LLM would otherwise repeat. Their purpose is to make experience improve the next execution: less model work, lower latency and usage, and more consistent results. Those improvements are measured, not assumed.

Part I covers memory, Part II skills, and Part III tools as a learning outcome. Each has an owner, version, tests and provenance. A profile may own an explicit set of domains; each domain has one canonical owner (Agents § 0.1). Module-specific catalogues remain under the module's agent tree: Configuration, Support, Data & Manipulation, Development.

The memory convention is already estate practice [F: serdica-backend has a root AGENTS.md on master, and the AI branch carries 40 per-module AGENTS.md guidance files — inspected 31.08.2026]; the PC agent's routed 20-document library is the proven single-domain instance [F: artifact].

P Retrieval strategies and indexing. Experience retrieval and memory strategies defines the distinct current-case registry, reviewed case experience and domain knowledge; purpose-based retrieval; root routing synopses; publication/index watermarks; and reuse checks. Memory remains canonical in its owning domain. Indexes project references rather than copy all memories into the classifier.

Part I — Memory

One writing profile per domain — profile, instance and domain are distinct (Agents § 0.1). Every node in the memory tree has an AGENTS.md index; the agent profile that owns the node boots from it, reads the whole tree, and writes nothing outside its own node.

1. The tree — the principle, and an example

P The shape. One tree. Its top-level branches are the platform's own knowledge, the connectors' knowledge (one node per system), and one branch per module. Below a module branch there is one node per thing that has an owning profile: a stage, a repository, a symptom family. A node exists because a profile writes it, never the other way round; a module's branch therefore has exactly the shape of its agent tree.

P The example — the two branches that belong to no module are real; the module branch is a schema, and each module page draws its own instance:

memory/
├─ AGENTS.md                          ← the protocol (§ 2)
├─ platform/
│  ├─ AGENTS.md                          sessions, gates, audit, runtime operations
│  ├─ intake/AGENTS.md                   source identity, normalisation and intake entitlement (Agents § 5c); classification belongs to Support
│  ├─ experience/AGENTS.md               the platform's case record — what was asked, what was accepted, per customer
│  └─ handovers/AGENTS.md                the consult catalogue and the handover packet per direction
├─ connectors/
│  ├─ AGENTS.md                          index of systems
│  └─ <system>/AGENTS.md                 one per connected system: per-env scoping, error decode, session budgets
└─ <module>/                          ← one branch per module — drawn at the head of the module's page
   ├─ AGENTS.md                          the module's rules and the index of its nodes
   ├─ <stage or repository or symptom>/  one node per owning profile
   │  └─ AGENTS.md
   └─ experience/AGENTS.md               where a module keeps a past-case index (§ 5) — Support does; the others read it

P What one node holds — the AGENTS.md index (one-liners, one per article, in the proven v1 MEMORY.md shape), the articles themselves, and nothing that belongs to another node. Contents are mechanics of the running system — table chains, traps, rules, what breaks and how — never a narrative. A domain that is a stage holds what the stage agent needs to plan; a domain that is a system (a connector's) holds how to reach it and how it fails; a domain that is a repository holds its service index and its build truths.

P Seeds. Every domain is seeded from material that already exists — v1 memory articles, the PC agent's library, the estate's own guidance files — and every seed is a fact with a link. Migration is per domain and accepted on a measurement (§ 7), never big-bang. The seed list per domain is on the module page beside the node it seeds.

2. The root AGENTS.md — the protocol

The root file every agent inherits. Its outline P:

1. Boot. An agent starts from its own node's AGENTS.md plus the task prompt — not the whole chain; a consulted profile also boots from its own node, not a chain (D106). But it is required to be aware of the rest of the tree: the index of every domain is always available to it, and it reads any node it judges relevant, at any depth, without asking. Boot is light; awareness is total. Writing stays restricted to the own domain.

Why both halves matter: loading the full chain at boot is waste on a narrow task, while an agent that does not know the rest of the tree exists reproduces v1's failure — knowledge that is present but never consulted. 2. Writing practice. ATA Spec 100 discipline: declarative present tense, one subject per document, statements are fact (sourced) / plan / challenge. Articles follow the proven upkeep rules [F: the PC agent's knowledge-upkeep rule]: belief order running system → consuming code → memory; four kinds of wrong (wrong/stale/ambiguous/environment-specific) with four treatments; fix the claim where it is made; guide-not-diary (no dates/sessions/incidents in bodies — provenance in metadata; values replaced by the regenerating query); record the pattern, never the incident; no customer PII F: [rule]. 3. Dreaming protocol (§ 4). 4. Node creation — only if really necessary. A new node needs: recurring content, a distinct owning profile, and a retrieval need the parent index cannot serve. Creating one updates the parent AGENTS.md index in the same change. Anything less stays as entries under the existing node. The automatic path — a summarizer creating a node an agent actually needed — is Agents § 0.6. 5. Reading another domain versus asking its agent. Reading is unrestricted, and the question that matters is not may I but which of the two: - Read the articles when you need a fact — a table name, a known trap, a rule of the running system. This is the default: it is cheap, it needs no coordination, and the article was written to be read. - Ask the owning agent when you need judgement — whether this case is the exception, what a contradiction between two articles means, or what is not written down. A lateral consult is evidence, never authority (Architecture § 2). - Always ask after two failed attempts at an unknown contract [F: the PC 9951 run]. Two failures mean the articles do not cover the case, and a third read will not fix that.

Why reading is not restricted: the memory tree holds no secrets and no customer PII by construction (rule 2), so restricting reads would buy no confidentiality — it would only hide knowledge from an agent that needs it, which is v1's measured failure. The real cost of reading everything is context and money, not exposure, and that is what the boot rule addresses: an agent boots with its own node and reads outward on demand.

6. Cross-domain findings. Handed to the parent (if it owns the domain) or to an instance of the owning domain's agent — never written directly into a foreign domain.
7. Case-local memory, and confirmation before common storage. Anything an agent learns inside a case is written first into the case's papers, which persist with the case (Agent Runtime § 11.2) — per-session memory is never lost, and no other case retrieves it. A finding worth reusing is filed as a proposal into the target domain: a proposed-state entry, absent from normal retrieval; the originating case and explicitly assigned validation cases may read it as a labelled candidate. Only on confirmation — a human review, or two independent cases that used it without contradiction (§ 7.4b) — does the domain's owning profile write it into the shared tree as active, reusable by every case. A proposal is evidence with provenance, never authority, and never another profile's write (Trust and Data § 1).
8. Escalation. Doubt and dead ends travel upward; only root agents reach the human.

An example of the protocol at work. A stage agent meets an unknown write contract. First attempt: it reads its own node and the connector's node — the fact is not there. Second attempt: it reads the neighbouring domain's articles — still not there. Rule 5 now applies: it stops and raises a consult to the owning domain, whose profile answers from the same nodes with the judgement the articles lack (Agents § 5, D92). What the consult taught is written case-locally (rule 7), filed as a proposal into the owning domain, and becomes shared knowledge only when the owner confirms it.

3. What a domain holds, and what seeds it

P The rule is the same for every domain: the mechanics of the running system a profile needs to plan, the traps it has met, and the seeds it was built from — each seed a fact with a link. The instances differ by kind:

P The per-domain tables — domain · owning profile · contents · seeds — live on the module pages, directly under the module's agent tree, so a reader sees the profile and the node it owns in one place.

4. The dreaming protocol

When a case closes (mandatory pass) and on schedule (consolidation):

1. Harvest candidates from the case papers and report: what was learned, what was reused, what was missing, and which repeated model work should become a tool.
2. Classify each: executable tool candidate (Part III), with its calling skill (Part II) · article (pattern) · experience entry · index line only · nothing (justified in the report).
3. Write within the own domain, under § 2 writing practice; candidates for foreign domains become proposals the owning profile confirms into shared storage (§ 2 rule 7); skills go through the governance flow (test → publish, Agent Framework § 6).
4. Cross-domain candidates are handed to the parent or the owning domain's agent instance — with the evidence, as a request record.
5. Consolidate (scheduled): merge duplicates, prune stale entries against the running system, resolve or explicitly mark contradictions, refresh the node's AGENTS.md one-liners.
6. New nodes only per the § 2 gate; parent index updated in the same change.
7. Every memory write is an audit record; the case chat shows memory operations live (Platform PG-5).

5. A past-case index

P Case journeys adds canonical source-request identity, family, confirmed trigger and actual outcome to the experience paper. Occurrence, verified reuse and clean platform execution are distinct counters. Proposed SQL and owner reports can teach a mechanism but do not count as an executed platform write. Extended metadata lives in the immutable source paper linked from the experience entry; mirrors, forks and subcases retain their shared origin. Configuration and Development submit experience through the same curator; their profiles retain stage/repository knowledge ownership.

P The principle. Triage needs "has this been seen before" over cases, in seconds — and past cases are not articles. Whichever module keeps the estate's memory of what breaks keeps a sub-index with this entry shape; every module reads it, and one profile writes it. In the Bulstrad case study that module is Support, the index is support/experience, and its owning profile is the curator (Data & Manipulation Module § 0).

• Entry: symptom signature (customer phrase + system error, verbatim) · systems/environment touched · mechanism found (one sentence, layer-named) · fix shape (data fix / config cell / code / answer) · links (analysis, KI, checklist, commit) · reusable artifacts (query pack, skill). No PII. Entries arrive as proposals from the agents that worked the case; the curator confirms them into shared storage (§ 2 rule 7).
• Indexes: a theme index (domain-grouped one-liners, the proven v1 MEMORY.md shape) + a symptom-signature lookup.
• Retrieval mechanics, granularity for multi-ticket sagas and staleness are stated once, for every past-case index, in § 7.3.

6. Reading another module's domain

P Every agent may read any node of the tree (§ 2 — boot is light, awareness is total). What it may not do is answer for a domain it does not own: a Configuration agent that reads the past-case index gets the articles, not the judgement. When the question needs judgement — has this shape failed before, and how does it fail? — the asking agent raises a consult, and the domain's own profile answers from the same nodes with the mechanics that go with them (Agents § 5). Why the distinction earns its keep: a past-case index is an index over cases, and reading an index without the methodology that built it is how v1's four documented error families recurred after their rule already existed.

P The past-case index is therefore written case-locally by the agent that worked the case and filed as a proposal; its curator promotes it into shared storage, read by every module. The platform's own case record — what a customer asked for and accepted, across modules — is platform/experience, a deterministic projection maintained by the platform's case-record handler; modules submit result references, not direct foreign-node writes.

7. Migrating an inherited corpus

AISA v1 holds 548 memory files, 509 ticket analyses (frozen baseline 31.08.2026), 56 known-issue entries and a set of living checklists (Baseline). That corpus is the platform's largest inherited asset and its most-cited goal (SG-7). It is also measurably not working as retrieval: the cross-session audit of 20.05.2026 found four error families recurring after the rule against them already existed F: [write-time discipline], while cached knowledge is 10–60× cheaper and 30–300× faster than rediscovery when it does fire F: [measurement].

So migration is not copying. Restructuring flat files into a tree changes where things live; it does not by itself make them fire. This section defines the method and, more importantly, the test that says whether it worked. The method is the same for any inherited corpus; v1's is the example.

7.1 The method

P The two memories are independent, and the migration is a one-time event (decision 01.09.2026). v1 keeps its own memory/; v2 has its own tree; neither writes into the other and nothing synchronises them. v2 supersedes v1 over time, and the corpus crosses once.

Why this is the simpler design: a shared tree during transition means two systems writing one domain, producing contradictions that neither notices. Independence removes that failure mode entirely, at the cost of a period where the same fact exists in both — acceptable because v1 is being retired, not maintained in parallel indefinitely.

P One-time does not mean one push: the migration is executed in waves (§ 7.4) so each domain is measured before the next starts (§ 7.2). What is one-time is the crossing itself — a domain migrates once, and after it has, v1's copy is no longer consulted for it.

Per domain, four passes:

1. Inventory — list the v1 files the domain's seeds name, plus what a grep of the domain's vocabulary finds. Record what was not taken and why.
2. Classify each item — mechanic (becomes pipeline behaviour or a skill, not an article), article (a pattern worth recalling), experience entry (a past case, § 5), index line only, or drop (superseded, environment-specific, or already true of the running system).
3. Rewrite under the writing practice (§ 2): declarative, one subject, guide-not-diary, values replaced by the regenerating query, the pattern not the incident, no customer PII.
4. Index — the domain's AGENTS.md one-liners are rewritten from the migrated content, not carried over.

P The classification is the point. v1's failure mode is that disciplines were stored as memory files that had to happen to fire. Anything that must always happen becomes a mechanic — a pipeline phase, a gate, an assertion, a skill — and is deliberately removed from the article set (Support Details SG-2).

7.2 The acceptance test

P Migration of a domain is accepted on a measured result, not on a file count:

Triage hit-rate on held-out cases. Hold back N resolved v1 cases the domain covers, excluded from the migration. Present each as it originally arrived. Measure how often the migrated domain surfaces the relevant precedent, mechanism, or checklist before investigation starts — and how often it surfaces a wrong one.

Recorded per domain: hit-rate, false-precedent rate, and time-to-first-relevant-item. The baseline to beat is v1's own retrieval — grep over flat files with one-line descriptions — measured the same way on the same held-out set. F Measured 02.09.2026 (Measurements § TB, scripts/triage_baseline.py): on 30 held-out resolved tickets, grep over the 619 MEMORY.md one-liners and KI titles finds a cited precedent in the top 5 for 3 of 30 (10 %), top-1 correct 1 of 30, 98 % of returned slots are noise, 7 tickets return nothing — Bulgarian symptom phrases against English one-liners are the main miss. This is the number every retrieval alternative (full article bodies, Bulgarian aliases, a vector index) is measured against on the same script.

P A domain that does not beat its baseline is not migrated; it is re-classified. Moving files without improving retrieval is the failure this test exists to catch.

7.3 The past-case entries

P Past cases are not articles; their entry shape is § 5. C Retrieval mechanics — title/grep index versus vector search (the estate retains Qdrant as a rebuildable index [F: docs/architecture/health-ai/00-program.md, inspected 31.08.2026]) — are decided by measuring § 7.2 on the migrated corpus, not by preference: both are cheap to try against the same held-out set. P Granularity for multi-ticket sagas — KI-anchored entries with case links first; a saga entry about one business object carries the keyed hash of the object number and never a person key (D44, Trust and Data § 4). P Staleness — entries carry the environment and version observed; re-verify before relying.

7.4 Order — the example

P Domains migrate in the order the tracks need them (Delivery § 1). For the first customer:

P platform/ has no v1 predecessor (§ 3), so it is written new rather than migrated. The domain names per wave are on the module pages.

7.4b Publication — memory is governed, not just written

P Candidate validation. A curator/owner may assign a proposed article revision to two explicit read-only validation cases. The candidate remains proposed, labelled derived, and absent from ordinary search. Each case records the article hash and an independent check against current evidence in MEMORY_USES plus its verdict paper. Cases must have distinct source-request identities; mirrors, subcases and forks of the proposing case do not count as independent uses. No contradiction and a passing check are required; mere retrieval is not a successful use. Until such evidence exists, use human review to promote.

P One canonical writer. The owner map is in Modules and MEMORY_DOMAINS. support.resolution owns support/methodologies; support.curator owns support/experience; each investigator owns its named symptom node. Curators/summarizers may draft for another node, but the owning profile activates the revision. A profile can own an explicitly listed set of nodes; ownership never follows whichever task happened to read one first.

P Memory is governed the way prompts and skills are — draft → test → publish — because the summarizer writes nodes automatically and memory informs without ever authorizing (Trust and Data § 1): an article that quietly misleads every future case is expensive even when it holds no authority.

P Every memory write carries provenance: which case, which profile version, which sources it was derived from, and whether a human ever reviewed it. An article whose provenance chain reaches untrusted content is marked as such and stays marked.

P Four storage/activation states, and the difference is what agents may do with an entry:

The shared tree holds only proposed/active/retired; the write into it is the owning profile's alone (§ 2 rule 7).

P Version pinning. A case records the article versions it relied on. When a later case contradicts an article, the earlier case's reasoning is still reconstructable — which is what makes a retraction traceable instead of a mystery.

P Rollback publishes a new version containing the previous accepted content, with its provenance and evaluation; retired records are not edited. Articles are immutable once active; a change is a new version.

P Dependency-scoped evaluation. Changing an article re-runs the eval sets of the profiles whose domain it sits in — not everything (CR-4 scoped by domain, per the cost envelope).

P The two-independent-uses promotion rule is the initial rule (decision 02.09.2026 — D56): it might promote a wrong article that happened not to be contradicted twice. Measure it on the migrated corpus before relying on it — the same held-out set as § 7.2 — and the rule is revised from that measurement, not from preference.

7.5 What is deliberately not migrated

P Workspace-operational memory that describes v1 itself — tool invocation quirks, connection state, session-handling workarounds — is not carried into the tree. It describes a system that is being replaced. Where such a file records a domain fact rather than a v1 mechanic, that fact is extracted and the wrapper dropped.

P The others/, hdesk/ and emails/ archives are evidence, not memory. Whether the past-case index links them in place or extracts entries from them is decided in wave 3, on the retrieval measurement.

Part II — Skills

A skill is a reusable domain procedure with typed inputs, applicability conditions, tool bindings and assertions. It may be fully automated, or contain explicit judgement points between automated segments. Its tools perform the repeatable operations; the LLM chooses the applicable skill, supplies justified inputs and interprets unresolved findings. Not every skill writes to a target, and a pure calculation/comparison tool needs no invented connector call. Which skills a module needs is recorded on its module page (§ 13).

8. What a skill is — the anatomy P

Every skill carries the same five parts, and a skill that cannot state one of them is not ready to be published:

Around the five parts: a dry-run default — the packet is simulated before it is promoted unless the recorded exemption test passes (PG-21); a teardown for every write, emitted by the same skill in the same step (D120); and a coverage map where more than one write path exists — per configuration object, whether the system's own endpoint, a guarded statement or a gateway sequence carries it, and why (D136). The manifest that declares all of this is a draft contract, skill-manifest.schema.json (Contracts § 2, D139).

P Tools are the mechanical execution within a skill. The skill binds published tool versions, connector operations and assertions into a procedure. A declared automated segment runs without a model round-trip between every item or step. A judgement point is explicit; a tool returns a typed finding when it cannot establish the answer. It must not hide another LLM call behind a claim of deterministic automation.

9. When a skill exists — the evidence rule and the ladder P

The automation rule. Evaluate repeated mechanical work for extraction into a tool: parsing, normalising, traversing a family, calculating, comparing, rendering, checking or replaying a known sequence. Repetition may occur across cases or hundreds of times inside one case. Repeated model calls, avoidable latency/usage or inconsistent results justify the assessment; a task need not consume an hour before a useful tool can exist. Keep interpretation as judgement when its method or expected result is not established.

The ladder (Stage Precipitation § 2) is a default review cadence: the third occurrence forces an automation/reuse assessment, and the seventh and twentieth revisit the resulting capability. It is not a prohibition on earlier tool creation. A bounded, testable operation with demonstrated repeated effort or a correctness need can be implemented earlier, with the same tests and publication requirements. A wrong existing tool or claim is corrected immediately. Frequency alone never establishes correctness.

The evidence rule. A skill proposed before the ladder reaches it — the seed catalogue a module starts with — is justified by ticket evidence, never by preference: how often the shape recurs, what it costs today, what it costs once packaged, and how many people can work it today (the bus factor). The method is mining the ticket archive with request-side keyword rules and analysis-side token rules, an effort class inferred per ticket, and the holder read from the ticket system's own tag F (Measurements § TM; the caveats — inferred effort classes, one ticket matching several shapes, the archive being the working set and not the whole desk — are recorded with the numbers). The numbers themselves, per shape, are on the module page that owns the shape; hours are estimates the ledger replaces (Value and ROI § 4), and their use is ranking, not accounting (D117).

P Two kinds of skill, one anatomy. A shape skill packages a recurring request — the case study's data corrections, account actions, document prints. A stage skill is what a module's stage runs to do or to prove its own work — a write path through a system's own configuration endpoints, a test that drives a quotation, a snapshot with a signature. Their evidence differs (the ticket stream for the first, the module design for the second); their parts do not.

10. Governance P

A skill's procedure and applicability stay in the owned Markdown source; its executable implementation is a pinned source/binary tool package or declared connector sequence. Publication freezes the procedure, manifest and dependency digests as one tested release. A running case stays pinned; rollback publishes a new release binding the prior tested implementation. Tool tests and affected profile evaluations rerun when code, binaries, runtime or dependencies change (Agent Framework § 6).

P A skill never widens a grant. It runs inside the case's grants, through the effect applier and past the effect applier like any other write (Gating § 6); the skill adds a reusable procedure, tested mechanics, recorded classifications and proof.

11. What happens when a skill fails P

P A skill is the work's only path, so a broken skill is a work item, not an obstacle to route around. The agent finishes the case and repairs the skill — diagnose, correct the skill or the tool it calls, re-run it, and let the corrected run produce the result. Doing the step by hand and leaving the skill broken is not a completed case: the same failure returns on the next case, and what was learned survives only in one transcript.

P So a case that met a skill defect closes with three artefacts — the delivered work, the amended skill or tool, and the memory entry naming what it could not do before (§ 4). The amendment is itself a change: a skill's own tests re-run, and a skill the modules gate on re-runs its eval set before the amended version is used (Agent Framework).

P Two bounds keep this from becoming open-ended. Improvisation stops at two attempts — after two failures against an unknown contract the agent asks the peer who owns it rather than trying a third time or substituting a manual step (P-15, Product Configurator § P; § 2 rule 5). And a defect that is not the skill's to fix is a gate, not a repair: a missing endpoint, a backend constraint or a frontend component is Hd to the Customer-specific development module, which is a legitimate result rather than a workaround.

12. Three samples P

One per kind, each read as inputs → read set → classification → write packet → verification, with the v1 material that seeds it. The full catalogues these come from are on the module pages (§ 13).

13. Where the catalogues are

The same page holds each module's branch of the memory tree (§ 0.1), so a reader sees a domain, its owner, its seeds and the skills bound to it in one place.

Part III — Tools as retained learning

14. What a tool is P

A tool is source code and/or a binary that automates a bounded operation. Examples are a parser, a query-result normaliser, a family traversal, a calculator, a comparator, a renderer or an assertion runner. The LLM should not reconstruct a known algorithm, enumerate hundreds of rows in prose, recalculate totals or rewrite the same script on every request. A tested tool carries that work forward as reusable execution.

The model-facing calls such as papers.read are also called “tools” in the action protocol. Here tool package specifically means the executable learning asset. A tool package may use connector operations, but a local parser or comparator needs no external system. Source/binaries are stored as artefacts; the prompt gets their usage contract, not their entire code or binary bytes.

15. From expensive reasoning to a reusable tool P

flowchart TB
  E["Observe repeated effort
or inconsistent results"]:::work
  S["Reuse an existing tool
or define the bounded step"]:::work
  C["Implement source
or package a known binary"]:::work
  T["Test correctness
and measure the change"]:::proof
  P["Publish tool, skill binding
and knowledge index"]:::decision
  R["Next case runs the tool
with fresh inputs"]:::learn
  E --> S
  S --> C
  C --> T
  T --> P
  P --> R
  R -.->|"failures and usage evidence"| E
  classDef work fill:#eef4ff,stroke:#6889ba,color:#17365b
  classDef proof fill:#e9f5ef,stroke:#689b81,color:#224e39
  classDef decision fill:#fff4df,stroke:#b78c36,color:#65470d
  classDef learn fill:#f1edf9,stroke:#9580b9,color:#534172
  click E href "agents-memory.html#19-prove-the-benefit-p" "Compare model work, tool time, correctness and repeatability on the same cases."
  click S href "agents-memory.html#16-ownership-discovery-and-publication-p" "Search existing capabilities before creating a tool; retain one owner and a clear usage contract."
  click C href "../contracts/tool-package.schema.json.html" "Source and/or binary, immutable hashes, entry point, runtime and dependency contract."
  click T href "agent-framework.html#66-skills" "Tool tests and affected skill/profile evaluations gate publication."
  click P href "agents-memory.html#16-ownership-discovery-and-publication-p" "Publish the tested package and its consuming bindings together."
  click R href "agent-runtime.html#23-tool-execution-without-a-model-turn" "A known tool segment executes without an intervening LLM call per item."

The working agent records the repeated step, its inputs and expected output, which part is mechanical, and which judgement must remain. It first searches the domain's tool index. If an existing tool is compatible, it uses or extends it. Otherwise it proposes the smallest executable operation, with examples and negative cases from the work that taught it. The domain owner retains its business meaning; a code-capable task implements and tests it in the existing confined workspace. Creating a tool does not require a new agent profile.

One coherent learning change can contain tool source/binary, tests, a skill binding and an index/article correction, plus its mandatory experience entry. These are related parts of one capability, not competing choices limited to one output file. Consolidation asks both “what should be remembered?” and “what should become executable so the model stops repeating it?”.

16. Ownership, discovery and publication P

Every domain index lists its reusable tools alongside its articles and skills: purpose, when to use, supported inputs/variants, owning profile, published version and calling skill. This is how the next agent discovers executable capability before spending tokens reconstructing it. Detailed code and usage examples are loaded only when needed; binary bytes never enter context.

Tool authoring follows draft → test → publish → retire, using the existing skill governance. The first implementation embeds the tool-package manifest in SKILLS.MANIFEST.tool_bindings and stores source/binary bytes in the governed artefact store, identified by digest. A directly callable tool has a minimal hosting skill; there is no separate tool service or database table to build first. Shared bindings point to the same immutable package/digest instead of copying divergent code. The skill version records the complete dependency set, and the profile's TOOLS/SKILLS bindings name the allowed published versions.

Source, tests and usage documentation live with the owning domain's versioned skill material or its linked source repository. Published package bytes live in a read-only, digest-addressed tool-artifacts/sha256/<digest> area of the existing owned registry/content volume. SKILLS.MANIFEST is their catalogue and authorization reference; global packages are not stored as fake case papers. AI.Support.Skills resolves and materialises the permitted package into the task's confined workspace. Invocation inputs, outputs and measurements are real case papers. Retention keeps every package still pinned by a running case or required for its retained evidence; retirement removes new selection before garbage collection is considered.

Publishing another tool for an already supported runtime updates the package and skill binding; it does not require another core service or agent profile. An unsupported runtime or new external capability is an explicit framework/connector prerequisite. A tool can be proposed and developed in the current case's confined workspace, but it does not become a shared published capability merely because that one run succeeded.

A source change, dependency/runtime change or rebuilt binary changes the package version/digest and reruns tool tests plus the affected skill/profile evaluations. A running case keeps its pinned tool unless explicitly migrated; a currently revoked package is refused even if pinned. Rollback publishes a new skill release binding the previous tested package. Retain earlier bytes so old results remain explainable. Studio's existing skill-version view exposes these bindings, code/artifact changes and evaluation evidence.

17. The executable package contract P

The tool-package schema and examples make these requirements concrete:

The hosting-skill example binds a source-only family checker as its automated entry. Its connector-operation list is empty because it processes supplied snapshots locally; the owning domain skill supplies the current data and required proof. This is an illustrative manifest, not a published implementation.

Source-only can run as a script on a pinned interpreter. Source requiring compilation is built and tested into a pinned runnable artefact before publication/use; workers do not compile “latest” source on every case. Binary-only tools are allowed with identified origin, digest, supported platform and tested behaviour; absent source is declared, not invented. An opaque binary defect needs a replacement or its owner's fix, not a fabricated source repair. When both artefacts are present, record the build relationship so tests apply to the binary actually executed.

18. Invocation, evidence and failure P

skills.run executes an automated segment from its published procedure. tools.run invokes one tool binding using skill key/version + tool key/version + typed input; the runtime resolves the immutable binding and verifies its digest. Neither call accepts an arbitrary filesystem path or substitutes a newly generated script for a published package. AI.Support.Skills owns the tool runner within the existing service; source/scripts and third-party binaries run in the confined execution environment, with case-scoped input/output and the declared capability facade. Trusted managed handlers may use the existing deterministic handler path.

The runner validates input, records intent in RUNTIME_CALLS with KIND=tool, executes the known sequence without model calls between mechanical steps, validates output and assertions, and stores a result paper. Record package/runtime/dependency digests, input and output hashes, duration, exit/failure classification and relevant operation ids. Connector subcalls retain their own effect identities and results. The case receives a compact typed summary plus evidence references; large tables stay in papers.

A tool that prepares SQL or a release packet returns a proposal. Effects still pass through the existing auditor/gates/executor, including effects caused by verification. Local computation needs no target write gate. Tool publication is not approval to use it on every target. A model-assisted tool must declare that dependency and its model calls/usage; it is not counted as deterministic replacement of LLM work.

An invalid input, unsupported variant, failed assertion, timeout or uncertain external effect is a typed outcome. Never ask the LLM to relabel a failed mechanical check as success or silently perform the same step by hand. Follow § 11: fix the skill/tool, rerun its checks, or raise the explicit missing-capability/owner dependency. On resume, do not replay successful effects merely because the surrounding tool process stopped. New evidence that invalidates a tool becomes a regression case and a new version.

19. Prove the benefit P

Compare the previous method and the tool on the same inputs and acceptance criteria. Measure provider calls/tokens, active model time, tool wall time, end-to-end active time, correctness, unsupported cases and output variation. Record build/maintenance effort separately. Do not claim savings from moving an LLM call inside a binary, skipping checks, using stale cached state or dropping difficult cases. No new monetary UI or fixed speedup target is needed.

Pure deterministic tools must give the same semantic output for identical normalised input and pinned versions; timestamps and diagnostic metadata are compared separately. Tools reading a live system record the observed state/version and test reproducibility on captured snapshots. Where tolerance or unavoidable nondeterminism is declared, tests use that contract and report the observed variation. A faster wrong result fails publication.

Example — family-invariant checking. The domain skill identifies the family and obtains current authorised snapshots. A source or binary tool enumerates the members, applies the declared status/date/amount relationships, checks coverage and returns pass / fail / unsupported with per-member evidence. The LLM handles a new mechanism or ambiguous business intent; it does not recalculate every row or manually compare each period. The next case runs the same published checker on fresh snapshots. A missing final member becomes a regression test; the repaired tool and its skill/index binding are the learning outcome. This pattern applies to many families without creating one agent per family or one tool per ticket.

Challenges

• P The manifest is a draft (D139): a small required core the platform validates and an open body a case may extend; it graduates only after three modules' cases stop extending it.
• P Effort classes behind the catalogues are inferred, not measured. The ledger replaces them after the first month; until then a catalogue ranks, it does not budget. Recorded with the numbers on the module pages.