diff --git a/docs/tools/creating-skills.md b/docs/tools/creating-skills.md
index 964165ad0a2..f3882dcf25e 100644
--- a/docs/tools/creating-skills.md
+++ b/docs/tools/creating-skills.md
@@ -1,9 +1,5 @@
 ---
 title: "Creating Skills"
-summary: "Build and test custom workspace skills with SKILL.md"
-read_when:
-  - You are creating a new custom skill in your workspace
-  - You need a quick starter workflow for SKILL.md-based skills
 ---
 
 # Creating Custom Skills 🛠
@@ -39,11 +35,27 @@ description: A simple skill that says hello.
 When the user asks for a greeting, use the `echo` tool to say "Hello from your custom skill!".
 ```
 
-### 3. Add Tools (Optional)
+### 3. Declare Capabilities
+
+If your skill uses system tools, declare them in the `metadata.openclaw.capabilities` field:
+
+```markdown
+---
+name: deploy_helper
+description: Automate deployment workflows.
+metadata: { "openclaw": { "capabilities": ["shell", "filesystem"] } }
+---
+```
+
+Available capabilities: `shell`, `filesystem`, `network`, `browser`, `sessions`.
+
+Skills without capabilities are treated as read-only (model-only instructions). Community skills published to ClawHub **must** declare capabilities matching their tool usage — undeclared capabilities are blocked at runtime.
+
+### 4. Add Tools (Optional)
 
 You can define custom tools in the frontmatter or instruct the agent to use existing system tools (like `bash` or `browser`).
 
-### 4. Refresh OpenClaw
+### 5. Refresh OpenClaw
 
 Ask your agent to "refresh skills" or restart the gateway. OpenClaw will discover the new directory and index the `SKILL.md`.