superpowers Fix: Update OpenCode skills directory path to match official spec

Update all references from 'opencode/skills' to 'opencode/skill' to align with OpenCode Agent Skills documentation (https://opencode.ai/docs/skills)

Changes:

.opencode/plugin/superpowers.js: Update project and personal skills dir paths from plural skills to singular skill.
docs/README.opencode.md: Update all path references in documentation to reflect the correct directory structure.

This fixes a critical issue where find_skills cannot locate user-defined skills, and users are prevented from applying a workaround by OpenCode core itself.

Motivation and Context

The official OpenCode documentation mandates that user-defined skills reside in .opencode/skill (singular).

The current implementation of superpowers incorrectly searches for a plural skills directory. Crucially, users cannot manually rename their directory to skills to work around this bug, because OpenCode core strictly enforces the naming convention and throws the following error on startup:

Directory "skills" in /Users/.../.config/opencode is not valid. Rename the directory to "skill" or remove it. This is a common typo.

This creates a deadlock where the plugin expects a directory name that the core application explicitly forbids. This PR resolves this conflict by aligning the plugin with the core specification.

How Has This Been Tested?

I tested this locally on macOS:

Renamed my local config directory to skill (as required by OpenCode core).
Applied the fix to superpowers.js.
Ran use find_skills tool within OpenCode.
Result: The agent successfully located and listed the skills from ~/.config/opencode/skill (global skills) and .opencode/skill (project skills).

Breaking Changes

None. Previously, it was impossible to use custom skills with this plugin because OpenCode core would reject the skills directory required by the plugin. This change enables the intended functionality.

Types of changes

[x] Bug fix (non-breaking change which fixes an issue)
[ ] New feature (non-breaking change which adds functionality)
[ ] Breaking change (fix or feature that would cause existing functionality to change)
[x] Documentation update

Checklist

[x] I have read the MCP Documentation
[x] My code follows the repository's style guidelines
[x] New and existing tests pass locally
[x] I have added appropriate error handling
[x] I have added or updated documentation as needed

Summary by CodeRabbit

Chores
- Reorganized skills directory paths: personal skills now at ~/.config/opencode/skill/ and project skills at .opencode/skill/
- Updated user-facing messages and error text to reference the new singular "skill" paths
Documentation
- Updated README and setup instructions to use the new directory names and creation commands
Tests
- Adjusted test fixtures and checks to verify the new skill directory locations

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Dec 30 '25 09:12 chada

📝 Walkthrough

Walkthrough

Project and personal "skills" directories were renamed from plural to singular: project .opencode/skills → .opencode/skill and personal ~/.config/opencode/skills → ~/.config/opencode/skill. All code, tests, and documentation references were updated to the new paths.

Changes

Cohort / File(s)	Summary
Core plugin `.opencode/plugin/superpowers.js`	Changed project/personal skills path references from `.opencode/skills` / `~/.config/opencode/skills` to singular `.opencode/skill` / `~/.config/opencode/skill`; updated user-facing messages and error text.
Documentation `docs/README.opencode.md`	Replaced all examples and instructions to use `.opencode/skill` and `~/.config/opencode/skill`; updated mkdir examples, SKILL.md path references, and priority ordering section.
Tests `tests/opencode/setup.sh`, `tests/opencode/test-plugin-loading.sh`, `tests/opencode/test-priority.sh`	Updated test fixtures and assertions to create and check SKILL.md under `.../skill/...` instead of `.../skills/...`; no test logic changes beyond path updates.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐇 I hopped from "skills" to a single "skill" with cheer,
Paths trimmed and tidy, the burrow's now clear,
Tests and docs aligned, no more plural frill,
A neat little change — I celebrate with a trill!

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically identifies the main change: updating the OpenCode skills directory path from plural to singular form to align with official specification.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

[ ] 📝 Generate docstrings

📜 Recent review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 56ecf428a73518d1fed464eb12da3169e6ff09b5 and e34229b7553bd21f8ce16fb0b929d58ae3a70ab1.

📒 Files selected for processing (3)

tests/opencode/setup.sh
tests/opencode/test-plugin-loading.sh
tests/opencode/test-priority.sh

🔇 Additional comments (6)

tests/opencode/test-plugin-loading.sh (1)

73-73: LGTM! Path correctly updated to singular form.

The fixture verification now checks the correct singular path skill/personal-test/SKILL.md, consistent with the OpenCode specification.

tests/opencode/setup.sh (2)

32-33: LGTM! Personal skill fixture updated correctly.

Both directory creation and file writing now use the singular skill/ path, properly aligning with the OpenCode specification.

46-47: LGTM! Project skill fixture updated correctly.

The project-level test fixture now uses .opencode/skill/ (singular), consistent with the specification and the personal skill path updates.

tests/opencode/test-priority.sh (3)

35-36: LGTM! Personal priority fixture updated correctly.

The personal-level priority test skill now uses the singular skill/ path, consistent with the specification.

49-50: LGTM! Project priority fixture updated correctly.

The project-level priority test skill now uses .opencode/skill/ (singular), maintaining consistency with the personal path updates.

75-82: LGTM! Verification checks updated consistently.

Both fixture existence checks now verify the singular skill/ paths for personal (line 75) and project (line 82) skills. Note that the superpowers path at line 68 correctly remains as skills/ (plural) since it references the bundled skills directory within the superpowers package installation, which is distinct from user custom skills.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Dec 30 '25 09:12 coderabbitai[bot]

This PR has 2 commits with the same title because I forgot to check the tests/opencode/ directory to fix related test files when making the initial fix. Please squash when merging if accepted.

Dec 30 '25 10:12 chada

Research Results

I tested this claim on OpenCode v1.1.31 (macOS):

Test Performed

mkdir -p ~/.config/opencode/skills/test-skill
echo '---
name: test-skill
description: Test skill for verification
---
# Test Skill
This is a test.' > ~/.config/opencode/skills/test-skill/SKILL.md

Result

OpenCode found and registered the skill without any error:

service=permission permission=skill pattern=test-skill

The find_skills tool correctly returned:

- test-skill — Test skill for verification

Conclusion

The claim that "OpenCode strictly enforces singular skill and throws an error for skills" is not reproducible on OpenCode v1.1.31. The plural skills/ directory works correctly.

Could you provide:

The exact OpenCode version where you saw this error?
The exact error message OpenCode displayed?
Steps to reproduce the issue?

Without a reproducible case, I'm closing this PR as the underlying issue cannot be verified.

Jan 22 '26 18:01 obra

Closing as unable to reproduce the claimed behavior. Please reopen with a reproducible case if this is still an issue on a specific OpenCode version.

Jan 22 '26 18:01 obra