Skip to content
TilloTech Docs

Codify Engineering Standards as Skills

Date: 2026-07-09

Status

Accepted

Context

Engineering standards currently live in Notion. Because nothing enforces a link between those documents and the code being written, they drift: Notion is edited on its own schedule, actual practice moves independently, and there is no mechanism that keeps the two in sync. Drift alone would be a documentation-hygiene problem; what makes it urgent is that the models used for everyday coding tasks have no access to Notion at all. An agent generating or reviewing code in a repository has no way to consult these standards at the moment they’d matter, so however accurate a given Notion page is, it has zero bearing on the code an agent actually produces. Standards that only humans can read are, for AI-assisted work, standards that don’t exist.

The same gap shows up at the tooling level. Repositories have accumulated ad hoc, per-tool skill setups (for example, storefront’s separate and inconsistent .cursor, .claude, and similar directories) with no shared source of truth and no consistent way for a given skill to reach every AI client a team might use. Any fix has to produce something a coding agent loads automatically as part of its working context, not another document an agent must be told to go find.

Decision

Engineering standards will be codified as skills, not as documents, and stored in the central EOS repository so that coding agents load them automatically as working context instead of requiring a human to go find and paste them in.

This applies across all repositories, PHP and non-PHP alike. The distribution mechanism differs by ecosystem but the principle doesn’t: PHP repositories get skills distributed via Laravel Boost from a checked-in .ai/guidelines source of truth, and non-PHP repositories get them via APM. In both cases the skill, is the thing a coding agent actually utilizes.

This covers existing standards, not just ones written from now on. Notion remains the home for narrative and process documentation, but any existing standard that should shape day-to-day coding — conventions, patterns, rules — is migrated into a skill over time rather than left to drift out of sync in a document models can’t read.

Consequences

Positive

  • Coding agents consult standards as part of their normal working context automatically, closing the gap where documented standards had no bearing on the code an agent actually produced.
  • Standards live in one versioned, PR-reviewable place instead of being scattered across per-tool, per-repo setups like the inconsistent .cursor/.claude directories seen in storefront.
  • Distribution reuses tooling already committed to (Laravel Boost for PHP, APM elsewhere) rather than inventing a new mechanism.

Negative

  • Migrating the existing body of Notion standards into skill form is real, ongoing work that doesn’t happen automatically; until it’s done, some standards remain invisible to agents exactly as before.
  • Not every standard translates cleanly into a skill. Content that’s inherently narrative or judgment-based is harder to phrase as something that triggers reliably, and authors need to learn to write in that constrained style.
  • Adopting a third-party skill now means going through a PR-gated trial rather than installing it directly, which is slower for an individual even though it’s the point of the control.
  • Officially supporting only APM- and Boost-based distribution means anyone using an unsupported client or workflow is unsupported by design, not by oversight.

Neutral

  • Notion isn’t eliminated — it remains the home for narrative and process documentation that doesn’t need to shape day-to-day coding, so each piece of content now needs a judgment call about which home it belongs in.
  • Skills trigger on relevance rather than being force-injected into every context, so a skill only helps if its description is written accurately enough for an agent to recognize when it applies.

Alternatives considered

Keep standards in Notion, linked from git-based context files

Rather than moving content, git-based context files (e.g. agents.md) would simply link out to the relevant Notion pages. This was rejected for the same reason keeping standards in Notion outright was rejected: the models doing everyday coding work have no access to Notion. A link is only useful to something that can follow it and read the destination at the moment it matters — an agent generating code in a repo can’t, so the standard still never reaches the code being produced.

Guidelines instead of skills

Standards could be written as guideline files that get bundled wholesale into every agent’s context (the pattern Laravel Boost and similar tools already support). This was rejected because guidelines are injected in full regardless of relevance, which pollutes context and drives up token cost on every task, whether or not that particular standard applies. Skills, by contrast, trigger only when their description matches the task at hand, which was the specific property needed to keep this scalable across a growing set of standards.

Status quo: per-tool, per-repo bespoke skill directories

Individual repos and teams could keep maintaining their own skill setups per AI client, as storefront currently does with separate, inconsistent .cursor, .claude, and similar directories. This was rejected because it produces exactly the tooling-level gap this decision is meant to close: no shared source of truth, duplicated or drifting copies of the same intent across tools, and no consistent way to get a given standard in front of whichever client a person happens to be using.

Unrestricted third-party skill installation

Letting anyone install any third-party skill directly, the way a dependency might be added today, would have been the lowest-friction path. This was rejected because a skill runs as part of an agent’s working context with real access to the repository, and an unvetted third-party skill carries a concrete prompt-injection risk — the same risk that motivated the PR-gated trial process instead of open installation.