skills-sync

Manage and synchronize AI agent skills from local SKILL.md files and remote Git repositories, generating Cursor rules with Agent Skills specification XML. This skill should be used when users need to sync skills, add/remove skill repositories, or set up the skills infrastructure.

⭐23stars🔀6forks📁View on GitHub🕐Updated Dec 28, 2025⬇️1downloads

When & Why to Use This Skill

Skills Sync is a specialized developer tool designed to manage and synchronize AI agent capabilities across local environments and remote Git repositories. It automates the generation of Cursor rules using the Agent Skills specification XML format, ensuring that AI assistants in the Cursor IDE have immediate, context-aware access to the latest tools and documentation. By streamlining the distribution and versioning of SKILL.md files, it provides a robust infrastructure for maintaining consistent agent behavior across projects and teams.

Use Cases

  • Team Collaboration: Synchronizing a shared library of custom AI skills from a central Git repository to all team members' local development environments.
  • Cursor IDE Optimization: Automatically generating and updating .cursor/rules/skills.mdc to ensure the AI assistant understands available project-specific tools and workflows.
  • Multi-Project Management: Using the precedence system to apply global AI skills across all projects while overriding them with specialized logic in specific project directories.
  • Infrastructure Automation: Setting up a standardized 'skills infrastructure' that auto-installs dependencies like 'uv' and 'git' to maintain a consistent agent execution environment.
nameskills-sync

Skills Sync

Overview

Synchronizes AI agent skills from local directories and Git repositories, generating .cursor/rules/skills.mdc for Cursor IDE integration.

Usage

First time setup (installs uv if needed, then installs skills-sync as a tool):

python3 .claude/skills/skills-sync/scripts/skills_sync.py

Subsequent runs:

skills-sync

The script auto-detects the project root by walking up the directory tree.

Skill Locations (Precedence Order)

Priority Location Type
1 (highest) $PROJECT/.cortex/skills/ Project
2 $PROJECT/.claude/skills/ Project
3 ~/.snowflake/cortex/skills/ Global
4 (lowest) ~/.claude/skills/ Global

Higher precedence locations override skills with the same name from lower locations.

Repository Configuration

Place repos.txt in any skill directory to sync skills from Git repositories:

https://github.com/anthropics/skills
https://github.com/your-org/your-skills-repo
# Comments start with #

The script checks all four skill locations for repos.txt files and deduplicates URLs.

Repository Skill Extraction

Skills are extracted ONLY from .cortex/skills/*/SKILL.md and .claude/skills/*/SKILL.md paths within repositories. Extracted skills are placed in ~/.snowflake/cortex/skills/ with a repo prefix (e.g., skills-dbt-core/).

Managing Repositories

Add Repository: Add URL to repos.txt, run skills-sync

Remove Repository: Delete URL from repos.txt, run skills-sync, optionally delete extracted skills from ~/.snowflake/cortex/skills/<repo>-<skill>/

Output

The script generates .cursor/rules/skills.mdc containing <available_skills> XML that Cursor loads automatically for all AI interactions.

Sync Process

  1. Read repos.txt from all locations, deduplicate URLs
  2. Clone/update repositories to ~/.snowflake/.cache/repos/
  3. Extract skills to ~/.snowflake/cortex/skills/ with repo prefix
  4. Scan all four skill locations with precedence rules
  5. Validate skills using Agent Skills CLI
  6. Generate .cursor/rules/skills.mdc with embedded XML
  7. Clean up old marker-delimited sections from AGENTS.md

Requirements

  • Python 3.8+
  • uv (auto-installed when running as script)
  • Git (auto-installed if missing)

When run as a Python script, it auto-installs uv, then installs itself as a uv tool. Git is auto-installed if missing using the appropriate method for your platform.

Troubleshooting

Skills not appearing: Verify SKILL.md exists in immediate child directory with valid frontmatter:

---
name: my-skill
description: What this skill does and when to use it
---