# SkillClient v3 Endpoints: Complete Guide to 17 CRUD, File, and Extraction APIs

> Discover the 17 SkillClient v3 endpoints for CRUD operations, file management, and asynchronous extraction. This guide details every API under the /v3/skill prefix for efficient skill lifecycle management.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: api-reference
- Published: 2026-08-31

---

**The `SkillClient` class exposes exactly 17 HTTP endpoints under the `/v3/skill` prefix, covering Skill lifecycle management (create, read, update, delete), file operations (write, remove, read, export), listing for prompt injection, and asynchronous skill extraction.**

The TencentDB Agent Memory SDK provides a TypeScript `SkillClient` that wraps these 17 endpoints into a clean, promise-based interface. Whether you're automating Skill management, synchronizing resource files, or triggering background extraction tasks, understanding this endpoint taxonomy is essential for effective integration.

## CRUD Endpoints (1-9)

The nine core lifecycle endpoints manage Skill creation, modification, retrieval, and discovery.

### Create, Update, and Patch

Three distinct mutation strategies handle different modification patterns:

- **`POST /v3/skill/create`** – Initializes a new Skill at version 1 with `is_head=true`. Implemented in the server at [[`MemoryCore/src/gateway/skill-handlers.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/skill-handlers.ts)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryCore/src/gateway/skill-handlers.ts).

- **`POST /v3/skill/update`** – Full-document replacement that increments version. Requires `expected_version` for optimistic concurrency.

- **`POST /v3/skill/patch`** – Targeted string replacement within a Skill's content, also creating a new version.

### Deletion

- **`POST /v3/skill/delete`** – Soft-archives a Skill without version bump. The record remains retrievable via `get` with a specific version number.

### Retrieval and Discovery

Four query endpoints support different access patterns:

- **`POST /v3/skill/get`** – Fetches a Skill instance by ID, optionally targeting a specific historical version.

- **`POST /v3/skill/get-by-name`** – Alternative lookup using `name` + `team_id` + `agent_id` composite key.

- **`POST /v3/skill/list`** – Paginated enumeration of head rows for a team.

- **`POST /v3/skill/versions`** – Lists complete version history for a single Skill.

- **`POST /v3/skill/search`** – BM25, embedding, or hybrid search across active Skills.

## File Operations Endpoints (10-13)

Resource file management uses four dedicated endpoints, all versioned like content mutations:

- **`POST /v3/skill/files/write`** – Batch upload of resource files with automatic version increment.

- **`POST /v3/skill/files/remove`** – Batch deletion of resource files, also +1 version.

- **`POST /v3/skill/files/read`** – Single file retrieval with optional encoding specification.

- **`POST /v3/skill/export`** – Complete Skill export as ZIP archive containing `.md` manifest and resource files.

## Extraction and Conversation Endpoints (14-17)

The final four endpoints support runtime Skill discovery and asynchronous extraction:

- **`POST /v3/skill/listing`** – Generates `<available_skills>` XML block for prompt injection contexts.

- **`POST /v3/skill/extract`** – **Asynchronous** task creation for skill extraction from conversation history. Returns `task_id` for polling.

- **`POST /v3/skill/conversation/add`** – Incrementally persists conversation turns; may trigger auto-archive based on buffer policy.

- **`POST /v3/skill/conversation/force-archive`** – Manual flush of the current session buffer to persistent storage.

## TypeScript SDK Usage Examples

The [[`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)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/sdk/memory-core/typescript/src/v3/skill-client.ts) file implements all 17 endpoints as methods on the `SkillClient` class.

### Initialization

```typescript
import { SkillClient } from "@tencentdb-agent-memory/memory-sdk-ts";

const client = new SkillClient({
  endpoint: "https://memory.tencentyun.com",
  apiKey: "sk-...",
  serviceId: "mem-abc",
  teamId: "team-1",
  agentId: "agent-coder",
  userId: "u42",
});

```

### CRUD Operations

```typescript
// Create
await client.create({
  name: "python-best-practices",
  content: "---\nname: python-best-practices\nversion: 1\n---\n",
});

// Read head version
const skill = await client.get({ skill_id: "skill-123" });

// Update with concurrency check
await client.update({
  skill_id: "skill-123",
  expected_version: 1,
  content: "---\nname: python-best-practices\nversion: 2\n---\nUpdated guidance...",
});

```

### File Management

