docs(plugin): trim keboola-expert prompt to ~47.8 KB

[padak]

Why

plugins/kbagent/agents/keboola-expert.md sat at 61 999 B against what was then a 62 000 B PROMPT_BYTE_BUDGET — 1 byte free. The next command group that genuinely needed a tool-matrix row could not get one. Two changes already shipped without touching the file for exactly this reason: #587 (config clone) and #593 (config state-get/state-set) both put their knowledge in gotchas.md instead. That workaround only works because adding to an existing command group needs no new matrix row; it does not extend to a new group.

Rebased onto v0.88.0, which raised the cap to 70 000 B. The comment introducing that bump says the quiet part out loud: "It is NOT a licence to grow the file… Trim before you add." This PR is that trim — it does not touch PROMPT_BYTE_BUDGET itself. The budget is a real runtime cost (the prompt loads into every subagent invocation), so headroom should come from removing duplication, not from the ceiling.

Where the bloat actually was

Not the version tags. All ~95 (since vX.Y.Z) notes together are only ~1 KB.

section	before	after
§2 TOOL SELECTION MATRIX	32 044 B (52 % of the file)	21 092 B
§3 INLINE GOTCHAS	14 768 B	10 978 B
everything else	unchanged	unchanged

§2 had grown into a second manual. The 37 files in skills/kbagent/references/ (677 KB) already carry that prose — semantic-layer-workflow.md even opens with a "When to use what" table in the same intent→command shape, which made the 11 semantic-layer matrix rows (7.3 KB) near-verbatim duplication.

What changed

• §2 — cells now carry the decision only (command, outcome-changing flags, the NEVER list) and point at the matching *-workflow.md for the rationale. The semantic-layer block collapses 11 rows → 2 (read; and "any write: export first, then read the workflow"). Its three sharp gotchas stay in §3.
• §3 — entries whose prose duplicated gotchas.md are back to one-line triggers, which is the section's own stated design rule.
• Version tags — retired where the floor no longer bites. Kept every gate where an older version is silently wrong: 0.54.0 plaintext #-secrets, 0.66.1 dormant cron, 0.86.0 Azure cipher + POST/PATCH no-retry, 0.87.0 data-app workspace flag.
• Dropped the hand-copied session_unsupported_features list — the surrounding text already tells the agent not to reconstruct it from memory (auth login --json ships it), so an inline hand-copy was both contradictory and a drift risk.
• Freed headroom put to use — config clone (config new: cloning a config by hand silently drops sibling keys like runtime (parallelism) — no clone command, examples show only parameters #587) and config state-get/state-set (config: no CLI path to write configuration state (PUT .../state unused); config update --set 'state...' silently no-ops #593) now have proper matrix rows instead of living only in gotchas.md.

The one thing worth reviewing carefully

Rule 6 is reworded in the same pass, and this is load-bearing. It used to say:

Every command in the §2 matrix and §3 gotchas carries its own (X.Y.Z+) since-tag — treat those inline tags as the authoritative version floor.

Strip tags under that wording and an untagged command silently reads as "safe on any version". Rule 6 and both section preambles now state that a tag marks a floor that still bites, that its absence is not a promise, and that a No such command / unknown-option error is a failed version gate rather than a reason to improvise (§5 already had that branch).

Two carve-outs were deliberately kept after an initial over-trim: dev-portal is not on session_unsupported_features (own identity, no project token) and flow list/flow detail are plain Storage — without them the agent could pre-emptively refuse commands that work.

Rebase note (#629)

#629 landed on main while this was open and amended the BigQuery repartition row. That guidance is preserved in the resolved row: verify a repartition with storage table-detail --json → .definition.timePartitioning / .clustering (0.88.0+), because create-table only echoes the layout you requested and so proves nothing. The conflict was that one 9-row block; both sides' value is folded in.

Result

61 960 → 47 830 B — 22 170 bytes free of the 70 000 budget. PROMPT_BYTE_BUDGET is not modified by this PR.

Only one file changed. Nothing was moved into gotchas.md — every trimmed block was already documented there or in a topical workflow file, verified per block before cutting.

Verification

wc -c plugins/kbagent/agents/keboola-expert.md   # 47830
uv run pytest tests/test_agent_prompt.py -q      # 41 passed

tests/test_skill_frontmatter.py also passes (45 total). Markdown table integrity checked programmatically after the conflict resolution — every §2 row has exactly 4 columns. No CLI command was added, removed or renamed, so the other convention #17 drift surfaces (SKILL.md, commands-reference.md, context.py, CLAUDE.md) need no update, and no version bump means no changelog entry.

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.