Split OK project skill into lean core + on-demand references#339
Merged
Conversation
* refactor(open-knowledge): split project skill into lean core + references Restructure the bundled project SKILL.md from a 69KB monolith into a ~16KB always-loaded core plus 14 on-demand references/ files. This cuts the per-turn agent-context footprint by roughly 77% with zero behavioral loss: all STOP/MUST safety rules stay inline in the core, the long-tail guidance moves to references that load only when the task needs them. Also rewrites the project skill description to the Anthropic what+when contract (third person, under 1024 chars, no XML tags) and dedups the tool index into a one-line-per-tool router so it stops duplicating the always-on MCP tool descriptions. build-skill-bundles.ts now copies references/ (and any future skill subdirs) into dist so the install, desktop reclaim, and .skill ZIP carriers all ship them. Includes the grounding audit and the spec. The skills/MCP-off opt-out is tracked as a separate follow-up. PRD-7185 * chore(open-knowledge): brand-consistency pass on bundled skills Reconcile after merging main (PRD-6935 skill editor + the OpenKnowledge brand rename). Fix residual two-word "Open Knowledge" prose in the discovery and write-skill bundles (preserving the OKF "Open Knowledge Format" proper noun). Every other bundled skill is already under the ~5K-token / 500-line progressive-disclosure ceiling, so they are left un-split per the same standard (DL4); only the project skill warranted the core/reference split. PRD-7185 * fix(open-knowledge): restore skill-authoring vocabulary dropped in merge The merge of main took the pre-#1662 lean core via --ours, which silently dropped the skill-authoring contract that PRD-6935 (#1662) had added to the project skill. Restore it into the lean core: TL;DR #6 (author/improve a skill via open-knowledge-write-skill; never hand-edit .ok/skills or the installed projections), the tool index now documents 19 tools (adds the skills read tool, the install tool, and the skill write/edit/delete/move target), and the STOP rule gains the .ok/skills path anti-pattern. Verified against current main: every code identifier in main's SKILL.md is present in the core+references corpus (skill-authoring restored; remaining differences are the deliberate tool-index router compression). Core body 17,922 bytes, still under the 20,000 gate. PRD-7185 * test(open-knowledge): drift guard reads whole skill bundle after split The starter-pack-awareness drift guard asserted the pack list + the `ok seed --list-packs`/`--dry-run` ladder live in project/SKILL.md, but the core/reference split moved that content into references/workflow-guides.md. Read the whole bundle (core + every reference) so the guard finds the list wherever it lives. The pack-bullet regex still matches exactly the 8 STARTER_PACK_IDS across the bundle. PRD-7185 * fix(open-knowledge): write-skill gates overlap check + no-assume rules Harden the bundled open-knowledge-write-skill so a recurring bad pattern can't repeat: building a near-duplicate of an existing skill, assuming harness/format from a scope answer, and bypassing the author-through-verbs flow. - Promote the "does this already exist?" check from a passive reminder to an active Stage 1 gate: scan installed skills, recommend reuse on heavy overlap, decide with the user BEFORE writing anything. - Add reminders: scope is the only placement decision (don't fold harness/format assumptions in); author via write({skill}) + install, never hand-write editor projections; ground system-fact claims. PRD-7185 * test(open-knowledge): enforce reference pointer-completeness + core byte gate Address two reviewer suggestions by turning manual invariants into CI guards: - Bidirectional reference-pointer guard: every references/<name>.md pointer in the core SKILL.md resolves to a file (no dead pointer), and every reference file is pointed to from the core (no orphan). The prior test only asserted the references dir was non-empty. - Core-body byte gate: strip frontmatter and assert the body is <= 20,000 bytes (spec V4/R-IS1), which was documented but unenforced in CI. PRD-7185 GitOrigin-RevId: 4b94342712f40ff22d35a037d4b844d276a10c7b
![inkeep-internal-ci[bot]](https://avatars.githubusercontent.com/u/123133689?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Automated approval from agents-private public-mirror-sync (run: https://github.com/inkeep/agents-private/actions/runs/28271515319). Source of truth is the monorepo; direct edits on inkeep/open-knowledge are overwritten on next sync.
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.