Context
Epic #11317 adds skill-document ingestion to the Knowledge Base. During PR #11325 review, the public query/schema exposure for type: skill appeared inside a Gemini-authored #11321 branch alongside #11321, #11322, #11323, and unrelated #11312 substrate changes. The operator clarified the governing shape: one PR, one non-epic ticket; PRs must not target epics, and #11317 must not become a Gemini-only PR stream.
The Problem
SkillSource ingestion is incomplete as an agent-facing feature unless the MCP Knowledge Base query tools expose skill as a filterable content type. On current origin/dev, ai/mcp/server/knowledge-base/openapi.yaml exposes enums for all, blog, guide, src, example, ticket, release, test, but not skill. Folding this public query contract into #11321 collapses separate review surfaces and violates fair lane distribution.
The Architectural Reality
The consumed contract lives in ai/mcp/server/knowledge-base/openapi.yaml, not in SkillSource.mjs. The relevant public surfaces are query_documents and ask_knowledge_base input schemas / tool descriptions. This is a narrow MCP schema/docs contract update that depends on #11321's SkillSource chunk type but should ship as its own child PR under #11317.
The Fix
Add skill to the Knowledge Base MCP query content-type contract in openapi.yaml, keeping the descriptions terse and runtime-tool-budget compliant. Ensure any prose lists stay synchronized with the enum values, including the pre-existing test type.
Contract Ledger Matrix
| Target Surface |
Source of Authority |
Proposed Behavior |
Fallback |
Docs |
Evidence |
query_documents.type |
#11317 / #11316 skill semantic search contract |
Accept skill as a filter value and document it in the runtime tool surface |
Without this, callers can still search all content but cannot type-filter skills |
ai/mcp/server/knowledge-base/openapi.yaml |
Static enum/prose check |
ask_knowledge_base.type |
#11317 / #11316 skill semantic search contract |
Accept skill as a filter value and document it in the runtime tool surface |
Without this, callers can still search all content but cannot type-filter skills |
ai/mcp/server/knowledge-base/openapi.yaml |
Static enum/prose check |
Acceptance Criteria
Out of Scope
- Implementing
SkillSource.mjs itself (#11321).
- Wiring
SkillSource into the sync source list (#11322).
- Parser/source behavior tests for
SkillSource (#11323).
isAtlasMonolithSubRule classification, which belongs to the trigger-aware workflow lane (#11319/#11320).
Avoided Traps / Gold Standards Rejected
- Bundling with #11321: Rejected because it erases the one PR / one ticket boundary and concentrates #11317 under one author.
- Closing #11317 from a PR: Rejected because epics close through sub-issue completion, not PR magic keywords.
- Verbose OpenAPI narrative: Rejected because MCP tool descriptions are runtime payload, not architecture notes.
Related
Retrieval Hint: "#11317 skill content type KB MCP query schema openapi skill filter"
Context Epic #11317 adds skill-document ingestion to the Knowledge Base. During PR #11325 review, the public query/schema exposure for
type: skillappeared inside a Gemini-authored #11321 branch alongside #11321, #11322, #11323, and unrelated #11312 substrate changes. The operator clarified the governing shape: one PR, one non-epic ticket; PRs must not target epics, and #11317 must not become a Gemini-only PR stream.The Problem
SkillSourceingestion is incomplete as an agent-facing feature unless the MCP Knowledge Base query tools exposeskillas a filterable content type. On currentorigin/dev,ai/mcp/server/knowledge-base/openapi.yamlexposes enums forall, blog, guide, src, example, ticket, release, test, but notskill. Folding this public query contract into #11321 collapses separate review surfaces and violates fair lane distribution.The Architectural Reality The consumed contract lives in
ai/mcp/server/knowledge-base/openapi.yaml, not inSkillSource.mjs. The relevant public surfaces arequery_documentsandask_knowledge_baseinput schemas / tool descriptions. This is a narrow MCP schema/docs contract update that depends on #11321'sSkillSourcechunk type but should ship as its own child PR under #11317.The Fix Add
skillto the Knowledge Base MCP query content-type contract inopenapi.yaml, keeping the descriptions terse and runtime-tool-budget compliant. Ensure any prose lists stay synchronized with the enum values, including the pre-existingtesttype.Contract Ledger Matrix
query_documents.typeskillas a filter value and document it in the runtime tool surfaceai/mcp/server/knowledge-base/openapi.yamlask_knowledge_base.typeskillas a filter value and document it in the runtime tool surfaceai/mcp/server/knowledge-base/openapi.yamlAcceptance Criteria
query_documentsrequest schema enum includesskill.ask_knowledge_baserequest schema enum includesskill.skillwithout dropping or hiding the existingtesttype.Out of Scope
SkillSource.mjsitself (#11321).SkillSourceinto the sync source list (#11322).SkillSource(#11323).isAtlasMonolithSubRuleclassification, which belongs to the trigger-aware workflow lane (#11319/#11320).Avoided Traps / Gold Standards Rejected
Related
Retrieval Hint: "#11317 skill content type KB MCP query schema openapi skill filter"