Connections Guide
Connect your dev environment to your team’s SkillRepo library. The skillrepo CLI is the only tool you need:
npx skillrepo initOne command validates your access key, detects your dev environment, and pulls your library to disk so your agent can activate skills locally with no per-activation network round-trip. New team members typically don’t run this by hand — the team-invite email walks them through it automatically when they accept.
On this page
How It Works
The skillrepo CLI keeps a local copy of your library on disk where your dev environment expects it. Your agent reads those files directly during a session — no per-activation network call to render a skill. Run npx skillrepo init once to wire it up, then skillrepo update (or the optional SessionStart hooks init installs into Claude Code, Cursor, Gemini CLI, Codex CLI, and VS Code + Copilot) to keep the on-disk copy current.
Local library sync
Your library — the set of skills you've subscribed to — is pulled to disk so your agent can activate them without hitting the network for the SKILL.md body. The CLI writes to one of two project paths depending on the agent: Claude Code reads from .claude/skills/<name>/; Cursor, Windsurf, Gemini CLI, Codex CLI, Cline, and GitHub Copilot all read from the shared .agents/skills/<name>/ path. Both paths are added to your .gitignore on first run — skills are a per-developer cache, not committed content. Run skillrepo update periodically to pull new versions, or use add/remove to change what's in your library. See Supported agents for the full path matrix.
Supported agents
skillrepo init writes skills to one of two project paths depending on the agent. Six of the seven supported agents share .agents/skills/, so a single cohort write reaches every cohort agent — no duplication. Both paths are gitignored automatically; skills are a per-developer cache, not committed content.
| Agent | Project skill path | Personal (--global) path | Auto-refresh today |
|---|---|---|---|
| Claude Code | .claude/skills/<name>/ | ~/.claude/skills/<name>/ | Yes — SessionStart hook installed by init |
| Cursor | .agents/skills/<name>/ | ~/.agents/skills/<name>/ | Yes — SessionStart hook installed by init |
| Windsurf | .agents/skills/<name>/ | ~/.codeium/windsurf/skills/<name>/ | Manual skillrepo update |
| Gemini CLI | .agents/skills/<name>/ | ~/.agents/skills/<name>/ | Yes — SessionStart hook installed by init |
| Codex CLI | .agents/skills/<name>/ | ~/.agents/skills/<name>/ | Yes — SessionStart hook installed by init |
| Cline | .agents/skills/<name>/ | ~/.agents/skills/<name>/ | Manual skillrepo update |
| GitHub Copilot | .agents/skills/<name>/ | — | Yes — SessionStart hook installed by init |
Cohort dedupe
Cursor, Windsurf, Gemini CLI, Codex CLI, Cline, and GitHub Copilot all share .agents/skills/<name>/ for project-scope writes. Six agents resolve to a single write — no per-vendor duplication on disk. Use--agent claude, --agent agents, or --agent claude,agents to override detection. --agent none writes config and gitignore but skips placement entirely.
Auto-refresh hooks per agent
For five of the seven supported agents, init installs a user-scope SessionStart hook so skillrepo update runs automatically when you open a new agent session — no need to remember to sync by hand. The cohort hook command is npx --yes skillrepo update --silent; Claude Code uses an older mechanism that calls the installed binary by absolute path. Pass --no-session-sync to skip every hook install in a single run, or see the CLI Reference for the full per-vendor matrix (config paths, event-name casing, and JSON schemas).
| Agent | Hook config path | Per-vendor note |
|---|---|---|
| Claude Code | .claude/settings.local.json (project) or ~/.claude/settings.local.json (--global) | Legacy mechanism — runs your installed skillrepo binary by absolute path with a POSIX || true backstop. Toggle with the dedicated session-sync command. |
| Cursor | ~/.cursor/hooks.json | sessionStart event (lowercase), timeout: 60 seconds. Multi-tool merge surface (1Password, Snyk, Apiiro extend the same file); unknown keys preserved on every write. |
| Gemini CLI | ~/.gemini/settings.json | SessionStart event (uppercase), timeout: 60000 milliseconds — distinct from every other vendor. Group requires matcher: “*” or Gemini silently skips it; entry id is skillrepo-update. |
| Codex CLI | ~/.codex/hooks.json | SessionStart event (uppercase), timeout: 60 seconds. Codex also reads a [hooks] table from ~/.codex/config.toml — Codex merges both at runtime, so a hand-written TOML entry coexists with our JSON. |
| VS Code + CopilotPreview | ~/.copilot/hooks/skillrepo-update.json | sessionStart event (lowercase), timeout: 60 seconds. Per-tool single file (not a shared multi-tool surface). GitHub currently labels Copilot's hook system as Preview — the schema may shift before GA. |
| Windsurf | — | Not supported. No documented SessionStart-equivalent event in Windsurf docs as of 2026-05. Run skillrepo update manually. |
| Cline | — | Not supported. Cline uses per-task hooks (TaskStart / TaskEnd) and stores configs at a non-standard global path. Run skillrepo update manually. |
Unit tip when copying snippets between vendors: Gemini CLI's timeout is in milliseconds; Cursor, Codex CLI, and VS Code + Copilot all use seconds. The values look interchangeable but a 60 that means a minute on one vendor means 60 milliseconds on Gemini — check the unit before hand-editing a hook entry.
Cloud agent runners do not see these hooks or skill files
Both the skill placement paths and every hook config file above live under the developer's $HOME or under gitignored project directories — so cloud-hosted runners (GitHub Codespaces, GitHub-hosted Copilot agents, cloud-Cursor sessions) cannot read them. Auto-refresh and on-disk skills are local-developer only; cloud runners always rely on whatever pre-warmed library shipped in the image. The local integrations in VS Code, Cursor, and the desktop CLIs read skills correctly. Document this if your team relies on cloud agents for production work.
CLI command reference
The skillrepo CLI ships seven commands. All commands read credentials from ~/.claude/skillrepo/config.json, the SKILLREPO_ACCESS_KEY environment variable, or the --key flag — in that order. See the full CLI Reference for every flag, exit-code, and retry detail.
| Command | What it does |
|---|---|
skillrepo init | First-run setup. Validates your access key, auto-detects your agent, and pulls your library. Idempotent — safe to re-run. Use --force to rotate credentials or --agent claude / --agent agents to bypass detection. |
skillrepo update | Sync your library against the registry. Uses delta sync (ETag + since filter) so repeat runs are cheap. Handles tombstones — skills removed from the library are deleted locally. |
skillrepo get @owner/name | Fetch a single skill by identifier. Does NOT mutate your library — pure read + local write. Useful for previewing a skill before adding it. |
skillrepo add @owner/name | Add a skill to your library and pull it locally. Requires a write-scoped access key. Idempotent — adding an already-present skill re-fetches the current version. |
skillrepo remove @owner/name | Remove a skill from your library and delete the local directory. Requires a write-scoped access key. |
skillrepo list | Render your library as a table. Pass --json for machine-readable output. |
skillrepo search <query> | Search the public registry by keyword. Use --limit to cap results and --json for scripting. |
Every command supports --help (per-command options), --verbose (stack traces on error, including retry attempts), --global (target the personal-scope path — ~/.claude/skills/ for Claude Code or ~/.agents/skills/ for the cohort — instead of the project), and --json (structured output).
Read-only commands (init, update, get, list, search) automatically retry transient server failures (429, 502, 503, 504, and network errors) with exponential backoff. Write commands (add, remove) are single-shot to keep behavior predictable.
Team Setup
RecommendedEach engineer connects their own dev environment with their own access key. The team-invite email walks new members through npx skillrepo init automatically when they accept; admins don't need to send a separate snippet.
The Team page is where admins send invitations. The Connect page is where each engineer mints (or rotates) their own access key — one active key per user.
Prerequisites
- A SkillRepo account on the Team plan
- Owner or admin role to send invitations
- Each engineer needs their own access key (auto-minted on invite acceptance, or self-minted at Connect)
Send team invitations
As an owner or admin, open the Team page and invite each engineer by email. The invitation email includes the team name, the inviter, the assigned role, and a paragraph that explains how to run npx skillrepo init after accepting.
Each engineer accepts and runs npx skillrepo init
After clicking the accept link and signing in, each engineer is taken to the dashboard. They open a terminal in their project root and run:
npx skillrepo initinit validates the access key, detects the engineer's dev environment, pulls the team's library to disk, and (in Claude Code) installs the SessionStart hook so future sessions auto-sync. The access key is written to ~/.claude/skillrepo/config.json (chmod 0600 on POSIX) and to .env.local (gitignored on first run).
For a non-interactive setup (e.g. a workspace bootstrap script), pass the key directly:
npx skillrepo init --key sk_live_abc123 --yes--yes skips every confirmation prompt.
Keeping everyone’s library current
Each engineer runs skillrepo update to pull the latest state of the library. The sync uses ETag caching so repeat runs are cheap — a no-op update returns 304 Not Modified and touches no files. In Claude Code, the SessionStart hook installed during init handles this automatically on every new session.
When you want to add or remove specific skills from the library, use skillrepo add @owner/name and skillrepo remove @owner/name. Both require a write-scoped access key (admin role) and update the registry, not just the local copy.
What to gitignore
The CLI manages the gitignore entries automatically on first run. Each engineer's access key lives in their local ~/.claude/skillrepo/config.json and .env.local — never commit either. The two project-scoped skill paths (.claude/skills/ for Claude Code and .agents/skills/ for the cohort — Cursor, Windsurf, Gemini CLI, Codex CLI, Cline, GitHub Copilot) are added to .gitignore too, so each engineer pulls their own library via skillrepo update rather than fighting merge noise on every version bump.
Enterprise Setup
Org-scale deploymentsFor organizations that manage developer tooling centrally, IT can pre-provision the skillrepo CLI and the SKILLREPO_ACCESS_KEY environment variable through their existing tooling (MDM, configuration management, dotfiles repositories) so engineers don't have to set anything up by hand.
Per-engineer access keys
Each engineer should have their own access key, not a shared one. SkillRepo enforces a one-active-key-per-user limit on every plan tier so audit logs always attribute each request to a specific person. Issue keys via the Connect page (each user mints their own) or via the team-invite email flow (auto-minted on acceptance). When IT pushes the SKILLREPO_ACCESS_KEY env var to a managed machine, push the engineer's key — not a shared one.
Talk to sales
Best fit for teams on the Team plan. Volume, contract, or self-hosted needs are handled through sales@skillrepo.dev.
Per-Developer Setup
If you’re setting up SkillRepo for yourself rather than a team, or want to add it to a personal project, follow these steps.
- 1
Run
npx skillrepo initRun the setup command from your project directory. It will prompt for your access key if one is not already set. If you do not have a key yet, create one at Connect. See the Getting Started guide for details.
npx skillrepo initThe CLI auto-detects your dev environment, writes the access key to
.env.local, and pulls your library to disk. For Claude Code, files land in.claude/skills/<name>/and the SessionStart hook is offered to keep things current. - 2
Done — start using skills
Your agent can now activate skills from the on-disk library. Activations are instantaneous — no per-skill network round-trip — and the local copy stays current as long as you run
skillrepo update(or the optional SessionStart hook does it for you in Claude Code).
Manual setup (if you cannot use npx)
If npx is not available on this machine, install the CLI globally with npm install -g skillrepo and run the same command:
- Create an access key at Connect
- Run
skillrepo initfrom your project root - Run
skillrepo updateany time you want to pull new versions
FAQ
Does each team member need their own access key?
Yes. SkillRepo enforces one active access key per user, so every engineer mints their own. The key lives in the engineer's local ~/.claude/skillrepo/config.json and .env.local, both of which are gitignored by the CLI. Per-user keys are also what makes the audit log useful — every request is attributed to a specific person.
I hit my access-key quota. What now?
The Connect page surfaces a Rotate key CTA when you're at the limit. Rotating revokes your oldest active key and mints a new one in the same transaction — useful when you've lost an old key or want to invalidate one without a separate revoke step. See Access Keys in a Team for the full flow. CLI users running with --key directly will see a quota_exceeded error and need to rotate or revoke through the dashboard.
What if I add new skills to the library?
Run skillrepo update to pull the latest state of your library. The sync is delta-based, so if you added one skill, only that skill's files are written. Removed skills (tombstones from the server) are deleted locally on the next update. If you want to add a specific skill to your library, use skillrepo add @owner/name instead of re-running init.
Does the CLI work with my agent?
npx skillrepo init auto-detects every installed agent and writes skills to the path that agent reads natively. Claude Code lands at .claude/skills/<name>/; Cursor, Windsurf, Gemini CLI, Codex CLI, Cline, and GitHub Copilot all share .agents/skills/<name>/. See Supported agents for the full matrix. Auto-refresh on session start is shipped for Claude Code today; for other agents, run skillrepo update manually to pull library changes.
What should I commit vs. gitignore?
Gitignore .env.local (contains your access key) and the two skill directories the CLI writes to — .claude/skills/ for Claude Code and .agents/skills/ for the cohort (Cursor, Windsurf, Gemini CLI, Codex CLI, Cline, GitHub Copilot). Each engineer pulls their own library via skillrepo update, so committing the synced content would produce merge noise on every version bump. The CLI manages the gitignore entries automatically on first run.
Next steps
Browse the full CLI command set, dig into the public REST API, or learn how to publish your own skills.