build-skill_skill

Overview

This skill helps teams create effective OpenCode agent skills by providing a clear format, naming conventions, progressive disclosure patterns, and validation tools. It should be loaded first when building, reviewing, or debugging other skills to ensure consistency and token-efficient design. The skill includes scaffolding scripts and a pre-flight checklist to catch common errors before use.

How this skill works

The skill inspects a skill directory for required frontmatter, naming consistency, file structure, and internal link resolution. It guides authors through a decision tree that selects the appropriate skill type (instructions-only, reference-heavy, script-heavy, multi-file, or progressive) and recommends when to split content into external references. Validation scripts automatically check structure, line counts, and manifest fields and can package the skill for distribution.

When to use it

• When you are authoring a reusable agent capability that will be invoked multiple times
• When domain knowledge or internal APIs are missing from the model and must be encoded
• When a workflow requires three or more ordered steps or repeatable automation
• When you need shared procedural knowledge across a team
• When reviewing or debugging existing skills for structure and token-efficiency

Best practices

• Start with the manifest frontmatter: name, concise description, and clear usage guidance
• Choose the simplest skill type that covers the use case; prefer references for large docs and scripts for repeatable automation
• Use progressive disclosure: keep the main file short and surface detailed references only when needed
• Follow a consistent directory structure for scripts/, references/, and assets/ to make discovery and validation reliable
• Run the provided validation script and pre-flight checklist before sharing or deploying a skill

Example use cases

• Scaffold a new skill from a template and validate its manifest and filenames
• Convert an internal API spec into a reference-heavy skill for agent lookup
• Bundle a repeatable data-processing workflow with scripts and validation checks
• Create a multi-step release or deployment workflow that agents can execute reliably
• Audit and fix existing skills to reduce token usage and improve progressive disclosure