# Skill Sync Manager

> Safely discover, cache, compare, audit, install, update, deduplicate, and roll back agent Skills from GitHub with strict request budgets. Use when the user asks to find GitHub Skills, make a current or weekly stars ranking, install or refresh downloaded Skills, check whether local Skills are outdated, consolidate duplicates, or reduce repeated GitHub failures and token usage during Skill maintenance.

- Skill: `zhaolong666520/skill-sync-manager` (Agent Skill, multi-file: 11 files)
- Install (CLI): `npx skillmds@latest add zhaolong666520/skill-sync-manager`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zhaolong666520/skill-sync-manager/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Zhaolong666520 (https://skillmd.com/u/zhaolong666520)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zhaolong666520/skill-sync-manager

---


# Skill Sync Manager

Use a local-first pipeline. Keep network results and source artifacts on disk, return compact summaries to the model, and never execute downloaded code during discovery or review.

## Operating sequence

Set `SKILL_DIR` to this skill's directory, then follow these gates in order.

1. Index local Skills before searching or downloading:

   `python "$SKILL_DIR/scripts/index_local_skills.py"`

2. Reuse `~/.codex/skill-sync-manager/catalog.json`, search caches, repository metadata, source artifacts, and snapshots while they are fresh. Search GitHub only when the user asks for current information or the cache cannot answer:

   `python "$SKILL_DIR/scripts/github_search.py" "agent skills in:name,description,readme" --limit 30`

3. Probe metadata for candidates. Do not request repository trees until a shortlist exists. Pass a search report directly or provide explicit repositories:

   `python "$SKILL_DIR/scripts/github_probe.py" --search-report SEARCH_REPORT --max-repos 20 --max-requests 20`

   For shortlisted repositories only, add `--with-tree`. Reject truncated trees as incomplete evidence.

4. Fetch one selected Skill path at an immutable commit. Do not clone or install an entire repository unless the user explicitly chose the repository root:

   `python "$SKILL_DIR/scripts/fetch_skill.py" --repo OWNER/REPO --ref REF --path PATH/TO/SKILL`

5. Audit the cached directory without running it:

   `python "$SKILL_DIR/scripts/audit_skill.py" CACHED_CONTENT --out AUDIT_JSON`

   Treat critical and high findings as a stop. Explain medium findings and require explicit acceptance before applying. Manually inspect files the scanner cannot decode or cover.

6. Generate a dry-run diff. This is the default:

   `python "$SKILL_DIR/scripts/sync_skill.py" CACHED_CONTENT --audit-report AUDIT_JSON`

7. Apply only if the user already authorized installation or update and the audit gate passed:

   `python "$SKILL_DIR/scripts/sync_skill.py" CACHED_CONTENT --audit-report AUDIT_JSON --apply`

   Add `--accept-warnings` only after reviewing and explaining every warning. The script creates and verifies a versioned backup before replacing an existing Skill.

## Duplicate and update policy

- Treat the frontmatter `name` as the canonical identity and the tree SHA-256 as the content identity.
- If name and hash match, report a no-op and make no copy.
- If the name matches but content differs, update the canonical target through the audited sync path.
- If the same name exists in another directory, stop and report every path. Do not delete, merge code, or pass `--allow-name-conflict` without explicit user direction.
- Preserve unrelated local edits and Skills. Never bulk-delete stale directories.

## Weekly stars policy

Capture candidate metadata after a probe:

`python "$SKILL_DIR/scripts/weekly_snapshot.py" capture PROBE_JSON`

Rank the latest two snapshots:

`python "$SKILL_DIR/scripts/weekly_snapshot.py" rank --metric gained --top 10 --format markdown`

Call a list “weekly stars gained” only when both boundary snapshots exist. On the first run, report current total stars as a baseline; do not invent or reconstruct historical gains from current totals. A ranking covers the tracked candidate set, not every repository on GitHub, unless the candidate universe was explicitly defined that broadly.

## Hard limits and failure behavior

- Default to one search request, metadata-only probes, no more than 20 repositories per probe, and no more than two attempts per operation.
- Process GitHub requests serially. On HTTP 403/429 or rate-limit signals, stop the batch and use a clearly labeled stale cache if available.
- Prefer existing `gh` authentication and `gh api --cache`. Never ask the user to paste a token, print a token, or persist credentials in this Skill's state.
- Never run package installation hooks, scripts, binaries, or commands from fetched content during discovery, audit, or sync.
- Do not repeatedly call GitHub to confirm an unchanged result. Integrity-check the immutable local artifact instead.

Read [references/operations.md](references/operations.md) for cache layout, restore steps, command options, and the safety interpretation guide.