# How Skills in TencentDB Agent Memory Work and Are Versioned

> Discover how Skills in TencentDB Agent Memory function as versioned knowledge assets. Learn about their structure, management, and team-wide accessibility. Explore reusable agent expertise.

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

---

**TLDR: TencentDB Agent Memory treats Skills as first-class, versioned knowledge assets that encapsulate reusable agent expertise — each skill contains metadata, immutable version history, resource files, trigger boundaries, and execution steps, managed through 15 HTTP endpoints and accessible across teams via ACL-based sharing.**

Tencent Cloud's open-source [TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory) repository delivers a production-grade memory system for intelligent agents. Within that system, **Skills are the primary mechanism for capturing, versioning, and reusing expertise** extracted from an agent's workflow. This article walks through the Skill architecture, versioning model, sharing rules, and practical SDK usage as implemented in the repository's source code.

## Understanding the Skill Architecture

A Skill is much more than a static prompt. It is a structured, version-controlled knowledge asset with its own lifecycle. The architecture spans five layers, each with a clear responsibility.

| Layer | Responsibility | Key Components |
|-------|---------------|----------------|
| **API Definition** | Defines every Skill-related request and response payload. | [`sdk/memory-core/typescript/src/v3/skill-types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/skill-types.ts) — includes `SkillSummary`, `SkillDetail`, `SkillVersionSummary`, pagination, search, and conversation-extraction types |
| **Client Wrapper** | Thin TypeScript client around the 15 `/v3/skill/*` HTTP endpoints. | [`skill-client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/skill-client.ts) — handles CRUD, search, versioning, resource-file I/O, and conversation-add operations |
| **MemoryCore Gateway** | Central service that stores Skill data, runs RAG-based search, and orchestrates conversation-driven extraction. | `/MemoryCore/src/core/` (Skill service implementation) |
| **Proxy Layer** | Lets agents call Skills without knowing backend details; injects Skills into prompts and forwards skill-tool calls. | `MemoryProxy` — forwards `/v3/skill/*` calls and expands `<cloud_skills>` and `<skill_tools>` blocks inside system prompts |
| **Asset-Level ACL** | Treats each Skill as a Memory Asset with ownership (User / Team / Agent) and visibility rules. | Asset metadata model documented in [`MemoryCore/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/README.md) |

### Core Types in [`skill-types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/skill-types.ts)

The type definitions in [`skill-types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/skill-types.ts) give the clearest view of what a Skill contains:

- `SkillSummary` — lightweight metadata for search results and list views.
- `SkillDetail` — full representation including resources, trigger definitions, and execution steps.
- `SkillVersionSummary` — immutable snapshot metadata for rollback scenarios.
- `SkillSearchMode` — enum selecting BM25, embedding, or hybrid retrieval.
- `SkillSearchHit` — a concise result object returned from search queries.

These types ensure that creating, updating, searching, and invoking a Skill all share one consistent shape, which keeps the API predictable across the 15 underlying endpoints.

## The Skill Lifecycle

According to the repository's implementation, a Skill moves through five distinct stages, from creation to invocation.

1. **Creation** — An agent or human sends a `SkillCreateRequest` via [`skill-client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/skill-client.ts), optionally attaching resource files.
2. **Versioning** — Every edit produces a new `SkillVersionSummary`. Older versions are treated as immutable snapshots, making rollback straightforward.
3. **Extraction** — After a human turn, the MemoryProxy posts the conversation slice to `/v3/skill/conversation/add`, and the system automatically archives a new Skill version if the conversation matches the Skill's defined trigger boundaries.
4. **Search & Retrieval** — Skills are searchable by BM25, embedding, or hybrid modes. Search returns `SkillSearchHit` objects containing concise summaries ready to inject into a prompt.
5. **Invocation** — Agents receive `<cloud_skills>` (summaries) and `<skill_tools>` (curl-style invocation snippets) inside their system prompt, allowing direct call of the Skill as an HTTP tool. The runtime setting `skillRuntime.allowLlmWrite` controls whether the model may modify a Skill during invocation.

## How Skill Versioning Works

Versioning is built directly into the asset model. Each time a Skill is edited, the system compares the change and creates a new `SkillVersionSummary`. Old versions are never mutated, which enables consistent rollback and historical auditing.

The key implementation detail is that **versioning is tightly coupled to extraction**. During conversation-driven extraction, the proxy sends a conversation slice to `/v3/skill/conversation/add`. If the slice's content aligns with the Skill's declared trigger boundaries, the MemoryCore service automatically commits a new version. This means Skills evolve organically from real agent usage, not just manual edits.

## Sharing Skills Across Users and Teams

Sharing relies on the upstream **Memory Asset ACL model** described in [`MemoryCore/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/README.md).

### Ownership and Visibility

By default, a Skill is **private to its creator**. Once an admin reviews it, the owner can set `visibility` to either `team` or `public`.

The ACL evaluation order is strict: **Team → User → Agent → Visibility**, combining fixed bindings with per-asset ACL rules. Only assets the requester is explicitly entitled to see are returned from any Skill search or listing operation.

### Cross-Agent Reuse

Once a Skill is visible at the team level, any agent that belongs to that team can import it via `SkillConversationAddRequest`. This enables cross-agent reuse of proven workflows without duplicating resources — a single versioned Skill can serve an entire team's toolchain.

## Practical SDK Usage Examples

All examples below use the TypeScript SDK found in [`sdk/memory-core/typescript/src/v3/skill-client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/skill-client.ts).

### 1. Creating a Skill with a Resource File

```ts
import { SkillClient } from '@tencentdb/memory-core';

// Initialise client (serviceToken is injected by MemoryProxy)
const client = new SkillClient({ baseURL: 'http://localhost:8420', serviceToken: 'YOUR_TOKEN' });

await client.create({
  user_id: 'u123',
  team_id: 't456',
  agent_id: 'a789',
  name: 'Release Checklist',
  description: 'Standard steps for releasing a product',
  resources: [
    { path: 'checklist.md', encoding: 'utf-8', content: '# Release Checklist\n...' }

  ],
});

```

This creates a new Skill with a markdown resource attached.

### 2. Searching for Relevant Skills

```ts
const result = await client.search({
  user_id: 'u123',
  team_id: 't456',
  query: 'how to release a new version',
  mode: 'hybrid',          // combines BM25 & embedding
});
console.log(result.items.map(s => s.name));

```

The `hybrid` mode merges BM25 keyword scoring with embedding similarity for the best retrieval accuracy.

### 3. Invoking a Skill from an LLM Prompt via MemoryProxy

When the proxy injects Skill definitions into the system prompt, it expands the `<skill_tools>` placeholder into a callable snippet. In a conversation, the assistant might emit:

```json
{
  "role": "assistant",
  "content": "Here is the release checklist:\n<skill_tools name=\"Release Checklist\"/>"
}

```

The proxy expands this to an actual HTTP invocation the LLM can execute:

```bash
curl -X POST http://localhost:8420/v3/skill/run \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"skill_id":"skill-xyz","input":{}}'

```

### 4. Sharing a Skill (Making It Team-Visible)

```ts
await client.update({
  user_id: 'admin',
  team_id: 't456',
  skill_id: 'skill_xyz',
  visibility: 'team',          // now any member of team t456 can use it
});

```

After this call, every agent in team `t456` can import and invoke that Skill.

## Key Files to Know

| File | Purpose |
|------|---------|
| [`sdk/memory-core/typescript/src/v3/skill-types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/skill-types.ts) | Type definitions for all Skill APIs (summary, detail, pagination, search, conversation extraction). |
| [`sdk/memory-core/typescript/src/v3/skill-client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/skill-client.ts) | SDK client for all 15 Skill HTTP endpoints. |
| [`MemoryCore/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/README.md) | Asset metadata model, including Skill support and full ACL semantics. |
| [`MemoryProxy/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/README.md) | How the proxy injects `<cloud_skills>` and `<skill_tools>` into prompts and forwards skill-tool calls. |
| [`MemoryCore/src/core/skill.service.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/skill.service.ts) | Core implementation for Skill storage, versioning, and RAG search. |
| [`MemoryPanel/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/README.md) | UI for browsing, reviewing, and sharing Skills across teams. |

## Summary

- **Skills are first-class, versioned knowledge assets** in TencentDB Agent Memory, not static prompts — they pack metadata, resources, triggers, execution steps, and validation rules.
- **Versioning is automatic and immutable** every edit or conversation-driven extraction produces a new `SkillVersionSummary`, enabling rollback without data loss.
- **Sharing is ACL-governed** through an ownership model that filters by Team → User → Agent → Visibility, keeping Skills private by default.
- **Skills integrate directly into agent flows** the MemoryProxy injects `<cloud_skills>` summaries and `<skill_tools>` curl snippets, so agents can invoke a shared Skill as if it were a local tool.
- **The TypeScript SDK** (`SkillClient`) exposes the entire lifecycle in a single, predictable client, and the core abstraction lives in [`skill-types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/skill-types.ts) and [`skill-client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/skill-client.ts).

## Frequently Asked Questions

### How does TencentDB Agent Memory version a Skill?

Each edit to a Skill creates a new `SkillVersionSummary`. Old versions stay immutable, so you can roll back anytime. When an agent runs a conversation-driven extraction that matches a Skill's workflow, the system automatically commits a new version from the conversation. slice.

### Can Skills be shared between different agents in the same team?

Yes. A Skill is private by default, but an admin can set `visibility` to `team`. Once that is done, any agent in that team can import the Skill via `SkillConversationAddRequest` and invoke it through the `memory`-injected `<skill_tools>` snippets.

### Where is the core implementation of Skills located in the repository?

The main Skill service lives in [`MemoryCore/src/core/skill.service.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/skill.service.ts), which handles storage, versioning, and RAG search. The client-facing code is in [`sdk/memory-core/typescript/src/v3/skill-types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/skill-types.ts) (types) and [`skill-client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/skill-client.ts) (HTTP wrapper), while prompt injection and routing are handled by the `MemoryProxy` layer.

### What search modes does Skill retrieval support?

The `SkillSearchMode` enum supports **BM25**, **embedding**, and **hybrid** modes. The hybrid mode combines both, making it the recommended choice when you need reliable keyword matching and semantic understanding at the same time.