my-skills

my-skills — Claude Code Skill Sync Manager

Sync Claude Code skills across multiple machines using a personal GitHub repository. Manages individual skill-level symlinks so the user's existing ~/.claude/skills/ directory stays intact.

Prerequisites

• gh CLI installed and authenticated (gh auth status)
• git installed

Configuration

• Config file: ~/.my-skills.yml
• Local repo clone: ~/.my-skills-repo/

Repo Structure

The repo separates user-level and project-level skills:

~/.my-skills-repo/
├── user/                          ← user level skills
│   ├── memo/SKILL.md
│   └── recap/SKILL.md
└── projects/                      ← project level skills (by project name)
    ├── retrievo/
    │   └── backend-init/SKILL.md
    └── execute/
        └── frontend-init/SKILL.md

Symlink paths:

• User level: ~/.claude/skills/<skill> → ~/.my-skills-repo/user/<skill>
• Project level: {cwd}/.claude/skills/<skill> → ~/.my-skills-repo/projects/<project>/<skill>

Commands

Parse the user's input to determine which command to run. The user will typically say /my-skills <command> [args].

---

setup

Initial setup: connect to GitHub, create or clone the repo, and configure.

Steps:

1. Verify gh is installed and authenticated:

   gh auth status
   

   If not authenticated, tell the user to run ! gh auth login to authenticate.

2. Check if ~/.my-skills.yml already exists. If so, read it and ask if the user wants to reconfigure.

3. Ask the user for the repo name (default: my-skills). The repo will be created as private.

4. Check if the repo already exists on GitHub:

   gh repo view <username>/my-skills --json name 2>/dev/null
   

5. If the repo exists, clone it:

   git clone https://github.com/<username>/my-skills.git ~/.my-skills-repo
   

   If it doesn't exist, create it:

   gh repo create my-skills --private --description "My Claude Code skills" --clone --gitignore=""
   

   Then move the cloned repo to ~/.my-skills-repo if needed. Create the directory structure:

   mkdir -p ~/.my-skills-repo/user ~/.my-skills-repo/projects
   

6. Create ~/.my-skills.yml:

   repo: <username>/my-skills
   local_path: ~/.my-skills-repo
   linked_skills: []
   

7. If the cloned repo already contains skills (from another machine), list them and ask which ones to link:

   # User level skills
   ls -d ~/.my-skills-repo/user/*/SKILL.md 2>/dev/null | sed 's|.*/user/\(.*\)/SKILL.md|\1|'
   # Project level skills
   find ~/.my-skills-repo/projects -name SKILL.md 2>/dev/null
   

   For each selected user-level skill, create a symlink (see the Linking section below).

8. Report setup complete with a summary of what was configured.

---

push

Push local skills to the remote repo.

Usage:

• /my-skills push — push all linked user-level skills
• /my-skills push <skill-name> — push a specific user-level skill
• /my-skills push <skill1> <skill2> — push multiple user-level skills
• /my-skills push <skill-name> --project (-p) — push a project-level skill (auto-detect project name from cwd, confirm with user)
• /my-skills push <skill-name> --project (-p) <project-name> — push a project-level skill to a specific project name

Steps:

1. Read ~/.my-skills.yml to get config. If not found, tell the user to run setup first.

2. Determine scope and source directory:

   • User level (default): source is ~/.claude/skills/, repo target is ~/.my-skills-repo/user/
   • Project level (--project (-p)):
     • Source is {cwd}/.claude/skills/
     • Detect project name: basename $(git rev-parse --show-toplevel 2>/dev/null || pwd)
     • If project name is not specified via argument, show the detected name and ask the user to confirm
     • Repo target is ~/.my-skills-repo/projects/<project-name>/

3. If no skill names specified (user level only), push all currently linked skills:

   • For each skill in linked_skills, changes are already in the repo directory via symlink. Just commit and push.

4. If skill names are specified:

   • For each skill, check if it exists in the source directory
   • If the skill is not yet in the repo, copy it to the appropriate repo path:

     # User level
     cp -r <source>/<skill-name> ~/.my-skills-repo/user/<skill-name>
     # Project level
     mkdir -p ~/.my-skills-repo/projects/<project-name>
     cp -r <source>/<skill-name> ~/.my-skills-repo/projects/<project-name>/<skill-name>
     

   • Then replace the original with a symlink (see Linking section)
   • For user-level skills, add to linked_skills in ~/.my-skills.yml

5. Commit and push:

   cd ~/.my-skills-repo
   git add -A
   git commit -m "Update skills: <skill-names>"
   git push
   

6. Report which skills were pushed.

---

pull

Pull skills from the remote repo to this machine.

Usage:

• /my-skills pull — pull all updates for linked user-level skills + show new ones
• /my-skills pull <skill-name> — pull and link a specific user-level skill
• /my-skills pull <skill1> <skill2> — pull and link multiple user-level skills
• /my-skills pull <skill-name> --project (-p) — show project list from repo, let user select, then pull
• /my-skills pull <skill-name> --project (-p) <project-name> — pull a project-level skill directly

Steps:

1. Read ~/.my-skills.yml. If not found, tell the user to run setup first.

2. Pull latest from remote:

   cd ~/.my-skills-repo
   git pull
   

