diff --git a/claw-skills/SKILL.md b/claw-skills/SKILL.md
index f82c6f8..e95772e 100644
--- a/claw-skills/SKILL.md
+++ b/claw-skills/SKILL.md
@@ -1,3 +1,8 @@
+---
+name: claw-skills
+description: ClawSkills management and collaboration suite — scripts and workflows for using and improving skills.
+---
+
 # claw-skills
 
 ClawSkills management and collaboration suite — scripts and workflows for using and improving skills.
diff --git a/claw-skills/docs/guide.md b/claw-skills/docs/guide.md
index 3d5f32b..3f7ee96 100644
--- a/claw-skills/docs/guide.md
+++ b/claw-skills/docs/guide.md
@@ -13,7 +13,16 @@ A skill is a directory with the following layout:
 
 ## Writing Requirements
 
-**SKILL.md should be concise.** It serves as a table of contents for workflows — list each workflow file path with the scenario that triggers it.
+**SKILL.md must start with a YAML frontmatter block:**
+
+```yaml
+---
+name: {skill-name}
+description: {when-to-use}
+---
+```
+
+**SKILL.md body should be concise.** It serves as a table of contents for workflows — list each workflow file path with the scenario that triggers it. For supplementary documentation, use `docs/`.
 
 > **All skill-related documentation must be written in English.**