skills-utils-mi 0.10.4

Sync agent skills from GitHub repos via API

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 [e-mail]: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.