From 39e6346e896cabd74ad34da1c84464a1d0539a84 Mon Sep 17 00:00:00 2001
From: Yacine Hmito <6893840+yacinehmito@users.noreply.github.com>
Date: Sun, 18 Jan 2026 22:49:19 +0100
Subject: [PATCH] docs: clarify skill naming is convention, not enforced

The documentation incorrectly stated that skill names must follow strict
validation rules (lowercase alphanumeric with hyphens, regex pattern, etc).

Looking at the actual code in skill.ts, there is no such validation - the
name field accepts any string. This validation was proposed in PR #5930
but removed before merging because it broke backward compatibility
(see issue #6432).

Updated the docs to present these as recommended conventions rather than
enforced requirements.

Fixes #9294
---
 packages/web/src/content/docs/skills.mdx | 23 ++++++++---------------
 1 file changed, 8 insertions(+), 15 deletions(-)

diff --git a/packages/web/src/content/docs/skills.mdx b/packages/web/src/content/docs/skills.mdx
index 553931eec49..6ed10ba8f55 100644
--- a/packages/web/src/content/docs/skills.mdx
+++ b/packages/web/src/content/docs/skills.mdx
@@ -44,28 +44,21 @@ Unknown frontmatter fields are ignored.
 
 ---
 
-## Validate names
+## Naming conventions
 
-`name` must:
+For consistency and compatibility with Claude Code's `.claude/skills/` format, we recommend:
 
-- Be 1–64 characters
-- Be lowercase alphanumeric with single hyphen separators
-- Not start or end with `-`
-- Not contain consecutive `--`
-- Match the directory name that contains `SKILL.md`
+- Lowercase alphanumeric names with hyphens (e.g., `git-release`, `code-review`)
+- Matching the directory name to the skill name
+- Keeping names concise and descriptive
 
-Equivalent regex:
-
-```text
-^[a-z0-9]+(-[a-z0-9]+)*$
-```
+These are conventions, not enforced requirements. The `name` field accepts any non-empty string.
 
 ---
 
-## Follow length rules
+## Description length
 
-`description` must be 1-1024 characters.
-Keep it specific enough for the agent to choose correctly.
+Keep descriptions specific enough for the agent to choose correctly—aim for 1-2 sentences that clearly explain when to use the skill.
 
 ---