home / skills / different-ai / agent-bank / skill-authoring

skill-authoring skill

safe

This skill helps you author and register new OpenCode skills in the repo by enforcing naming, placement, and discovery rules.

npx playbooks add skill different-ai/agent-bank --skill skill-authoring

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.9 KB

---
name: skill-authoring
description: Create and register new OpenCode skills in this repo
compatibility: opencode
metadata:
  scope: repo
  format: skill-md
---

## What I do

- Define the steps and checks for adding a new OpenCode skill
- Ensure the skill is discoverable by the `skill` tool
- Validate naming, frontmatter, and placement rules

## When to use

- Adding a new reusable workflow or playbook as a skill
- Updating skill metadata to meet OpenCode discovery requirements

## Workflow

1. Pick a skill name that matches `^[a-z0-9]+(-[a-z0-9]+)*$` and is 1–64 chars.
2. Create `.opencode/skill/<name>/SKILL.md` and ensure the folder matches the name.
3. Add YAML frontmatter with `name` and `description` (optional: `license`, `compatibility`, `metadata`).
4. Write the body with clear sections (Purpose/What I do, When to use, Workflow, Completion criteria).
5. Confirm discovery: run OpenCode in the repo and check `skill` tool list.
6. If permissions block it, update `opencode.json` with `permission.skill` rules.

## Placement rules (from opencode.ai docs)

- Project: `.opencode/skill/<name>/SKILL.md`
- Project (Claude compatible): `.claude/skills/<name>/SKILL.md`
- Global: `~/.config/opencode/skill/<name>/SKILL.md`
- Global (Claude compatible): `~/.claude/skills/<name>/SKILL.md`

## Validation checklist

- `SKILL.md` is all caps and contains YAML frontmatter
- `name` matches folder name
- `description` is 1–1024 characters
- No duplicate skill names in the repo

## Example

```
---
name: git-release
description: Create consistent releases and changelogs
compatibility: opencode
---

## What I do

- Draft release notes from merged PRs
- Propose a version bump
- Provide a `gh release create` command
```

## Completion criteria

- Skill appears in `skill` tool list
- `skill({ name })` loads without errors
- Instructions are clear enough to execute without extra context

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

FAQ

What file name and location are required?

Create SKILL.md inside .opencode/skill/<name>/ with the folder name matching the skill name; alternate paths exist for global or Claude-compatible placement.

What must the frontmatter include?

YAML frontmatter must include name and description. Optional fields: license, compatibility, and metadata.