Skip to content
Recaply.
Sign inSubmit a tool

LearnTutorials

OpenCodeTutorialsOpen OpenCode

Install agent skills in OpenCode

Add a skill to OpenCode with npx or a premium ZIP, load it with @skill-id, and control who may use it. Covers every folder OpenCode reads and which copy wins.

By Recaply EditorsBeginner5 min6 stepsUpdated

A hand slips an index card into an open card file box

OpenCode reads skills from .opencode/skills, .claude/skills and .agents/skills in your project, and from ~/.config/opencode/skills, ~/.claude/skills and ~/.agents/skills for all your projects.

Short answer: run the skill's npx line with -a opencode, start OpenCode in the project, then mention the skill as @skill-id or just ask for the job.

What you need

  1. Step 1: Choose a project or global skill

    1 min

    OpenCode searches several folders, and the folder decides the skill's ID.

    1. Project: .opencode/skills/, .claude/skills/ or .agents/skills/. OpenCode checks every level from your current folder up to the project root.
    2. Global: ~/.config/opencode/skills/, ~/.claude/skills/ or ~/.agents/skills/.
    3. The skill's ID comes from its path and is case-sensitive. Use lowercase words joined by hyphens, 1 to 64 characters, matching the folder name.

    Same ID in two places? The source OpenCode reads later wins, in this order: built-in, .claude/skills/, .agents/skills/, ~/.config/opencode/skills/, then the project's .opencode/skills/. Skills listed in your config come last of all.

  2. Step 2: Install a free skill with one line

    1 min

    The skills CLI copies the skill from its maker's GitHub repo into .agents/skills/.

    1. Open a terminal in your project folder.
    2. Paste the line from the skill's Recaply page. It ends in -a opencode.
    3. To install it for all your projects instead, add -g. It then goes to ~/.agents/skills/.
    The install line
    npx skills add <owner>/<repo> --skill <skill-name> -a opencode

    You should see a new .agents/skills/<skill-name>/ folder with SKILL.md inside.

    The CLI asks which agents to install to?

    The line is missing its -a value. Pick your agent in the list, or run the line again with it. Add -y to skip the questions.

  3. Step 3: Or install a premium skill from its ZIP

    2 min

    A premium skill comes as one ZIP that holds a single folder named after the skill.

    1. On the skill's Recaply page, sign in, buy it (or use the plan), then click Download ZIP.
    2. Move the ZIP into your project folder and open a terminal there.
    3. Run the line below. It unzips the folder, then installs it for your agent.
    4. When it's done, you can delete the ZIP and the unzipped folder: the CLI made its own copy.
    Your line
    unzip <slug>.zip && npx skills add ./<slug> -a opencode

    You should see .agents/skills/<slug>/SKILL.md, with the skill's other files beside it.

    On Windows, there's no unzip?

    Right-click the ZIP, choose Extract All, and move the extracted folder into .agents/skills/ in your project.

    Unzipping straight into a skills folder works too: unzip <slug>.zip -d .opencode/skills/.

  4. Step 4: Check that OpenCode sees it

    1 min

    OpenCode's docs give no command that lists skills. At each step, it shows the model the skills it may load.

    1. Start OpenCode in your project folder. If it was open, restart it.
    2. Type @ and the skill's ID in a prompt, such as @skill-name, to load it yourself.
    3. Or ask which skills it can load: the model sees each allowed skill's ID, name and description.

    You should see OpenCode load the skill when you mention it.

    The skill is missing?

    A skill needs a description for the model to see it, and its file must be named exactly SKILL.md.

  5. Step 5: Run the skill

    1 min

    OpenCode loads a skill with its skill tool when your task fits, or when you mention it.

    1. Describe the job in words from the skill's description.
    2. Or mention it as @skill-id in your prompt.
    Your prompt
    @<skill-id> <what you want it to do>

    You should see OpenCode follow the skill's steps for your task.

    It loads only when you mention it?

    Check its SKILL.md for opencode/autoinvoke: false. That hides it from the model's list, but @skill-id still loads it.

  6. Step 6: Not working? Check these

    2 min

    OpenCode's own checklist covers the usual causes.

    1. The file is a nested file named exactly SKILL.md (or a .md file at the top of a skills folder).
    2. You used the ID from the path, not the name in the file. The name is only a label.
    3. The skill has a description.
    4. Your agent's permissions allow it. Rules in opencode.jsonc use the skill action with the skill's ID, and the last rule that matches wins: allow loads it, ask asks you first, deny hides it.
    5. No source that OpenCode reads later defines the same ID.

You get

A skill OpenCode can load on its own or with @skill-id

Try next

Install an agent skill in any AI coding agent6 steps · 5 minInstall agent skills in GitHub Copilot6 steps · 5 minInstall agent skills in Gemini CLI6 steps · 5 min

Did this guide work for you?

Sources

0 of 6Next: Choose a project or global skill