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 for cache layout, restore steps, command options, and the safety interpretation guide.