Why we replaced static agent skills with Oddlynew
Static skill files are useful for stable execution capabilities. They had become the wrong home for knowledge that changes with our work, so we moved the evolving part into Oddlynew and left the repository to bootstrap agents and enforce the mechanics that belong beside the code. Reusable Skills remain part of that live knowledge: maintained methods that agents can find, apply, verify, and improve.
Modern coding agents are already capable enough to inspect code, compose tools, and solve unfamiliar problems. The bottleneck is increasingly not whether the model can reason. It is whether every agent can reach the same current decisions, architecture, history, and working conventions without loading an ever-growing prompt bundle.
That changed how we document our own monorepo.
What we changed
On 2026-08-04 we merged refactor(repo): make Oddlynew the knowledge layer. In that commit, we removed 82 files and 9,660 lines from .agents/skills/. The root AGENTS.md went from 227 lines to 75 in the cutover commit. It has grown modestly since then as we strengthened the bootstrap, but its job remains deliberately small.
The repository now tells an agent to connect to Oddlynew before substantive work, enter our internal organization, read its designated AGENTS.md, and continue through the Monorepo Knowledge Hub. It also defines the authority order: current code, tests, generated schemas, and package contracts describe implementation reality; accepted live documents carry product decisions, architectural intent, and durable organizational knowledge.
We did not delete all repository documentation. Code-coupled references still belong beside the code. Executable scripts, schemas, tests, safety checks, and mechanical enforcement stay local. What moved was the evolving agent instruction layer: explanations, decisions, patterns, debt, active disagreements, and working knowledge that should improve without waiting for a repository release.
Why static skills became too rigid
A static skill is useful when it packages a stable execution capability. It is a poor home for a living body of knowledge.
As the system grows, static guidance creates pressure to choose what fits. Teams duplicate the same instructions for Codex, Claude, ChatGPT, CI agents, and future runtimes. Corrections require code changes and redistribution. Different agents can load different generations of the truth. More context helps until the bundle becomes expensive, stale, or too large to load by default.
A live knowledge layer changes the optimization target. Knowledge can grow beyond what fits in one prompt. Agents retrieve the smallest relevant slices, follow references to canonical sources, compare more than one plausible result, and verify consequential claims against code or current systems. The corpus can keep expanding without every session paying to load all of it.
Maintained Skills and compiled execution views
A 2026 Google Research paper, WikiSkill: Compiling Agent Experience into Persistent Knowledge for Skill Evolution, sharpened this distinction. WikiSkill separates immutable execution experience, a persistent wiki that consolidates recurring success and failure patterns, and concise executable skills. Across five benchmarks and five tested models, the persistent wiki improved automated skill evolution relative to the compared methods. The paper is evidence for the architecture, not evidence that every organizational gardener or compiled procedure will work unchanged.
Our adaptation is: evidence → maintained capability → execution projection. High-volume traces and operational rows can stay in the systems that own them. The Oddlynew organization preserves durable patterns, root causes, examples, decisions, current guidance, and accepted or rejected intervention history. A maintained Skill belongs in this knowledge layer: it describes a reusable method, when to use it, its inputs, steps, boundaries, and completion evidence. A chosen agent or runtime may derive a smaller execution view for a task, such as a static skill bundle, AGENTS.md fragment, Lens working set, checklist, prompt fragment, or tool policy.
A Skill can support many outcome loops without owning their outcomes or acquiring a standing schedule. A run selects the methods it needs; the outcome owner remains responsible for acceptance and verification. Loop and Graph Engineering explains the distinction between Loop, run, Skill, and runtime. Here Skill means maintained reusable instructions, kept as a document of the platform Skill type, which every organization has. Discover the chosen organization's current types first: if it already keeps its methods in its own Skill type or a maintained guide, use that.
Dynamic retrieval and compiled projections are complementary. Open-ended work may benefit from direct access to the maintained organization. Repeated work may benefit from a short tested projection. Some tasks may use both: a compiled default plus live retrieval for exceptions and fresh evidence. WikiSkill also found negative cross-model transfer, so a projection should name its source version, target model or model class, harness, tools, context budget, evaluation, and known regressions rather than claiming universal compatibility.
Our current teaching starts with named outcome Loops: MCP Improvement, Public Knowledge and Gardening. Each can be requested directly, use reusable Skills, accept handoffs and verify the original outcome. Users choose any optional cadence in an external runtime. The earlier Experience-to-Capability root arrangement is historical evidence, not the operating model readers should install. By 29 August 2026, its two operating cycles and one four-mode evaluation had recorded duplicate rejection, overlap coalescing, correction and verified no-ops. Those results do not prove the revised pattern or a current automation cutover. The public beta guide Make Every Agent Run Improve the Next teaches the named-Loop pattern and keeps its fresh-agent installation and continuation test explicit.
The flywheel: use it more to get more from it
The best way to get more value from a shared knowledge layer is to use it more.
Put the bootstrap in AGENTS.md. Connect the agents people already use. Give substantial implementations one shared tracker. Let agents consolidate durable findings into the document that owns them. Record accepted architecture, product decisions, operational guidance, and resolved disagreements where the next agent can retrieve them.
Each additional piece of well-owned knowledge improves later reasoning. Each agent that reads and updates the same corpus reduces rediscovery for every other agent. Better retrieval makes it worthwhile to preserve more context; preserving more context makes retrieval and reasoning more valuable. The result is not a larger prompt. It is a self-improving organizational starting point.
One knowledge layer across interactive agents and CI
This is not only an interactive coding-assistant pattern. Our trusted GitHub review workflow uses a dedicated Agent automation credential to read accepted context and write typed review evidence back into the same organization. The credential belongs only in trusted same-repository workflow jobs; forked or otherwise untrusted code must never receive it.
Organization-scoped principals make other patterns possible. A public repository could give an automation agent write access to a documentation organization while keeping product or company knowledge read-only or inaccessible. After a feature merges, that agent could inspect the accepted change and update the public documentation that owns the affected behavior.
An Agent automation key currently grants read/write authority across its selected organization rather than limiting writes to one document type. The workflow prompt, document schemas, and review lifecycle constrain intended behavior, but they do not narrow the credential itself. Treat the key as a powerful secret, choose the organization boundary deliberately, and keep untrusted execution on an unprivileged path. More granular write grants or a purpose-built GitHub App can narrow this boundary later without changing the shared-knowledge pattern.
Guidance, not model compensation
This architecture only became practical because agents became capable enough to do more with less procedural guidance.
We do not want to encode every workflow as a rigid skill. We give agents coordinates, authority boundaries, canonical sources, and observable completion criteria. The agent still searches, chooses, implements, verifies, and consolidates. For substantial work, a live implementation tracker lets people and other agents see the objective, active work, findings, approval gates, and evidence without reconstructing one private chat.
The knowledge layer does not replace intelligence. The chosen agent supplies the reasoning and invention. Oddlynew supplies durable, typed, searchable, collaborative state that lets intelligence begin from a stronger position and leave the position stronger for whoever comes next.
The costs and boundaries are real
Moving live guidance out of the checkout creates a dependency. An offline or unauthorized agent has less organizational context. Search is bounded and ranking is not truth. Arbitrary readable documents are evidence, not instructions. Current code and tests can disagree with an accepted decision, and the disagreement must be surfaced rather than silently resolved for convenience.
That is why the local bootstrap remains. It explains how to connect, what authority wins, what can proceed safely when Oddlynew is unavailable, and which mechanics must stay synchronized with the checkout.
A mutable knowledge layer is a security boundary
A live knowledge layer can steer downstream intelligence. Anyone who can change trusted guidance may influence many later searches, decisions, and agent actions. Compromised credentials, poisoned guidance, malicious imports, and prompt injection therefore become an intelligence supply-chain risk, not only a data-integrity problem.
That is not an argument for freezing the layer. Useful knowledge has to change, just as code, dependencies, CI, and human organizations change. The answer is to govern knowledge with comparable care: grant the least authority needed, choose organization members deliberately, separate trust domains, designate canonical guidance, preserve provenance and lifecycle state, scope and attribute writes, review consequential changes, and retain history for correction and recovery. Arbitrary readable documents remain evidence, not instructions, and the current code and tests remain authoritative for implementation reality.
Keeping the layer clean means more than keeping it orderly. It means making authority legible and preventing unreviewed or low-provenance material from silently becoming guidance. Security and trust are top priorities for Oddlynew, which is why we are actively securing the identity, authority, provenance, review, and recovery paths around this layer. We do not claim that prompt injection or knowledge poisoning is solved.
Later articles should show the engineering underneath that posture: scoped machine principals, the trust and provenance model, why we use Effect to make failure and invariants explicit, and why we deliberately own many critical packages and integration boundaries ourselves. Those choices reduce ambiguity and third-party supply-chain exposure. They do not eliminate risk.
Why commodity pricing matters
This pattern works best when teams do not ration every useful read, write, search, or intermediate document.
Our design direction is commodity pricing: make the shared substrate inexpensive enough that people and agents can use it freely, then keep reducing the cost of useful work as the underlying system improves. Exact plans and limits are separate product decisions, not promises hidden inside an engineering post. The principle is simpler: knowledge compounds through use, so the product should encourage use rather than punish it.
Cheap storage alone is not the product. The value comes from making a growing body of knowledge retrievable, governable, and usable by every authorized intelligence that works with it.
What this makes possible
Once a repository, its interactive agents, and its trusted automation share one knowledge layer, documentation stops being a bundle delivered to each model. It becomes part of the engineering system itself.
A new agent can enter through a small bootstrap. A review workflow can apply current architectural decisions. A long implementation can expose its state to the next collaborator. A correction discovered in one session can improve the next session across clients. People can invent new use cases because the primitives remain general.
The repository still owns the code. The organization owns the evolving understanding around it. Connecting the two gives capable agents something they have rarely had: one maintained body of work that every authorized agent can continue and improve.