OpenCode Skills Installation Guide: Manually Configuring Professional Skill Packages

2026-01-22 1040 words 5 minutes

Contents

You will learn:
What OpenCode Skills are and their function
How to create a standard Skills directory structure
How to import and verify skill packages
Troubleshooting common issues
How to create custom skill packages

What are OpenCode Skills?

OpenCode Skills are OpenCode’s modular extension mechanism, injecting domain-specific expertise and workflows into the AI assistant through structured instruction packages. Each Skill encapsulates industry best practices, checklists, and execution templates, enabling OpenCode to perform tasks like a subject matter expert. Common Skills include SEO audits, code reviews, test writing, API design, and other professional capabilities.

This article will guide you on how to install custom Skills for the OpenCode assistant to extend its functionality.

Installation Steps

1. Create Configuration Directory

In your project root directory, you need to build a standard directory structure to store skill files.

First, create a folder named .opencode in the project root.
Inside the .opencode folder, create a subfolder named skills.

If you are using the command line, run:

mkdir -p .opencode/skills

2. Import Skill Package

Copy the skill package folder you obtained (e.g., seo-review or other custom Skills) directly into the .opencode/skills/ directory you just created.

The recommended directory structure after installation looks like this:

Project_Root/
├── .opencode/
│   └── skills/
│       └── your-custom-skill/  <-- Your skill package folder
│           ├── SKILL.md
│           └── ...
└── ...

Verify Installation

After installation, verify if the Skill is successfully loaded by talking to OpenCode.

Open the OpenCode terminal in the project directory.
Enter a query command, such as: “What skills do you have” or “List current available skills”.

Output Example

If installed successfully, OpenCode will recognize and list available skills, as shown below:

> What skills do you have

Thinking: User asked what skills I have. According to my tool description, I have a skill tool that can load specific skills to get detailed guidance.
Let me check what skills are listed in available_skills:
According to tool description, currently available skills are:
- seo-review: Performs focused SEO audits on JavaScript concept pages to maximize search visibility, snippet optimization, and ranking potential

I currently have the following available skills:
seo-review - Performs focused SEO audits on JavaScript concept pages to maximize search visibility, snippet optimization, and ranking potential

When a specific skill is needed, I will automatically load it to get detailed guidance for specific tasks.

At this point, you have successfully installed a new skill for OpenCode. In subsequent conversations, OpenCode will automatically load and apply these skills when related tasks are involved.

Troubleshooting

Issue 1: OpenCode cannot recognize installed Skill

Symptom: Skill package copied to .opencode/skills/ directory, but OpenCode says no available skills when queried.

Possible Causes:

Incorrect directory structure
Missing SKILL.md file
Permission issues

Solution:

# 1. Verify directory structure
ls -la .opencode/skills/your-skill/
# Should see SKILL.md file

# 2. Check file permissions
chmod -R 755 .opencode/skills/

# 3. Verify SKILL.md format (Must start with YAML frontmatter)
head -n 5 .opencode/skills/your-skill/SKILL.md

# 4. Restart OpenCode (Relaunch in project directory)
cd /path/to/project
opencode

Issue 2: Skill file format error

Symptom: OpenCode throws error on startup or skill fails to load.

Common Format Errors:

# ❌ Error 1: Missing YAML frontmatter
# Skill: SEO Review
This is my skill...

# ✅ Correct Format:
---
name: seo-review
description: "SEO Audit Skill"
version: 1.0.0
---
# Skill: SEO Review

# ❌ Error 2: Filename is not SKILL.md
skill.md  # Lowercase not allowed
Skill.md  # Mixed case error

# ✅ Correct Naming:
SKILL.md  # Must be all uppercase

Issue 3: Skill not triggering automatically

Symptom: Skill recognized, but OpenCode doesn’t use it in related tasks.

Solution:

# 1. Explicitly specify skill usage
> Please use the seo-review skill to review this article

# 2. Check skill triggers (triggers section in SKILL.md)
cat .opencode/skills/seo-review/SKILL.md | grep -A 5 "triggers"

# 3. Use explicit prompts
# ❌ Vague: "Check this article"
# ✅ Explicit: "Perform an SEO audit on this article"

FAQ

Q1: Difference between Skills and MCP?

A: They serve different purposes:

Feature	Skills	MCP
Purpose	Provides expertise & workflows	Provides external tools & data access
Content	Instructions, Checklists, Templates	APIs, Databases, Commands
Trigger	Auto-triggered by task type	Tool invoked as needed
Example	SEO Audit, Code Review	File I/O, Network Requests

In simple terms: Skills tell AI “How to do it”, MCP gives AI “Tools to do it”.

Q2: Where can I find more Skills?

A: Currently, Skills are mainly obtained via:

Official Repo: github.com/opencode-ai/skills (Examples)
Community Sharing: OpenCode Community Forum
Create Your Own: Write following existing Skills format

Q3: Can I install multiple Skills simultaneously?

A: Yes. Just create multiple subfolders in the .opencode/skills/ directory:

.opencode/skills/
├── seo-review/
│   └── SKILL.md
├── code-review/
│   └── SKILL.md
└── api-design/
    └── SKILL.md

OpenCode will automatically load all valid skill packages.

Q4: Do Skills increase token consumption?

A: Yes, but the impact is manageable:

Skills use progressive loading, injecting instructions only when needed
Initial load reads only metadata (~100 tokens)
Detailed instructions load only when triggered (~500-2000 tokens)
For simple chats, no Skills content is loaded

Q5: How to create my own Skill?

A: Basic steps to create a custom Skill:

1. Create Directory Structure

mkdir -p .opencode/skills/my-custom-skill
cd .opencode/skills/my-custom-skill

2. Create SKILL.md File

---
name: my-custom-skill
description: "My custom skill description"
version: 1.0.0
author: "Your Name"

triggers:
  - type: keyword
    patterns:
      - "custom task"
      - "special analysis"
---

# My Custom Skill

## Workflow

1. Step 1: ...
2. Step 2: ...
3. Step 3: ...

## Checklist

- [ ] Item 1
- [ ] Item 2

## Examples

[Provide specific examples...]

3. Test and Verify

# Restart OpenCode
opencode

# Query Skills
> What skills do you have

# Test Trigger
> Execute custom task

Q6: What languages do Skills support?

A: Skill instructions can be written in any language (English, Chinese, etc.) since they are text instructions for AI. However, it is recommended to:

Use English for broader sharing
Use the target user’s language for better understanding
Maintain consistency in key terminology

Want to investigate more OpenCode capabilities? Recommended reading:

OpenCode Installation Guide - Start from scratch
OpenCode MCP Configuration Guide - Configure external tools and data
Claude Code Skills Complete Guide - Understand Skills design and advanced usage
OpenCode Antigravity Integration - Use top LLMs for free