opencode-skills

To use opencode-sessions for multi-agent collaboration and workflow orchestration, add it to your opencode.json configuration file:

{
  "plugin": ["opencode-sessions"]
}

As skills support has become native to OpenCode, you should migrate from the opencode-skills plugin to the native implementation. Follow these three steps:

1. Remove the Plugin: Uninstall or remove the opencode-skills plugin from your configuration.
2. Move Your Skills Directory: The native implementation uses skill/ (singular) at the project root, whereas the plugin used .opencode/skills/. Move your skill files to the new location.
   • Note for Global Skills: If you are using global skills, ensure they are moved to the appropriate native global directory.
3. Update Your Config (Optional): Review your configuration for any remaining plugin-specific keys that may no longer be required by the native implementation.

To use the opencode-sessions tool, add it to the plugin array within your opencode.json configuration file.

{
  "plugin": ["opencode-sessions"]
}

The plugin searches for SKILL.md files in several locations. If duplicate tool names are found, the location with the highest priority wins.

Discovery Order (Lowest to Highest Priority):

1. XDG Config: $XDG_CONFIG_HOME/opencode/skills or ~/.config/opencode/skills
2. Global Home: ~/.opencode/skills
3. Custom Config: $OPENCODE_CONFIG_DIR/skills (if OPENCODE_CONFIG_DIR is set)
4. Project Local: [project_root]/.opencode/skills

The plugin automatically generates tool names for the agent based on the directory structure relative to the skill's base directory. The pattern is skills_{{path_components_joined_by_underscore}}, where hyphens in directory names are replaced with underscores.

Examples:

• .opencode/skills/brand-guidelines/SKILL.md $\rightarrow$ skills_brand_guidelines
• .opencode/skills/document-skills/docx/SKILL.md $\rightarrow$ skills_document_skills_docx

In OpenCode v1.0.190+, permissions for the skill tool are managed via the permission.skill object in opencode.json. This allows you to use pattern-based matching to control access. Use allow to grant access and deny to restrict it.

Example configuration to allow a specific skill while denying all others:

{
  "permission": {
    "skill": {
      "my-skill": "allow",
      "*": "deny"
    }
  }
}

The opencode-skills plugin implements Anthropic's Agent Skills Specification. To create a skill, you must create a SKILL.md file within a directory. The directory name must match the name field in the YAML frontmatter.

Frontmatter Requirements

• name: Must be lowercase alphanumeric with hyphens (e.g., my-skill).
• description: Must be at least 20 characters long.
• license: (Optional) String.
• allowed-tools: (Optional) Array of strings.
• metadata: (Optional) Key-value pairs.

Example SKILL.md

---
name: brand-guidelines
description: Provides the official brand colors and typography rules.
license: MIT
---

# Brand Guidelines
Use #FF5733 for primary buttons.

Common issues when using the opencode-skills plugin:

• Skills not discovered:
  • Verify SKILL.md exists in discovery paths (.opencode/skills/, ~/.opencode/skills/, or ~/.config/opencode/skills/).
  • Check that frontmatter is valid YAML.
• Tool not appearing:
  • Ensure the name in SKILL.md matches the directory name exactly.
  • Restart OpenCode after adding/modifying skills.
• Paths not resolving:
  • Ensure paths in SKILL.md are relative to the skill directory.
  • Check the base directory provided in the skill output.
• Invalid skill errors:
  • Name must be lowercase with hyphens only ([a-z0-9-]+).
  • Description must be at least 20 characters.
• Plugin not updating:
  • Check version: cat ~/.cache/opencode/node_modules/opencode-skills/package.json | grep version
  • Force update: rm -rf ~/.cache/opencode and then restart OpenCode.

When using the opencode-skills plugin, tool names are automatically generated based on your directory structure. To ensure compatibility, follow these rules:

• Directory Name: Must be lowercase with hyphens (e.g., my-skill).
• Frontmatter name: Must match the directory name exactly.
• Generated Tool Name: The plugin converts the directory name to an underscore-separated format prefixed with skills_ (e.g., skills_my_skill).