Skill documentation incorrectly states name validation is enforced

[yacinehmito]

Description

The Agent Skills documentation states that skill names must follow strict validation rules:

name must:

• 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

Equivalent regex: ^[a-z0-9]+(-[a-z0-9]+)*$

However, looking at the actual code in packages/opencode/src/skill/skill.ts, there is no such validation:

export const Info = z.object({
  name: z.string(),  // No regex validation
  description: z.string(),
  location: z.string(),
})

How this happened

The documentation (PR #5931) and code (PR #5930) were created together, but merged in different order:

1. PR docs: Agent Skills #5931 (docs) merged first at 2025-12-22T05:49:28Z — documenting the validation that existed in the code PR
2. Maintainer simplified PR feat: add native skill tool with permission system #5930 in commit 9a5dd18 at 2025-12-22T23:20:19Z — removing NAME_REGEX validation
3. PR feat: add native skill tool with permission system #5930 (code) merged at 2025-12-22T23:24:07Z — without the validation

The documentation was accurate when written, but became incorrect when the code was simplified before merging.

Impact

Users may:

1. Avoid using underscores or other valid characters unnecessarily
2. Be confused when skills with "invalid" names work fine

Proposed Fix

Update the documentation to reflect the actual behavior:

• Remove the strict regex requirement
• Keep naming conventions as recommendations for consistency

[github-actions]

This issue might be a duplicate of or related to existing issues. Please check:

• Backward compatibility broken - enforcement of the /skill directory naming #6432: Backward compatibility broken - enforcement of the /skill directory naming (discusses validation rules and backward compatibility decisions)

Feel free to ignore if your specific case differs, but issue #6432 may provide additional context about why the validation was originally removed.

[rekram1-node]

Believe code should be updated to match the expectation of the actual spec, believe this is a bug

[rekram1-node]

if you'd prefer to update ur pr to do this^ feel free

[yacinehmito]

Believe code should be updated to match the expectation of the actual spec, believe this is a bug

What's the rationale behind it? @thdxr purposefully removed the validation; and honestly I don't understand why it should be this way, other than being always compatible with Claude Code.

In our codebase, the file naming convention mandates the use of snake_case. This would be the first software I use that forces a particular casing for generic files.