A command-line tool that queries a local skill registry for compatible agent skills based on a project's skill manifest, then copies and installs them into the local environment with proper versioning and MCP server configuration.

Quick Start • Features • Examples • Contributing

What is this?

SkillSync CLI streamlines the setup of agent skills by reading a project's skill manifest, locating matching versions in a local skill registry, and installing them with correct MCP configuration. It is aimed at developer experience engineers and teams who want a single‑command workflow similar to npm install for agent capabilities.

$ skill-sync install --manifest skill.yaml
Installed 3 skills to ./skill_sync/install/

Problem

Developers waste time manually searching for MCP servers, copying installation instructions, and matching versions, especially when working across multiple agent frameworks.

Features

Feature	Description
Parse Skill Manifest	Reads and validates a YAML manifest (skill.yaml) extracting skill IDs and version constraints.
Query Local Skill Registry	Looks up each requirement in a local SQLite registry and returns the highest satisfying version.
Populate the Registry	skill-sync registry add inserts an id/version/location entry into the local SQLite registry -- there is no bundled or remote catalog.
Download and Install Skills	Copies skill files to ./skill_sync/install/ (or --target) and generates an MCP config file.
Version Constraint Handling	Supports semantic versioning operators (==, >=, >, <=, <).
MCP Config Generation	Produces mcp-config.yaml listing installed skills, their versions, and install paths.
Clear Error Reporting	Exits with distinct codes (2‑4) and helpful messages for manifest, resolution, or copy failures.

Note: SkillSync CLI is a local, self-contained tool. It does not talk to any remote discovery service (e.g. Loaditout) out of the box -- the registry is a local SQLite file you populate yourself with skill-sync registry add.

Quick Start

1. Clone the repository:
   git clone https://github.com/m2ai-portfolio/skillsync-cli.git
cd skillsync-cli
2. Install the CLI (editable install, registers the skill-sync command):
   pip install -e .
3. The local skill registry lives at ~/.skill_sync/registry.db by default (override with SKILL_REGISTRY_PATH). It starts empty -- populate it with skill-sync registry add (see below) before resolve/install can find anything.
4. Run the parser to see what skills are required:
   skill-sync parse --manifest samples/good.yaml
   Sample output:

   Found 3 skill requirements:
     - skill-a >=1.0.0
     - skill-b ==2.5.1
     - skill-c <3.0.0
   

Examples

Parsing a manifest

$ skill-sync parse --manifest samples/good.yaml
Found 3 skill requirements:
  - skill-a >=1.0.0
  - skill-b ==2.5.1
  - skill-c <3.0.0

Seeding the local registry
The registry starts empty -- there is no bundled catalog. Register a skill's location and version with registry add. The samples/skills/ directory ships three toy skills for exactly this purpose:

$ skill-sync registry add --id skill-a --version 1.4.2 --location samples/skills/skill-a
Added skill-a v1.4.2 @ samples/skills/skill-a to the registry.
$ skill-sync registry add --id skill-b --version 2.5.1 --location samples/skills/skill-b
Added skill-b v2.5.1 @ samples/skills/skill-b to the registry.
$ skill-sync registry add --id skill-c --version 2.9.0 --location samples/skills/skill-c
Added skill-c v2.9.0 @ samples/skills/skill-c to the registry.

Resolving skills against the registry

$ skill-sync resolve --manifest samples/good.yaml
Resolved 3 skills:
  - skill-a v1.4.2 @ samples/skills/skill-a
  - skill-b v2.5.1 @ samples/skills/skill-b
  - skill-c v2.9.0 @ samples/skills/skill-c

Installing skills locally
--target defaults to ./skill_sync/install/ if omitted:

$ skill-sync install --manifest samples/good.yaml
Installed 3 skills to ./skill_sync/install/:
  - skill-a v1.4.2
  - skill-b v2.5.1
  - skill-c v2.9.0

The generated ./skill_sync/install/mcp-config.yaml contains:

skills:
- id: skill-a
  path: skill_sync/install/skill-a
  version: 1.4.2
- id: skill-b
  path: skill_sync/install/skill-b
  version: 2.5.1
- id: skill-c
  path: skill_sync/install/skill-c
  version: 2.9.0

File Structure

SkillSync CLI/
  skill_sync/          # Core source code
    __init__.py
    main.py            # CLI entry point (click)
    manifest_parser.py # Parse YAML manifest
    skill_registry.py  # SQLite lookup + registry-add helpers
    installer.py       # File copy and MCP config generation
    models.py          # Pydantic data models
  tests/               # Test suite
    test_cli.py
    test_installer.py
    test_manifest_parser.py
    test_skill_registry.py
  samples/             # Runnable example manifest + toy skills
    good.yaml
    skills/skill-a/, skill-b/, skill-c/
  assets/              # Infographic used in banner
  requirements.txt     # Pinned dependencies
  pyproject.toml       # Packaging + `skill-sync` console-script entry point
  README.md
  LICENSE

Tech Stack

Technology	Purpose
Python 3.11+	Core language
Click 8.1.7	CLI framework
Pydantic 2.7.0	Data validation and settings
SQLite (stdlib)	Local skill registry storage
Pytest 8.2.2	Testing framework

Contributing

Fork the repo, make changes, run tests, and submit a pull request.

License

MIT

Author

Matthew Snow -- M2AI | @m2ai-portfolio