Expose skill MCP surfaces (codex)

[numnx]

🧩 Task: Expose skill MCP surfaces

Automated task PR opened by Code UX for T03.

📋 Summary

Sprint: Sprint 149 · Self Reflection & Persisten Skills · Task: T03

Add disabled-by-default persistent skill storage for shareable agent self-enhancement and a configurable self-reflection improvement loop for planning and QA agents, with MCP management/search surfaces, runtime prompt injection, dashboard controls, tests, and docs.

📝 Full Task Prompt

## Objective
Expose persistent skill storage through MCP so project managers and other authorized agents can create, manage, and retrieve skills, including a comprehensive skill-authoring prompt.

## Scope
- `src/contracts/mcp-tool-definitions.ts`
- `src/contracts/internal-management-types.ts`
- `src/mcp/management-tool-handler.ts`
- `src/mcp/management/skill-actions.ts` (new)
- `src/server/mcp-request-router.ts`
- `src/mcp/mcp-tool-availability.ts`
- `src/services/skill-service.ts`
- `tests/backend/mcp/management-skill-actions.test.ts` (new)
- `tests/backend/mcp/mcp-tool-availability.test.ts` or nearest existing MCP availability suite
- `docs/mcp/tools-and-contracts.md`
- `docs/mcp/runtime-and-dispatch.md`

## Implementation Requirements
1. Add `manage_skills` for storage CRUD, skill CRUD, agent attachment management, markdown import/export, and returning a skill-creation guide prompt; use existing payload parser and approval-envelope patterns for validation and destructive actions.
2. Add `search_skills` as a retrieval-focused MCP tool that accepts `projectId`, optional `agentPresetId`, optional `storageId`, query text, limits, and similarity threshold, then returns concise ranked skill summaries with IDs and metadata.
3. Register both tools in MCP definitions, request routing, management handler dispatch, and tool availability, placing them in the existing `agents_memory` category.
4. Ensure `search_skills` can be exposed to agents as the separate retrieval surface referenced by the issue, while `manage_skills` remains governed by Code UX tool access and approvals.
5. Include a comprehensive authoring prompt response that explains the expected markdown/frontmatter format and tells agents how to save new skills to persistent storage without writing into the workspace.
6. Add tests for validation failures, project isolation, approval-required delete/reset flows, successful create/update/search, and per-agent MCP tool filtering.
7. Update MCP docs with schemas, examples, approval behavior, and the distinction between management and retrieval tools.

## Constraints
- Depends on T02 `SkillService`; do not duplicate persistence logic in MCP handlers.
- Preserve existing management error envelope shape and `MethodNotFound` behavior for unavailable tools.
- Do not grant unknown agents broad tool access; respect existing fail-closed per-agent MCP policy.
- Keep returned skill content concise unless a caller explicitly asks for a specific full skill by ID.

## Verification
- Run `pnpm run lint`.
- Run `pnpm run test:backend -- tests/backend/mcp/management-skill-actions.test.ts` plus the focused MCP availability test file.
- Success means MCP callers can manage and search skills with consistent validation, approvals, and tool availability behavior.

✅ QA Review

⏳ QA review runs after this PR is opened. Check the task card in the dashboard for the outcome once it lands.

🤖 Model & Provider

Provider	Codex CLI
Model	gpt-5.5

⏱️ Timing

Started	2026-07-07 01:23:36 UTC
Finished	2026-07-07 01:34:01 UTC
Duration	10m 24s

📊 Token Usage

Metric	Value
Input tokens	178,131
Cached input tokens	4,926,848
Output tokens	23,212
Total tokens	5,128,191
Invocations	1
Tool calls	83
Active time	9m 55s

Included usage estimate (subscription/local login): $4.05

🌿 Branch Info

Base: feature/CODUX-149-self-reflection-persisten-skills
Head: task/feature-codux-149-self-reflection-persisten-skil-t03-codex-mr9ytmtn

---

🤖 Generated by Code UX