The portable idea in this article is simple: split the instruction layer into always-on rules and on-demand skills, then update both as reality changes. At Titanium Birch, the painful failures we cared about were almost always the same shape—useful guidance existed, but it lived in chat, memory, or a one-off ticket, so the next session reinvented half of it. What helped was treating conventions like code: versioned, reviewed files that load before work begins, with a clear rule for which updates belong in the always-on layer versus a skill you pull in when a task needs depth.
Key takeaways
- The practical split is simple: rules are always loaded, skills are pulled in when a task needs depth.
- One update to a skill can change behaviour across every future agent session.
- The system is still evolving, and the quality comes from continuously folding lessons back into the instructions.
The problem we had to solve
A five-person human team cannot scale an engineering operation by repeating context in every hand-off. In an agent workflow, the pain shows up even faster: we found that undocumented conventions tended to be applied inconsistently.
Early on, we saw the same pattern repeatedly. Useful guidance existed, but it lived in chat threads, memory, or old tickets. Agents could still ship work, but output quality varied, and review conversations often included rework—enough that the team tightened guardrails in the instruction layer.
Act 1: make the baseline context always-on
The first step was to make a baseline set of rules unavoidable. AGENTS.md files provide that baseline at monorepo root, .github, and app levels, so each session starts with shared context before any implementation begins.
In practice, those rules answer foundational questions up front: what Titanium Birch is, how the engineering model works, which constraints are non-negotiable, and where to find deeper guidance. This does not remove ambiguity completely, but it narrows the unknowns before an agent writes a line of code.
Act 2: move detailed process into on-demand skills
Always-on rules are intentionally concise. Detailed process lives in skills, invoked when the task requires it. Across TB’s repos, that means practical guides for product management, content authoring, development conventions, and ticket mechanics—each scoped to the repo and context where the skill applies.
The important bit is not the catalogue of skill names. It is the propagation effect: a convention written once can shape behaviour everywhere. Commit formatting is a good example. The development-conventions skill defines:
<type>(<scope>): <description>
A ticket references the skill instead of pasting the rule. The worker agent reads it and commits accordingly. Across the engineering work in Trunk—data pipelines, portfolio analytics, deal-side tooling—the git log then shows the same shape across unrelated sessions:
feat(portfolio-analytics): add sector attribution to the PnL view
fix(data-pipeline): correct currency normalisation in the dlt source
docs(skills): clarify verification honesty rule
One source file, many sessions, less drift.
Act 3: convert friction into better instructions
A significant shift was cultural, not structural: when something goes wrong, we do not just patch the immediate ticket—we update the instruction that allowed the mistake.
As automated checks and guardrails mature, we revise skills so human attention goes to prioritisation and judgement rather than steps the pipeline can now handle reliably.
That pattern repeats across the repo. A routing mistake adds clearer repo-targeting rules. An embellished claim adds stricter factual guidance. A noisy hand-off adds tighter ticket-writing conventions. Each fix is small, but the compounding effect is meaningful.
External skills and version pinning
Some skills are sourced from external repositories. In Trunk, they are pinned in skills-lock.json with source and hash, then updated intentionally after review. The goal is straightforward: no silent behavioural changes in the instruction layer.
This is the same discipline we apply to code dependencies, because skills are operational dependencies. They directly influence what agents produce.
Why the instruction layer matters
The result is an opinionated, imperfect system that is actively maintained. Conventions are not something each person rediscovers from scratch; when the system falls short, the fix includes updating the instructions, not only the code.
That is the narrative arc in one line: we started with scattered know-how, encoded it into versioned instructions, and now improve the organisation by continuously editing the instructions alongside the code. The system is useful today, and it still needs regular refinement.