api-reference

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

August 31, 2026 TencentCloud/TencentDB-Agent-Memory ↗

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/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/feat/server_team/sdk/memory-core/typescript/src/v3/skill-client.ts) file implements all 17 endpoints as methods on the SkillClient class.

Initialization

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

// 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

// 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

// 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

|---|----------|------|---------| | 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/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/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/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/feat/server_team/MemoryCore/src/gateway/skill-handlers.ts).

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:

curl -s "https://instagit.com/install.md"

Add to your MCP client configuration:

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}

Ask your agent:

"Use Instagit MCP to understand how TencentCloud/TencentDB-Agent-Memory works."

Works with

Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →