---
id: 11326
title: Expose skill content type in KB MCP query schema
state: CLOSED
labels:
  - enhancement
  - ai
  - build
  - model-experience
assignees:
  - neo-gpt
createdAt: '2026-05-13T19:29:55Z'
updatedAt: '2026-05-13T20:45:12Z'
githubUrl: 'https://github.com/neomjs/neo/issues/11326'
author: neo-gpt
commentsCount: 0
parentIssue: 11317
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-13T20:45:12Z'
---
# Expose skill content type in KB MCP query schema

**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**
- [ ] `query_documents` request schema enum includes `skill`.
- [ ] `ask_knowledge_base` request schema enum includes `skill`.
- [ ] Runtime tool description prose mentions `skill` without dropping or hiding the existing `test` type.
- [ ] OpenAPI description budget remains terse; no internal ticket/session narrative is added to tool descriptions.
- [ ] Add or update a targeted static/unit check if an existing test surface covers OpenAPI enum drift.
- [ ] PR close-target is this ticket only; #11317 is referenced as related parent, not closed.

**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**
- Parent epic: #11317
- Source implementation: #11321
- Sync wiring: #11322
- Source tests: #11323
- Scope violation caught in PR #11325 review

Retrieval Hint: "#11317 skill content type KB MCP query schema openapi skill filter"

## Timeline

- 2026-05-13T19:29:56Z @neo-gpt assigned to @neo-gpt
- 2026-05-13T19:29:57Z @neo-gpt added the `enhancement` label
- 2026-05-13T19:29:57Z @neo-gpt added the `ai` label
- 2026-05-13T19:29:58Z @neo-gpt added the `build` label
- 2026-05-13T19:29:58Z @neo-gpt added the `model-experience` label
- 2026-05-13T19:30:14Z @neo-gpt added parent issue #11317
- 2026-05-13T19:30:26Z @neo-gpt cross-referenced by PR #11325
- 2026-05-13T19:35:06Z @neo-gemini-pro cross-referenced by PR #11327
- 2026-05-13T19:43:30Z @neo-gpt cross-referenced by PR #11329
- 2026-05-13T20:45:13Z @tobiu referenced in commit `f5f22a2` - "feat(knowledge-base): expose skill query type (#11326) (#11329)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-13T20:45:13Z @tobiu closed this issue
- 2026-05-13T21:30:31Z @neo-gpt cross-referenced by #11334

