Prd 6236

.changeset/file-routed-skills-ui.md

@@ -0,0 +1,5 @@
+---
+'@inkeep/agents-manage-ui': patch
+---
+
+Add file-routed skill browsing and editing so synced skill files open in dedicated read-only and edit pages with file-level remove actions.

.changeset/nested-skill-files.md

@@ -0,0 +1,8 @@
+---
+'@inkeep/agents-core': patch
+'@inkeep/agents-sdk': patch
+'@inkeep/agents-api': patch
+'@inkeep/agents-manage-ui': patch
+---
+
+Add nested skill file persistence and syncing so skill directories keep auxiliary files alongside `SKILL.md` during API updates and `inkeep push`.

agents-api/__snapshots__/openapi.json

@@ -7299,6 +7299,26 @@
             "minLength": 1,
             "type": "string"
           },
+          "files": {
+            "items": {
+              "properties": {
+                "content": {
+                  "type": "string"
+                },
+                "filePath": {
+                  "maxLength": 1024,
+                  "minLength": 1,
+                  "type": "string"
+                }
+              },
+              "required": [
+                "filePath",
+                "content"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
           "metadata": {
             "allOf": [
               {
@@ -7323,6 +7343,39 @@
         ],
         "type": "object"
       },
+      "SkillFile": {
+        "properties": {
+          "content": {
+            "type": "string"
+          },
+          "createdAt": {
+            "type": "string"
+          },
+          "filePath": {
+            "type": "string"
+          },
+          "id": {
+            "maxLength": 256,
+            "type": "string"
+          },
+          "skillId": {
+            "maxLength": 64,
+            "type": "string"
+          },
+          "updatedAt": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "skillId",
+          "filePath",
+          "content",
+          "createdAt",
+          "updatedAt"
+        ],
+        "type": "object"
+      },
       "SkillListResponse": {
         "properties": {
           "data": {
@@ -7341,17 +7394,6 @@
         ],
         "type": "object"
       },
-      "SkillResponse": {
-        "properties": {
-          "data": {
-            "$ref": "#/components/schemas/Skill"
-          }
-        },
-        "required": [
-          "data"
-        ],
-        "type": "object"
-      },
       "SkillUpdate": {
         "properties": {
           "content": {
@@ -7363,6 +7405,26 @@
             "minLength": 1,
             "type": "string"
           },
+          "files": {
+            "items": {
+              "properties": {
+                "content": {
+                  "type": "string"
+                },
+                "filePath": {
+                  "maxLength": 1024,
+                  "minLength": 1,
+                  "type": "string"
+                }
+              },
+              "required": [
+                "filePath",
+                "content"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
           "metadata": {
             "allOf": [
               {
@@ -7376,6 +7438,38 @@
         },
         "type": "object"
       },
+      "SkillWithFiles": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/Skill"
+          },
+          {
+            "properties": {
+              "files": {
+                "items": {
+                  "$ref": "#/components/schemas/SkillFile"
+                },
+                "type": "array"
+              }
+            },
+            "required": [
+              "files"
+            ],
+            "type": "object"
+          }
+        ]
+      },
+      "SkillWithFilesResponse": {
+        "properties": {
+          "data": {
+            "$ref": "#/components/schemas/SkillWithFiles"
+          }
+        },
+        "required": [
+          "data"
+        ],
+        "type": "object"
+      },
       "StatusComponent": {
         "properties": {
           "description": {
@@ -36662,7 +36756,7 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/SkillResponse"
+                  "$ref": "#/components/schemas/SkillWithFilesResponse"
                 }
               }
             },
@@ -36883,7 +36977,7 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/SkillResponse"
+                  "$ref": "#/components/schemas/SkillWithFilesResponse"
                 }
               }
             },
@@ -37005,7 +37099,7 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/SkillResponse"
+                  "$ref": "#/components/schemas/SkillWithFilesResponse"
                 }
               }
             },

agents-api/src/__tests__/manage/integration/skills.test.ts

@@ -0,0 +1,193 @@
+import { generateId } from '@inkeep/agents-core';
+import { afterEach, describe, expect, it } from 'vitest';
+import { cleanupTenants } from '../../utils/cleanup';
+import { makeRequest } from '../../utils/testRequest';
+import { createTestTenantWithOrg } from '../../utils/testTenant';
+
+describe('Skill Routes - Integration Tests', () => {
+  const createdTenants = new Set<string>();
+
+  afterEach(async () => {
+    await cleanupTenants(createdTenants);
+    createdTenants.clear();
+  });
+
+  const createTrackedTenant = async (suffix: string) => {
+    const tenantId = await createTestTenantWithOrg(suffix);
+    createdTenants.add(tenantId);
+    return tenantId;
+  };
+
+  const createProject = async (tenantId: string, projectId: string) => {
+    const response = await makeRequest(`/manage/tenants/${tenantId}/projects`, {
+      method: 'POST',
+      body: JSON.stringify({
+        id: projectId,
+        name: 'Test Project',
+        description: 'Test project',
+        models: {
+          base: {
+            model: 'claude-sonnet-4',
+            providerOptions: {},
+          },
+        },
+      }),
+    });
+
+    expect(response.status).toBe(201);
+  };
+
+  it('should create, fetch, and update nested skill files', async () => {
+    const tenantId = await createTrackedTenant('skills-crud');
+    const projectId = `project-${generateId()}`;
+    await createProject(tenantId, projectId);
+
+    const createResponse = await makeRequest(
+      `/manage/tenants/${tenantId}/projects/${projectId}/skills`,
+      {
+        method: 'POST',
+        body: JSON.stringify({
+          name: 'weather-safety-guardrails',
+          description: 'Safety rules.',
+          content: 'Always check the weather.',
+          metadata: null,
+          files: [
+            {
+              filePath: 'SKILL.md',
+              content: `---
+name: weather-safety-guardrails
+description: "Safety rules."
+---
+Always check the weather.`,
+            },
+            {
+              filePath: 'reference/safety-checklist.txt',
+              content: 'Check alerts',
+            },
+          ],
+        }),
+      }
+    );
+
+    expect(createResponse.status).toBe(201);
+    const createdBody = await createResponse.json();
+    expect(createdBody.data.files).toEqual([
+      expect.objectContaining({ filePath: 'SKILL.md' }),
+      expect.objectContaining({ filePath: 'reference/safety-checklist.txt' }),
+    ]);
+
+    const listResponse = await makeRequest(
+      `/manage/tenants/${tenantId}/projects/${projectId}/skills`
+    );
+    expect(listResponse.status).toBe(200);
+    const listBody = await listResponse.json();
+    expect(listBody.data[0].files).toBeUndefined();
+
+    const detailResponse = await makeRequest(
+      `/manage/tenants/${tenantId}/projects/${projectId}/skills/weather-safety-guardrails`
+    );
+    expect(detailResponse.status).toBe(200);
+    const detailBody = await detailResponse.json();
+    expect(detailBody.data.files.map((file: any) => file.filePath)).toEqual([
+      'SKILL.md',
+      'reference/safety-checklist.txt',
+    ]);
+
+    const updateResponse = await makeRequest(
+      `/manage/tenants/${tenantId}/projects/${projectId}/skills/weather-safety-guardrails`,
+      {
+        method: 'PUT',
+        body: JSON.stringify({
+          description: 'Updated safety rules.',
+          content: 'Always check alerts.',
+          files: [
+            {
+              filePath: 'SKILL.md',
+              content: `---
+name: weather-safety-guardrails
+description: "Updated safety rules."
+---
+Always check alerts.`,
+            },
+            {
+              filePath: 'templates/alert.md',
+              content: 'Alert template',
+            },
+          ],
+        }),
+      }
+    );
+
+    expect(updateResponse.status).toBe(200);
+    const updatedBody = await updateResponse.json();
+    expect(updatedBody.data.files.map((file: any) => file.filePath)).toEqual([
+      'SKILL.md',
+      'templates/alert.md',
+    ]);
+  });
+
+  it('should round-trip nested skill files through the full project API', async () => {
+    const tenantId = await createTrackedTenant('skills-project-full');
+    const projectId = `project-${generateId()}`;
+
+    const createResponse = await makeRequest(`/manage/tenants/${tenantId}/project-full`, {
+      method: 'POST',
+      body: JSON.stringify({
+        id: projectId,
+        name: 'Test Project',
+        description: 'Test project',
+        models: {
+          base: {
+            model: 'claude-sonnet-4',
+            providerOptions: {},
+          },
+        },
+        agents: {},
+        tools: {},
+        skills: {
+          'structured-itinerary-responses': {
+            id: 'structured-itinerary-responses',
+            name: 'structured-itinerary-responses',
+            description: 'Structured itineraries.',
+            content: 'Use itinerary templates.',
+            metadata: null,
+            files: [
+              {
+                filePath: 'SKILL.md',
+                content: `---
+name: structured-itinerary-responses
+description: "Structured itineraries."
+---
+Use itinerary templates.`,
+              },
+              {
+                filePath: 'templates/day/itinerary-card.html',
+                content: '<article>Plan</article>',
+              },
+            ],
+          },
+        },
+      }),
+    });
+
+    expect(createResponse.status).toBe(201);
+
+    const getResponse = await makeRequest(`/manage/tenants/${tenantId}/project-full/${projectId}`);
+    expect(getResponse.status).toBe(200);
+    const getBody = await getResponse.json();
+    expect(getBody.data.skills['structured-itinerary-responses'].files).toEqual([
+      {
+        filePath: 'SKILL.md',
+        content: `---
+name: structured-itinerary-responses
+description: "Structured itineraries."
+---
+Use itinerary templates.`,
+      },
+      {
+        filePath: 'templates/day/itinerary-card.html',
+        content: '<article>Plan</article>',
+      },
+    ]);
+  });
+});