You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: improve skills-manager skill with troubleshooting, auth recovery, and tighter description
- Add troubleshooting section with 6 error-to-fix pairs (push rejected, rebase
conflict, no skills found, unknown agents, auth failure, not a git repo)
- Add scope boundary clarifying this tool doesn't install skills
- Add quick reference table and installation fallback instructions
- Document first-time behavior and possible outcomes for push/pull
- Highlight non-interactive flags for AI agent automation
- Add re-link-after-install workflow
- Trim description to improve trigger accuracy while keeping all key phrases
@@ -7,13 +7,21 @@ description: Manage AI agent skills backup and sync via the skills-manager CLI.
7
7
8
8
CLI companion to [vercel-labs/skills](https://github.com/vercel-labs/skills) — backup, restore, and symlink AI agent skills via GitHub.
9
9
10
-
## Invocation
10
+
> **Scope boundary:** This tool backs up and syncs skills you already have. It does NOT install new skills from the registry — that's `npx skills add`. If the user wants to install a new skill, point them to `npx skills add <repo>` instead.
11
+
12
+
## Quick Reference
13
+
14
+
| Goal | Command |
15
+
|------|---------|
16
+
| Backup skills to GitHub |`sm push`|
17
+
| Restore skills on new machine |`sm pull --repo owner/name`|
Auth is **optional** — if git already has credentials (SSH keys, macOS Keychain, etc.), push/pull work without setup.
51
+
Auth is **optional**. If git already has credentials configured (SSH keys, macOS Keychain, credential manager, etc.), push/pull work without any extra setup.
38
52
39
-
When git cannot authenticate, the CLI tries these sources in order:
53
+
When git cannot authenticate on its own, the CLI looks for a token in this order:
If none are found, git attempts the operation without a token — this works for public repos but fails for private ones.
60
+
61
+
**The `link` command never requires authentication.**
48
62
49
-
`link` never requires authentication.
63
+
### Fixing Auth Failures
64
+
65
+
If push/pull fails with a permission or authentication error:
66
+
67
+
1.**Check if `gh` is installed:** run `gh --version`
68
+
2.**If `gh` exists:** run `gh auth login` to authenticate, then retry
69
+
3.**If `gh` missing:** set a token: `export GITHUB_TOKEN=ghp_your_token_here`, then retry
70
+
4.**If using SSH:** ensure `~/.ssh/` has a valid key added to GitHub and `origin` uses the `git@github.com:` URL format
71
+
72
+
Tokens are used transiently in-memory — they are never persisted to `.git/config`.
50
73
51
74
## Commands
52
75
@@ -59,19 +82,37 @@ sm push # auto-generated commit message
59
82
sm push -m "add new skill"# custom message
60
83
```
61
84
62
-
First run auto-initializes git repo and prompts for a remote URL. On conflict (remote ahead of local), rejects with instructions to pull first.
85
+
**First-time behavior:**
86
+
1. If `~/.agents/` is not a git repo, auto-runs `git init`
87
+
2. If no `origin` remote exists, prompts for `owner/name`
88
+
3. If `gh` CLI is installed, offers to create the repo on GitHub automatically
89
+
4. If `gh` is not installed, shows a note telling the user to create the repo manually at https://github.com/new
90
+
91
+
**Possible outcomes:**
92
+
-`Skills pushed successfully!` — new commit created and pushed
93
+
-`Unpushed commits pushed successfully!` — working tree clean, but local was ahead
94
+
-`No changes to push — already up to date.` — nothing new
95
+
-`Push rejected` — see Troubleshooting below
63
96
64
97
### pull
65
98
66
-
Pull from GitHub. Auto-runs `link` afterward unless skipped.
99
+
Pull from GitHub. Auto-runs `link` afterward unless `--skip-link` is passed.
67
100
68
101
```bash
69
102
sm pull --repo owner/name # first time — specify repo
70
103
sm pull # subsequent runs — uses existing remote
71
-
sm pull --skip-link # pull only, skip auto-link
104
+
sm pull --skip-link # pull only, don't re-link
72
105
```
73
106
74
-
On rebase conflict, aborts and shows manual resolution steps.
107
+
**First-time behavior:**
108
+
- If no `--repo` and no existing `origin` remote, prompts for `owner/name`
109
+
- If `~/.agents/` doesn't exist yet, clones into it
110
+
111
+
**Possible outcomes:**
112
+
-`Skills cloned successfully!` — fresh clone on new machine, auto-runs link
113
+
-`Skills updated from remote.` — pulled new changes, auto-runs link
114
+
-`Already up to date.` — no new changes, skips link
115
+
-`Rebase conflict` — see Troubleshooting below
75
116
76
117
### link (global mode)
77
118
@@ -82,37 +123,53 @@ sm link # interactive prompt
82
123
sm link --agents cursor opencode # non-interactive, skip prompt
83
124
```
84
125
85
-
**Interactive prompt behavior:**
126
+
**Interactive behavior:**
86
127
87
-
The agent selection uses a **searchable multiselect** with two sections:
128
+
The agent selector has two sections:
129
+
1.**Locked section** — 10 universal agents (amp, cline, codex, cursor, gemini-cli, github-copilot, kimi-cli, opencode, replit, universal) are always included because they share `~/.agents/skills/` as their path.
130
+
2.**Searchable list** — 31 non-universal agents. Type to search/filter.
88
131
89
-
1.**Locked section** — Universal agents (amp, cline, codex, cursor, gemini-cli, github-copilot, kimi-cli, opencode, replit, universal) are always included. They share `~/.agents/skills/` as their project path, so linking them is a no-op beyond the global symlink — they're locked to avoid confusion.
2.**Searchable list** — All 31 non-universal agents appear here. Type to filter by name. Pre-selection comes from (in priority order): last saved selection → `.skill-lock.json` → agents whose directory already exists on disk.
134
+
When `--agents` is provided, the interactive prompt is skipped entirely. Use this for scripting and AI agent automation:
92
135
93
-
When `--agents` is provided, the prompt is skipped entirely. Selection is persisted to `~/.config/skills-manager/config.json` for the next run.
136
+
```bash
137
+
sm link --agents cursor opencode claude-code
138
+
```
94
139
95
140
### link --project
96
141
97
-
Link or copy skills to the **current working directory**. Three-step interactive flow:
98
-
99
-
1.**Select skills** (`--skills`) — which skills to include (none pre-selected)
100
-
2.**Copy or symlink** (`--mode`) — `copy` (default, recommended) or absolute `symlink`
101
-
3.**Select agents** (`--agents`) — same searchable multiselect with locked universal section as global mode
142
+
Link or copy skills to the **current working directory**.
102
143
103
144
```bash
104
-
cd /path/to/project
105
-
sm link --project # interactive
106
-
sm link --project --agents cursor claude-code --skills my-skill --mode copy#non-interactive
145
+
sm link --project# interactive
146
+
sm link --project --agents cursor claude-code --skills my-skill# non-interactive (copy is default)
147
+
sm link --project --agents cursor claude-code --skills my-skill --mode symlink#explicit symlink
107
148
```
108
149
109
-
Agents sharing the same `projectPath` are deduplicated — one copy/link operation per unique path.
150
+
**Interactive flow (3 steps):**
151
+
1.**Select skills** (`--skills` to skip) — choose which skills to include
152
+
2.**Select copy/symlink** — in practice this prompt is skipped because `--mode` defaults to `copy` in the CLI. Only appears if `linkCommand` is called programmatically without defaults
153
+
3.**Select agents** (`--agents` to skip) — same searchable multiselect with locked universal section
0 commit comments