# How to Create, Update, and Patch Skills Using the TencentDB Agent Memory API > Easily create, update, and patch Skills using the TencentDB Agent Memory API. Learn how to insert new Skills, perform full content replacements, and apply partial modifications efficiently. - Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory) - Tags: api-reference - Published: 2026-09-02 --- **Use `POST /v3/skill/create` to insert new Skills, `POST /v3/skill/update` for full content replacement with optimistic locking, and `POST /v3/skill/patch` for partial string-based modifications.** The TencentDB-Agent-Memory repository exposes a unified `/v3/skill/*` HTTP API that treats a **Skill** as a versioned, reusable asset. These endpoints enable programmatic lifecycle management—creating new Skills, replacing entire content versions, or applying targeted string patches—while maintaining consistency through optimistic concurrency control. The implementation resides in [`MemoryCore/src/gateway/skill-handlers.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/skill-handlers.ts) with the formal contract documented in [`MemoryCore/v3-api-memorycore-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/v3-api-memorycore-doc.md). ## Creating a Skill via POST /v3/skill/create The **create** endpoint initializes a new Skill with mandatory isolation fields and optional resource attachments. At minimum, the request body must include `name`, `content`, `team_id`, `agent_id`, and `user_id`. ### Request Schema The payload accepts the following structure: ```json { "team_id": "t_1", "agent_id": "agt_1", "user_id": "u_1", "name": "code-review", "content": "---\nname: code-review\n---\n# Code Review\n\nReview PRs automatically.", "resources": [ { "path": "helper.sh", "content": "...", "encoding": "utf-8", "mime_type": "application/x-sh" } ], "metadata": { "tags": ["review","ci"] } } ``` A successful invocation returns a `SkillSummary` containing the generated `skill_id` and initial version number. ### Example: Creating a Skill ```bash curl -X POST /v3/skill/create \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "team_id":"t_1","agent_id":"agt_1","user_id":"u_1", "name":"code-review", "content":"---\nname: code-review\n---\n# Code Review" }' ``` ```python import requests response = requests.post( "/v3/skill/create", headers={"Authorization": "Bearer ", "Content-Type": "application/json"}, json={ "team_id": "t_1", "agent_id": "agt_1", "user_id": "u_1", "name": "code-review", "content": "---\nname: code-review\n---\n# Code Review" } ) data = response.json()["data"] skill_id = data["skill_id"] ``` ## Updating a Skill via POST /v3/skill/update The **update** operation performs a full replacement of the Skill's content, resources, and metadata. This endpoint requires **optimistic locking** via the `expected_version` field to prevent concurrent overwrites. ### Request Schema Provide the `skill_id`, current `expected_version`, and complete new content: ```json { "skill_id": "skl_42", "expected_version": 3, "team_id": "t_1", "agent_id": "agt_1", "user_id": "u_1", "content": "---\nname: code-review\n---\n# Updated Review Guide\n\nNew steps…" } ``` If the supplied `expected_version` does not match the current server version, the API returns **error code 40901** (Skill version stale) and includes the `current_version` field, allowing the client to retry with fresh data. ### Example: Full Content Replacement ```javascript import fetch from 'node-fetch'; const updateSkill = await fetch('/v3/skill/update', { method: 'POST', headers: { 'Authorization': 'Bearer ', 'Content-Type': 'application/json', }, body: JSON.stringify({ skill_id: 'skl_42', expected_version: 3, team_id: 't_1', agent_id: 'agt_1', user_id: 'u_1', content: '---\nname: code-review\n---\n# Updated Review Guide', }), }); const result = await updateSkill.json(); if (result.code === 40901) { console.error(`Version conflict. Current version is ${result.current_version}`); } ``` ## Patching a Skill via POST /v3/skill/patch The **patch** endpoint applies a string-based partial modification without transmitting the entire content body. This is useful for surgical updates to large Skills. ### Request Schema The patch operation requires `old_string`, `new_string`, and optionally `replace_all` (boolean): ```json { "skill_id": "skl_42", "expected_version": 4, "team_id": "t_1", "agent_id": "agt_1", "user_id": "u_1", "old_string": "Review PRs automatically.", "new_string": "Automated PR review with linting.", "replace_all": true } ``` If `old_string` occurs multiple times and `replace_all` is omitted or false, the server returns **error code 42202** (patch not unique) to prevent ambiguous replacements. Like the update endpoint, patch requires `expected_version` for optimistic locking. ### Example: Partial String Replacement ```python patch_resp = requests.post( "/v3/skill/patch", headers={"Authorization": "Bearer ", "Content-Type": "application/json"}, json={ "skill_id": "skl_42", "expected_version": 4, "team_id": "t_1", "agent_id": "agt_1", "user_id": "u_1", "old_string": "Review PRs automatically.", "new_string": "Automated PR review with linting.", "replace_all": True } ) ``` ## Error Handling and Status Codes All three endpoints map internal `SkillCoreError` types to standardized HTTP error codes in [`MemoryCore/src/gateway/skill-handlers.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/skill-handlers.ts) (lines 30-46). Implement retry logic for stale versions and validation checks for duplicate names. | Code | Meaning | Resolution | |------|---------|------------| | **40001** | Invalid request (e.g., front-matter mismatch) | Verify request schema against documentation | | **40301** | Caller is not the Skill owner | Check `user_id` and permissions | | **40401** | Skill not found | Verify `skill_id` exists | | **40901** | Version stale (optimistic lock conflict) | Fetch current version and retry | | **42201** | Duplicate Skill name | Choose a unique `name` value | | **42202** | Patch not unique | Set `replace_all: true` or refine `old_string` | | **41301** | Resource or file too large | Reduce payload size | ## Implementation Reference The Skill API implementation spans several key files in the TencentDB-Agent-Memory repository: - **[`MemoryCore/v3-api-memorycore-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/v3-api-memorycore-doc.md)** – Official API specification defining request/response schemas for `/v3/skill/create`, `/v3/skill/update`, and `/v3/skill/patch` - **[`MemoryCore/src/gateway/skill-handlers.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/skill-handlers.ts)** – HTTP handler implementation that routes requests to the core service and maps domain errors (e.g., `SKILL_VERSION_STALE`) to HTTP status codes - **[`sdk/memory-core/typescript/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/README.md)** – TypeScript SDK reference documenting the `V3SkillClient` wrapper - **[`sdk/memory-core/python/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/python/README.md)** – Python SDK reference providing idiomatic client methods ## Summary - **Create** Skills using `POST /v3/skill/create` with mandatory isolation fields (`team_id`, `agent_id`, `user_id`) and optional resource attachments - **Update** entire Skill content via `POST /v3/skill/update`, supplying `expected_version` to prevent concurrent overwrite conflicts (error 40901) - **Patch** specific text segments using `POST /v3/skill/patch` with `old_string` and `new_string` parameters; use `replace_all` to handle multiple occurrences - Handle **error code 42202** when patch strings match non-uniquely, and **error code 40901** for optimistic locking failures - Reference [`MemoryCore/src/gateway/skill-handlers.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/skill-handlers.ts) for the complete error code mapping logic ## Frequently Asked Questions ### What is the difference between update and patch in the Skill API? The **update** endpoint (`POST /v3/skill/update`) performs a complete replacement of the Skill's content, resources, and metadata, requiring the full payload each time. The **patch** endpoint (`POST /v3/skill/patch`) applies a string-based substitution (find and replace) to the existing content, transmitting only the delta. Use patch for minor edits to large Skills to reduce bandwidth and avoid race conditions on unrelated content sections. ### How does optimistic locking work when updating Skills? Both update and patch operations enforce optimistic concurrency control through the `expected_version` parameter. You must supply the version number obtained from the last read operation. If another client modifies the Skill in the interim, the server detects the mismatch and returns **error code 40901** with the `current_version` field. You must fetch the latest version and retry the operation with the updated version number. ### What happens if my Skill patch matches multiple locations? If the `old_string` value exists multiple times within the Skill content and you do not set `replace_all: true`, the server returns **error code 42202** (patch not unique). To replace all occurrences, explicitly set `"replace_all": true` in the request payload. To target a specific single occurrence, refine your `old_string` to include additional unique surrounding context. ### Which authentication method does the Skill API require? All Skill endpoints require Bearer token authentication via the `Authorization` header. Include `-H "Authorization: Bearer "` in cURL requests or set the equivalent header in SDK clients. The token validates the caller's identity against the `user_id`, `team_id`, and `agent_id` fields provided in the request body, returning **error code 40301** if the caller is not the Skill owner.