[idea] ship SKILL.md in skills/herdr/ so npx skills add doesn't vendor the whole repo

[Azd325]

idea / problem

installing the herdr agent skill via npx skills add ogulcancelik/herdr (the command shown on skills.sh) copies the
entire repo into the consumer's skill directory, not just the skill.

the skills CLI vendors the directory that contains SKILL.md. per its docs, the first discovery location is "Root directory
(if it contains SKILL.md)":
https://github.com/vercel-labs/skills#skill-discovery

herdr keeps SKILL.md at the repo root, so "the skill" = the whole repo. a fresh add pulls ~1689 files / ~33 MB (Rust src/,
vendor/libghostty-vt, website/assets/*.mp4, Cargo.lock, .github/, tests/) when the actual skill is a single
self-contained SKILL.md (~12 KB). vendoring it into a dotfiles/config repo drags the full app source into git history; the
only workaround is deleting everything except SKILL.md after install. (--full-depth only widens discovery — nothing
narrows a root match.)

requested change

move the skill into its own folder so the CLI only pulls the skill:

skills/herdr/SKILL.md

optionally keep a root ./SKILL.md shim/symlink so existing README links still resolve. then npx skills add ogulcancelik/herdr@herdr vendors ~12 KB instead of ~33 MB — matching the documented flat layout skills//SKILL.md
and how packaged skills lay themselves out (e.g. pulumi/agent-skills, firecrawl/*).

why you want this

makes the published skill installable via the documented npx skills add path without pulling the whole codebase

[yuu-no]

+1 — there is a second reason for this layout now: the GitHub CLI's new skill manager (gh skill, preview) cannot discover a root-level SKILL.md at all:

$ gh skill install ogulcancelik/herdr
no standard skills found, but 3 skill(s) exist in hidden directories

It only discovers skills/*/SKILL.md and */SKILL.md layouts, and gh skill update uses the same rules, so the skill currently cannot be installed or tracked with gh. Moving it to skills/herdr/SKILL.md fixes both this and the vendoring issue above.

One caveat on the root shim idea: a symlink likely will not work for API-based installers (the contents API returns the link target as the blob content), so a synced copy would be safer if the root file stays.

[yuu-no]

maybe resolved #2022

[JasonLandbridge]

Consider using this: https://github.com/runkids/skillshare

Works much better than npx skills

[mlvnd]

Another approach that could complement (or replace) the folder move: bundle the SKILL.md into the binary and expose it as a CLI command, similar to how herdr completion zsh works.

herdr skill > ~/.config/pi/agent/skills/herdr/SKILL.md

Benefits:

• Always matches the installed binary version, not whatever master happens to be
• No dependency on the repo or npx, works offline once Herdr is installed
• Trivially small embed (~10KB)
• Pairs well with the folder move too: just include_str!("skills/herdr/SKILL.md")

This doesn't replace moving SKILL.md into a subfolder, that fix still matters for tooling like npx skills add. But herdr skill gives users and agents a zero-friction fallback that's guaranteed to match their binary.

[mlvnd]

I put together a working prototype on the skill-cli-command branch of my fork. About 3 files, 40 lines. Embeds SKILL.md via include_str!() and prints it with herdr skill. Happy to open a PR if this direction seems right.

[johannesamee]

One more consequence of the root layout, not mentioned above: it also makes the skill report a phantom update on every commit.

npx skills records a skillFolderHash for the folder containing SKILL.md. With SKILL.md at the root that folder is the repo, and the CLI falls back to the whole-tree sha:

// skills/dist/cli.mjs — getSkillFolderHashFromTree
if (!folderPath) return tree.sha;   // root SKILL.md → repo-wide sha

So the tracked "skill version" is herdr's HEAD on master. Any commit — Rust, website, CI — flips it, and npx skills update re-clones and re-copies the repo to land a byte-identical SKILL.md. As of today there are 61 commits on master since SKILL.md last changed (0f161fa, Jul 21), none of them touching it.

For anyone updating skills on a schedule (topgrade's skills step, here) herdr is the only entry out of 44 installed skills that reports an update on essentially every run — the other 43 all use skills/<name>/SKILL.md and stay quiet until their own folder changes.

Moving to skills/herdr/SKILL.md scopes the hash to that folder's subtree sha, which fixes this alongside the vendoring size and gh skill discoverability already raised.

[marcoscale98]

Confirming the same issue today: npx skills add ogulcancelik/herdr --copy pulled the full repo (~41 MB, Cargo.lock/vendor/website/src/tests) into a private dotfiles repo instead of just SKILL.md (~12 KB). Also confirms the phantom-update behavior noted above — the skill showed up outside skills-lock.json entirely rather than tracking a stable hash, consistent with the root-level sha fallback described in the comments. Moving to skills/herdr/SKILL.md would fix this for us too.