OpenCode skills: install, create, and troubleshoot them

An OpenCode skill gives an agent reusable instructions for a specific task. Keep them in a SKILL.md file. OpenCode shows the agent each skill's name and description, then loads the full instructions through its skill tool when needed.

Start with OpenCode installed and a working model. If you need setup help, follow the OpenCode installation guide. Open it in your project folder. The example below uses pasted notes; it doesn't need a connected tracker or calendar. The OpenCode skills documentation is the reference for discovery paths and permissions.

If the job needs a separate worker with its own permissions or model, follow the OpenCode custom agents tutorial. An agent can use skills; the agent defines the role and access, while the skill supplies task instructions.

Step 1. Choose where the skill belongs

Use a project folder for a skill you want to keep with that project's files. Use a global folder when you want it available across projects on your machine.

OpenCode searches these paths:

• Project: .opencode/skills/<name>/SKILL.md
• Global: ~/.config/opencode/skills/<name>/SKILL.md
• Claude-compatible project: .claude/skills/<name>/SKILL.md
• Claude-compatible global: ~/.claude/skills/<name>/SKILL.md
• Agent-compatible project: .agents/skills/<name>/SKILL.md
• Agent-compatible global: ~/.agents/skills/<name>/SKILL.md

Here, ~ means your home directory and <name> is the skill's name. You need one copy, not a copy in every location.

For project skills, OpenCode checks from its current working directory up to the project root. Start it inside the right project. A skill in an unrelated project won't become available because it lives somewhere on the same computer.

Step 2. Create and load a small skill

In your project, create the folders .opencode/skills/daily-note/ and a file named SKILL.md inside the last folder. Paste this into the file:

---
name: Daily Note
description: Turn pasted work notes into a short status note. Use when asked to run daily-note.
---

Use only the notes the user supplies. Return three labeled lines:
Progress: what finished.
Blocker: what is blocked, or None stated.
Owner: the named owner, or TBD.

Do not invent facts or send the note anywhere.

The YAML block between the --- lines is frontmatter. The folder gives this skill its ID, daily-note. The name is a display label; it can be Daily Note without changing the ID. Add a clear description so OpenCode can advertise the skill to the agent.

IDs are case-sensitive. For portability, choose a unique lowercase ID with single hyphens between words, such as daily-note. Frontmatter is optional at runtime, but a skill without a description won't appear in the model's available list. You can keep scripts, references, and templates beside SKILL.md; paths in the instructions are relative to that skill's folder.

Start a new OpenCode session in the project folder. Paste this as a chat prompt, not a shell command:

@daily-note The draft is finished. Publishing is blocked on approval. Owner: Alex.

The @daily-note mention loads the skill explicitly by ID. The agent can also choose a relevant skill from its description and load it through the skill tool.

Confirm that daily-note loaded. The response should preserve the facts in the notes:

Progress: The draft is finished.
Blocker: Publishing is blocked on approval.
Owner: Alex.

Alex is a placeholder in this example. Try your own notes next. If you leave out the owner, the skill should return TBD rather than guess.

For turning a larger workflow into instructions, use the skill-writing guide.

Step 3. Install Pipa's business skills

To try the existing Pipa pack, run this in your terminal. Select all skills and choose OpenCode in the installer:

npx skills add lunchpaillola/pipa-skills

This uses the separate skills installer and requires Node.js/npm for npx. Choose project or global scope in the installer. Inspect downloaded instructions before using them, and keep the pack's folders and references together: its router calls other skills.

Ask OpenCode to check that one is available:

Load pipa-daily-plan. Don't run it yet.

Confirm that it loads. For planning, triage, and project-update prompts, follow the OpenCode skills for business guide.

Installing a skill supplies instructions. Connect apps separately before asking the agent to read them.

Step 4. Fix a skill that won't load

If the skill is missing, check these in order:

• Location: Is it in one of the discovery paths, inside the project OpenCode is using or in a global location?
• Filename: Is it exactly SKILL.md, including capitals?
• Frontmatter: If you added a YAML block, does it open and close with --- and contain valid YAML?
• ID: Are you using the exact, case-sensitive folder ID rather than the display name in frontmatter?
• Description: Does it clearly say what the skill does and when to use it?
• Permissions: Is the skill denied by a global or agent-specific rule?

In opencode.json or opencode.jsonc, the permissions array controls loading with action: "skill", the skill ID as resource, and an effect of allow, ask, or deny. Rules run in order; the last matching rule wins. A deny hides the skill and blocks loading. Agent-specific rules live under agents.<id>.permissions. File-editing and shell permissions are separate; see the OpenCode permissions guide for configuration examples.

If it loads the wrong instructions, check for duplicate IDs across project, global, and compatibility folders. A project .opencode skill overrides a global one with the same ID; explicit skills configuration can override both. Use unique IDs unless you intend an override. Ask the agent to load it and report which file it used. Start a new session after changing files or configuration so you can check the revised setup.

If it loads but isn't chosen for your task, invoke it with @skill-id. A broad or vague description makes selection harder. If the task needs a tracker or calendar, verify that connection separately; moving the skill file won't grant account access.

Step 5. Review the response

Check the response against your sources. Before the agent posts a comment, assigns work, or sends an update, require approval for each action.

The skills run in OpenCode without Pipa Local. If you want to use that setup from Slack, follow how to run OpenCode from Slack.

FAQ

Is a skill the same as an OpenCode plugin?

No. A skill provides instructions in SKILL.md. Plugins are code that extends OpenCode through hooks. Installing the Pipa skill pack doesn't install the Pipa Slack bridge.

Can a skill access my apps after I install it?

Only if the agent already has a working connection and the necessary permissions. Installation alone doesn't connect your accounts. For a first check, use pasted notes instead of live app data.

Should a skill live in Git?

Commit project skills when your team should share the same instructions. Keep personal defaults in a global folder. Leave API keys and other credentials out of SKILL.md in either location.