@vikasagarwal101/skill-sync 1.0.0

package/README.md

@@ -0,0 +1,206 @@
+# skill-sync
+
+Manage AI agent skills across multiple directories. Auto-discovers skill locations, maintains a manifest, and provides create/edit/sync/validate/deploy/doctor commands.
+
+## The problem
+
+Different AI coding agents look for skills in different directories:
+
+| Agent | Scans |
+|-------|-------|
+| OpenCode | `~/.agents/skills/`, `~/.config/opencode/skills/`, `~/.claude/skills/` |
+| Codex | `~/.agents/skills/`, `~/.codex/skills/` |
+| Claude Code | `~/.claude/skills/` only |
+
+No single directory is scanned by all three. Skills end up duplicated across locations, versions drift, and symlinks don't work reliably (Claude Code's skill discovery breaks on symlinks).
+
+## The solution
+
+`skill-sync` treats `~/.agents/skills/` as the canonical source and syncs real copies to agents that need them (currently Claude Code). A manifest tracks what syncs where. A config file allows custom sources and targets.
+
+## Quick start
+
+### Via npm (recommended)
+
+```bash
+npm install -g @vikasagarwal101/skill-sync     # global install
+skill-sync doctor                                # verify health
+```
+
+Or one-off without installing:
+
+```bash
+npx @vikasagarwal101/skill-sync doctor
+```
+
+### Via git clone
+
+```bash
+git clone https://github.com/vikasagarwal101/skill-sync ~/dev/skill-sync
+cd ~/dev/skill-sync
+./install.sh
+skill-sync doctor    # verify health
+```
+
+## Commands
+
+### Core
+
+```
+sync [name]                Sync all manifest skills, or just one
+add <name> [--to T]        Deploy a skill to a target (default: claude)
+remove <name> [--from T]   Remove from target(s) — use --purge to also delete source
+status                     Show sync state for all tracked skills
+```
+
+### Authoring
+
+```
+create <name> [--scope S]  Scaffold new skill with valid frontmatter (default: agents)
+edit <name>                Open SKILL.md in $EDITOR, offer sync on exit
+rename <old> <new>         Rename a skill across source + all targets + manifest
+```
+
+### Inspection
+
+```
+info <name>                Show source, sync state, health for one skill
+list [--all]               List synced skills, or --all for every skill everywhere
+search <query>             Find skills by keyword in name or description
+diff <name>                Show content diff between source and target copies
+```
+
+### Health
+
+```
+validate [name]            Check frontmatter + naming (one or all)
+doctor                     Full health check across all locations
+```
+
+### Target management
+
+```
+target list                Show all configured sources and targets
+target add <label> <path>  Add a new sync target (persists to config)
+target remove <label>      Remove a target (directories untouched)
+```
+
+### Maintenance
+
+```
+init                       Rebuild manifest from current state
+pull <name> [--from T]     Reverse sync: copy target edits back to source
+```
+
+### Global flags
+
+```
+--dry-run                  Preview any command without making changes
+```
+
+## Configuration
+
+### Config file
+
+`~/.config/skill-sync/config` is auto-generated when you use `target add/remove`. It's a sourceable bash file that overrides the defaults at startup. You can also edit it manually:
+
+```bash
+# Example: add a project-local target
+declare -A TARGETS=(
+    [claude]="$HOME/.claude/skills"
+    [work-project]="/path/to/project/.claude/skills"
+)
+```
+
+### Environment variables
+
+All paths have env var overrides (checked before the config file):
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SKILLSYNC_BIN_DIR` | `~/.local/bin` | Where the CLI is installed |
+| `SKILLSYNC_CONFIG_DIR` | `~/.config/skill-sync` | Manifest and config storage |
+| `SKILLSYNC_AGENTS_DIR` | `~/.agents/skills` | Shared canonical source |
+| `SKILLSYNC_OPENCODE_DIR` | `~/.config/opencode/skills` | OpenCode-only source |
+| `SKILLSYNC_CODEX_DIR` | `~/.codex/skills` | Codex-curated source |
+| `SKILLSYNC_CLAUDE_DIR` | `~/.claude/skills` | Claude Code sync target |
+
+## Architecture
+
+```
+Canonical sources (where skills live — auto-discovered)
+  ~/.agents/skills/          ← shared (scanned by OpenCode + Codex)
+  ~/.config/opencode/skills/ ← opencode-only
+  ~/.codex/skills/           ← codex-curated
+
+Sync targets (real copies, pushed from sources)
+  ~/.claude/skills/          ← Claude Code (can't follow symlinks)
+
+Config file (sourced at startup, overrides defaults)
+  ~/.config/skill-sync/config
+
+Manifest (tracks which skills sync to which targets)
+  ~/.config/skill-sync/manifest
+```
+
+## Nested skills
+
+Skills with no root `SKILL.md` but subdirectories containing `SKILL.md` are detected as nested skills with `parent/child` naming (e.g., `greptile/check-pr`). This matches Codex's depth-6 scanning behavior.
+
+## YAML frontmatter support
+
+The parser handles all common YAML scalar styles:
+- Inline: `description: My skill`
+- Quoted: `description: "My skill"`
+- Folded: `description: >` (multi-line, joined with spaces)
+- Literal: `description: |-` (multi-line)
+
+## Supported agents (8)
+
+| Agent | Detection path | Registration method |
+|-------|---------------|-------------------|
+| **OpenCode** | `~/.config/opencode/` | Rule file + `opencode.json` instructions array |
+| **Claude Code** | `~/.claude/` | Rule file + `@import` in `CLAUDE.md` |
+| **Codex** | `~/.codex/` | Marker section in `AGENTS.md` |
+| **Kilo Code** | `~/.config/kilo/` | Rule file + `kilo.jsonc` instructions array |
+| **Gemini CLI** | `~/.gemini/` | Rule file + `@import` in `GEMINI.md` |
+| **Auggie** | `~/.augment/` | Rule file (auto-discovered in `~/.augment/rules/`) |
+| **Devin** | `~/.devin/` | Marker section in `AGENTS.md` |
+| **Antigravity** | `~/.gemini/antigravity/` | No registration needed (reads `AGENTS.md` + scans `~/.agents/skills/`) |
+
+## Install
+
+```bash
+git clone https://github.com/vikasagarwal101/skill-sync ~/dev/skill-sync
+cd ~/dev/skill-sync
+./install.sh
+```
+
+Interactive mode detects all installed agents and prompts for each:
+
+```
+Detected agents: opencode, claude, codex, kilo, gemini, auggie, antigravity
+
+  Register with opencode (rule file + opencode.json)? [Y/n]
+  Register with claude (rule file + CLAUDE.md import)? [Y/n]
+  Register with codex (AGENTS.md section)? [Y/n]
+  Register with kilo (rule file + kilo.jsonc instructions)? [Y/n]
+  Register with gemini (rule file + GEMINI.md import)? [Y/n]
+  Register with auggie (rule file, auto-discovered)? [Y/n]
+  Antigravity: automatic — no registration needed
+```
+
+Non-interactive options:
+
+```bash
+./install.sh --with-rules all                    # register with all detected agents
+./install.sh --with-rules opencode,claude,kilo   # specific agents only
+./install.sh --no-rules                           # CLI only, no agent registration
+./install.sh --uninstall                          # remove everything (prompts per agent)
+```
+
+## Requirements
+
+- Bash 4.0+ (associative arrays)
+- `awk`, `find`, `md5sum`, `du`
+- Linux or macOS

package/bin/skill-sync.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+"use strict";
+
+/**
+ * skill-sync — thin Node.js wrapper that spawns the bundled bash script.
+ *
+ * This file exists so that `npm install -g skill-sync` puts `skill-sync` on PATH.
+ * It simply forwards all arguments to the bash implementation.
+ */
+
+const { spawn } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+// Find the bundled bash script (next to this JS file)
+const scriptPath = path.join(__dirname, "skill-sync.sh");
+
+if (!fs.existsSync(scriptPath)) {
+  process.stderr.write("Error: bundled script not found at " + scriptPath + "\n");
+  process.stderr.write("Run: bash scripts/bundle.sh\n");
+  process.exit(1);
+}
+
+// Spawn bash with the script, forwarding all arguments
+const child = spawn("bash", [scriptPath, ...process.argv.slice(2)], {
+  stdio: "inherit",
+  env: process.env,
+});
+
+child.on("close", (code) => {
+  process.exit(code ?? 1);
+});
+
+child.on("error", (err) => {
+  process.stderr.write("Error: " + err.message + "\n");
+  process.exit(1);
+});