```typescript
// Write executable resource
await client.writeFiles({
  skill_id: "skill-123",
  expected_version: 2,
  files: [
    SkillClient.encodeUtf8("deploy.sh", "#!/bin/bash\nnpm run deploy", { 
      is_executable: true 
    })
  ],
});

// Read back with encoding
const file = await client.readFile({
  skill_id: "skill-123",
  path: "deploy.sh",
  encoding: "utf-8",
});

```

### Extraction Task

```typescript
// Trigger async extraction
const { task_id } = await client.extract({
  user_id: "u42",
  team_id: "team-1",
  agent_id: "agent-coder",
  messages: [
    { role: "user", content: "How do I optimize PostgreSQL connection pooling?" }
  ],
});

```

## Endpoint Reference Table

| # | Endpoint | HTTP | Purpose |

|---|----------|------|---------|
| 1 | `/v3/skill/create` | POST | Create new Skill (v1, `is_head=true`) |
| 2 | `/v3/skill/update` | POST | Full replacement (new version) |
| 3 | `/v3/skill/patch` | POST | Targeted string patch (new version) |
| 4 | `/v3/skill/delete` | POST | Soft archive (no version change) |
| 5 | `/v3/skill/get` | POST | Retrieve by ID |
| 6 | `/v3/skill/get-by-name` | POST | Retrieve by name + team + agent |
| 7 | `/v3/skill/list` | POST | Paginated team listing |
| 8 | `/v3/skill/search` | POST | BM25/embedding/hybrid search |
| 9 | `/v3/skill/versions` | POST | Historical version enumeration |
| 10 | `/v3/skill/files/write` | POST | Batch file upload (+1 version) |
| 11 | `/v3/skill/files/remove` | POST | Batch file deletion (+1 version) |
| 12 | `/v3/skill/files/read` | POST | Single file retrieval |
| 13 | `/v3/skill/export` | POST | ZIP export of Skill + resources |
| 14 | `/v3/skill/listing` | POST | `<available_skills>` block generation |
| 15 | `/v3/skill/extract` | POST | **Async** extraction task creation |
| 16 | `/v3/skill/conversation/add` | POST | Incremental conversation persistence |
| 17 | `/v3/skill/conversation/force-archive` | POST | Manual buffer flush |

## Key Implementation Files

| Path | Role |
|------|------|
| [[`MemoryCore/src/gateway/skill-handlers.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/skill-handlers.ts)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryCore/src/gateway/skill-handlers.ts) | Server-side HTTP handlers for all 17 endpoints |
| [[`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)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/sdk/memory-core/typescript/src/v3/skill-client.ts) | TypeScript SDK client implementation |
| [[`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)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/sdk/memory-core/typescript/src/v3/skill-types.ts) | Request/response type definitions |

## Summary

- **17 total endpoints** comprise the complete SkillClient v3 API surface under `/v3/skill`
- **9 CRUD endpoints** handle creation, mutation, retrieval, and search with optimistic versioning
- **4 file endpoints** support batch write/remove, single read, and full ZIP export
- **2 extraction endpoints** enable async skill extraction (`/extract`) and conversation persistence (`/conversation/*`)
- **1 listing endpoint** generates prompt-injection compatible skill catalogs
- All endpoints use **POST method** with JSON payloads, implemented consistently across server handlers and TypeScript SDK

## Frequently Asked Questions

### What distinguishes `update` from `patch` in SkillClient v3?

`update` performs a complete document replacement requiring the full Skill content, while `patch` accepts a targeted string operation for surgical modifications. Both create new versions; neither modifies existing versions in place due to the immutable versioning model.

### Why does the `extract` endpoint return a task ID instead of results?

The `/v3/skill/extract` endpoint triggers an **asynchronous** extraction pipeline that may involve LLM inference, embedding generation, and candidate ranking. Returning immediately with `task_id` prevents client blocking while the server-side task executes. Poll for completion or use webhooks if supported by your deployment.

### Are file operations versioned like content operations?

Yes. Both `files/write` and `files/remove` increment the Skill version by exactly 1, preserving historical resource states alongside content changes. This enables point-in-time recovery of complete Skill configurations including bundled files.

### What authentication scope is required for SkillClient endpoints?

All 17 endpoints require valid `apiKey` and `serviceId` at minimum. Endpoints targeting specific Skills additionally enforce `team_id`, `agent_id`, and `user_id` scoping as implemented in the gateway authorization layer at [[`MemoryCore/src/gateway/skill-handlers.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/skill-handlers.ts)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryCore/src/gateway/skill-handlers.ts).