How to Create, Update, and Patch Skills Using the TencentDB Agent Memory API

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 with the formal contract documented in 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:

{
  "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

curl -X POST <BASE_URL>/v3/skill/create \
  -H "Authorization: Bearer <TOKEN>" \
  -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"

      }'

import requests

response = requests.post(
    "<BASE_URL>/v3/skill/create",
    headers={"Authorization": "Bearer <TOKEN>", "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:

{
  "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

import fetch from 'node-fetch';

const updateSkill = await fetch('<BASE_URL>/v3/skill/update', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <TOKEN>',
    '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):

{
  "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

patch_resp = requests.post(
    "<BASE_URL>/v3/skill/patch",
    headers={"Authorization": "Bearer <TOKEN>", "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 (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 – Official API specification defining request/response schemas for /v3/skill/create, /v3/skill/update, and /v3/skill/patch
• 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 – TypeScript SDK reference documenting the V3SkillClient wrapper
• 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 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 <TOKEN>" 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.

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