SkillSync

Git-native CLI for syncing AI agent skills across environments.

Define your AI agent skills once in a GitHub repository. Install them into Claude Code, Levante, Hermes or any other agent environment. Keep them updated with a single command. Let agents propose improvements through Pull Requests.

npm install -g @saulgomez/skillpush
skillsync init
skillsync repo connect https://github.com/<you>/my-agent-skills
skillsync install brand-analysis

Why SkillSync

Working with AI agents across different projects, machines and tools usually means duplicating the same skills folder everywhere. That breaks the moment one of those copies improves and the others don't follow.

SkillSync turns a GitHub repository of yours into the single source of truth for your skills, agents and workflows, and gives you a CLI to:

1. Connect that repo as your skill source.
2. Install skills into Claude Code (and other targets via adapters).
3. Update them with a single command.
4. Validate them (schema, secrets, dangerous patterns) before installation.
5. Let agents propose improvements via Pull Request — never direct push to main.

Install

npm install -g @saulgomez/skillpush

Requirements:

• Node.js ≥ 18
• git
• GitHub CLI (gh) authenticated with gh auth login

Quick start

1. Initialize

skillsync init

Creates ~/.skillsync/config.json and ~/.skillsync/lock.json.

2. Connect a repository

If you already have a skills repo:

skillsync repo connect https://github.com/<you>/my-agent-skills

If you want a fresh one with the standard structure:

skillsync repo create my-agent-skills --private

3. Install skills

skillsync list
skillsync install brand-analysis
skillsync install all

4. Stay up to date

skillsync status
skillsync update

5. Improve and propose

skillsync add customer-support -d "Triage and answer support tickets"
# edit skills/customer-support/SKILL.md
skillsync propose customer-support -m "feat: customer-support skill"

Commands

| Command | Description | |---------|-------------| | skillsync init | Initialize SkillSync on this machine | | skillsync repo create <name> | Create a new skills repository on GitHub | | skillsync repo connect <url> | Connect to an existing skills repository | | skillsync list | List skills in the connected repository | | skillsync install <name\|all> | Install a skill into the configured target | | skillsync update [name] | Update installed skills | | skillsync status | Show install status and pending updates | | skillsync add <name> | Create a new skill from a template | | skillsync validate [name] [--repo <dir>] | Validate one skill or the whole repo | | skillsync propose <name> -m "..." | Open a Pull Request with local changes | | skillsync doctor | Diagnose your local setup |

Run skillsync <command> --help for full options.

Repository layout

my-agent-skills/
  skillsync.json
  README.md
  skills/
    brand-analysis/
      SKILL.md
      README.md
  agents/
  workflows/
  templates/
  policies/
  .github/
    workflows/
      validate-skills.yml

SKILL.md format

---
name: brand-analysis
version: 0.1.0
description: Analyze a company, its positioning, market, audience and opportunities.
author: You
tags: [business, research, sales]
targets: [claude-code]
---

# Brand Analysis Skill

## Goal
Help the agent analyze a company from public information.

## When to use this skill
Whenever the user asks for a brand, competitor or ecommerce analysis.

## Instructions
1. Identify the company.
2. Collect available information.
3. Produce a structured report.

Targets

The first version ships with the claude-code adapter:

• User scope → ~/.claude/skills/
• Project scope → ./.claude/skills/

Custom paths are supported via the custom adapter and --path.

More adapters (Levante, Hermes, OpenCode, …) are planned in the roadmap.

Security model

• Default mode is copy, not symlink.
• Day-to-day skill changes should go through Pull Requests via propose; only repository bootstrap writes directly to main.
• Skills are validated before installation: schema, secrets, dangerous patterns.
• Secret scanning catches OpenAI / Anthropic / GitHub / AWS / Slack / Google patterns.

See phase 03 for the full ruleset.

Roadmap

• v0.1 — Claude Code, install/update/status/validate
• v0.2 — add/propose/repo-create
• v0.3 — symlink mode, custom adapter polish, CI templates
• v0.4+ — Levante / Hermes / OpenCode adapters, public skill discovery, signed releases

License

MIT — see LICENSE.