Docs: Skill path mismatch - 'skills' (plural) vs 'skill' (singular)

[bjesuiter]

Summary

The documentation specifies skill paths with plural skills/, but opencode actually loads from singular skill/.
Loading from skills/ does NOT WORK right now!
The agent says when using the skills tool, my skills don't show up when I place them in skills/, but they DO show up when placed at skill/

Documentation Says

From the docs :

Global config: ~/.config/opencode/skills/<name>/SKILL.md

Link to the Docs: https://opencode.ai/docs/skills/#:~:text=Troubleshoot%20loading-,Agent%20Skills,-Define%20reusable%20behavior

Actual Behavior

Skills only load from:

~/.config/opencode/skill/<name>/SKILL.md

Steps to Reproduce

1. Create a skill at ~/.config/opencode/skills/my-skill/SKILL.md (plural, as documented)
2. Restart opencode
3. Skill is not found
4. Move to ~/.config/opencode/skill/my-skill/SKILL.md (singular)
5. Restart opencode
6. Skill is found

Expected Behavior

Either:

• Update docs to reflect actual path (skill/ singular), OR
• Update code to match docs (skills/ plural), OR
• Support both paths

Environment

• macOS
• opencode (latest as of 2025-01-21)

[github-actions]

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

• Skill Discovery Only Checks skills/ Directory, Ignoring skill/ Path #8054: Skill Discovery Only Checks skills/ Directory, Ignoring skill/ Path
• Tweak .opencode/skill into .opencode/skills #9044: Tweak .opencode/skill into .opencode/skills
• skills directory name why not use same specify as claude clode #9207: skills directory name why not use same specify as claude code
• Inconsistency in docs for where to install skills #6171: Inconsistency in docs for where to install skills
• Skill discovery doesn't match Claude Code's skills/ directory structure #6177: Skill discovery doesn't match Claude Code's skills/ directory structure
• Does opencode actually support finding skills at .claude/skills? #6266: Does opencode actually support finding skills at .claude/skills?
• Backward compatibility broken - enforcement of the /skill directory naming #6432: Backward compatibility broken - enforcement of the /skill directory naming

Feel free to ignore if none of these address your specific case.

[rekram1-node]

Hm looking

[rekram1-node]

Cannot replicate

[rekram1-node]

and you are on 1.1.28 correct?

[rothnic]

I'm having the same issue with the latest opencode (1.1.29), setting up fresh on a new dev machine, trying to use the vercel skill installer package to try that out along with creating some of my own skills. It seems vercel was confused by the location to put them and the opencode cli is confused as well, since the debug command for skills finds them in the "wrong" location. None of these skills are listed as available in opencode, even after restarting.

It would be nice to have some easy way to see the tools, skills etc available to the default or particular agent, using the same underlying functionality, from the cli to validate configurations, along with where permissions or settings are coming from. It seems the cli debug commands don't use the same functionality.

  /data/projects/ntm on  copilot/add-opencode-server-support opencode debug skill
[
  {
    "name": "humanizer",
    "description": "Remove signs of AI-generated writing from text. Use when editing or reviewing\ntext to make it sound more natural and human-written. Based on Wikipedia's\ncomprehensive \"Signs of AI writing\" guide. Detects and fixes patterns including:\ninflated symbolism, promotional language, superficial -ing analyses, vague\nattributions, em dash overuse, rule of three, AI vocabulary words, negative\nparallelisms, and excessive conjunctive phrases.\n",
    "location": "/home/ubuntu/.config/opencode/skills/humanizer/SKILL.md"
  },
  {
    "name": "skill-creator",
    "description": "Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.",
    "location": "/home/ubuntu/.config/opencode/skills/skill-creator/SKILL.md"
  },
  {
    "name": "opencode",
    "description": "A comprehensive skill for managing all aspects of OpenCode, including configuration, installation, extensions, SDK usage, and ecosystem research.",
    "location": "/home/ubuntu/.config/opencode/skills/opencode/SKILL.md"
  },
  {
    "name": "agent-mail",
    "description": "Detailed usage patterns for the mcp-agent-mail server, including registration, file reservations, and communication macros.",
    "location": "/home/ubuntu/.config/opencode/skills/agent-mail/SKILL.md"
  },
  {
    "name": "skills-discovery",
    "description": "Search for and install Agent Skills that give you specialized capabilities. Before starting work, ask might a skill exist that handles this better than my base knowledge? If the task involves specific technologies, frameworks, file formats, or expert domains. Search proactively, even if the user doesn't mention skills. Skills encode best practices, tools, and techniques you wouldn't otherwise have. Also use when users explicitly ask to find, install, or manage skills.",
    "location": "/home/ubuntu/.opencode/skill/skills-discovery/SKILL.md"
  }
]

  /data/projects/ntm on  copilot/add-opencode-server-support ls ~/.config/opencode/skills
