skill authoring

Other Community

Skill notes

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

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

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

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
Other
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@different-ai · no license declared
Token usage
Lean
Setup complexity
Guided setup
External API key
Not required
Operating systems
Unspecified (assume cross-platform)
Runtime requirements
No explicit requirements detected
Detected file/system behavior
  • Read-only
  • Write / modify
  • Shell exec
Network behavior
Local-only
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

Author source file 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

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.