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.
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.
| name | skills-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
- Read
repos.txtfrom all locations, deduplicate URLs - Clone/update repositories to
~/.snowflake/.cache/repos/ - Extract skills to
~/.snowflake/cortex/skills/with repo prefix - Scan all four skill locations with precedence rules
- Validate skills using Agent Skills CLI
- Generate
.cursor/rules/skills.mdcwith embedded XML - 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
---