Agent Skills: a one-skill install quietly leaves the shared references/ directory behind

A one-skill install copies skills/<name>/ and leaves references/ on the floor

The most important warning in the file is a blockquote about the per-skill path. A per-skill npx install copies only skills/<name>/, not the repo-level references/ directory. The skill still works, but paths to supplementary shared checklists are unavailable. Three fixes are offered: use a whole-repo integration, clone the repository, or copy the needed checklist into a references/ directory inside the installed skill. The gap is filed as issue 361.

npx skills add addyosmani/agent-skills --skill code-review-and-quality   # five-axis review before merge

Consequence for a reader: there is no error, no warning at load time, and no failure you would notice until the agent follows a path into a directory that was never copied. The skill looks installed and behaves as though the checklist it names is there, which is the worst shape for a quality gate, since the thing you installed to raise the bar is the thing quietly missing.

The fix for one plugin's SSH error rewrites Git URLs for every repository

The Claude Code section is the longest install section in the file, and two thirds of it is about transport. The marketplace clones repos via SSH, so a user without keys on GitHub is told to add a key or force HTTPS by passing the full clone URL.

/plugin marketplace add https://github.com/addyosmani/agent-skills.git
/plugin install agent-skills@addy-agent-skills

If /plugin install still fails with [email protected]: Permission denied (publickey) on Windows or macOS, the recommended workaround is to configure Git once, for subprocess clones, to rewrite GitHub SSH URLs to HTTPS.

git config --global url."https://github.com/".insteadOf [email protected]:

Consequence: a problem scoped to one plugin marketplace is fixed with a machine-wide setting that applies to every repository you clone, SSH or not. The visible text gives no way to scope it to this repository, and no way to undo it other than removing the global config key yourself.

The lifecycle diagram has six boxes and the command table has nine rows

The picture at the top of the README runs DEFINE, PLAN, BUILD, VERIFY, REVIEW, SHIP, with /spec, /plan, /build, /test, /review and /ship under the boxes. The table below it lists nine commands, and three of them have no box: /constraints, /webperf and /code-simplify. Their principles also do different work from the pipeline stages. /test is Tests are proof, while /constraints is Decide it once, enforce it everywhere, which is a bar you set rather than a step you pass through. /webperf is Measure before you optimize and /code-simplify is Clarity over cleverness. Consequence: the diagram is the memorable part and the table is the truth, so anyone who plans their process from the picture will quietly drop the quality bar command and the two maintenance commands.

Auto activation has no list and no off switch in the visible text

There are two ways a skill fires, and only one of them is a command you type. Skills also activate automatically based on what you are doing, and two triggers are given by name: designing an API triggers api-and-interface-design, and building UI triggers frontend-ui-engineering. The list ends with and so on. That is the whole enumeration. The visible text does not give the full trigger mapping, does not say which of the 25 skills can auto-activate, and does not say how to turn automatic activation off for a skill you did not want invoked. Consequence: with 25 skills in the repository and 9 commands on top, you cannot tell from this file which of them are dormant until the right task appears, and you have no documented way to pin a skill to explicit invocation only.

/build auto trades nine approvals for one, and does not say what risky means

The escape hatch from the manual loop is a single word appended to a command.

/build auto

It generates the plan and implements every task in a single approved pass, so you approve the plan once and then it runs autonomously. The claim about what is preserved is specific and worth reading closely: it removes the human stepping between tasks, not the verification, and every task is still test-driven and committed individually. It also pauses on failures or risky steps. Consequence for a reader: the approval granularity moves from the task to the plan, so a plan with twenty tasks gets one human decision instead of twenty, and the only thing standing between an approved plan and a long autonomous run is a pause condition. The visible text does not define which steps count as risky, so what that pause catches is not something you can predict or tune from here.

On affected Antigravity releases the commands convert but the wrappers stay invisible

The Antigravity CLI entry carries a compatibility caveat that no other section in the file has. In affected Antigravity CLI releases, legacy command TOMLs are reported as converted but their wrapper commands are not discoverable, and the instruction is to invoke the underlying namespaced skills directly. The install itself is a single command.

agy plugin install https://github.com/addyosmani/agent-skills.git

Consequence: the whole point of the 9 command table, the /spec through /ship lifecycle with a named principle attached to each stage, is unavailable as a command surface on those releases. The conversion report is the trap, because it says the command files were handled. You would be typing namespaced skill names instead, which means the principles in that table are still in the skills but no longer attached to a step you can invoke by name, and you have to know the namespace layout yourself.

Four of the named agents have no install command, only file copies to maintain

The quick start advertises the open skills CLI installing into 70+ agents in one command, but the per-agent sections that follow are not uniform. Cursor has no command at all: put workflow skills under .cursor/skills/ and sync from agent-skills/skills/, put short policies in .cursor/rules/*.mdc, and the file explicitly says do not paste full skills into rules. Windsurf has no command either, only add skill contents to your Windsurf rules configuration. OpenCode is copy skills to .opencode/skills/ or ~/.config/opencode/skills/, add a project-local AGENTS.md, and optionally add slash commands under .opencode/commands/. Copilot is the tightest fit, since agent definitions from agents/ become personas and skill content goes into a single .github/copilot-instructions.md. Consequence: the one command is the exception, not the rule, and a Cursor or Windsurf user ends up with a manually synced copy that goes stale the next time the repository changes.

Editorial conclusion

Agent Skills is a reasonable choice if you want a written engineering process your agent can be held to, and you are willing to install it whole rather than a piece at a time. Prefer the whole-repo or clone route, because the per-skill path is the one that loses the shared checklists. Do not expect one install command to cover every agent, since the Cursor, Windsurf, OpenCode and Copilot paths are file copies you maintain yourself. Before adopting it, read docs for your own agent, check the 9 commands land as discoverable wrappers rather than converted files, and confirm you can keep the version pinned rather than tracking a moving tag.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes