Skill Asset Structure in TencentDB Agent Memory: Frontmatter and Body Format

A Skill asset in TencentDB Agent Memory is a Markdown document consisting of a YAML frontmatter header enclosed in triple dashes (---) followed by a structured Markdown body that defines the skill's purpose, workflow, and operational constraints.

The TencentDB Agent Memory framework uses structured Markdown files to define reusable capabilities called Skill assets. According to the TencentCloud/TencentDB-Agent-Memory repository, these files combine declarative metadata with procedural documentation to standardize how the runtime identifies and executes agent capabilities. Understanding the precise structure is essential for developers extending the framework with custom database operations or memory management functions.

Anatomy of a Skill Asset

Every Skill asset follows a two-part architecture that separates machine-readable metadata from human-readable documentation.

YAML Frontmatter Header

The frontmatter appears at the very top of the file, delimited by --- markers. This section declares the metadata that the runtime engine uses to identify and manage the skill. The framework parses these fields during initialization to register the skill within the agent's capability registry.

Structured Markdown Body

Following the closing --- of the frontmatter, the body contains detailed documentation organized into logical sections using standard Markdown headings. The reference implementation in MemoryCore/SKILL.md defines a canonical set of sections that ensure consistency across all skills in the ecosystem.

Required Frontmatter Fields

The runtime engine requires three mandatory fields in the frontmatter:

• name (string) – A unique identifier for the skill, typically using kebab-case notation (e.g., openclaw-memory-tencentdb-setup). This serves as the primary key for skill registration and invocation.
• description (string) – A concise, human-readable explanation of the skill's functionality that appears in debugging logs and documentation generators.
• version (string) – The semantic version of the skill (e.g., 1.0.0) that enables version pinning and dependency management within the agent system.

Optional keys may be added to extend functionality, but the core engine requires these three fields to properly load and execute the asset.

Standard Body Sections

According to MemoryCore/SKILL.md, the body of a Skill asset should include the following logical sections, typically using Chinese headings as implemented in the reference:

• ## 目的 – Declares the Purpose of the skill and what it accomplishes when invoked.

• ## 适用场景 – Defines Applicable Scenarios where the skill should be triggered based on user intent.

• ## 不适用场景 – Specifies Inapplicable Scenarios where the skill must not be used to prevent incorrect execution.

• ## 标准工作流 – Documents the Standard Workflow as numbered sub-steps (e.g., 环境预检, 安装插件, 写入最小配置) that the agent follows to complete the task.

• ## 故障排查速查 – Provides a Troubleshooting Quick Reference for common failure modes and diagnostic steps.

• ## 安全与合规约束 – Lists Security and Compliance Constraints that govern safe execution.

• ## 完成定义 – Establishes the Definition of Done (criteria that must be satisfied for successful completion).

• ## 交付话术模板 – Contains Delivery Script Templates for communicating successful completion to users.

The body can include any valid Markdown elements, including fenced code blocks (bash, json) and tables to illustrate example commands or configuration snippets.

Complete Skill Asset Template

Below is a minimal example of a valid Skill asset that follows the canonical structure defined in the framework. This template can serve as a foundation when creating new skills for the TencentDB Agent Memory ecosystem.

---
name: my-new-skill
description: 在 OpenClaw 中演示自定义技能的安装与验证
version: 0.1.0
---

## 目的

为 OpenClaw 平台提供 **演示** 用的自定义记忆插件，使得对话能够被持久化并在后续对话中召回。

## 适用场景

- 用户请求在 OpenClaw 中 **尝试** 新的记忆功能。  
- 开发者需要快速验证插件的安装、配置和检索流程。

## 标准工作流

### 1) 环境检查

```bash
openclaw --version
node -v

2) 安装插件

openclaw plugins install @tencentdb-agent-memory/my-new-skill

3) 配置插件

{
  "my-new-skill": {
    "enabled": true
  }
}

4) 重启网关并验证

openclaw gateway restart

故障排查速查

• 插件未加载 → 检查 openclaw.json 中 my-new-skill.enabled 是否为 true。
• 召回不到数据 → 确认 embedding 配置完整且 apiKey 已提供。

完成定义

• 插件成功安装并且 openclaw gateway restart 后日志出现 [my-new-skill] 前缀。
• 至少一次成功调用 tdai_memory_search 并返回结果。

## Reference Implementation Locations

The TencentDB Agent Memory repository contains two key files that define and demonstrate the Skill asset structure:

- **[`MemoryCore/SKILL.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/SKILL.md)** – The canonical reference document that establishes the standard format for all Skill assets, including detailed specifications for frontmatter fields and required body sections.
- **[`agents/skills/setup-proxy/SKILL.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/agents/skills/setup-proxy/SKILL.md)** – A concrete implementation example showing how the `setup-proxy` skill applies the standard structure to a specific use case, demonstrating proper formatting for workflows and troubleshooting sections.

## Summary

- A **Skill asset** is a Markdown file with YAML frontmatter and a structured body, stored with the `.md` extension.
- The **frontmatter** must declare `name`, `description`, and `version` fields between `---` delimiters.
- The **body** follows the section structure defined in [`MemoryCore/SKILL.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/SKILL.md), including purpose, applicable scenarios, standard workflow steps, and completion criteria.
- Code blocks within the body use standard Markdown fencing (`````bash`````, `````json`````) to illustrate commands and configurations.
- Concrete examples can be found in the `agents/skills/` directory of the TencentCloud/TencentDB-Agent-Memory repository.

## Frequently Asked Questions

### What file extension do Skill assets use?

Skill assets use the standard `.md` (Markdown) file extension. The runtime specifically parses these files as Markdown documents to extract both the YAML frontmatter and the rendered HTML content for documentation generation.

### Which frontmatter fields are mandatory for a Skill asset?

The runtime requires three mandatory fields: `name` (unique identifier string), `description` (human-readable explanation string), and `version` (semantic version string like `1.0.0`). While additional custom fields can be added to the YAML header, these three core fields must be present for the skill to register properly.

### Where is the canonical definition of the Skill asset format?

The canonical specification resides in [`MemoryCore/SKILL.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/SKILL.md) within the TencentCloud/TencentDB-Agent-Memory repository. This file serves as the authoritative reference for the frontmatter schema, required body sections, and formatting standards that all Skill assets must follow to ensure compatibility with the agent runtime.

### Can Skill assets include executable code examples in the body?

Yes, the Markdown body supports fenced code blocks using triple backticks with language specifiers such as `bash` or `json`. These blocks illustrate example commands, configuration snippets, or API calls that the agent may execute during the workflow steps documented in the `## 标准工作流` section.

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