Skip to main content

​
Overview

Resources are updated as part of the skill update workflow using the skills.update endpoint. You can add new resources, modify existing ones, or delete resources that are no longer needed.

​
Updating Resources

The skills.update endpoint accepts a resources array where you can specify changes:

​
Input Schema

​
id
string
required
The UUID of the skill containing the resources to update
​
resources
array
Array of resource operations (add, update, or delete)

​
Operations

​
Add New Resources

Include resource objects without an id field: 
await trpc.skills.update.mutate({
  id: 'skill-uuid',
  resources: [
    {
      // No id = new resource
      path: 'scripts/new-script.sh',
      kind: 'script',
      content: '#!/bin/bash\necho "New script"'
    }
  ]
});

​
Update Existing Resources

Include the id field with updated content: 
await trpc.skills.update.mutate({
  id: 'skill-uuid',
  resources: [
    {
      id: 'resource-uuid',
      path: 'scripts/install.sh',
      kind: 'script',
      content: '#!/bin/bash\n\n# Updated script\necho "Installing..."',
      metadata: { version: '2.0' }
    }
  ]
});

​
Delete Resources

Set delete: true with the resource id: 
await trpc.skills.update.mutate({
  id: 'skill-uuid',
  resources: [
    {
      id: 'resource-uuid',
      delete: true
    }
  ]
});

​
Complete Example

import { trpc } from './trpc';

// Add, update, and delete resources in one call
const updatedSkill = await trpc.skills.update.mutate({
  id: 'skill-uuid',
  resources: [
    // Add a new resource
    {
      path: 'reference/new-guide.md',
      kind: 'reference',
      content: '# New Guide\n\nSee [[docker]] for setup.'
    },
    // Update an existing resource
    {
      id: 'existing-resource-uuid',
      path: 'scripts/install.sh',
      kind: 'script',
      content: '#!/bin/bash\n\n# Updated version\necho "v2.0"',
      metadata: { version: '2.0' }
    },
    // Delete a resource
    {
      id: 'old-resource-uuid',
      delete: true
    }
  ]
});

console.log(`Skill now has ${updatedSkill.resources.length} resources`);

​
Mention Re-validation

When you update resource content that contains skill mentions:
  1. Validation - All [[skill-name]] mentions are validated against accessible skills
  2. Link Sync - The knowledge graph links are automatically updated
  3. Rendering - Updated content is re-rendered with clickable mention links
  4. Error Handling - If mentions are invalid, the update fails and no changes are made

​
Example with Mentions

// Update resource with new mentions
await trpc.skills.update.mutate({
  id: 'skill-uuid',
  resources: [
    {
      id: 'resource-uuid',
      path: 'reference/guide.md',
      content: `
# Installation Guide

This guide depends on:
- [[docker]] for containerization
- [[kubernetes]] for orchestration
- [[git]] for version control

See also: [[troubleshooting]]
      `.trim()
    }
  ]
});

// All mentions are validated and links are synced automatically
When resources are updated:
1

Content Analysis

The system parses the new content and extracts all [[skill-name]] mentions
2

Validation

Each mention is validated to ensure the referenced skill exists and is accessible
3

Graph Update

Old graph links from this resource are removed and new links are created for the updated mentions
4

Rendering

Content is rendered with mentions converted to clickable links in renderedContent
This happens automatically - you don’t need to manually manage graph links.

​
Partial Updates

If you only include some resources in the update, other resources remain unchanged: 
// Only updates the specified resources
// All other resources in the skill remain as-is
await trpc.skills.update.mutate({
  id: 'skill-uuid',
  resources: [
    {
      id: 'resource-1',
      path: 'scripts/install.sh',
      kind: 'script',
      content: 'updated content'
    }
    // resource-2, resource-3, etc. are not affected
  ]
});

​
Error Handling

​
BAD_REQUEST
Returned when:
  • Mention syntax is malformed
  • Referenced skills don’t exist or aren’t accessible
  • Duplicate resource paths within the same skill
​
FORBIDDEN
Returned when:
  • User doesn’t have write access to the skill’s vault
  • Attempting to reference skills from inaccessible vaults
​
NOT_FOUND
Returned when:
  • The skill ID doesn’t exist
  • The resource ID doesn’t exist (for updates/deletes)

​
Access Control

To update resources:
  • User must have write access to the skill’s vault
  • Referenced skills must be in accessible vaults (same vault or vaults user has read access to)
  • Resources cannot reference skills from inaccessible vaults

​
Response

The endpoint returns the complete updated skill object with all resources (including the updated renderedContent): 
type UpdatedSkill = {
  id: string;
  slug: string;
  name: string;
  // ... skill fields
  resources: Array<{
    id: string;
    path: string;
    kind: 'reference' | 'script' | 'asset' | 'other';
    content: string;           // Raw content with mentions
    renderedContent: string;   // Content with rendered links
    metadata: Record<string, unknown>;
    createdAt: Date;
    updatedAt: Date;
  }>;
};
  • skills.update - Main endpoint for updating resources
  • skills.getById - Get a skill with all its resources
  • resources.getById - Retrieve a specific resource
  • resources.create - Create resources with new skills

Build docs developers (and LLMs) love

Get started for freeTalk to us