Skip to content

[FEATURE]: explicit skill sources and source-qualified duplicates #49108

New issue
New issue
Open
Open
[FEATURE]: explicit skill sources and source-qualified duplicates#49108
Assignees
rekram1-node

Description

@Studnicky
Studnicky
opened on Sep 15, 2026
  • I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

I use separate skill trees for multiple agent harnesses and want to compare them independently. OpenCode automatically scans compatibility directories such as ~/.claude/skills and ~/.agents/skills. When both trees contain a skill with the same directory name, OpenCode reports duplicate-name warnings and can fail while building the system prompt with:

TypeError: undefined is not an object (evaluating 'a.name')
at SystemPrompt.environment

Reproduction on macOS with OpenCode from the dev branch:

  1. Create ~/.claude/skills/review/SKILL.md.
  2. Create ~/.agents/skills/review/SKILL.md.
  3. Start OpenCode in a project that can discover both roots.
  4. Observe duplicate-name warnings and, depending on discovered ordering, a system-prompt construction failure.

Please support explicit skill sources and source-qualified IDs:

{
  "skills": {
    "sources": [
      { "id": "opencode", "path": "~/.config/opencode/skills", "enabled": true },
      { "id": "agents", "path": "~/.agents/skills", "enabled": true },
      { "id": "claude", "path": "~/.claude/skills", "enabled": true }
    ],
    "collision": "source-qualified"
  }
}

Expected behavior:

  • Explicit sources control which roots are scanned.
  • Same-named skills from different sources coexist as claude/review and agents/review.
  • Discovery and selection are deterministic.
  • Duplicate or malformed skill files produce diagnostics without crashing.
  • Existing behavior remains unchanged when skills.sources is not configured.
  • Source IDs support isolated harness and version A/B comparisons.

This complements related reports #31977, #32202, #7575, #25119, and #41288.

Activity

  1. github-actions
    assigned
    rekram1-node
    on Sep 15, 2026

  2. github-actions commented on Sep 15, 2026

    @github-actions
    github-actionsBot
    on Sep 15, 2026 – with GitHub Actions
    Contributor

    This issue doesn't fully meet our contributing guidelines.

    What needs to be fixed:

    • No issue template was used. This project requires one of three templates: Bug Report, Feature Request (title must start with [FEATURE]:), or Question. This issue appears to be a feature request but doesn't use the Feature Request template and the title doesn't start with [FEATURE]:.
    • The issue references several specific issue numbers and reads like AI-generated content. Please describe the problem from your own experience — include your OpenCode version, OS, and steps that reproduce the crash or warnings you encountered.
    • No system information provided (OpenCode version, OS, terminal).

    Please edit this issue to address the above within 2 hours, or it will be automatically closed.

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

    If you believe this was flagged incorrectly, please let a maintainer know.

  3. github-actions
    added
    needs:complianceThis means the issue will auto-close after 2 hours.
    on Sep 15, 2026
  4. Studnicky
    changed the title [-]feat(skills): support explicit skill sources and source-qualified duplicates[/-] [+][FEATURE]: explicit skill sources and source-qualified duplicates[/+] on Sep 15, 2026

  5. github-actions commented on Sep 15, 2026

    @github-actions
    github-actionsBot
    on Sep 15, 2026 – with GitHub Actions
    Contributor

    Thank you for updating the issue title to start with [FEATURE]:. However, the issue body is still empty and does not meet our contributing guidelines.

    What still needs to be fixed:

    The Feature Request template requires:

    • A description explaining the problem or need you are trying to solve
    • A verification checkbox confirming you have searched for existing issues

    Please edit the issue body to include this information. If you are unsure how to fill it out, check the Feature Request template for guidance.

  6. github-actions
    removed
    needs:complianceThis means the issue will auto-close after 2 hours.
    on Sep 15, 2026

  7. github-actions commented on Sep 15, 2026

    @github-actions
    github-actionsBot
    on Sep 15, 2026 – with GitHub Actions
    Contributor

    Thanks for updating the issue! Everything looks good now — the feature request is clear, includes reproduction steps, and explains the problem well. We appreciate the detail.

  8. tdytaylor commented on Sep 21, 2026

    @tdytaylor
    tdytaylor
    on Sep 21, 2026

    Related use case from a Windows user managing skills installed via the skills.sh CLI
    (bunx skills add owner/repo → ~/.agents/skills/):

    Beyond collision handling, it would be very helpful if skill listings also exposed
    provenance:

    1. In the TUI slash-command menu / skill picker, show a dimmed source hint next to each
      skill (the source id from skills.sources, or the containing directory).
    2. In the skill list advertised to the model, include the source id/path per skill, so
      agents can disambiguate shadowed or source-qualified entries.
    3. Optionally, read .skill-lock.json (skills.sh convention) when present, to surface
      the origin repository (e.g. grill-with-docs — mattpocock/skills) and help users
      know what to skills update.

    The source-qualified collision mode proposed here already implies skills carry a
    source identity internally — surfacing that identity in UI/listings would be a natural
    extension and would greatly help users with skills from multiple ecosystems
    (Claude plugin bundles, skills.sh installs, team catalogs).

  9. Studnicky commented on Sep 26, 2026

    @Studnicky
    Studnicky
    on Sep 26, 2026
    Author

    Could the core team weigh in on the design here? CONTRIBUTING asks for approval before a feature PR, so I should have waited. #49114 is up for reference only, and I'll rework it to whatever shape you prefer, or close it.

    On @tdytaylor's point: source-qualified mode gives every skill a source id, which is what source hints in the picker and in the model's skill list would build on. I'd keep that out of #49114 and do it as a follow-up if you want it.

  10. opencodejr commented on Oct 28, 2026

    @opencodejr
    opencodejrBot
    on Oct 28, 2026
    Contributor

    Thanks for the detailed write-up, @Studnicky!

    To restate the request: let skills.sources explicitly control which skill roots OpenCode scans (each with an id, path and enabled), and add an opt-in collision: "source-qualified" mode. With that, same-named skills from different roots could coexist as claude/review and agents/review, which would let you compare harnesses and versions in isolation. Maintainers will consider it.

    On the crash: the stack trace (SystemPrompt.environment / a.name) looks like it comes from OpenCode v1 (1.x). In v2 (2.x, @opencode/cli), skills with the same name in .claude/skills and .agents/skills are deduplicated by ID without crashing: the skill found later replaces the earlier one. If you can reproduce a crash on 2.x, please open a separate bug with the output of opencode --version.

    Related issues you referenced, all now closed:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions