home / skills / sfc-gh-dflippo / snowflake-dbt-demo / skills-sync

skills-sync skill

needs review

This skill helps you synchronize AI agent skills from local and remote sources, generating Cursor rules for seamless agent integration.

npx playbooks add skill sfc-gh-dflippo/snowflake-dbt-demo --skill skills-sync

Review the files below or copy the command above to add this skill to your agents.

Files (4)

SKILL.md

3.1 KB

---
name: skills-sync
description:
  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.
---

# 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):

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

**Subsequent runs:**

```bash
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:

```text
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:

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

Overview

This skill manages and synchronizes AI agent skills from local skill directories and remote Git repositories. It consolidates discovered skills, validates them, and generates Cursor-compatible Agent Skills XML rules for IDE integration. Use it to establish and maintain a consistent skills catalog across machines and projects.

How this skill works

The tool scans prioritized local skill locations and reads a central repos.txt to collect remote Git URLs. It clones or updates each repository into a cache, extracts skill definition files from expected paths, and places normalized copies into a centralized skills directory. Finally, it validates skills with the Agent Skills validator and writes an embedded <available_skills> XML block into Cursor rules so the IDE can load skills automatically.

When to use it

Onboard new or updated skills from remote Git sources into your local environment
Ensure project-level skills override global skills using defined precedence
Bootstrap or refresh Cursor IDE skill rules after adding or removing skills
Automate validation and normalization of skill metadata before use
Synchronize skills across developer machines or CI environments

Best practices

Keep a single repos.txt per project or user location to manage remote skill sources
Place project-specific skills in the project skill directory to ensure higher precedence
Use clear frontmatter metadata in skill definition files (name, description) for reliable extraction
Run the sync regularly or integrate into CI to catch outdated or invalid skills early
Remove URLs from repos.txt to stop syncing a remote source, then optionally delete extracted skills

Example use cases

Add a shared team skills repo URL to repos.txt to make team skills available locally
Develop a new skill in a project skill directory to override a global skill with the same name
Run the sync in CI to validate skills and update Cursor rules before deployment
Clean up deprecated skills by removing their URLs and rerunning the sync
Migrate skills from multiple sources into a single ~/.snowflake/cortex/skills/ store for tooling consumption

FAQ

How does precedence between project and global skills work?

The sync applies a fixed priority: project skill locations override global locations. Skills found in a higher-precedence location replace those with the same name from lower locations.

What configuration file lists remote skill sources?

Place a plain text repos.txt in any recognized skill location; the sync reads all such files, deduplicates URLs, and clones or updates them.