Opencode not auto-detecting skills located in ~/.agents/skills/**

The docs seem to state these will be detected.

/Users/[MYHOMEDIR]/.agents/skills/vercel-react-best-practices however is not being picked up. Am i missing something or is the docs out of date?

On opencode 1.1.40.

Is there something missing from my configuration, do I need to explicitly grant anything in opencode.jsonc. It feels like it's either not behaving as expected or the docs are incomplete?

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

[FEATURE]: Support standard skills location at .agents/skills/ #10986: [FEATURE]: Support standard skills location at .agents/skills/ - This feature request is about supporting the standard .agents/skills/ directory
feat: add support for reading skills from .agents/skills directories #11842: feat: add support for reading skills from .agents/skills directories - This PR was merged to add auto-detection of skills from .agents/skills/ directories

It appears the feature has already been implemented in #11842 (merged), so if auto-detection isn't working as expected in your version, this may be a bug rather than a missing feature. Please check if you're running a recent version (v1.1.40 or later based on your message) and whether the feature is working correctly. If the problem persists, this might be worth reporting as a separate bug issue.

Feel free to ignore if this doesn't match your specific case.

In the console version 1.1.59, it also failed to load, but it works fine in the desktop version.

Are the files here detected automatically?

I hit this with project-level .agents/skills/ (not global), and traced it to the source.

In packages/opencode/src/skill/skill.ts, project-level external skill dirs are scanned via:

```ts
for await (const root of Filesystem.up({
targets: EXTERNAL_DIRS,
start: Instance.directory,
stop: Instance.worktree,
})) {
await scanExternal(root, "project")
}
```

When the working directory is the worktree root (i.e. Instance.directory === Instance.worktree), Filesystem.up() produces an empty range — the root itself is excluded. So .agents/skills/ at the repo root is never scanned.

The global path (using Global.Path.home) works fine because it doesn't go through Filesystem.up. This explains why ~/.agents/skills/ (issue #12741 title) would also fail if Filesystem.up has the same off-by-one for the home directory case — but in the global branch it's just a direct path.join, so that one should work. The project-level branch is the broken one.

The fix would be to make Filesystem.up inclusive of the start directory, or to explicitly add Instance.worktree as a candidate when scanning project-level external dirs.

OpenCode version: whatever is running locally (identified via source inspection on the dev branch).

Correction to my earlier comment — I traced through the code more carefully and Filesystem.up() does include the start directory when start === stop. The glob scan also works correctly in isolation (Glob.scan('skills/**/SKILL.md', { cwd: '.agents' }) returns the expected SKILL.md files).

So the discovery pipeline itself looks correct on paper. I'm still experiencing the symptom (project-level .agents/skills/ skills not appearing in the <available_skills> list), but I haven't been able to pin down the actual root cause yet. It may be session/context-timing related — e.g., skill state being initialized before the Instance context is fully set up, or a caching issue where the skill list is computed once and not refreshed.

Apologies for the premature diagnosis.

Update: this might just be stale cache, not broken discovery.

After an embarrassing amount of source-diving (tracing Filesystem.up, Instance.provide, State.create, checking env flags, reading logs, writing diagnostic scripts...), we finally realized the actual issue: Skill.state is a lazy-init, permanently-cached async closure. It initializes once per opencode process and never refreshes.

So if you:

Launch opencode
Add .agents/skills/foo/SKILL.md (perhaps with the help of an agent)
Start a /new session expecting a fresh environment

...the skill list is still cached from step 1. Even /new does not re-scan. You have to fully restart opencode.

This could explain the original report and the "console fails, desktop works" comment — if you happened to restart the desktop app but not the CLI, you'd see exactly that pattern.

The real bug is arguably that Skill.state should be invalidated on filesystem changes or at least on new sessions, rather than cached for the entire process lifetime. But it's not a discovery logic bug — the scanning code is correct.

Apologies for the earlier noise. We spent hours convinced the plumbing was broken when we just needed to restart the program.

I'm actually seeing the same thing - skills in .agents ignored, even if I restart OC. mv .agents .opencode does solve the problem, so it;s not an issue with the skill file.

I've been using skills.path[] property on opencode.json config file as workaround.. i think it's working ?

It is a workarounf. The documentations says it should work without a workaround: https://opencode.ai/docs/skills/#place-files

@jayair

I do not know what yet but yes it is broken. v1.3.0 still.

$ opencode debug skill --print-logs --log-level DEBUG
INFO  2026-03-30T21:27:26 +1ms service=skill count=0 init
[]

If I just run ln -s .agents .opencode it then magically start to work for this directory.

Top level also does not work anymore (used to work) ~/.agents/skills and it get healed the same way. So it avoids .agents for some reason.

UPD: for me the reason it does not work export OPENCODE_DISABLE_CLAUDE_CODE=1 - this seem disables .agents discovery alongside with .claude... @jayair

Yes. I am seeing this in the package level .opencode/skills/ directory on 1.3.15.
Not using any particularly complex configurations either. Not a blocker.

UPD: for me the reason it does not work export OPENCODE_DISABLE_CLAUDE_CODE=1 - this seem disables .agents discovery alongside with .claude... @jayair

This should really be avoided. It's a terrible behavior

#12432

To stay organized issues are automatically closed after 60 days of no activity. If the issue is still relevant please open a new one.

Navigation Menu

Repository navigation

Opencode not auto-detecting skills located in `~/.agents/skills/**` #12741

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Opencode not auto-detecting skills located in ~/.agents/skills/** #12741

Description

Activity

github-actions commented on Feb 8, 2026

shihyuho commented on Feb 12, 2026

rumeysakicali commented on Feb 25, 2026

rndmcnlly commented on Feb 28, 2026

rndmcnlly commented on Feb 28, 2026

rndmcnlly commented on Mar 1, 2026

xl0 commented on Mar 25, 2026

diegohb commented on Mar 26, 2026

xl0 commented on Mar 26, 2026

FelikZ commented on Mar 30, 2026

davidbernat commented on Apr 5, 2026

patacca commented on Apr 8, 2026

lirc571 commented on Apr 17, 2026

github-actions commented on Jul 3, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Opencode not auto-detecting skills located in `~/.agents/skills/**` #12741