# How Skills Are Created and Versioned in TencentDB Agent Memory: A Complete Technical Guide

> Learn how skills are created and versioned in TencentDB Agent Memory. Discover immutable, versioned artifacts with atomic increments and historical snapshot retention. A complete technical guide.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: how-to-guide
- Published: 2026-08-29

---

**Skills in TencentDB Agent Memory are immutable, versioned artifacts that start at version 1 and increment atomically through write operations requiring the current `expected_version`, with all historical snapshots retained in the SkillVersions table until they exceed the `versionTtlSeconds` retention window.**

TencentDB Agent Memory models every Skill as an immutable artifact scoped to a team-agent context within the TencentCloud/TencentDB-Agent-Memory repository. When skills are created and versioned in TencentDB Agent Memory, the system assigns a unique **skill_id** and initializes the version counter at 1, enforcing strict optimistic concurrency controls for all subsequent modifications. Each write operation validates the provided `expected_version` before atomically incrementing the version number and persisting a new snapshot of the SKILL.md content and accompanying resources.

## Understanding the Skill Lifecycle Architecture

The skill lifecycle follows a structured protocol designed to prevent race conditions and ensure complete auditability. All mutations occur through specific API endpoints that interact with the **SkillVersions** table, where every state change generates a new record rather than modifying existing data.

### Initial Skill Creation (Version 1)

When you invoke `POST /v3/skill/create` through the TypeScript SDK or direct API call, the server initializes the artifact with the provided `name`, `content` (typically formatted as SKILL.md), optional `resources`, and `metadata`. As defined in [`src/v3/skill-types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/skill-types.ts), the response contains the generated **skill_id** and initial version metadata. This first snapshot automatically becomes the head version, marked with `is_head: true` in all query responses.

### Atomic Updates Using Expected Version

Modifications occur through two primary mechanisms: `POST /v3/skill/update` for full content replacement and `POST /v3/skill/patch` for partial text substitution. Both endpoints require the `expected_version` parameter, representing the current head version you intend to supersede. According to the implementation in [`src/gateway/skill-schemas.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/gateway/skill-schemas.ts) and mirrored in the SDK, the server validates this value against the actual head version stored in the SkillVersions table. If the values match, the server increments the version counter and persists the new snapshot; if they diverge, the operation fails with error codes `40001` or `40301`, signaling a concurrent modification conflict.

### Archiving and Deletion

To remove a skill entirely, use `POST /v3/skill/delete` with the current `expected_version`. This archives or removes the entire skill lineage across all versions, not just the current iteration. The operation requires the same version validation to prevent accidental deletion of unexpectedly modified resources.

## Version Storage and Retention Mechanics

The versioning system maintains complete history through dedicated types and retention policies that balance audit requirements with storage constraints.

### The SkillVersions Table and Type Hierarchy

The `SkillSummary` type defines the core metadata fields including `version` (the numeric identifier) and `is_head` (boolean indicating the latest iteration). For historical queries, `SkillVersionSummary` extends `SkillSummary` to include the `is_expired` flag, as specified in [`src/v3/skill-types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/skill-types.ts). When retrieving specific points in history via `POST /v3/skill/get`, you optionally supply the `version` parameter; omitting it returns the current head. For bulk enumeration, `POST /v3/skill/versions` accepts `SkillPagination` parameters (`limit`, `offset`) to page through large version histories efficiently.

### Expiration Policy and versionTtlSeconds

Versions transition to an expired state when their age exceeds the `versionTtlSeconds` configuration value. While expired versions remain queryable and appear in list results with `is_expired: true`, they become candidates for storage reclamation. The system never returns expired versions when requesting the head snapshot, ensuring active agents always receive current, supported skill definitions.

## Implementing Version Control with the TypeScript SDK

The TencentDB Agent Memory TypeScript SDK abstracts the REST protocol through strongly-typed clients located in [`src/v3/skill-client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/skill-client.ts). These wrappers enforce required context fields and provide convenience methods for the complete skill lifecycle.

### Client Initialization and Context

