Managing Skills

Project-level (as submodule)

git submodule add https://github.com/user/repo .claude/skills/repo

**Always ask the user which location they want before installing.**
</quick_start>

<install_locations>
Skills can be installed in multiple locations depending on the tool:

**Claude Code:**
- User skills: `~/.claude/skills/<skill-name>/` - available in all projects
- Project skills: `<project>/.claude/skills/<skill-name>/` - available only in that project

**OpenCode:**
- User skills: `~/.config/opencode/skill/<skill-name>/` - available in all projects
- Project skills: `<project>/.opencode/skill/<skill-name>/` - available only in that project

**Important:** Always ask the user which location they want before installing.
</install_locations>

<skill_reference_types>

<type name="github-repository">
A dedicated GitHub repo containing a skill.

**How to recognize:**
- Shorthand: `user/repo`
- Full URL: `https://github.com/user/repo`
- May contain `/tree/<branch>` but NO path after the branch

**Install (User - Claude Code):**
```bash
mkdir -p ~/.claude/skills
git clone https://github.com/user/repo ~/.claude/skills/repo

Install (User - OpenCode):

mkdir -p ~/.config/opencode/skill
git clone https://github.com/user/repo ~/.config/opencode/skill/repo

Install (Project - as submodule):

mkdir -p .claude/skills
git submodule add https://github.com/user/repo .claude/skills/repo

Update (User):

git -C ~/.claude/skills/skill-name pull

Update (Project):

git -C .claude/skills/skill-name pull
git add .claude/skills/skill-name

How to recognize:

• Contains /tree/<branch>/ followed by a path within the repo
• Example: https://github.com/org/repo/tree/main/skills/my-skill
• Differs from Type 1: there's a path AFTER the branch name

Parse the URL:

• Repository: https://github.com/org/repo
• Subpath: skills/my-skill
• Skill name: my-skill (last path component)

Install (User or Project):

# Clone to temp directory
git clone --depth 1 https://github.com/org/repo /tmp/skill-clone-$$

# Copy subdirectory to target
mkdir -p ~/.claude/skills
cp -r /tmp/skill-clone-$$/skills/my-skill ~/.claude/skills/my-skill

# Create .skill-manager-ref with source URL
echo "https://github.com/org/repo/tree/main/skills/my-skill" > ~/.claude/skills/my-skill/.skill-manager-ref

# Cleanup
rm -rf /tmp/skill-clone-$$

Update:

# Read source URL
SOURCE_URL=$(cat ~/.claude/skills/my-skill/.skill-manager-ref)

# Re-run installation (same steps as above, overwrites existing)

How to recognize:

• URL ends with .skill
• Example: https://example.com/skills/my-skill.skill

Parse the URL:

• Skill name: filename without .skill extension

Install (User or Project):

# Download to temp
curl -L -o /tmp/skill-$$.zip "https://example.com/skills/my-skill.skill"

# Create target and extract
mkdir -p ~/.claude/skills/my-skill
unzip -o /tmp/skill-$$.zip -d ~/.claude/skills/my-skill

# If zip contained a single directory, move contents up
if [ $(ls -1 ~/.claude/skills/my-skill | wc -l) -eq 1 ] && [ -d ~/.claude/skills/my-skill/* ]; then
  mv ~/.claude/skills/my-skill/*/* ~/.claude/skills/my-skill/
  rmdir ~/.claude/skills/my-skill/*/
fi

# Create .skill-manager-ref with source URL
echo "https://example.com/skills/my-skill.skill" > ~/.claude/skills/my-skill/.skill-manager-ref

# Cleanup
rm /tmp/skill-$$.zip

Update:

# Read source URL
SOURCE_URL=$(cat ~/.claude/skills/my-skill/.skill-manager-ref)

# Re-run installation (same steps as above, overwrites existing)

Project skill (submodule):

git submodule deinit -f .claude/skills/skill-name
git rm -f .claude/skills/skill-name
rm -rf .git/modules/.claude/skills/skill-name

Project skill (not a submodule):

rm -rf .claude/skills/skill-name

OpenCode

ls ~/.config/opencode/skill/ ls .opencode/skill/

</operation>

<operation name="check-source">
**GitHub repo:**
```bash
git -C ~/.claude/skills/skill-name remote get-url origin
git -C ~/.claude/skills/skill-name rev-parse --short HEAD

Subdirectory or Zip (has .skill-manager-ref):

cat ~/.claude/skills/skill-name/.skill-manager-ref

# Python dependencies
if [ -f ~/.claude/skills/skill-name/requirements.txt ]; then
  pip install -r ~/.claude/skills/skill-name/requirements.txt
fi

# Node dependencies
if [ -f ~/.claude/skills/skill-name/package.json ]; then
  cd ~/.claude/skills/skill-name && npm install
fi

User-level (share skills globally):

First, check which tool already has skills:

ls -la ~/.claude/skills 2>/dev/null
ls -la ~/.config/opencode/skill 2>/dev/null

If Claude Code has skills, make them available to OpenCode:

mkdir -p ~/.config/opencode
ln -s ~/.claude/skills ~/.config/opencode/skill

If OpenCode has skills, make them available to Claude Code:

mkdir -p ~/.claude
ln -s ~/.config/opencode/skill ~/.claude/skills

Project-level (share skills in a project):

If Claude Code has project skills, make them available to OpenCode:

mkdir -p .opencode
ln -s ../.claude/skills .opencode/skill

If OpenCode has project skills, make them available to Claude Code:

mkdir -p .claude
ln -s ../.opencode/skill .claude/skills

Important considerations:

• Only ONE directory should contain actual files; the other should be a symlink
• If both directories already exist with different skills, ask user which to keep as primary
• Symlinks should be committed to git for project-level interop (use relative paths)
• After creating symlinks, verify with ls -la that the link points correctly

Resolution:

1. Verify the URL is correct: curl -I https://github.com/user/repo
2. Check if repo is private (requires auth): gh auth status
3. For private repos, use SSH: git clone git@github.com:user/repo

Resolution:

1. Ask user: "Skill already exists. Update it or reinstall fresh?"
2. Update: git -C <path> pull
3. Reinstall: rm -rf <path> then clone again

Resolution:

1. Check URL format matches expected patterns (user/repo or full GitHub URL)
2. Normalize shorthand user/repo to https://github.com/user/repo
3. Ask user to verify the URL

Resolution:

1. Check if skill uses different structure (look for README or other entry point)
2. Warn user: "This doesn't appear to be a valid skill (no SKILL.md found)"
3. Ask if they want to keep it anyway

Update is successful when:

• git pull completes without errors (for git repos)
• New files are present after re-download (for subdirectory/zip)

Removal is successful when:

• Target directory no longer exists
• For submodules: no entry in .gitmodules or .git/modules/

Important: After installing, updating, or removing skills, always tell the user they need to restart Claude Code/OpenCode for changes to take effect.