Skip to main content

​
Endpoint

skills.delete
This operation is irreversible. Deleted skills and their resources cannot be recovered.
This endpoint requires authentication and validates write permissions for the skill’s vault.

​
Input Schema

​
id
string
required
UUID of the skill to delete

​
Output Schema

​
success
boolean
Always returns true on successful deletion

​
Behavior

​
Permission Validation

  1. Verifies the skill exists
  2. Validates user has write permission to the skill’s vault
  3. Throws FORBIDDEN if:
    • User lacks write access
    • Vault is read-only (system_default or enterprise without admin role)

​
Cascade Deletion

Foreign key constraints automatically cascade the deletion:
  1. Resources: All skillResource records linked to the skill are deleted
  2. Links: All skillLink records where:
    • sourceSkillId = skill.id, or
    • targetSkillId = skill.id, or
    • sourceResourceId references a deleted resource, or
    • targetResourceId references a deleted resource
Graph integrity is maintained automatically through database constraints.

​
Hard Delete

Skills are hard deleted (not soft-deleted). The row is removed from the database immediately.

​
TypeScript Example

import { createTRPCClient, httpBatchLink } from '@trpc/client';
import type { AppRouter } from '@better-skills/api';

const client = createTRPCClient<AppRouter>({
  links: [
    httpBatchLink({
      url: 'http://localhost:3000/trpc',
      headers: {
        authorization: `Bearer ${token}`,
      },
    }),
  ],
});

// Delete a skill
try {
  const result = await client.skills.delete.mutate({
    id: skillId,
  });
  
  console.log('Skill deleted successfully');
  console.log(result); // { success: true }
} catch (error) {
  if (error.code === 'NOT_FOUND') {
    console.error('Skill not found or access denied');
  } else if (error.code === 'FORBIDDEN') {
    console.error('Permission denied:', error.message);
  }
}

​
Confirm Before Delete

// Best practice: fetch skill details first to show confirmation
const skill = await client.skills.getById.query({ id: skillId });

const confirm = await promptUser(
  `Delete skill "${skill.name}"? This will also delete ${skill.resources.length} resources.`
);

if (confirm) {
  await client.skills.delete.mutate({ id: skillId });
  console.log(`Deleted: ${skill.name}`);
}

​
Bulk Delete

// Delete multiple skills (sequential to handle errors individually)
const skillIds = ['uuid-1', 'uuid-2', 'uuid-3'];

for (const id of skillIds) {
  try {
    await client.skills.delete.mutate({ id });
    console.log(`Deleted: ${id}`);
  } catch (error) {
    console.error(`Failed to delete ${id}:`, error.message);
  }
}

​
Check Permissions Before Delete

// Fetch skill to check if it's deletable
const skill = await client.skills.getById.query({ id: skillId });

if (skill.vault.isReadOnly) {
  console.error(`Cannot delete skill in read-only vault: ${skill.vault.name}`);
} else if (skill.vault.type === 'system_default') {
  console.error('Cannot delete system default skills');
} else {
  // Proceed with deletion
  await client.skills.delete.mutate({ id: skillId });
}

​
Error Handling

​
NOT_FOUND
  • Skill does not exist
  • User lacks read permission to the skill’s vault (skill is hidden)
​
FORBIDDEN
  • User lacks write permission to the skill’s vault
  • Vault is read-only:
    • system_default vaults (always read-only)
    • enterprise vaults where user is not admin
​
UNAUTHORIZED
No valid session

​
Impact on References

​
Incoming References

When a skill is deleted, other skills that mentioned it lose those links:
  • skillLink records are automatically deleted
  • Mention syntax (@[skill-name](skill-id)) remains in source markdown
  • Next render shows the mention as unresolved or plain text

​
Outgoing References

Deleting a skill removes all its outgoing mentions:
  • Links from the skill to other skills/resources are deleted
  • Referenced targets remain unchanged
  • No orphaned data is left behind

​
Notes

  • Deletion is atomic: either the entire operation succeeds or nothing changes
  • Database foreign key constraints ensure referential integrity
  • No way to recover deleted skills (consider backup/export before deletion)
  • Personal vault skills can always be deleted by the owner
  • System default skills cannot be deleted by any user
  • Enterprise vault skills can only be deleted by vault admins
  • Deleting a skill with many incoming references will break those mention links

Build docs developers (and LLMs) love

Get started for freeTalk to us