diff --git a/docs/tools/creating-skills.md b/docs/tools/creating-skills.md
index 0b7e88baa4d..624c0e223f8 100644
--- a/docs/tools/creating-skills.md
+++ b/docs/tools/creating-skills.md
@@ -29,7 +29,7 @@ For how skills are loaded and prioritized, see [Skills](/tools/skills).
 
     ```markdown
     ---
-    name: hello_world
+    name: hello-world
     description: A simple skill that says hello.
     ---
 
@@ -39,6 +39,9 @@ For how skills are loaded and prioritized, see [Skills](/tools/skills).
     "Hello from your custom skill!".
     ```
 
+    Use hyphen-case with lowercase letters, digits, and hyphens for the skill
+    `name`. Keep the folder name and frontmatter `name` aligned.
+
   </Step>
 
   <Step title="Add tools (optional)">
@@ -83,13 +86,13 @@ For how skills are loaded and prioritized, see [Skills](/tools/skills).
 
 The YAML frontmatter supports these fields:
 
-| Field                               | Required | Description                                 |
-| ----------------------------------- | -------- | ------------------------------------------- |
-| `name`                              | Yes      | Unique identifier (snake_case)              |
-| `description`                       | Yes      | One-line description shown to the agent     |
-| `metadata.openclaw.os`              | No       | OS filter (`["darwin"]`, `["linux"]`, etc.) |
-| `metadata.openclaw.requires.bins`   | No       | Required binaries on PATH                   |
-| `metadata.openclaw.requires.config` | No       | Required config keys                        |
+| Field                               | Required | Description                                                    |
+| ----------------------------------- | -------- | -------------------------------------------------------------- |
+| `name`                              | Yes      | Unique identifier using lowercase letters, digits, and hyphens |
+| `description`                       | Yes      | One-line description shown to the agent                        |
+| `metadata.openclaw.os`              | No       | OS filter (`["darwin"]`, `["linux"]`, etc.)                    |
+| `metadata.openclaw.requires.bins`   | No       | Required binaries on PATH                                      |
+| `metadata.openclaw.requires.config` | No       | Required config keys                                           |
 
 ## Best practices