Governed Vibecoding vs Unmanaged AI CodingRead Now →
Skip to main content

OpenCode Skills

Learn how OpenCode Skills use SKILL.md definitions, compatible skill folders, native skill-tool loading, permissions, and enterprise controls.

11 min read
Axiom Studio Team· Engineering

How OpenCode Skills Work

OpenCode Skills are SKILL.md definitions that can live in OpenCode, Claude-compatible, or agent-compatible folders. The native skill tool exposes available skills and loads full instructions only when permitted.

Source checked against OpenCode skills docs

Official documentation source

OpenCode discovers reusable instructions from repo and home-directory skill folders.

Skills load on demand through OpenCode's native skill tool.

OpenCode documents skill permissions with allow, deny, and ask behavior.

Primary file

SKILL.md

Project paths

.opencode/skills, .claude/skills, .agents/skills

Invocation

Native skill tool loads selected skills

Permission modes

allow, deny, ask

Good fit

Teams that want one skill library to interoperate across OpenCode, Claude-style, and agent-compatible folder conventions.

Watch closely

Permission rules can hide, reject, or prompt for skills; do not assume a visible skill can always load.

Governance move

Make opencode.json skill permissions explicit and review wildcard patterns such as internal-* or experimental-*.

OpenCode Skills define reusable behavior through SKILL.md files. The agent sees available skills in the native skill tool description, then can load the full skill content on demand.

This is useful for team conventions, release procedures, review checklists, and agent workflows that should not be pasted into every prompt.

Where OpenCode Skills Live

OpenCode guide

OpenCode searches several repo and home-directory locations. It supports .opencode/skills paths as well as Claude-compatible .claude/skills paths and agent-compatible .agents/skills paths.

For project-local paths, OpenCode walks up from the current directory until it reaches the git worktree, which lets a monorepo expose skills from relevant parent folders.

1

.opencode/skills/<name>/SKILL.md for project OpenCode skills.

2

~/.config/opencode/skills/<name>/SKILL.md for global OpenCode skills.

3

.claude/skills/<name>/SKILL.md for Claude-compatible project skills.

4

.agents/skills/<name>/SKILL.md for agent-compatible project skills.

Frontmatter and Naming Rules

OpenCode guide

OpenCode recognizes a focused frontmatter shape: name, description, optional license, optional compatibility, and optional metadata. Unknown frontmatter fields are ignored.

Skill names are constrained to lowercase alphanumeric words separated by single hyphens and must match the containing directory name.

Do not over-port platform behavior

Each platform can use SKILL.md-style files, but discovery paths, invocation rules, frontmatter, permissions, and distribution mechanics differ. Verify the target platform before copying a skill unchanged.

Discovery and Invocation

OpenCode guide

OpenCode lists available skills in the skill tool description. The agent can call that tool with a skill name to load the full SKILL.md.

This keeps the initial prompt compact while preserving a discoverable menu of reusable procedures.

Permissions and Security

OpenCode guide

OpenCode lets teams control skill access through pattern-based permissions. A matching rule can allow a skill, deny it, or require a user prompt before loading.

That permission layer is important because skills change agent behavior and may point the model toward privileged tools, scripts, or internal procedures.

1

Prefer deny or ask for experimental and internal-only skill groups.

2

Keep wildcard rules narrow enough that future skill names do not inherit too much trust.

3

Disable the skill tool for agents that should not use reusable workflow packs.

4

Review global skills separately from project skills because both can influence behavior.

Enterprise Governance Checklist

OpenCode guide

OpenCode's folder compatibility is useful, but it also means a team may have skills coming from several locations. Governance should inventory each location, permission pattern, and skill owner.

For regulated teams, log which skill loaded, which work item it affected, and whether the permission was allow, deny, or ask.

Govern OpenCode Skills with tracked agent work

VibeFlow connects reusable agent workflows to work items, execution logs, commit records, security review, QA, and durable project context. That audit trail makes skills reviewable instead of invisible prompt behavior.

See VibeFlow

Ready to get started?

See how Axiom Studio can transform your AI infrastructure with enterprise-grade governance, security, and cost optimization.

Contact Us

Continue Learning

What Are Agent Skills?

The shared skill model behind reusable agent workflows.

Skills vs Agents vs MCP

Where skills sit relative to tools, MCP servers, and project instructions.

OpenClaw Skills

A related AgentSkills-compatible implementation with precedence and security gates.

Agent Skill Security

How to review permissions, provenance, scripts, and secrets exposure.

Code Review Skill

A practical reusable skill example for structured code review.