File path location error in skill

[util6]

Description

Here is the directory structure of my skill：
skill-name/
├── SKILL.md
├── scripts/
├── references/

It's failing to resolve the paths correctly. Instead of looking inside the skill directory, it's treating the paths as relative to my workspace root, so it can't find anything in references/.

Plugins

No response

OpenCode version

No response

Steps to reproduce

No response

Screenshot and/or share link

No response

Operating System

No response

Terminal

No response

[github-actions]

This issue might be a duplicate of existing issues. Please check:

• Bug: Agent resolves skill resource relative paths against CWD instead of skill's install directory #17101: Bug: Agent resolves skill resource relative paths against CWD instead of skill's install directory (same issue - relative paths in skill instructions resolved against CWD instead of skill directory)
• skill can't find scripts path #6900: skill can't find scripts path (same root cause - skill relative paths not resolved against skill install directory)

Both issues have been closed. It may be worth checking if the fix was applied and if this is a regression, or if your setup differs in some way.

[util6]

这是来自QQ邮箱的假期自动回复邮件。   你好，我最近正在休假中，无法亲自回复你的邮件。我将在假期结束后，尽快给你回复。

[zcutlip]

Many claude skills use ${CLAUDE_PLUGIN_ROOT}, as in:

${CLAUDE_PLUGIN_ROOT}/scripts/helper_script.sh.

I don't think opencode supports this or something similar, but I don't know how to have a skill locate a script dynamicaly without it.

[zol9527]

Many claude skills use ${CLAUDE_PLUGIN_ROOT}, as in:

${CLAUDE_PLUGIN_ROOT}/scripts/helper_script.sh.

I don't think opencode supports this or something similar, but I don't know how to have a skill locate a script dynamicaly without it.

Hi friend, have you solve it? Recently I use claude code & opencode both rencetly, but opencode can't read rules, scripts path properly.

[zcutlip]

have you solve it?
Sorry, no. This is a bug in opencode, and without a solution to dynamically resolve relative paths to skill resources, there's no solution.

I will say the model is usually persistent enought to try a bunch of paths, and eventually finds the helper script, but it's annoying and is probably wasteful of tokens.

[micha149]

I noticed that this issue only occurs when triggering the skill as a slash command like /my-skill. When doing so, the command is expanded to content of .agents/skills/my-skill/SKILL.md in my prompt. Maybe OpenCode loses the connection to the actual skill here.

When the skill is triggered by the agent through its description, for example by saying „lets plan the next story“, paths can be resolved correctly. This can help as a workaround, too. But hopefully this will help fixing this bug.

[zcutlip]

I've been working on a project which I'll share publicly later that generates supplemental documentation for OpenCode. I won't go into details of that project here, but I've learned quite a bit about how skills work internally, and what the agent sees vs. what's presented to the user on the console.

Here's an excerpt. Skip below for SKILL.md suggestions to help the agent locate bundled resources. (Note this is based on an older tag of the source code, so the source code reference may have changed). The excerpt below was fully automated, generated by a combination of scripts and LLM.

---

The Agent's View: <skill_content>

When the agent invokes the skill tool, it receives a structured XML block. Understanding this block is critical for writing effective skills. Here is exactly what the agent sees:

<skill_content name="my-skill">

# Skill: my-skill

[the full body of your SKILL.md, minus the frontmatter]

Base directory for this skill: file:///Users/you/.config/opencode/skills/my-skill/
Relative paths in this skill (e.g., scripts/, reference/) are relative to this base directory.
Note: file list is sampled.

<skill_files>
<file>/Users/you/.config/opencode/skills/my-skill/scripts/helper.sh</file>
<file>/Users/you/.config/opencode/skills/my-skill/reference/api-spec.yaml</file>
</skill_files>

</skill_content>

Key observations for skill authors:

1. Your content comes first, followed by metadata about the skill's directory and files. The agent may read your instructions before it gets to the path hints.
2. The file list is sampled — only up to 10 files are shown, and SKILL.md itself is excluded. Large skills may not list all files. The agent will find unlisted files by searching.
3. File paths are absolute, not relative. The agent can execute them directly via bash without resolving relative paths.
4. Your SKILL.md content is emitted verbatim — no variable substitution, no macro expansion, no placeholder replacement of any kind (see next section).

Source: packages/opencode/src/tool/skill.ts:23-72 (execute function), packages/opencode/src/tool/skill.txt (tool description)

---

...hi human here again.

Take away: the agent doesn't have any sort of variable or macro expansion that resolves to the skill location. No special SKILL_LOCATION/scripts/script.py syntax. However, it does have more context to work with than you realize. It gets a skill_content XML block with a nested skill_files XML tag. It's also explicitly told the "Base directory" of the skill, e.g.: /Users/user/projects/ProjectName/.opencode/skills/my-fancy-skill/.

You should be able to work with this information in your SKILL.md and the agent will know what you mean. Here's an example that's been working for me surprisingly well:

---
name: dev-setup
description: Set up development environment
---

Run the development environment setup script.

Step 1:

> Note: BASE_DIRECTORY should be the "Base Directory" from your "<skill-content ... >" message.
Execute: `{BASE_DIRECTORY}/scripts/dev-setup.sh`

Of course rather than being preprocessed by the harness and expanded deterministically, this gets handled by the LLM probabilistically. So it's going to depend on your model and what else is in the conext window.

But play around with it, and see if you get good results! Report back positive and negative findings so followers of this issue can take away lessons learned, until we get a proper, templated "skill location" macro.

[zcutlip]

Oh another thing I've learned: there's A LOT you can ask the agent about what it "saw" that you didn't see, and it'll help you diagnose when things went wrong. For example you can say:

When I invoked "my-fancy-skill" you either couldn't find the helper script, or it took you several tries. I'd like to improve the skill. can you show me the "skill_content" XML block you received when I invoked it?

This is especially effective if you switch back to a mode like Plan so the agent doesn't jump straight to fixing the problem, like "oh you're right. Now that I've found the script I'll run it..."

Then you can back-and-forth with the agent on ideas that might improve the skill.

Also, often when the agent tries something and fails, it gets error messages in the context window that you don't see. You can ask it to show you those, especially if you interrupted right when the error happened.

Using the agent harness to improve the agent harness is an untapped superpower of these tools. Give it a try!