Seed the agent knowledge base#18253
Conversation
.agents/knowledge/: an index routing to the contributor docs plus agent-only entries for judgment the docs don't cover. First entry: the Enum-vs-String trade-off (promoted from schema-review, which now references it). BACKLOG.md lists candidate entries by docs-coverage. AGENTS.md and the three workflows point agents at the index.
This comment was marked as outdated.
This comment was marked as outdated.
| @@ -0,0 +1,36 @@ | |||
| --- | |||
There was a problem hiding this comment.
Entries in .agents/knowledge/ are intended to cover decision points or otherwise tacit knowledge that the contributor documentation does not cover.
A question that we'll need to ask ourselves: should this exist as an agent-only knowledge entry, or promoted to the contributor documentation?
I would say in most new cases, it'll be more efficient to have new topics/decision points exist as new entries outside of the contributor documentation. These entries are intended to be optimized for LLM ingestion and also fed by future session learnings.
Over time, I expect the % of documentation readers to lean towards mostly agents, whether initiated by a human author or not.
| @@ -0,0 +1,27 @@ | |||
| # Knowledge backlog | |||
There was a problem hiding this comment.
An initial scan of potentially missing knowledge entries seeded from my own personal agentic sessions and some initial PR investigations.
Each entry would be codifying potentially ambiguous or stylistic decision-making, and should be reviewed/discussed individually. I believe it to be the most important tool our team has in curbing the last ~20% of scenarios the base models+harnesses cannot do alone.
| @@ -0,0 +1,56 @@ | |||
| # Knowledge index | |||
There was a problem hiding this comment.
Lightweight index for agents to deliberately read so they are aware of all existing documentation available to them.
The intention is that it performs better than the agent sporadically deciding to grep for existing documentation via specific terms or phrases.
It could still decide to NOT consult any documentation (without more forceful guardrails), but this should cover awareness at the very least.
|
Hi there, I'm the Modular magician. I've detected the following information about your changes for commit 315dc75: Diff reportYour PR hasn't generated any diffs, but I'll let you know if a future commit does. |
|
|
||
| ## Entry format | ||
|
|
||
| One Markdown file, one topic, ≤120 lines, YAML frontmatter: |
There was a problem hiding this comment.
Is the frontmatter a well-known format or did you define it? Will agents do progressive disclosure with the format if it's custom?
There was a problem hiding this comment.
Is the frontmatter a well-known format
Having YAML frontmatter is a well-known format. Gemini skills/rules use it (name+description), and so does the GCP Open Knowledge Format. The exact contents of the frontmatter were my invention, but can be fairly flexible if we find it's better to add or remove parts
Will agents do progressive disclosure with the format if it's custom?
Progressive disclosure doesn't depend on the frontmatter at all in these files. Right now frontmatter-driven loading only applies to skills + rules, and those are both location and frontmatter dependent.
Right now the mechanism is driven by a harness-level rule to read the index.
If Antigravity adopts an official shared knowledge system (not just local memories), we could switch to whatever that format is. They'll likely reuse name+description. The rest of the custom fields are mostly for record keeping.
There was a problem hiding this comment.
By well-known format I mean like OKF or skills i.e. https://agentskills.io/specification#frontmatter!
Right now the mechanism is driven by a harness-level rule to read the index.
So we expect the agent to proactively read the index into context, and then choose to follow the index for those topics on-demand?
|
Hi there, I'm the Modular magician. I've detected the following information about your changes for commit a2c2734: Diff reportYour PR hasn't generated any diffs, but I'll let you know if a future commit does. |
|
Hi there, I'm the Modular magician. I've detected the following information about your changes for commit dced8a6: Diff reportYour PR hasn't generated any diffs, but I'll let you know if a future commit does. |
|
Hi there, I'm the Modular magician. I've detected the following information about your changes for commit 9d1ab63: Diff reportYour PR hasn't generated any diffs, but I'll let you know if a future commit does. |
|
Hi there, I'm the Modular magician. I've detected the following information about your changes for commit 0093f6d: Diff reportYour PR hasn't generated any diffs, but I'll let you know if a future commit does. |
| @@ -0,0 +1,29 @@ | |||
| # Knowledge backlog | |||
There was a problem hiding this comment.
Maybe .BACKLOG.md or __BACKLOG.md if we don't intend agents to read this, but may not matter.
| ## Not in the docs | ||
|
|
||
| - **casing-and-pluralization** — how API names map to Terraform names; when `api_name` is required. | ||
| - **pr-mined-lessons** — recurring review catches and per-service quirks surfaced from merged PRs. |
There was a problem hiding this comment.
| - **pr-mined-lessons** — recurring review catches and per-service quirks surfaced from merged PRs. |
(up to you) IMO cut as we'd use historical analysis to determine new rules of this type to cover, rather than the outputs of historical analysis being a single rule.
3 participants
.agents/knowledge/: an index routing to existing docs plus agent-only entries for judgment the docs don't cover.Enum-vs-Stringguidance (promoted from the existingschema-reviewstub skill, which now references it).BACKLOG.mdlists candidate entries by docs-coverage.AGENTS.mdand all existing workflows point agents at the index.