3. Determine scope and target directory:

   • User level (default): target is ~/.claude/skills/, repo source is ~/.my-skills-repo/user/
   • Project level (--project (-p)):
     • Target is {cwd}/.claude/skills/
     • If project name is not specified, list available projects from the repo and let the user select:

       ls ~/.my-skills-repo/projects/
       

     • Repo source is ~/.my-skills-repo/projects/<project-name>/

4. If no skill names specified (user level):

   • Update all currently linked skills (symlinks already point to repo, so git pull is enough)
   • List any new skills in ~/.my-skills-repo/user/ that aren't linked yet, and ask if the user wants to link them

5. If skill names are specified:

   • For each skill, verify it exists in the appropriate repo path
   • Create symlink in the target directory (see Linking section)
   • For user-level skills, add to linked_skills in ~/.my-skills.yml

6. Report which skills were pulled/linked.

---

list

Show status of all skills (local and remote), separated by scope.

Usage:

• /my-skills list — show all user-level and project-level skills
• /my-skills list --project (-p) <project-name> — show skills for a specific project only

Steps:

1. Read ~/.my-skills.yml. If not found, tell the user to run setup first.

2. Pull latest repo info (fetch only, don't merge):

   cd ~/.my-skills-repo
   git fetch
   

3. Collect information (use bash -c '...' for complex shell scripts to avoid zsh compatibility issues):

   • User-level skills in ~/.my-skills-repo/user/
   • User-level skills linked locally (symlinks in ~/.claude/skills/ pointing to ~/.my-skills-repo/user/)
   • Local-only user-level skills (in ~/.claude/skills/, not a symlink)
   • Other skills (symlinks pointing to somewhere other than ~/.my-skills-repo/, e.g. plugin-installed skills)
   • Project-level skills in ~/.my-skills-repo/projects/ (grouped by project name)

   When checking symlinks, strip trailing slashes from paths before using [ -L ]. Use readlink to determine the symlink target.

4. Display as a table with these status labels:

   • [linked] — symlink points to ~/.my-skills-repo/
   • [remote] — exists in repo but not linked on this machine
   • [local only] — exists locally but not in repo (regular directory, not a symlink)
   • [other] — symlink pointing to somewhere else (e.g. plugin-installed)

   Repo: <username>/my-skills (private)
   
   ── User Level ──
   [linked]     memo            Create study notes from conversations
   [linked]     recap           Summarize session work
   [local only] backend-init    (no description)
   [other]      skill-creator   Create and improve skills (via plugin)
   
   ── Project Level ──
     retrievo/
       [linked]     backend-init  Spring Boot + Kotlin DDD project init
       [remote]     claude-api    Build apps with Claude API
   

   To get skill descriptions, read each SKILL.md and extract the description from frontmatter.

5. If there are updates available (local behind remote), note them.

---

unlink

Remove symlink and restore original skill from backup.

Usage:

• /my-skills unlink <skill-name> — unlink a user-level skill
• /my-skills unlink <skill1> <skill2> — unlink multiple skills
• /my-skills unlink <skill-name> --project (-p) — unlink a project-level skill

Steps:

1. Read ~/.my-skills.yml. If not found, tell the user to run setup first.

2. For each skill:

   • Verify it's currently a symlink pointing to ~/.my-skills-repo/
   • Remove the symlink
   • If a backup exists in ~/.my-skills-backup/<skill>, restore it:

     mv ~/.my-skills-backup/<skill> <target>/<skill>
     

   • If no backup exists, copy from repo to make it a regular directory:

     cp -r ~/.my-skills-repo/user/<skill> <target>/<skill>
     

   • Remove from linked_skills in ~/.my-skills.yml (for user-level)

3. The skill remains in the repo — only the local symlink is removed. The skill becomes a standalone local copy.

4. Report which skills were unlinked.

---

Linking (Symlink Management)

When linking a skill, handle these cases carefully:

1. Skill exists in target as a regular directory (not yet linked):

   • Back up to ~/.my-skills-backup/ (outside the skills directory to avoid being recognized as a skill):

     mkdir -p ~/.my-skills-backup
     mv <target>/<skill> ~/.my-skills-backup/<skill>
     

   • Create symlink:
     • User level: ln -s ~/.my-skills-repo/user/<skill> <target>/<skill>
     • Project level: ln -s ~/.my-skills-repo/projects/<project>/<skill> <target>/<skill>
   • Tell the user the original was backed up to ~/.my-skills-backup/<skill>

2. Skill already linked (symlink exists and points to repo):

   • Nothing to do, already synced

3. Skill exists as a symlink to somewhere else:

   • Warn the user and ask before replacing

4. Skill doesn't exist in target:

   • Just create the symlink

Config File Format

~/.my-skills.yml:

repo: kunsanglee/my-skills
local_path: ~/.my-skills-repo
linked_skills:
  - memo
  - recap

linked_skills tracks user-level linked skills only. Project-level links are determined by checking symlinks in the project's .claude/skills/ directory.

Error Handling

• If gh is not installed: "gh CLI is required. Install with: brew install gh"
• If not authenticated: "GitHub authentication required. Run: ! gh auth login"
• If config not found for push/pull/list: "Run /my-skills setup first."
• If git conflicts occur during pull: show the conflict and ask the user how to resolve
• If a skill name doesn't exist: list available skills and suggest the closest match

Language

Communicate with the user in Korean (matching their preference), but keep technical terms (GitHub, symlink, push, pull, etc.) in English.