codeux-ai · numnx · Jul 7, 2026 · Jul 7, 2026
diff --git a/docs-web/architecture/mcp-server.md b/docs-web/architecture/mcp-server.md
@@ -72,8 +72,8 @@ This is acceptable because clients are expected to re-`initialize` after restart
 ## Tool registry
 
 The request router (`src/server/mcp-request-router.ts`) is a `name → handler` map populated at boot.
-There is **one tool per management domain**, plus `search_knowledge` and the deprecated unified
-`manage_code_ux`:
+There is **one tool per management domain**, plus retrieval tools such as `search_knowledge` and
+`search_skills`, and the deprecated unified `manage_code_ux`:
 
 ```ts
 router
@@ -85,10 +85,12 @@ router
   .register("manage_scheduler",   h.handleManageScheduler)
   .register("manage_agents",      h.handleManageAgents)
   .register("manage_memory",      h.handleManageMemory)
+  .register("manage_skills",      h.handleManageSkills)
   .register("manage_settings",    h.handleManageSettings)
   .register("manage_preview",     h.handleManagePreview)
   .register("manage_telemetry",   h.handleManageTelemetry)
-  .register("search_knowledge",   h.handleSearchKnowledge);
+  .register("search_knowledge",   h.handleSearchKnowledge)
+  .register("search_skills",      h.handleSearchSkills);
 ```
 
 Every tool's input schema is declared in `TOOL_DEFINITIONS` (`src/contracts/mcp-tool-definitions.ts`).
@@ -102,16 +104,21 @@ Source: `src/server/mcp-request-router.ts`.
 ```
 Server returns getEnabledToolDefinitions(settings, runtimeRole)
   ├── Filter by settings.mcpTools[].enabled
+  ├── Filter by advertised agent Code UX policy, when present
   └── Filter by tool.runtimeRoles ⊇ runtimeRole
 ```
 
+Advertised agent identities fail closed when malformed, unknown, or missing an explicit MCP access
+policy. This prevents an unknown worker agent from inheriting broad project-manager tools.
+
 ### `CallTool`
 
 ```
 1. Validate tool name against the enabled set.
-2. AJV-validate args against TOOL_DEFINITIONS[name].inputSchema.
-3. toolRegistry.dispatch(name, args).
-4. Wrap handler errors via formatError().
+2. Apply the same per-agent enabled-set filtering used by `ListTools`.
+3. AJV-validate args against TOOL_DEFINITIONS[name].inputSchema.
+4. toolRegistry.dispatch(name, args).
+5. Wrap handler errors via formatError().
 ```
 
 Errors:
@@ -133,7 +140,9 @@ Each tool has an entry in `settings.mcpTools` (`McpToolToggle[]`). Defaults:
   { "name": "manage_scheduler",    "enabled": true, "isInternal": true },
   { "name": "manage_agents",       "enabled": true, "isInternal": true },
   { "name": "manage_memory",       "enabled": true, "isInternal": true },
+  { "name": "manage_skills",       "enabled": true, "isInternal": true },
   { "name": "search_knowledge",    "enabled": true, "isInternal": true },
+  { "name": "search_skills",       "enabled": true, "isInternal": true },
   { "name": "manage_settings",     "enabled": true, "isInternal": true },
   { "name": "manage_preview",      "enabled": true, "isInternal": true },
   { "name": "manage_telemetry",    "enabled": true, "isInternal": true },
@@ -143,6 +152,10 @@ Each tool has an entry in `settings.mcpTools` (`McpToolToggle[]`). Defaults:
 
 Disabling a tool removes it from `ListTools` and rejects `CallTool`.
 
+Per-agent overrides are layered over these system toggles. A project can expose `search_skills` to an
+agent while disabling `manage_skills`, which gives the agent persistent skill retrieval without
+storage mutation, markdown export, delete, or reset authority.
+
 ## Approval handshake
 
 Destructive and mutating actions (deletes, resets, settings replacements/patches) are flagged across
@@ -158,6 +171,13 @@ single-use.
 
 Source: `src/mcp/management-tool-handler.ts`.
 
+## Persistent skill dispatch
+
+Persistent skills use `SkillService` as the backend boundary. `manage_skills` routes storage CRUD,
+skill markdown import/export, agent storage attachment management, and the authoring prompt through
+`SkillActions`. `search_skills` is registered separately as a retrieval tool and returns concise
+ranked summaries with IDs and metadata. Full markdown retrieval stays behind `manage_skills`.
+
 ## Connection registry
 
 The `ConnectionRegistry` tracks every MCP client that connects. Each entry records:

diff --git a/docs-web/developer/mcp-tools.md b/docs-web/developer/mcp-tools.md
@@ -1,9 +1,9 @@
 # MCP tools
 
 Code UX is also an MCP server. When connected, it advertises a set of **management tools** that an
