User-level (available everywhere)

<objective> Manage Claude Code and OpenCode skills from multiple source types. Handle installation, updates, listing, and removal of skills at both user and project levels. </​objective>

<quick_start> Install a skill from GitHub:

# User-level (available everywhere)
git clone https://github.com/​user/​repo ~/​.claude/​skills/​repo

# 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):

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

</​type>

<type name="github-subdirectory"> A skill living as a subdirectory within a larger repository.

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)

</​type>

<type name="skill-zip"> A `.skill` zip file hosted at any URL.

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)

</​type>

</​skill_reference_types>

<operations> <operation name="remove"> **User skill:** ```bash rm -rf ~/​.claude/​skills/​skill-name ```

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

</​operation>

<operation name="list"> ```bash # Claude Code ls ~/​.claude/​skills/ ls .claude/​skills/

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

</​operation>

<operation name="post-install"> After installing any skill, check for and install dependencies:

# 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

</​operation>

<operation name="interop"> Make skills available to both Claude Code and OpenCode using symlinks.

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 </​operation>

</​operations>

<error_handling>

<error name="clone-failed"> **Symptom:** `git clone` fails with "repository not found" or network error

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 [email protected]:user/​repo </​error>

<error name="skill-exists"> **Symptom:** Target directory already exists

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 </​error>

<error name="invalid-url"> **Symptom:** Cannot parse GitHub URL

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 </​error>

<error name="missing-skill-md"> **Symptom:** Cloned directory has no SKILL.md

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 </​error>

</​error_handling>

<success_criteria> Installation is successful when:

• Target directory exists
• SKILL.md file is present in the directory
• For git repos: .git directory exists (or is a submodule)
• For subdirectory/​zip: .skill-manager-ref file exists with source URL
• Any dependencies have been installed

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. </​success_criteria>