OpenCode Skills: How to Teach Your AI Coding Agent

Sana uses an AI coding agent every day. And every day she types the same instructions: “Write release notes in this format. Mention breaking changes first. Update the changelog.” It works, but it is boring. What if the agent could remember those steps and load them only when needed? That is exactly what OpenCode skills do.

What Are OpenCode Skills?

OpenCode Skills are Markdown instructions that OpenCode Skills can advertise to an agent and load when they are relevant, and a skill can include supporting scripts, references, and other files in the same directory. Think of a skill as a recipe card. The agent sees a list of recipe titles and only opens the full card when the task calls for it.

Skills are loaded on demand through the native skill tool, so agents see the available skills and can load the full content when needed. This keeps the agent’s working memory tidy, because it does not carry every instruction all the time.

Also Read: Philippine Coding Number

Skills vs. Other OpenCode Features (OpenCode Skills)

It helps to know how skills differ from similar ideas:

Feature	Purpose
AGENTS.md	General project rules the agent always sees
Skills	Reusable how-to guides loaded when relevant
Commands	Slash commands you run on purpose
Agents	Different AI “personas” with their own permissions
Plugins	Code that extends how OpenCode works

Use skills for repeatable know-how: release steps, OpenCode Skills review checklists, test-writing style, or brand voice.

Where Do Skills Live?  (OpenCode Skills)

OpenCode Skills searches these locations: project config at .opencode/skills/<name>/SKILL.md, global config at ~/.config/opencode/skills/<name>/SKILL.md, plus Claude-compatible and agent-compatible folders such as .claude/skills and .agents/skills, both for projects and globally.

In plain words:

• Project skills live inside your repo, OpenCode Skills, so teammates share them.

• Global skills live in your home folder, so you can use them everywhere.

• Compatible folders let you reuse skills made for other agent tools.

Anatomy of a Skill (OpenCode Skills)

A skill is a folder with a file named exactly SKILL.md.

.opencode/skills/
└── pr-review/
├── SKILL.md
├── references/
│   └── style-guide.md
└── scripts/
└── run-checks.sh

A skill folder can include optional parts such as scripts for executable code, references for documentation loaded as needed, OpenCode Skills and assets for files used in output.

The file name must be written in capital letters. A common mistake is writing skills. md.

Writing Front Matter (OpenCode Skills)

Each skill starts with a small header called frontmatter. In the stable docs, the recognised fields are name and description (both required), plus optional licence, compatibility, and a string-to-string metadata map, OpenCode Skills, while unknown fields are ignored.

Naming rules from the stable docs: the name must be 1 to 64 characters, and the description must be 1 to 1024 characters and should be specific enough for the agent to choose correctly. A good habit is to use lowercase words with hyphens, like pr-review, and match the folder name OpenCode Skills.

A version difference: The newer “v2” docs say something different. There, frontmatter, name, and description are optional at runtime, but skills without a description are not advertised to the model. V2 also does not enforce the name rules, and the frontmatter name is only a display label. OpenCode Skills: So check the docs for the version you use. Following the stricter rules is a safe choice for both.

A Sample Skill You Can Copy (OpenCode Skills)

Here is an original example of OpenCode Skills. Save it as .opencode/skills/pr-review/SKILL.md:

markdown

—
name: pr-review
description: Review a pull request for bugs, tests, and readability. Use when asked to review code changes.
license: MIT
—

# PR Review Skill

## When to use
Use this skill when the user asks for a code review or checks a pull request.

## Steps
1. Read the changed files and summarise what changed in 2-3 sentences.
2. Check for bugs, missing error handling, and unclear names.
3. Check that tests cover the new behaviour.
4. List problems from most to least serious.
5. End with one positive note and a short next-step list.

## Rules
– Do not rewrite the whole file. Suggest small changes.
– Never include secrets or private data in the review.

Notice the clear description. It says what the skill does and when to use it. The agent reads this description to decide whether to load the skill.

How the Agent Uses a Skill (OpenCode Skills)

OpenCode Skills lists the available skills inside the skill tool description, with each entry showing the skill name and description. The agent loads one by calling the skill tool with the skill’s name. After that, the agent follows the instructions inside.

