Description
Issue
Context added to guide LLMs to the correct paths of script files does not work as intended.
SkillTool injects this context to guide LLMs to the right script paths:
`Base directory for this skill: ${base}`,
"Relative paths in this skill (e.g., scripts/, reference/) are relative to this base directory.",
Opencode doesn't have this documented explicitly, but it is generally recognized that relative paths to skill scripts should work: https://agentskills.io/skill-creation/using-scripts#referencing-scripts-from-skill-md
Testing across many different models (Terra, GLM 5.2, Grok 4.3, etc), this injected context is often ignored. The most common outcome is the LLM will first try to execute the script relative to the project, it fails because the script doesn't exist, then it will investigate and start using tools (find, ls, ...) to find the script.
However, the worst case scenario is far more costly: The LLM fails to find the script, ignores the SkillTool context, and then proceeds with the task without using the script at all. In my case, I ended up with a runaway session that tapped out my daily token limit.
Workarounds
A quick search across OSS projects, I'm seeing two ways people are dealing with this:
- A second callout with similar language as the SkillTool context, but within the SKILL.md.
- Home-relative path is used in all skill script paths. ie
~/user/.opencode/skills/<skill>/scripts/myscript.sh
I'm inclined to use the latter method until this is resolved.
Proposed solution
A replacement marker or template variable so opencode can inject the correct path into the skill text directly.
Example SKILL.md text:
Run this script: `{{SKILL_SCRIPTS}}/myscript.sh`
SkillTool would then replace {{SKILL_SCRIPTS}} with the appropriate path. The LLM would see something like this:
Run this script: `/home/user/.opencode/skills/myskill/scripts/myscript.sh`
Plugins
No response
OpenCode version
1.17.20
Steps to reproduce
No response
Screenshot and/or share link
No response
Operating System
No response
Terminal
No response
Description
Issue
Context added to guide LLMs to the correct paths of script files does not work as intended.
SkillTool injects this context to guide LLMs to the right script paths:
Opencode doesn't have this documented explicitly, but it is generally recognized that relative paths to skill scripts should work: https://agentskills.io/skill-creation/using-scripts#referencing-scripts-from-skill-md
Testing across many different models (Terra, GLM 5.2, Grok 4.3, etc), this injected context is often ignored. The most common outcome is the LLM will first try to execute the script relative to the project, it fails because the script doesn't exist, then it will investigate and start using tools (find, ls, ...) to find the script.
However, the worst case scenario is far more costly: The LLM fails to find the script, ignores the SkillTool context, and then proceeds with the task without using the script at all. In my case, I ended up with a runaway session that tapped out my daily token limit.
Workarounds
A quick search across OSS projects, I'm seeing two ways people are dealing with this:
~/user/.opencode/skills/<skill>/scripts/myscript.shI'm inclined to use the latter method until this is resolved.
Proposed solution
A replacement marker or template variable so opencode can inject the correct path into the skill text directly.
Example SKILL.md text:
SkillTool would then replace
{{SKILL_SCRIPTS}}with the appropriate path. The LLM would see something like this:Plugins
No response
OpenCode version
1.17.20
Steps to reproduce
No response
Screenshot and/or share link
No response
Operating System
No response
Terminal
No response