anomalyco/opencode
1
0
Fork 0
mirror of https://github.com/anomalyco/opencode.git synced 2026-07-22 02:05:26 -04:00
Code Issues 5.9k Packages Projects Releases 19 Wiki Activity

Skill documentation incorrectly states name validation is enforced #6726

New Issue
Open
opened 2026-02-16 18:05:04 -05:00 by yindo · 4 comments
yindo commented 2026-02-16 18:05:04 -05:00
Owner
Copy Link
Copy Source

Originally created by @yacinehmito on GitHub (Jan 18, 2026).

Originally assigned to: @rekram1-node on GitHub.

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 #5931 (docs) merged first at 2025-12-22T05:49:28Z — documenting the validation that existed in the code PR
  2. Maintainer simplified PR #5930 in commit 9a5dd18 at 2025-12-22T23:20:19Z — removing NAME_REGEX validation
  3. PR #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
Originally created by @yacinehmito on GitHub (Jan 18, 2026). Originally assigned to: @rekram1-node on GitHub. ## Description The [Agent Skills documentation](https://opencode.ai/docs/skills/) 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: ```typescript 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 #5931 (docs) merged first** at `2025-12-22T05:49:28Z` — documenting the validation that existed in the code PR 2. **Maintainer simplified PR #5930** in commit `9a5dd18` at `2025-12-22T23:20:19Z` — removing `NAME_REGEX` validation 3. **PR #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
yindo added the bug label 2026-02-16 18:05:04 -05:00
yindo commented 2026-02-16 18:05:04 -05:00
Author
Owner
Copy Link
Copy Source

@github-actions[bot] commented on GitHub (Jan 18, 2026):

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

  • #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.

@github-actions[bot] commented on GitHub (Jan 18, 2026): This issue might be a duplicate of or related to existing issues. Please check: - #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.
yindo commented 2026-02-16 18:05:04 -05:00
Author
Owner
Copy Link
Copy Source

@rekram1-node commented on GitHub (Jan 18, 2026):

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

@rekram1-node commented on GitHub (Jan 18, 2026): Believe code should be updated to match the expectation of the actual spec, believe this is a bug
yindo commented 2026-02-16 18:05:04 -05:00
Author
Owner
Copy Link
Copy Source

@rekram1-node commented on GitHub (Jan 18, 2026):

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

@rekram1-node commented on GitHub (Jan 18, 2026): if you'd prefer to update ur pr to do this^ feel free
yindo commented 2026-02-16 18:05:04 -05:00
Author
Owner
Copy Link
Copy Source

@yacinehmito commented on GitHub (Jan 19, 2026):

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.

@yacinehmito commented on GitHub (Jan 19, 2026): > 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.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
acp
bad
bug
discussion
docs
documentation
enhancement
extension
good first issue
growth
help-wanted
mcp
model-problem
needs:compliance
nix
opentui
perf
pull-request
Mirrored from GitHub Pull Request
 tui
web
windows
zen
No Label bug
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: anomalyco/opencode#6726
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?