Skills can refer to supporting files with relative paths, and the agent receives the skill’s base directory so it can find scripts and references.

Controlling Who Can Use Skills (OpenCode Skills)

You may not want every agent to use every skill. Permissions can be set in opencode.json with pattern rules, and wildcards like internal-* OpenCode Skills match several skills at once. A simple example:

json

{
“permission”: {
“skill”: {
“*”: “allow”,
“internal-*”: “deny”
}
}
}

You can also override permissions per agent, and skills set to deny are hidden from that agent. Check the current docs for exact options; OpenCode Skills settings can change. opencode

Adding Skills From Other Sources (OpenCode Skills)

The newer docs describe adding more sources. You can use a skills array in opencode.json or opencode.jsonc to add local directories or HTTP catalogues. This is helpful for teams who want a shared folder of approved skills.

There are also community plugins that add their own OpenCode Skills features, with different rules, such as stricter name matching. If you use one, follow its README.

Good Ideas for OpenCode Skills

• Release helper: version bump, changelog, and release notes

• Test writer: your preferred test style and tools

• Code reviewer: a checklist for quality and security

• Bug report triage: a standard way to reproduce and describe issues

• Documentation writer: tone, format, and examples

• Database migration guide: safe steps for schema changes

• Brand voice: words and style for marketing copy

• Deployment steps: a safe, OpenCode Skills repeatable checklist

Start with tasks you repeat at least once a week.

Tips for Writing Great Skills

1. Make the description specific. “Review pull requests for bugs and tests” beats “helpful skill”.

2. Say when to use it. Include trigger phrases like “when asked to prepare a release”.

3. Keep it short. Long skills waste attention. Move details to the references folder.

4. Use numbered steps. Agents follow clear sequences better.

5. Add rules and limits. Tell it what not to do.

6. Include one small example of good output OpenCode Skills.

7. Test with real tasks. Adjust the wording when the agent misses something.

8. Use version control. Treat skills like code.

Safety: Treat Skills Like Code

A skill can include scripts and instructions that make an agent run commands. So be careful:

• Install skills only from sources you trust.

• Read the SKILL.md and any scripts before you enable them.

• Do not store passwords or API keys inside a skill.

• Limit permissions for skills that run commands.

• Test in a safe project or branch first, OpenCode Skills.

• Review every change the agent makes, using Git.

• Be careful with remote catalogues and OpenCode Skills because a downloaded skill can change over time.

Troubleshooting

If a skill does not appear, verify that SKILL.md is spelt in all caps, that the frontmatter includes name and description, that skill names are unique across all locations, and that permissions do not deny it.

More checks:

1. Restart OpenCode Skills after adding or editing a skill.

2. Check the folder path against the list of search locations.

3. Look for duplicate names across project and global folders.

4. Read the YAML carefully. A missing dash or bad indent can break it.

5. Check the docs version. Rules differ between the stable and v2 docs.

6. Make the description clearer if the agent never picks the OpenCode skills.

Conclusions

OpenCode skills turn your best habits into reusable instructions. Write a clear description, keep steps short, store the skill in the right folder, and review it like code. Start with one skill that saves you the most time, then grow your collection. Soon your AI helper will not just write code. OpenCode Skills will follow your team’s way of doing things.

FAQs

What are OpenCode skills? 

They are reusable Markdown instruction files that the agent can load when a task matches.

Where do I put a skill? 

In a folder like .opencode/skills/<name>/SKILL.md for a project or ~/.config/opencode/skills/<name>/SKILL.md for global use.

Do skills work with Claude-style skill folders? 

OpenCode also searches .claude/skills and .agents/skills locations, according to its docs.

Why is my skill not showing up? 

Check the file name, front matter, duplicate names, and permissions, and restart the app. Also make sure it has a description.

Are skills the same as plugins? 

No. Skills are instructions. Plugins extend how the tool runs.

Can I share skills with my team? 

Yes. Put them in the project’s. Open the skills folder and commit them to Git.

Are skills safe? 

Only if they come from trusted sources. Review any scripts and keep secrets out.