build-skill

OpenCode skills fail to load when the YAML frontmatter is missing required name and description fields, or when the directory name does not match the frontmatter name field exactly. Enforcing valid naming patterns and required fields resolves these loading failures.

To create an OpenCode skill without errors, use executable scaffolding scripts to generate a compliant directory structure and apply valid YAML frontmatter rules. This ensures the SKILL.md file follows naming conventions and passes structural validation on the first try.

Progressive disclosure in skill authoring splits large skills into manageable reference files to minimize token usage. This design pattern prevents context bloat and degraded agent performance in long conversations by loading only necessary information.

Yes, you can validate and package custom OpenCode skills automatically using built-in executable scripts. These scripts enforce skill structure rules and generate distributable skill zip files for sharing across agents.

The best way to debug a broken SKILL.md file is to run executable validation scripts that check for exact YAML frontmatter rules, valid name patterns, and directory name matching. This identifies incorrect frontmatter or structural issues causing the agent to ignore the skill.

Yes, you must match your directory name to the frontmatter name field exactly when authoring agent skills. Directory naming that matches the frontmatter name field is a strict requirement to prevent loading failures and validation errors in OpenCode.