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:
PR docs: Agent Skills #5931 at 2025-12-22T05:49:28Z — documenting the validation that existed in the code PRMaintainer simplified PR feat: add native skill tool with permission system #5930 in commit 9a5dd18 at 2025-12-22T23:20:19Z — removing NAME_REGEX validationPR feat: add native skill tool with permission system #5930 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:
Avoid using underscores or other valid characters unnecessarily
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
Description
The Agent Skills documentation states that skill names must follow strict validation rules:
However, looking at the actual code in
packages/opencode/src/skill/skill.ts, there is no such validation:How this happened
The documentation (PR #5931) and code (PR #5930) were created together, but merged in different order:
2025-12-22T05:49:28Z— documenting the validation that existed in the code PR9a5dd18at2025-12-22T23:20:19Z— removingNAME_REGEXvalidation2025-12-22T23:24:07Z— without the validationThe documentation was accurate when written, but became incorrect when the code was simplified before merging.
Impact
Users may:
Proposed Fix
Update the documentation to reflect the actual behavior: