# What Are Skills in TencentDB Agent Memory and How Are They Versioned?

> Understand skills in TencentDB Agent Memory. Learn how these versioned, executable knowledge assets are managed with metadata, resource files, and TTL-based cleanup.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: deep-dive
- Published: 2026-09-02

---

**Skills in TencentDB Agent Memory are versioned, executable knowledge assets comprising a markdown document (SKILL.md), optional resource files, metadata, and immutable version history managed through a monotonic integer scheme with configurable TTL-based cleanup.**

TencentDB Agent Memory treats **skills** as first-class assets that agents can store, retrieve, and execute. This architecture enables reproducible agent behavior, rollback capabilities, and efficient knowledge management at scale. Below is a comprehensive breakdown of the skill data model and its versioning mechanics as implemented in the [TencentCloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory) repository.


## Skill Structure and Components

Every skill consists of four core elements defined in [`skill-types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/skill-types.ts)【/cache/repos/github.com/TencentCloud/TencentDB-Agent-Memory/feat/server_team/sdk/memory-core/typescript/src/v3/skill-types.ts】:

| Component | Purpose |
|-----------|---------|
| **SKILL.md** | Canonical markdown document with YAML front-matter (name, description, version) and instructional body content |
| **Resources** | Optional files stored under a `files/` directory, tracked via `SkillManifestEntry` objects |
| **Metadata** | Arbitrary JSON object (`metadata_json`) attached to each version for custom extensions |
| **Version Info** | Immutable version records with `version` integer, `is_head` flag, and `created_at_ms` timestamp |

The TypeScript SDK exposes these through **17 `/v3/skill/*` HTTP endpoints** wrapped by [`skill-client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/skill-client.ts).


## How Skill Versioning Works

TencentDB Agent Memory implements **append-only, immutable versioning** through the `SkillVersioning` class in [`skill-versioning.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/skill-versioning.ts)【/cache/repos/github.com/TencentCloud/TencentDB-Agent-Memory/feat/server_team/MemoryCore/src/core/skill/skill-versioning.ts】.

### Creating the First Version (v1)

When `SkillVersioning.createNewSkill()` is invoked:

1. The caller supplies a unique `skill_id`
2. Resources upload to COS (Cloud Object Storage) via the storage adapter
3. A version row inserts into the skill DB via `store.appendVersion`
4. Optional `onSkillCreated` hook registers the asset in meta-assets
5. System reports **+1 VDB delta** via `onSkillVdbChanged` to Shark (usage tracking)

```typescript
import { SkillClient } from "./sdk/memory-core/typescript/src/v3/skill-client";

const client = new SkillClient({
  teamId: "team-123",
  agentId: "agent-abc",
  userId: "user-xyz",
});

const createResp = await client.create({
  name: "DataAnalysisSkill",
  content: `---
name: DataAnalysisSkill
description: Analyzes sales CSV files
---

# Data Analysis Workflow

1. Load CSV from /data/sales.csv
2. Compute monthly aggregates`,
  resources: [
    {
      path: "files/analyze.py",
      content: "import pandas as pd\n...",
      encoding: "utf-8",
      mime_type: "text/x-python",
    },
  ],
});
console.log(createResp.skill_id, "v" + createResp.version);

```

The `SkillCreateRequest` type enforces this structure in [`skill-types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/skill-types.ts).

### Appending Subsequent Versions

The **append operation** (`expected_version` → new head) follows this logic:

1. Fetch current head version
2. **Idempotency check**: If `content_hash` and resources are unchanged, return existing head
3. Otherwise, `storage.copyTree` duplicates the old version's directory
4. Apply resource changes (`writeResource` / `removeResource`)
5. Update manifest and insert new DB row via `store.appendVersion`
6. Promote to head; previous head becomes historical version

```typescript
const head = await client.get({ skill_id: "skill-xyz" });
const updated = head.content!.replace("monthly", "weekly");

await client.update({
  skill_id: head.skill_id,
  expected_version: head.version,  // Optimistic concurrency
  content: updated,
  // resources: [...] // optional changes
});

```

**Critical**: The `expected_version` parameter prevents lost-update races. Mismatches return a concurrency error.

### Version Retention and Expiration

TTL-based cleanup runs via `SkillVersioning.cleanupExpiredVersionsForSkill()`:

- Each version has `created_at_ms` and configurable `ttlSeconds`
- **Default retention**: `KEEP_RECENT = 3` non-head versions are preserved regardless of TTL
- Expired versions beyond this threshold trigger:
  1. DB row deletion
  2. Storage directory removal
  3. **–1 VDB delta** per deleted version

```typescript
const versions = await client.versions({
  skill_id: "skill-xyz",
  pagination: { limit: 10 },
});
// SkillVersionSummary includes is_expired flag
versions.items.forEach(v => {
  console.log(`v${v.version} head=${v.is_head} expired=${v.is_expired}`);
});

```

### Complete Skill Deletion

`SkillVersioning.deleteSkill()` performs atomic cleanup:

```typescript
await client.delete({
  skill_id: "skill-xyz",
  expected_version: 5,  // Must match current head
});

```

This removes **all versions**, cleans all storage directories, and reports a single **–N VDB delta**.


## Storage Architecture

Skill version data spans two layers:

| Layer | Technology | Responsibility |
|-------|-----------|--------------|
| **Object Storage** | COS adapter | `files/` directory per version at `storage_dir` path |
| **Skill Database** | SQLite or TCVDB | Version rows with `skill_id`, `version`, `content_hash`, `manifest`, `is_head`, `is_expired` |

The [`skill-store.interface.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/skill-store.interface.ts) abstracts the database layer, while [`skill-resource-store.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/skill-resource-store.ts) handles COS operations and manifest management.


## Key Versioning Properties

**Immutable versions** — Once created, a version cannot be modified. All updates generate new versions with incremented integers.

**Idempotent operations** — Duplicate content hashes bypass storage writes and DB inserts, returning existing heads for efficiency.

**Configurable retention** — The `KEEP_RECENT` constant and `ttlSeconds` parameter balance storage costs against audit requirements.

**Hook integration** — `onSkillCreated` and `onSkillVdbChanged` enable external asset registries and usage analytics without coupling.


## Summary

- **Skills** are versioned knowledge assets with SKILL.md documents, optional resources, and metadata
- **Version numbers** are monotonic integers; `is_head` marks the latest stable version
- **Immutable append-only model** guarantees reproducibility and audit trails
- **Idempotent create/append** prevents redundant storage when content is unchanged
- **TTL cleanup with recent-version protection** automates lifecycle management while preserving rollback options
- **Dual-layer storage** separates metadata (DB) from binary assets (COS) for scalability


## Frequently Asked Questions

### How does TencentDB Agent Memory handle concurrent skill updates?

The SDK uses **optimistic concurrency control** via the `expected_version` parameter. The `update` and `delete` methods reject requests where the provided version doesn't match the current head, forcing clients to retry with fresh state. This prevents lost updates without distributed locking overhead.

### Can I recover a deleted skill version?

No. The **TTL cleanup and delete operations are permanent**. The system intentionally trades recoverability for storage efficiency. To preserve historical versions indefinitely, configure `ttlSeconds` to a large value or ensure your retention policy (`KEEP_RECENT`) covers your audit window.

### What happens if I append a version with identical content?

The operation is **idempotent**. `SkillVersioning` compares the content hash and resource signatures against the current head. If unchanged, it returns the existing head version without writing to storage or the database—avoiding version proliferation from no-op updates.

### How do I migrate skills between teams or environments?

The SDK doesn't provide native export/import. You must **read the skill via `client.get()`**, then `create()` in the target environment with identical content and resources. Version history doesn't transfer; the migrated skill starts at v1 with a new `skill_id`.