@akshar5/skillsync 0.1.0 → 0.1.2

package/README.md

@@ -2,7 +2,53 @@
 
 Local-first skill manager for AI agent skills.
 
-SkillSync uses a private GitHub repo as your cloud vault, then keeps selected skills linked into local agent skill folders on each device.
+SkillSync uses a private GitHub repo as your cloud vault, then keeps selected skills linked into local agent skill folders on each device. Install it once with npm, connect it to your vault, and use the `skillsync` command anywhere.
+
+## Quick start
+
+Install the CLI:
+
+```bash
+npm install -g @akshar5/skillsync
+```
+
+Connect this device to an existing private skills vault:
+
+```bash
+skillsync setup --repo AksharP5/skills
+```
+
+Add a local skill folder to the vault:
+
+```bash
+skillsync add ~/path/to/my-skill --skill my-skill
+```
+
+Add a skill from a GitHub repository:
+
+```bash
+skillsync add https://github.com/example-org/example-skill --skill example-skill
+```
+
+Install a vaulted skill into a local agent target:
+
+```bash
+skillsync target add codex ~/.codex/skills
+skillsync install my-skill --target codex
+```
+
+Open the interactive UI:
+
+```bash
+skillsync
+```
+
+## Requirements
+
+- Node.js 20 or newer
+- Git
+- GitHub CLI (`gh`) authenticated with `gh auth login`
+- A private GitHub repo for the skills vault
 
 ## What it manages
 
