skill-authoring_skill

Overview

This skill defines the process to create and register new OpenCode skills in this repository. It enforces naming, frontmatter, placement, and discovery requirements so skills are discoverable and loadable by the skill tool. Use it to add reusable workflows, playbooks, or agent capabilities consistently.

How this skill works

The skill outlines the exact file layout, YAML frontmatter fields, and content sections required for a valid SKILL.md. It includes a validation checklist and discovery steps so you can confirm the new skill appears in the skill tool and loads without errors. It also describes permission and placement rules for both project and global scopes.

When to use it

• Adding a new workflow, playbook, or agent capability as an OpenCode skill
• Updating skill metadata to meet OpenCode discovery and compatibility rules
• Fixing naming, frontmatter, or placement issues that prevent discovery
• Publishing a reusable skill meant to work with the skill tool
• Migrating skills for Claude compatibility or global installation

Best practices

• Choose a lowercase kebab-case name matching ^[a-z0-9]+(-[a-z0-9]+)*$ and keep it 1–64 chars
• Put SKILL.md in .opencode/skill/<name>/SKILL.md (or the appropriate global/Claude path)
• Include YAML frontmatter with name and description; optionally add license, compatibility, metadata
• Structure the document with Purpose/What I do, When to use, Workflow, and Completion criteria
• Run the repo’s OpenCode instance and confirm the skill shows in the skill list before publishing

Example use cases

• Create a git-release skill that drafts release notes and proposes a version bump
• Add a payment-reconciliation playbook as a reusable agent skill for finance ops
• Update an existing skill to include compatibility: opencode or add permission rules
• Install a global skill for shared team utilities available to multiple projects