hermes - 💡(How to fix) Fix hermes skills install URL source only downloads SKILL.md, misses reference files (references/, templates/, scripts/) [3 pull requests]

Summary

When installing a multi-file skill via direct URL (e.g. hermes skills install https://raw.githubusercontent.com/.../SKILL.md), only the SKILL.md file is downloaded. Supporting files in references/, templates/, and scripts/ directories are not fetched.

For example, installing supabase-postgres-best-practices (a supabase/agent-skills skill with 30+ reference rule files) only places SKILL.md — all 34 rule files under references/ are silently skipped.

Root Cause

The issue has two components:

1. UrlSource.fetch hardcodes single-file download (primary cause)

In tools/skills_hub.py:UrlSource.fetch (line 1148-1155):

return SkillBundle(
    name=skill_name,
    files={"SKILL.md": text},  # <-- only SKILL.md
    source="url",
    ...
)

The docstring at line 1052-1055 explicitly acknowledges this limitation:

Only single-file skills are supported — multi-file skills with references/ or scripts/ subfolders need a manifest we can't discover from a bare URL.

However, when the URL is a raw.githubusercontent.com URL (which is the common case for users installing from GitHub repos), the URL could be intelligently parsed to extract the owner/repo/branch/path and delegated to GitHubSource.fetch, which uses _download_directory to recursively download ALL files including references/.

2. Short name resolution timeout prevented alternative routing

Attempting hermes skills install supabase-postgres-best-practices (short name without URL) timed out because _resolve_short_name → unified_search searches all sources in parallel with a timeout. The skills.sh API and GitHub API calls can take 20-30s each, and on a device with limited network (SBC/ARM) this easily times out before finding the skill via SkillsShSource.

If SkillsShSource had been used, its fetch method (line 1294) delegates to GitHubSource.fetch, which recursively downloads the full directory — all 30+ reference files.

Impact

• Skills from GitHub repos installed via URL lose their supporting reference files
• Users must manually download references/ after install (as I had to)
• Skills with templates/ or scripts/ are similarly broken
• The hermes skills install UX reports success with misleading Files: SKILL.md output, giving no indication that files are missing

Proposed Fix

Option A (recommended): Parse raw.githubusercontent.com URLs and route to GitHubSource

In UrlSource.fetch or in the installer's _resolve_source_meta_and_bundle, detect URLs matching the pattern: https://raw.githubusercontent.com/{owner}/{repo}/{branch}/{path}/SKILL.md

Extract {owner}/{repo}/{path} and call GitHubSource.fetch(\"{owner}/{repo}/{path}\") instead, which recursively downloads the entire skill directory including all subdirectories.

# Pseudo-code
RAW_GITHUB_RE = re.compile(
    r'^https://raw\\.githubusercontent\\.com/(?P<owner>[^/]+)/(?P<repo>[^/]+)/[^/]+/(?P<path>.+)/SKILL\\.md$'
)

Option B: Post-download discovery in UrlSource

After downloading SKILL.md, parse it for linked file references (e.g. references/, templates/ paths) and attempt to discover those files relative to the SKILL.md URL. More fragile but doesn't require GitHub API access.

Steps to Reproduce

1. Run hermes skills install https://raw.githubusercontent.com/supabase/agent-skills/main/skills/supabase-postgres-best-practices/SKILL.md --name supabase-postgres-best-practices
2. Check ~/.hermes/skills/supabase-postgres-best-practices/
3. Observe: only SKILL.md exists, no references/ directory

Expected Behavior

All files from the skill directory should be downloaded:

~/.hermes/skills/supabase-postgres-best-practices/
├── SKILL.md
├── references/
│   ├── query-missing-indexes.md
│   ├── query-partial-indexes.md
│   ├── conn-pooling.md
│   ├── security-rls-basics.md
│   ├── data-n-plus-one.md
│   ├── ... (30+ files)

Environment

• Hermes Agent (latest)
• Linux ARM64 (Rockchip SBC)
• Network: domestic China (may have slower API response times) --label 'bug' --label 'skills-hub'