All operations require `team_id`, `agent_id`, and `user_id` context. The `SkillClient` validates these fields before transmission, though the server performs final authority checks. Initialize the client with your endpoint and default identifiers:

```typescript
import { SkillClient } from './src/v3/skill-client';

const client = new SkillClient({
  baseUrl: 'https://memory.tencentcloud.com',
  defaults: { 
    user_id: 'u-123', 
    team_id: 't-abc', 
    agent_id: 'a-xyz' 
  },
});

```

### Creating and Evolving Skills

Creating a skill initializes the version chain at 1, while updates require explicit version tracking:

```typescript
// Create initial skill (version automatically set to 1)
await client.createSkill({
  name: 'data-processing',
  content: `---
name: data-processing
description: Process incoming telemetry
---
export function run() { return "processed"; }`,
});

// Update to version 2 by providing expected_version = 1
await client.updateSkill({
  skill_id: 'skl-001',
  expected_version: 1,
  content: `---
name: data-processing
description: Process telemetry with filtering
---
export function run() { return "filtered"; }`,
});

```

### Retrieving Historical Versions

Access specific snapshots or enumerate the complete history with pagination:

```typescript
// Retrieve latest head version
const latest = await client.getSkill({ skill_id: 'skl-001' });
console.log(latest.version); // 2
console.log(latest.is_head);  // true

// Access specific historical version
const v1 = await client.getSkill({ 
  skill_id: 'skl-001', 
  version: 1 
});

// List all versions with expiration status
const versions = await client.listSkillVersions({ 
  skill_id: 'skl-001', 
  pagination: { limit: 10 } 
});

versions.items.forEach(v => {
  console.log(`v${v.version} - expired: ${v.is_expired}`);
});

```

## Summary

- **Immutable Versioning**: Every modification creates a new snapshot with an auto-incremented version number starting at 1, stored permanently in the SkillVersions table until expiration.
- **Optimistic Concurrency Control**: The `expected_version` parameter prevents lost updates by validating the client's view matches the server state before incrementing, returning errors `40001` or `40301` on mismatches.
- **TypeScript Contracts**: The SDK defines request/response schemas in [`src/v3/skill-types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/skill-types.ts) and implements the convenience layer in [`src/v3/skill-client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/skill-client.ts), with validation schemas maintained in [`src/gateway/skill-schemas.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/gateway/skill-schemas.ts).
- **Retention and Expiration**: Versions exceeding `versionTtlSeconds` are flagged with `is_expired: true` in `SkillVersionSummary` responses but remain accessible for audit purposes.
- **Scoped Operations**: All API calls require `team_id`, `agent_id`, and `user_id` context, ensuring strict isolation between different organizational units and agent instances.

## Frequently Asked Questions

### What happens if I provide the wrong expected_version when updating a skill?

The server rejects the request with error codes `40001` or `40301`. This optimistic locking mechanism prevents concurrent writers from overwriting each other's changes. You must first retrieve the current head version using `getSkill()` to obtain the correct version number before attempting any update or patch operation.

### Can I delete a specific version of a skill while keeping others?

No, the `POST /v3/skill/delete` endpoint archives or removes the entire skill lineage identified by `skill_id`. Individual versions cannot be selectively deleted through the public API. All versions remain accessible until they naturally expire based on the `versionTtlSeconds` retention policy, after which they may be purged from storage but remain listed with `is_expired: true`.

### How do I perform a partial text update without replacing the entire skill content?

Use the `POST /v3/skill/patch` endpoint via `SkillClient.patchSkill()`, specifying the `old_string` to locate and `new_string` for replacement, along with the required `expected_version`. This executes a targeted text substitution within the existing content while still incrementing the version number and creating a new immutable snapshot in the SkillVersions table.

### What distinguishes SkillSummary from SkillVersionSummary in the type system?

`SkillSummary` provides basic metadata including `version` and `is_head` status for general skill identification. `SkillVersionSummary` extends this type specifically for version enumeration operations (via `POST /v3/skill/versions`), adding the `is_expired` boolean field to indicate whether the specific version has exceeded the retention window defined by `versionTtlSeconds`.