3268860 drwxrwxr-x ubuntu ubuntu 4.0 KB Wed Jan 21 17:13:29 2026  .
2509121 drwxrwxrwx ubuntu ubuntu 4.0 KB Wed Jan 21 17:53:52 2026  ..
3268861 drwxrwxr-x ubuntu ubuntu 4.0 KB Wed Jan 21 16:18:15 2026  agent-mail
3275890 lrwxrwxrwx ubuntu ubuntu  33 B  Wed Jan 21 17:05:18 2026  humanizer ⇒ ../../../.agents/skills/humanizer
3271258 drwxrwxr-x ubuntu ubuntu 4.0 KB Wed Jan 21 17:10:32 2026  opencode
3276097 lrwxrwxrwx ubuntu ubuntu  37 B  Wed Jan 21 17:13:29 2026  skill-creator ⇒ ../../../.agents/skills/skill-creator

  /data/projects/ntm on  copilot/add-opencode-server-support opencode --version
1.1.29

  /data/projects/ntm on  copilot/add-opencode-server-support ls ~/.config/opencode
2509121 drwxrwxrwx ubuntu ubuntu 4.0 KB Wed Jan 21 17:53:52 2026  .
1055105 drwxrwxr-x ubuntu ubuntu 4.0 KB Wed Jan 21 17:43:16 2026  ..
2513590 .rwxrwxrwx ubuntu ubuntu 123 B  Wed Jan 21 15:15:17 2026  .gitignore
2512835 .rw-rw-r-- ubuntu ubuntu 1.4 KB Wed Jan 21 16:39:28 2026  AGENTS.md
2509176 .rw-rw-r-- ubuntu ubuntu 1.0 KB Wed Jan 21 17:50:38 2026  antigravity-accounts.json
2512784 .rw-r--r-- ubuntu ubuntu  11 KB Wed Jan 21 17:53:52 2026  bun.lock
2512856 .rw-rw-r-- ubuntu ubuntu 234 KB Wed Jan 21 17:00:29 2026  config.schema.json
3271260 drwxrwxr-x ubuntu ubuntu 4.0 KB Wed Jan 21 16:50:05 2026  docs
3268747 drwxrwxr-x ubuntu ubuntu 4.0 KB Wed Jan 21 16:18:15 2026  instructions
2514377 drwxrwxrwx ubuntu ubuntu 4.0 KB Wed Jan 21 17:51:49 2026  node_modules
2512839 .rw-rw-r-- ubuntu ubuntu 3.7 KB Wed Jan 21 17:29:46 2026  opencode.jsonc
2513589 .rwxrwxrwx ubuntu ubuntu 161 B  Wed Jan 21 17:53:52 2026  package.json
3273540 drwxrwxr-x ubuntu ubuntu 4.0 KB Wed Jan 21 17:00:29 2026  scripts
3268860 drwxrwxr-x ubuntu ubuntu 4.0 KB Wed Jan 21 17:13:29 2026  skills

[rekram1-node]

None of these skills are listed as available in opencode, even after restarting.

What do you mean?

[rothnic]

@rekram1-node the command i show above (opencode debug skill) to list out the 5 skills that I'd expect to see in the opencode TUI don't show up when i run opencode. I'm specifically trying to use the slash command to see it in the TUI like it is working for me on my other machine. I tried the approach you used and the agent shows the skills, so it must be a TUI issue.

The only thing i can think of is this is my first time trying that skill installer which leverages symlinks so we can use the same skill across agents.

[rekram1-node]

I think there is some confusion here, you can't invoke skills manually, so doing a /skill-creator won't do anything even if all the skills are loaded

[rothnic]

ahhh... sorry for the confusion, i think i installed oh my opencode on my other machine the same time that opencode added skill support and thought the slash commands were coming from opencode. I guess I assumed since if you really want an agent to use one that you need to reference it there would be a way to reference it. Not being able to @ mention them or something makes it a bit confusing.

Treating them as commands kind of felt odd but at the same time made sense, since you could technically use a slash command or reference the command markdown file or point an agent to a directory of files (essentially a skill), and get a similar result.

[rothnic]

I do still stand by the suggestion it would be a ux win to list out or view explicitly what skills or tools are available based on the path, then the status of the permissions for the given agent selected. Maybe with an option to hide or show disabled skills/tools. I think it is a common concern to both understand if something really is available to an agent and also how many tools and how much they take up context. Maybe keep them separate in a slash command of /skills and /tools where tools is grouped by custom/plugin vs mcp server.

Maybe I'll poke around at that sometime.