skills tap add accepts custom git repos that search/install cannot actually use

[ma-pony]

Problem

hermes skills tap add <repo> is documented as a way to add a custom repository as a skill source, but the current implementation only works for GitHub repos addressable through the GitHub Contents API.

In practice, adding a non-GitHub custom Git repository (for example a private/self-hosted Git server over SSH) is accepted by tap add, but skills search, skills inspect, and skills install cannot resolve anything from that tap.

Reproduction

Repository used:

• git@git.rccchina.com:crawl/spider-skills.git

The repository is reachable over SSH and contains valid skill directories such as:

• skills/spider-kit/SKILL.md
• skills/crawl-config/SKILL.md
• skills/crawl-troubleshoot/SKILL.md

However:

hermes skills tap add git@git.rccchina.com:crawl/spider-skills.git
hermes skills search spider-kit
# No skills found matching your query.

hermes skills inspect git@git.rccchina.com:crawl/spider-skills.git/skills/spider-kit
# Error: Could not find ... in any source.

Root cause

From the current implementation in tools/skills_hub.py:

• TapsManager.add() stores arbitrary {repo, path} values in taps.json
• but GitHubSource later assumes taps are GitHub repos in owner/repo form
• search/listing uses https://api.github.com/repos/{repo}/contents/{path}
• inspect/fetch identifiers are parsed as owner/repo/path/to/skill-dir

So tap add currently accepts a broader input surface than the backend actually supports.

Expected behavior

One of these should happen:

1. Minimal fix:

   • validate tap add input and clearly restrict it to GitHub/GitHub Enterprise repos that the backend can actually resolve
   • document that self-hosted/non-GitHub Git repos are not supported

2. Better fix:

   • support generic git-based taps, including SSH/private repositories
   • allow search/inspect/install by cloning or updating a local cache and scanning skills/*/SKILL.md
   • make tap/search/install work consistently for custom git repositories, not only GitHub API-backed repos

Why this matters

The current UX is misleading: tap add succeeds, but the tap is unusable unless the repo happens to match GitHub API assumptions.

This makes Hermes difficult to adopt in internal/company environments where skills are stored in private Git servers rather than public GitHub repos.

[Osraka]

Hi, I’d like to work on the minimal validation path for this.

My understanding is that taps are currently resolved through GitHubSource using the GitHub Contents API, so hermes skills tap add should reject non-owner/repo inputs instead of persisting taps that search, inspect, and install cannot resolve.

I’d keep the PR small:

• validate tap repo input before writing taps.json
• keep existing tap loading/removal behavior for already-written configs
• surface a clear CLI error for SSH/self-hosted Git URLs
• add regression tests for invalid SSH/non-GitHub inputs and valid owner/repo taps

Does that direction match what you’d prefer, or would you rather keep tap add permissive until generic git-backed tap support exists?

[g-radam]

Bumped into this issue today. Submitted a PR here which adds support for Git based sources. Requires the "repo" to have a .git postfix. This is a blocker for me so I'd personally prefer this PR over defaulting to an error. I think the error code can be patched ontop.

[GottZ]

This was generated by AI during triage.

Summary

Two PRs address #14290 through the same minimal compatibility fix: both normalize supported GitHub tap inputs, reject self-hosted or generic Git repositories before persistence, and surface the validation error in the CLI rather than adding generic-git support. Neither implements the clone/cache/index backend required to make non-GitHub taps searchable or installable.

Related pull requests

• fix(skills): reject unsupported tap repositories #14299 partial — (+62/-2) — partial fix: Validates and canonicalizes GitHub-backed taps and rejects the unusable self-hosted input reported in skills tap add accepts custom git repos that search/install cannot actually use #14290, but its diff leaves canonicalized taps inconsistent with exact-match removal and introduces an unhandled failure path for legacy invalid taps during snapshot import. The keep_open review on fix(skills): reject unsupported tap repositories #14299 correctly requires normalized removal with a legacy raw fallback plus per-entry snapshot-import error handling and regression tests.
• fix(skills): reject unsupported custom taps #14416 best fix — (+75/-2) — best partial fix: Implements the same focused GitHub-only validation at the tap manager and CLI boundaries with clearer actionable messaging, directly preventing the misleading successful add from skills tap add accepts custom git repos that search/install cannot actually use #14290. Consistent with the keep_open review on fix(skills): reject unsupported custom taps #14416, it should remain open until removal applies the same normalization with a raw-value fallback for legacy entries and an add-by-URL/remove-by-same-URL regression test.

Duplicates

#14299 and #14416 are substantive duplicates: both canonicalize GitHub repository forms to owner/repo, reject generic/self-hosted Git URLs, catch the resulting validation error in the CLI, and add closely overlapping tests.

Suggested consolidation

Merge #14416 after addressing its keep_open review by normalizing removal, retaining a raw fallback for legacy tap entries, and adding the requested regression coverage; it is the selected best fix and has the narrower remaining repair surface. Close #14299 as a duplicate of #14416 rather than merging it, since its overlapping diff also adds the unresolved snapshot-import failure path identified by the contributor review.

Complex graph

flowchart LR
    classDef open fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a
    classDef merged fill:#dcfce7,stroke:#15803d,color:#14532d
    classDef closed fill:#e5e7eb,stroke:#6b7280,color:#1f2937
    classDef unverified fill:#f3f4f6,stroke:#9ca3af,color:#374151
    classDef best stroke-width:3px,stroke:#b45309
    classDef target stroke-width:3px,stroke:#4338ca
    I14290(["issue #14290 (open)"])
    subgraph Dup14299 ["PRs duplicating each other"]
        P14299["PR #14299 (open)"]
        P14416["PR #14416 (open)"]
    end
    P14299 -.->|partial| I14290
    P14416 -->|best fix| I14290
    class I14290 open
    class I14290 target
    class P14299 open
    class P14416 open
    class P14416 best
    click I14290 "https://github.com/NousResearch/hermes-agent/issues/14290"
    click P14299 "https://github.com/NousResearch/hermes-agent/pull/14299"
    click P14416 "https://github.com/NousResearch/hermes-agent/pull/14416"

Loading

Graph: solid arrow = fixes / best fix, dashed arrow = partial or unverified (see edge label); boxed group = PRs duplicating each other; amber border = best fix; indigo border = target; gray node = closed or no verify verdict yet (state tag in the node label).

Cross-PR triage: Reviewed 2 pull requests and 1 issue in this complex. Each diff was read against this issue; Assessment working set: 11 kB of PR diffs, 5 kB of issue/PR text, 3 kB of discussion (5 comments), 4 verify verdicts. verdicts reflect diff content, not PR titles. Part of an automated triage batch.