-MCP client (or another agent) can call to drive projects, sprints, tasks, agents, memory, settings,
-previews, and telemetry. This page is the exact contract: the tool list, each tool's `action` enum,
-input shape, approval rules, and the error model.
+MCP client (or another agent) can call to drive projects, sprints, tasks, agents, memory, persistent
+skills, settings, previews, and telemetry. This page is the exact contract: the tool list, each
+tool's `action` enum, input shape, approval rules, and the error model.
 
 > **Server identity:** the server identifies as `code-ux`, with the version matching the installed
 > package. The package on npm is `@codeuxai/codeux`. Capabilities advertised at
@@ -17,15 +17,19 @@ Tools are filtered before being advertised on `ListTools`:
    (default and only functional role: `project_manager`).
 2. **Toggle** — each tool has an entry under `settings.mcpTools`. Disabled tools are not advertised
    and return `MethodNotFound` if called.
+3. **Per-agent Code UX policy** — HTTP worker clients can advertise an agent preset. Unknown,
+   malformed, or unconfigured agent identities fail closed and receive no built-in Code UX tools.
+   Known agents can receive tool-specific overrides; for example, `search_skills` can stay enabled
+   while `manage_skills` is disabled.
 
 All inputs are validated against their declared JSON Schema (AJV) before dispatch; validation
 failures return `InvalidParams` with the failing JSON path.
 
 ## The tools
 
-Code UX exposes **one tool per management domain**, plus `search_knowledge`. Each `manage_*` tool
-takes an `action` (from a fixed enum) plus action-specific fields, and an optional `approval` object
-for destructive actions.
+Code UX exposes **one tool per management domain**, plus retrieval tools such as `search_knowledge`
+and `search_skills`. Each `manage_*` tool takes an `action` (from a fixed enum) plus
+action-specific fields, and an optional `approval` object for destructive actions.
 
 | Tool | Category | Purpose |
 | --- | --- | --- |
@@ -36,7 +40,9 @@ for destructive actions.
 | `manage_scheduler` | orchestration | Create and run scheduled sprints, quicksprints, and messages. |
 | `manage_agents` | agents & memory | Manage agent presets and sync them to project markdown. |
 | `manage_memory` | agents & memory | Inspect, search, promote, and re-embed short/long-term memory. |
+| `manage_skills` | agents & memory | Manage persistent skill storages, skill markdown, and agent storage attachments. |
 | `search_knowledge` | agents & memory | Semantic search over the knowledge base subscribed to the caller. |
+| `search_skills` | agents & memory | Semantic retrieval over persistent project skills, optionally scoped to an agent or storage. |
 | `manage_settings` | platform | Get/resolve/patch/replace/reset system, project, and sprint settings. |
 | `manage_preview` | platform | Manage sprint preview containers (start/stop/rebuild, logs, scripts). |
 | `manage_telemetry` | platform | Read execution snapshots, invocations, sprint runs, and dispatches. |
@@ -54,6 +60,7 @@ Every tool requires `runtimeRoles: ["project_manager"]` and is enabled by defaul
 | `manage_scheduler` | `list`, `create`, `update`, `delete`, `run_due`, `schedule_sprint`, `schedule_quicksprint`, `schedule_chat` |
 | `manage_agents` | `list`, `get`, `create`, `update`, `delete`, `sync` |
 | `manage_memory` | `list`, `get`, `count`, `create`, `update`, `delete`, `search`, `promote`, `get_map`, `model_status`, `start_reembed` |
+| `manage_skills` | `authoring_prompt`, `list_storages`, `get_storage`, `create_storage`, `update_storage`, `delete_storage`, `reset_storage`, `list_agent_storages`, `attach_storage`, `detach_storage`, `list_skills`, `get_skill`, `create_skill`, `update_skill`, `delete_skill`, `import_markdown`, `export_markdown` |
 | `manage_settings` | `get_system`, `get_project_override`, `resolve_project_effective`, `get_sprint_override`, `resolve_sprint_effective`, `replace_system_settings`, `patch_system_setting`, `replace_project_settings`, `patch_project_setting`, `reset_project_settings`, `replace_sprint_settings`, `patch_sprint_setting`, `reset_sprint_settings` |
 | `manage_preview` | `list_sessions`, `start_session`, `stop_session`, `rebuild_session`, `remove_session`, `get_logs`, `get_url`, `get_script`, `update_script` |
 | `manage_telemetry` | `get_project_stats_snapshot`, `get_project_execution_snapshot`, `list_execution_invocations`, `list_execution_invocation_messages`, `list_sprint_runs`, `list_task_dispatches` |
@@ -92,6 +99,47 @@ subscriptions, so no project id is needed.
 Returns the most relevant passages with their source documents. See the
 [Knowledge](../user/dashboard/knowledge.md) page for managing the underlying documents.
 
+## Persistent skills
+
+`manage_skills` is the storage and authoring surface for durable project skills. It supports:
+
+- Storage CRUD: `list_storages`, `get_storage`, `create_storage`, `update_storage`, `delete_storage`.
+- Skill CRUD: `list_skills`, `get_skill`, `create_skill`, `update_skill`, `delete_skill`.
+- Agent attachment management: `list_agent_storages`, `attach_storage`, `detach_storage`.
+- Markdown import/export: `import_markdown`, `export_markdown`.
+- Authoring guidance: `authoring_prompt`.
+- Destructive cleanup: `delete_storage`, `reset_storage`, and `delete_skill` require the approval handshake.
+
+Skill markdown is saved through MCP payloads, not by writing files into the project workspace:
+
+```md
+---
+title: Review Discipline
+description: Keep review findings concrete.
+tags: ["review", "quality"]
+appliesTo: ["src/services", "tests/backend"]
+version: 1.0.0
+---
+
+Focus on bugs, regressions, missing tests, and rollback risk.
+```
+
+`search_skills` is the retrieval-only surface. It accepts:
+
+```jsonc
+{
+  "projectId": "project-123",      // required
+  "query": "review checklist",      // required
+  "agentPresetId": "agent-123",     // optional, searches attached storages
+  "storageId": "skills-review",     // optional, narrows to one storage
+  "limit": 5,                       // optional, capped by the handler
+  "minSimilarity": 0.3              // optional, 0-1
+}
+```
+
+Search results return concise ranked summaries with skill IDs and metadata. Full content retrieval
+requires `manage_skills` via `export_markdown` or `get_skill` with `includeContent: true`.
+
 ## Error model
 
 Tool handlers return one of:

diff --git a/docs/mcp/runtime-and-dispatch.md b/docs/mcp/runtime-and-dispatch.md
@@ -45,9 +45,13 @@ Registered schemas:
 ### Tool list handler
 Returns enabled tool definitions from `src/contracts/mcp-tool-definitions.ts`, filtered by dashboard `mcpTools` settings.
 
+When a worker MCP client advertises an agent preset, Code UX resolves that agent's explicit MCP access policy before listing tools. Unknown or malformed agent identities fail closed: `list_tools` returns no built-in Code UX tools, and `call_tool` returns MCP `MethodNotFound`.
+
 ### Tool call handler
 - Resolves tool name.
 - Verifies tool is enabled in `mcpTools`.
+- Applies the same per-agent Code UX access policy used by `list_tools`.
+- Validates tool arguments against the registered JSON schema before dispatch.
 - Dispatches through typed `ToolRegistry` registration in `src/api/mcp/tool-registry.ts`.
 - Wraps unknown tool as MCP `MethodNotFound`.
 - Normalizes runtime/API errors into `isError` response.
@@ -68,11 +72,27 @@ This allows all log lines emitted during a tool call to share a single `correlat
 - Typed registry layer: `src/api/mcp/tool-registry.ts`
   - Defines strict argument interfaces for every MCP tool.
   - Provides `register` and `dispatch` APIs with compile-time tool/argument matching.
+- Management dispatch target: `ManagementToolHandler`
+  - Routes dedicated management tools such as `manage_projects`, `manage_memory`, and `manage_skills` to domain action classes.
+  - Routes retrieval tools such as `search_knowledge` and `search_skills` separately, so agents can receive retrieval without broader management authority.
+  - Applies stateful approval fingerprints to destructive management actions before mutation.
 - Core dispatch target: `CoreToolHandler`
 - Agent dispatch target: `AgentToolHandler`
 
 This split keeps tool contracts stable while allowing orchestration internals to evolve independently.
 
+## Persistent Skill Tools
+
+Persistent skills use `SkillService` as the backend boundary. The MCP layer does not write markdown files into project workspaces and does not duplicate persistence logic; it validates payloads, formats concise responses, and calls the service.
+
+Runtime behavior:
+
+- `manage_skills` is a Code UX management tool in the `agents_memory` category. It supports storage CRUD, skill markdown import/export, agent storage attachment management, and the skill-authoring prompt.
+- `delete_storage`, `reset_storage`, and `delete_skill` return approval-required envelopes on first call and only mutate on the matching confirmed call.
+- `search_skills` is registered as a distinct retrieval tool in the same category. Per-agent MCP policy can disable `manage_skills` while leaving `search_skills` enabled.
+- Search scoping is project-owned. `storageId` limits retrieval to one storage; otherwise `agentPresetId` limits retrieval to the agent's attached storages; otherwise all project storages are eligible.
+- Search results return ranked summaries with IDs and metadata. Full markdown retrieval remains behind `manage_skills` (`export_markdown` or `get_skill` with `includeContent: true`).
+
 ## Custom MCP Defaults
 
 Dashboard settings include custom MCP servers that local CLI providers may receive at execution time.