@@ -18,56 +64,129 @@ devices/*.json       # generated, do not edit
 
 User-owned files are the skill folders under `skills/`. SkillSync owns `registry.json` and `devices/*.json`.
 
-## Install on another device
+Local target folders are per-device. For example, one laptop can install a skill into `~/.codex/skills`, while another can install the same vault skill into a different agent folder.
+
+## Install on a new device
 
-SkillSync is an npm-style CLI package. Once published, the nice path will be:
+Install prerequisites on macOS:
 
 ```bash
-npx @akshar5/skillsync setup --repo AksharP5/skills
-npx @akshar5/skillsync add https://github.com/raroque/vibe-security-skill --skill vibe-security
+brew install gh git node
+gh auth login
 ```
 
-It is not published to the public npm registry yet. Install it from the private GitHub repo for now:
+SkillSync clones vault repos over HTTPS using your GitHub CLI authentication, so a GitHub SSH key is not required.
+
+Install SkillSync:
 
 ```bash
-# macOS
-brew install gh git node
+npm install -g @akshar5/skillsync
+```
 
-gh auth login
-npm install -g git+ssh://git@github.com/AksharP5/skillsync.git
+Connect to an existing vault:
+
+```bash
+skillsync setup --repo AksharP5/skills
 ```
 
-If SSH is not set up on that device yet, use the clone/link fallback:
+Or create/select a vault repo interactively:
 
 ```bash
-mkdir -p ~/projects
-gh repo clone AksharP5/skillsync ~/projects/skillsync
-cd ~/projects/skillsync
-npm install
-npm link
+skillsync setup
 ```
 
-Connect to an existing vault:
+If you run plain `skillsync setup` in an interactive terminal, it first asks which vault type to use:
+
+- Choose `Use an existing GitHub repo`, then enter a repo like `AksharP5/skills`.
+- Choose `Create or use OWNER/<name>`, then enter a repo name like `skills`.
+
+`setup --name skills` is the non-interactive form of the second option. It creates `OWNER/skills` as a private GitHub repo if it does not exist. If it exists, SkillSync verifies it is private before using it.
+
+You can also run commands without a global install:
+
+```bash
+npx @akshar5/skillsync setup --repo AksharP5/skills
+npx @akshar5/skillsync add https://github.com/example-org/example-skill --skill example-skill
+```
+
+If an older SkillSync version failed with `git@github.com: Permission denied (publickey)`, update the CLI and rerun setup:
 
 ```bash
+npm install -g @akshar5/skillsync@latest
 skillsync setup --repo AksharP5/skills
 ```
 
-Or create/select a different private vault repo name:
+## Common workflows
+
+List available skills:
+
+```bash
+skillsync list
+```
+
+Check current vault/device state:
 
 ```bash
-skillsync setup --name my-skills
+skillsync status
 ```
 
-If you run plain `skillsync setup` in an interactive terminal, it asks for the repo name and defaults to `skills`. `setup --name` creates `OWNER/my-skills` as a private GitHub repo if it does not exist. If it exists, SkillSync verifies it is private before using it.
+Add local agent targets:
+
+```bash
+skillsync target add codex ~/.codex/skills
+skillsync target add claude ~/.claude/skills
+skillsync target add hermes ~/.hermes/skills/personal --scan-path ~/.hermes/skills
+```
+
+Add a skill folder to the vault:
+
+```bash
+skillsync add ~/Developer/skills/my-skill --skill my-skill
+```
+
+Add from a GitHub repo:
+
+```bash
+skillsync add https://github.com/example-org/example-skill --skill example-skill
+```
+
+If the source repo contains multiple skills, omit `--skill` in an interactive terminal and SkillSync will ask which ones to add. Add `--target codex` or `--target '*'` to install immediately after importing:
+
+```bash
+skillsync add https://github.com/example-org/example-skill --target codex
+skillsync add https://github.com/example-org/example-skill --target '*'
+```
+
+Install or uninstall a vaulted skill on this device:
+
+```bash
+skillsync install my-skill --target codex
+skillsync uninstall my-skill
+```
+
+Sync the vault and reapply local links:
+
+```bash
+skillsync sync
+```
+
+Scan configured target folders for already-installed local skills:
+
+```bash
+skillsync scan
+```
 
 ## Commands
 
 ```bash
 skillsync setup
+skillsync setup --repo owner/repo
+skillsync setup --name skills
 skillsync
+skillsync status
+skillsync list
 skillsync add <skill-folder-or-git-url> --skill <name>
-skillsync add https://github.com/raroque/vibe-security-skill --skill vibe-security
+skillsync add https://github.com/example-org/example-skill --skill example-skill
 skillsync import hermes
 skillsync install <skill> --target codex
 skillsync uninstall <skill>
@@ -77,6 +196,7 @@ skillsync target add hermes ~/.hermes/skills/personal --scan-path ~/.hermes/skil
 skillsync scan
 skillsync sync
 skillsync service install
+skillsync daemon
 ```
 
 ## Removal model
@@ -84,32 +204,6 @@ skillsync service install
 - `skillsync uninstall <skill>` removes the skill from the current device only.
 - `skillsync delete <skill>` removes the skill from the vault and all device manifests.
 
-## Add from GitHub
-
-You can import a skill directly from a GitHub repo into your private vault:
-
-```bash
-skillsync add https://github.com/raroque/vibe-security-skill --skill vibe-security
-```
-
-If the repo has multiple skills, omit `--skill` in an interactive terminal and SkillSync will ask which ones to add. Add `--target codex` or `--target '*'` to install it on the current device immediately after importing.
-
-## Publishing to npm
-
-Clone the project on the machine where your npm account is configured:
-
-```bash
-gh repo clone AksharP5/skillsync ~/projects/skillsync
-cd ~/projects/skillsync
-npm install
-npm test
-npm pack --dry-run
-npm login
-npm publish --access public
-```
-
-The package name is `@akshar5/skillsync` because `skillsync` is already taken on npm. The installed command is still `skillsync`.
-
 ## Detected versus managed skills
 
 `installed` skills are SkillSync-managed projections into a target folder. `detected` skills are already present in a local agent's skill tree, such as bundled Hermes skills under `~/.hermes/skills`.
@@ -129,3 +223,23 @@ skillsync scan
 - Linux: systemd user service
 
 The service periodically pulls/pushes the GitHub vault and reapplies symlinks.
+
+## Development
+
+Clone and test locally:
+
+```bash
+git clone https://github.com/AksharP5/skillsync.git
+cd skillsync
+npm install
+npm test
+npm pack --dry-run
+```
+
+The npm package name is `@akshar5/skillsync` because `skillsync` is already taken on npm. The installed command is still `skillsync`.
+
+Future releases are managed by Release Please and GitHub Actions. Use conventional commits:
+
+- `fix:` creates a patch release.
+- `feat:` creates a minor release.
+- `feat!:` or `BREAKING CHANGE:` creates a major release.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akshar5/skillsync",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Local-first GitHub-backed skill vault sync client for AI agent skills.",
   "type": "module",
   "repository": {

package/src/cli.js

@@ -97,10 +97,29 @@ async function resolveRepoCloneUrl(repo) {
   if (/^(git@|https?:\/\/|ssh:\/\/)/.test(repo)) return repo;
   if (!repo.includes('/')) return repo;
   if (!await commandExists('gh')) return repo;
-  const { stdout } = await gh(['repo', 'view', repo, '--json', 'isPrivate,sshUrl', '--jq', '.']);
+  return verifiedRepoCloneUrl(repo);
+}
+
+async function verifiedRepoCloneUrl(repo) {
+  const { stdout } = await gh(['repo', 'view', repo, '--json', 'isPrivate,url', '--jq', '.']);
   const view = JSON.parse(stdout);
   if (!view.isPrivate) throw new Error(`${repo} exists but is not private. Make it private before using it as a skill vault.`);
-  return view.sshUrl;
+  return view.url;
+}
+
+async function ensureOwnedVaultRepo(owner, name) {
+  const repo = `${owner}/${name}`;
+  let repoExists = true;
+  try {
+    await gh(['repo', 'view', repo]);
+  } catch {
+    repoExists = false;
+  }
+  if (!repoExists) {
+    console.log(`Creating private GitHub repo ${repo}...`);
+    await gh(['repo', 'create', repo, '--private', '--description', 'Private AI agent skills vault'], undefined, { inherit: true });
+  }
+  return verifiedRepoCloneUrl(repo);
 }
 
 async function setup(rest) {
@@ -119,24 +138,25 @@ async function setup(rest) {
   if (!repo) {
     const { stdout: ownerOut } = await gh(['api', 'user', '--jq', '.login']);
     const owner = ownerOut.trim();
-    const name = flagValue(rest, '--name') || (yes || !process.stdin.isTTY
-      ? 'skills'
-      : await input({ message: 'GitHub skills vault repo name:', default: 'skills' }));
-    repo = `${owner}/${name}`;
-    let repoExists = true;
-    try {
-      await gh(['repo', 'view', repo]);
-    } catch {
-      repoExists = false;
-    }
-    if (!repoExists) {
-      console.log(`Creating private GitHub repo ${repo}...`);
-      await gh(['repo', 'create', repo, '--private', '--description', 'Private AI agent skills vault'], undefined, { inherit: true });
+    const nameArg = flagValue(rest, '--name');
+    if (nameArg || yes || !process.stdin.isTTY) {
+      repo = await ensureOwnedVaultRepo(owner, nameArg || 'skills');
+    } else {
+      const setupMode = await select({
+        message: 'Which skills vault do you want to use?',
+        choices: [
+          { name: 'Use an existing GitHub repo', value: 'existing' },
+          { name: `Create or use ${owner}/<name>`, value: 'owned' },
+        ],
+      });
+      if (setupMode === 'existing') {
+        const existingRepo = await input({ message: 'Existing vault repo (owner/repo or URL):', default: `${owner}/skills` });
+        repo = await resolveRepoCloneUrl(existingRepo);
+      } else {
+        const name = await input({ message: `Vault repo name under ${owner}:`, default: 'skills' });
+        repo = await ensureOwnedVaultRepo(owner, name);
+      }
     }
-    const { stdout: viewOut } = await gh(['repo', 'view', repo, '--json', 'isPrivate,sshUrl', '--jq', '.']);
-    const view = JSON.parse(viewOut);
-    if (!view.isPrivate) throw new Error(`${repo} exists but is not private. Make it private before using it as a skill vault.`);
-    repo = view.sshUrl;
   } else {
     repo = await resolveRepoCloneUrl(repo);
   }