Sync Flownix Skills

Pulls updated skills from the Flownix backend into ~/.claude/skills/ using MD5 comparison to minimise token traffic — full content is only fetched for skills that actually changed.

Flow

list_skills()                   → {skills: [{slug, name, md5}, ...], retired: [{slug, replaced_by}]}
md5 local files                 → [{slug, local_md5}, ...]
compare                         → find slugs where md5 differs
get_skill(slug) per changed     → full content, only for diffs
write to ~/.claude/skills/

Workflow

1. Fetch remote metadata

Call list_skills — returns slug, name, description, and MD5 for every skill. No content is returned here.

The same response carries retired: slugs the backend no longer serves because the skill was renamed or removed. They matter as much as the skills themselves — see step 3.

2. Compute local MD5s

For each remote slug, check whether a local file exists and compute its MD5:

# macOS
md5 -q ~/.claude/skills/<slug>/SKILL.md 2>/dev/null || echo "MISSING"

# Linux
md5sum ~/.claude/skills/<slug>/SKILL.md 2>/dev/null | awk '{print $1}' || echo "MISSING"

3. Compare and categorise

Report the table before pulling.

RETIRED is the one row that removes something, and it exists for a specific failure. Synchronisation compares checksums of file contents, and renaming a file does not change its contents: without an explicit retired list a renamed skill would land next to its old copy, and the agent would keep reading the stale instruction while looking perfectly healthy. That is the worst kind of breakage — silent.

A retired entry usually names replaced_by. Say so when reporting: "flownix-basics → flownix-basics", not just "deleted".

4. Delete retired skills

For every slug in retired that exists locally:

rm -rf ~/.claude/skills/<slug>

Delete before pulling: if a rename is being delivered, the replacement arrives in the same run, and removing the old copy first keeps the directory from ever holding both.

5. Pull changed skills only

For each OUTDATED or MISSING skill, call get_skill(slug) to fetch full content, then write it to disk:

mkdir -p ~/.claude/skills/<slug>
# write skill.content to ~/.claude/skills/<slug>/SKILL.md

Skip IN_SYNC and LOCAL_ONLY entirely — no get_skill call needed.

6. Verify

After writing, recompute local MD5 and confirm it matches the remote MD5.

7. Report

Skill sync complete
  IN_SYNC   : execute-task, plan-feature                  (2)
  PULLED    : review-work, sync-skills                    (2)
  DELETED   : flownix-basics → flownix-basics             (1)
  LOCAL_ONLY: my-custom-skill                             (1)

Rules

• Never push local edits back to the backend — this skill is pull-only.
• Always compare MD5 before calling get_skill; never fetch content speculatively.
• LOCAL_ONLY skills are not touched — they may be project-specific or in-progress.
• RETIRED skills are deleted: the backend has explicitly said they no longer exist. This is the only case where synchronisation removes a file, and never by inference — only when the backend names the slug.
• On macOS use md5 -q, on Linux use md5sum | awk '{print $1}'.