skills-utils

Sync agent skills from GitHub repos into Cursor, Claude Code, or Copilot — no git clone required.

What it is for

Agent skills are folders with a SKILL.md file. Repos like anthropics/skills publish official skills, but agents have no built-in install/update flow.

skills-sync is an interactive CLI that:

• Lists skills from GitHub via API
• Installs selected skills into the correct agent directory
• Detects local edits vs upstream changes
• Supports multiple repos and agents
• Ships in Python and Node (shared config + manifest)

Install (pick one runtime)

Python (PyPI)

pip install skills-utils-mi
skills-sync doctor

Node (npm)

npm install -g skills-sync-node-mi
skills-sync-node doctor

Python registers skills-sync; Node registers skills-sync-node to avoid PATH collisions when both are installed.

From source (development)

# Python
git clone [email protected]:mariuszizydorek/skills-utils.git
cd skills-utils/python
python3 -m venv .venv && source .venv/bin/activate
pip install -e . --index-url https://pypi.org/simple/
skills-sync doctor

# Node
cd skills-utils/node
npm install && npm run build && npm link
skills-sync-node doctor

Usage

After install, run from any folder:

skills-sync                  # interactive: pick agent → repo → tick skills
skills-sync status           # show installed skills
skills-sync doctor           # health check
skills-sync doctor --fix     # repair symlinks / create missing dirs

Common workflows

| Goal | Command | |------|---------| | First-time setup | skills-sync → pick Cursor → anthropics/skills → tick skills | | Check what's installed | skills-sync status | | Check for upstream updates | skills-sync status --check-remote | | Fix broken setup | skills-sync doctor --fix |

Where data lives

~/.skills-utils/
├── config.yaml       # repos + agent paths (created on first run)
├── manifest.json     # installed skills tracking
└── cache/            # downloaded skill files

Skills install to agent dirs:

| Agent | Install path | |-------|----------------| | Cursor (personal) | ~/.cursor/skills/<repo>/<skill>/ | | Cursor (project) | <project>/.cursor/skills/<repo>/<skill>/ | | Claude Code (personal) | ~/.claude/skills/<repo>/<skill>/ | | Claude Code (project) | <project>/.claude/skills/<repo>/<skill>/ | | Copilot (project) | <project>/.github/skills/<repo>/<skill>/ |

Run project-scoped agents from the exact directory you want to receive .cursor/skills, .claude/skills, or .github/skills.

Flat symlinks (~/.cursor/skills/pdf → anthropics/pdf) are created by default so agents can discover skills.

Configuration

Edit ~/.skills-utils/config.yaml or the template config.yaml. Override with --config or SKILLS_UTILS_CONFIG.

For private repos, authenticate first with gh auth login, or pass a token with --token, GITHUB_TOKEN, or GH_TOKEN.

Troubleshooting private-repo failures

Start with:

skills-sync doctor

Then use the full troubleshooting playbook:

• Markdown: docs/troubleshooting.md
• HTML: docs/troubleshooting.html

Quick auth reminder:

• Resolution order: --token -> GITHUB_TOKEN/GH_TOKEN -> gh auth token

Documentation (GitHub Pages)

This repo publishes docs/ to GitHub Pages using .github/workflows/pages.yml.

• Docs index: https://<owner>.github.io/skills-utils/
• Troubleshooting page: https://<owner>.github.io/skills-utils/troubleshooting.html

One-time setup in GitHub:

1. Open Settings -> Pages
2. Set Source to GitHub Actions
3. Push to main (or run the Pages workflow manually)

Release-note helper:

• Snippet template: docs/release-notes-snippet.md

Development

# Python tests
cd python && .venv/bin/pytest -v

# Node tests
cd node && npm run build && npm test

# Build release artifacts
./scripts/publish.sh

Publishing (maintainers)

PyPI package: skills-utils-mi
npm package: skills-sync-node-mi

One-time setup:

1. Create a PyPI API token with upload scope for skills-utils-mi
2. Configure npm Trusted Publishing for package skills-sync-node-mi with this GitHub Actions workflow (publish.yml)
3. Enable PyPI trusted publishing for this repo

Notes for npm trusted publishing:

• npm trusted publishing removes NPM_TOKEN from GitHub secrets.
• If package does not exist yet, do one bootstrap manual publish before setting trusted publisher.
• Use npm publish --access public --provenance in CI (already configured).
• If package exists but CI returns 404 Not Found on PUT, trusted publisher is not configured (or mismatched) for this repo/workflow on npm.

Optional fallback (token-based CI, not recommended):

• Create an npm token and store it as GitHub secret NPM_TOKEN.
• A 403 Forbidden ... You may not perform that action with these credentials usually means token permission/scope mismatch.

Manual publish:

./scripts/publish.sh

# PyPI (use __token__ as username, API token as password)
cd python
twine upload dist/skills_utils_mi-*

# npm
cd node
npm login
npm publish --access public

Or create a GitHub Release — the publish workflow uploads both packages automatically.

See plans/skills-sync-cli/plan.md for the full design.