English | 简体中文

npx-skill-install

Install agent skills once and have every AI coding agent see them — via a shared skills hub.

npx skills can install a skill into many agents — Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode — each with its own skills directory. Doing that per agent is wasteful and drifts out of sync. npx-skill-install is an agent skill that automates the smarter pattern: keep one real hub directory of skills and symlink every agent's skills folder to it, so a single install reaches them all.

It bundles a one-shot diagnostic and a safe symlink setup script, plus a SKILL.md that teaches an agent the full check → (link) → install → verify workflow.

Why a hub?

Without a hub                          With a hub
─────────────                          ──────────
~/.claude/skills/  (copy A)            ~/.claude/skills   ─┐
~/.codex/skills/   (copy B)            ~/.codex/skills    ─┤
~/.cursor/skills/  (copy C)            ~/.cursor/skills   ─┼─►  ~/.agents/skills  (one real dir)
~/.gemini/skills/  (copy D)            ~/.gemini/skills   ─┤
~/.copilot/skills/ (copy E)            ~/.copilot/skills  ─┘
   install 5×, update 5×                  install once, update once

When every agent's skills directory is a symlink to one hub (conventionally ~/.agents/skills), installing a skill lands in the hub and is instantly visible to all of them.

Quick start

This is an agent skill — it is meant to be installed where your AI coding agent can discover it, then triggered by natural language. You can also run the bundled scripts directly.

Install the skill

# From a skills registry/repo with npx skills:
npx -y skills add OpenGHz/npx-skill-install -s npx-skill-install -g -y

# …or symlink the skill folder into your hub manually:
ln -s "$(pwd)/npx-skill-install" "$HOME/.agents/skills/npx-skill-install"

Use it

Just ask your agent, e.g.:

"Install the baoyu-translate skill for all my agents."

The skill will run the check, offer to set up symlinks if needed, then install once.

Run the scripts directly

# 1. One-shot diagnostic: what's installed + do agent dirs share one hub?
bash npx-skill-install/scripts/check-skills-setup.sh <skill-name>

# 2. Preview converging every agent's skills dir onto the hub:
bash npx-skill-install/scripts/setup-symlinks.sh --dry-run

# 3. Apply it (non-destructive; backs up real dirs first):
bash npx-skill-install/scripts/setup-symlinks.sh

How it works

1. Check (one shot). check-skills-setup.sh reads npx skills list -g --json to report installed skills, and resolves each agent's skills directory with readlink -f to decide whether they all converge on a single hub. It prints a machine-readable SUMMARY block (CONVERGED=yes|no, HUB=..., per-skill installed status).
2. Link (optional, recommended). If the directories don't converge, setup-symlinks.sh converges them onto the hub. Real directories are merged into the hub (no overwrite) and moved aside to a timestamped .backup-* before the symlink replaces them — nothing is deleted.
3. Install. Converged → install once (-a "<one agent>"); not converged → install to every agent (-a '*').
4. Verify. Re-run the check to confirm the skill now shows up for all agents.

See npx-skill-install/SKILL.md for the full workflow the agent follows.

Project structure

npx-skill-install/                 # repo root
├── npx-skill-install/             # the installable skill
│   ├── SKILL.md                   # workflow + triggering metadata
│   └── scripts/
│       ├── check-skills-setup.sh  # read-only diagnostic (installed + convergence)
│       └── setup-symlinks.sh      # converge agent dirs onto the hub (safe)
├── README.md
├── README.zh-CN.md
├── LICENSE
└── …community & hygiene files

Requirements

• bash, node/npx (the skills CLI is fetched on first use and cached).
• Works at user/global scope by default (-g); project scope is supported too.

Safety

• check-skills-setup.sh never modifies anything.
• setup-symlinks.sh never deletes data: real directories are copied into the hub without overwriting and backed up to <dir>.backup-<timestamp> before linking.
• Default hub is ~/.agents/skills; override with --hub <path>.

Contributing

Issues and PRs are welcome — see CONTRIBUTING.md and our Code of Conduct. For security reports, see SECURITY.md.

License

MIT © 2026 OpenGHz