Skip to content

Conversation

@yacinehmito
Copy link

@yacinehmito yacinehmito commented Jan 18, 2026

What does this PR do?

Fixes the Agent Skills documentation which incorrectly states that skill names must follow strict validation rules (regex ^[a-z0-9]+(-[a-z0-9]+)*$, directory name matching, etc).

The actual code in packages/opencode/src/skill/skill.ts shows 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
  2. Maintainer simplified PR feat: add native skill tool with permission system #5930 in commit 9a5dd18, 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 docs were accurate when written, but became incorrect when the code was simplified before merging.

Changes:

  • Renamed "Validate names" → "Naming conventions"
  • Changed strict requirements to recommended conventions
  • Clarified that the name field accepts any non-empty string
  • Simplified the description length section

Fixes #9294

How did you verify your code works?

  1. Traced git history to confirm timeline:
    • git log --all --oneline -- "packages/web/src/content/docs/skills.mdx" shows PR docs: Agent Skills #5931 added the docs
    • git show 9a5dd18 shows maintainer removed NAME_REGEX from skill.ts
  2. Reviewed current packages/opencode/src/skill/skill.ts confirming name: z.string() with no validation
  3. Verified PR merge timestamps via gh pr view --json mergedAt

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 anomalyco#5930
but removed before merging because it broke backward compatibility
(see issue anomalyco#6432).

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

Fixes anomalyco#9294
@github-actions
Copy link
Contributor

The following comment was made by an LLM, it may be inaccurate:

No duplicate PRs found

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Skill documentation incorrectly states name validation is enforced

1 participant