How do I install the Contacts Sync skill?

Run npx skillmds@latest add astralune-ai/contacts-sync in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Contacts Sync skill do?

contacts-sync — reconcile folders ↔ contacts.csv It is listed under Data & Analytics on SkillMD.

Is Contacts Sync safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Contacts Sync?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Contacts Sync free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Contacts Sync?

Astralune-ai (@astralune-ai) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Contacts Sync by astralune-ai — Agent Skill

Name: Contacts Sync
Author: Astralune-ai

File contents

contacts-sync — reconcile folders ↔ contacts.csv

Backed by sync.py in the dunbar root.

Where's my dunbar root?

This skill works on whatever the user has set as their dunbar workspace. Look in this order:

$DUNBAR_ROOT environment variable
The current working directory if it contains contacts.csv AND at least one 0N_* circle folder
Otherwise — ask the user where their dunbar workspace is

User input parsing

$ARGUMENTS containing dry, --dry-run, or preview → run as a dry-run. Otherwise → apply the changes.

Execute

# Apply (default)
python3 "$DUNBAR_ROOT/sync.py" --root "$DUNBAR_ROOT"

# Or, from inside the workspace:
cd "$DUNBAR_ROOT" && python3 sync.py

# Dry-run preview
python3 "$DUNBAR_ROOT/sync.py" --root "$DUNBAR_ROOT" --dry-run

Output meaning

Marker	Means	Script behavior
🔄 Updates	A person's folder changed circle	Update CSV's 圈层 + 详档 columns
✨ New	Folder exists in FS, no row in CSV	Append a new row (nickname + circle + profile only; other columns left blank)
⚠️ Orphans	CSV row exists, folder missing	Warn only — does NOT auto-delete
🗓️ Date normalized	Numbers/Excel mangled a date	Restored to ISO format
⚠️ Lint	真实姓名 == 昵称	Suggest blanking 真实姓名 until full name is known
✅ in sync	No diff	CSV untouched

When to run

After dragging a person folder to a different circle — main use case
After creating a new person folder (mkdir <circle>/<nickname>/ + writing the .md)
Periodic sanity check
When the AI notices the user is doing relationship-management actions (e.g. adding several contacts in a row), proactively offer to run

Data contract (important)

Field	Source of truth	How to change
圈层	Filesystem (which circle directory the folder is in)	Move the folder + sync
详档	Filesystem (actual .md path)	sync computes it
Row existence	Filesystem (folder presence)	`mkdir` → sync appends; deletion is manual
Other 19 columns (phone/Email/tags/birthday/…)	The CSV itself	Edit `contacts.csv` directly (Numbers, your editor, a spreadsheet UI). sync never touches these.

Don't

❌ Don't bypass sync to hand-edit the 圈层 or 详档 columns — the next sync will overwrite them
❌ Don't mv just the .md file without moving the whole person folder — sync only looks at folder location
❌ Don't create person folders outside the circle directories — sync won't see them

---name: contacts-syncdescription: contacts-sync — reconcile folders ↔ contacts.csv---# contacts-sync — reconcile folders ↔ contacts.csvBacked by `sync.py` in the dunbar root.## Where's my dunbar root?This skill works on whatever the user has set as their dunbar workspace. Look in this order:1. `$DUNBAR_ROOT` environment variable2. The current working directory if it contains `contacts.csv` AND at least one `0N_*` circle folder3. Otherwise — ask the user where their dunbar workspace is## User input parsing`$ARGUMENTS` containing `dry`, `--dry-run`, or `preview` → run as a dry-run.Otherwise → apply the changes.## Execute```bash# Apply (default)python3 "$DUNBAR_ROOT/sync.py" --root "$DUNBAR_ROOT"# Or, from inside the workspace:cd "$DUNBAR_ROOT" && python3 sync.py# Dry-run previewpython3 "$DUNBAR_ROOT/sync.py" --root "$DUNBAR_ROOT" --dry-run```## Output meaning| Marker | Means | Script behavior ||--------|-------|-----------------|| 🔄 Updates | A person's folder changed circle | Update CSV's 圈层 + 详档 columns || ✨ New | Folder exists in FS, no row in CSV | Append a new row (nickname + circle + profile only; other columns left blank) || ⚠️ Orphans | CSV row exists, folder missing | Warn only — does NOT auto-delete || 🗓️ Date normalized | Numbers/Excel mangled a date | Restored to ISO format || ⚠️ Lint | 真实姓名 == 昵称 | Suggest blanking 真实姓名 until full name is known || ✅ in sync | No diff | CSV untouched |## When to run- **After dragging a person folder to a different circle** — main use case- **After creating a new person folder** (`mkdir <circle>/<nickname>/` + writing the .md)- Periodic sanity check- When the AI notices the user is doing relationship-management actions (e.g. adding several contacts in a row), proactively offer to run## Data contract (important)| Field | Source of truth | How to change ||-------|-----------------|---------------|| **圈层** | Filesystem (which circle directory the folder is in) | Move the folder + sync || **详档** | Filesystem (actual .md path) | sync computes it || **Row existence** | Filesystem (folder presence) | `mkdir` → sync appends; deletion is manual || **Other 19 columns** (phone/Email/tags/birthday/…) | The CSV itself | Edit `contacts.csv` directly (Numbers, your editor, a spreadsheet UI). sync never touches these. |## Don't- ❌ Don't bypass sync to hand-edit the 圈层 or 详档 columns — the next sync will overwrite them- ❌ Don't `mv` just the `.md` file without moving the whole person folder — sync only looks at folder location- ❌ Don't create person folders outside the circle directories — sync won't see them

Frequently asked questions

Contacts Sync