Skill Sharing Reference

Use this when deciding whether a repo can share Agent Skills directly or needs OpenCode plugin code.

Generation Policy

OpenCode can discover several skill locations, but new shared generated skills should default to:

.agents/skills/<skill-name>/SKILL.md

Use .opencode/skills/<skill-name>/SKILL.md only for OpenCode-specific behavior. Do not generate .claude/skills/ as part of an OpenCode support task.

Discovery Paths OpenCode Supports

OpenCode can load project or global skills from:

Discovery compatibility means OpenCode can read existing .claude/skills. It does not mean this skill should generate new .claude/skills.

Because OpenCode can read existing .claude/skills, copying or symlinking skills is not always necessary. Prefer validation and discovery testing before creating duplicate skill trees.

Frontmatter Checks

Each SKILL.md needs YAML frontmatter with:

• name required.
• description required.
• license optional.
• compatibility optional.
• metadata optional.

OpenCode skill names should:

• Be lowercase alphanumeric with single hyphen separators.
• Match ^[a-z0-9]+(-[a-z0-9]+)*$.
• Match the containing directory name.
• Have descriptions between 1 and 1024 characters.

When Plugin Code Is Unnecessary

If a Claude plugin is only reusable instructions, scripts, references, and assets under Agent Skills, OpenCode may not need plugin code. Validate the skills, then document discovery and packaging.

Use opencode debug skill as the primary local discovery check when OpenCode is available.

Copying Skills Into Packages

Default source of truth for newly generated shared skills: .agents/skills/.

Use opencode-plugin/skills/ only for package-local distribution content. If copying from .agents/skills/, say how the copy is kept in sync. Avoid maintaining divergent Claude/OpenCode skill copies.

For this version, keep synchronization manual and reviewable. Document the declared source of truth and add a test or checksum/content-equality check for package-local copies, but do not create CI, GitHub Actions, release, publish, or sync workflow files.

Migration From Existing .claude/skills

When existing Claude skills live under .claude/skills/:

1. Treat them as valid input.
2. Validate frontmatter and helper references.
3. Ask before moving or copying them to .agents/skills/.
4. If copying, document that .agents/skills/ is the new shared source or that a sync process is required; do not automate that sync with workflow files in this version.