managing-skills
Install, update, list, and remove Claude Code and OpenCode skills. Supports GitHub repositories (user/repo), GitHub subdirectory URLs, and .skill zip files. Can set up interoperability between Claude Code and OpenCode via symlinks. Use when user wants to install, add, download, update, sync, list, remove, uninstall, delete skills, or share skills between Claude Code and OpenCode.
When & Why to Use This Skill
This Claude skill acts as a comprehensive package manager for Claude Code and OpenCode, enabling users to seamlessly install, update, and organize agent skills from GitHub repositories, subdirectories, or local files. It streamlines the workflow for extending AI agent capabilities with robust support for dependency management and cross-tool interoperability, making it an essential utility for developers building agentic workflows.
Use Cases
- Case 1: Installing new agent capabilities directly from GitHub repositories or specific subdirectories into user-level or project-specific directories.
- Case 2: Keeping a suite of custom skills up-to-date by automatically pulling the latest changes from remote sources and managing required dependencies.
- Case 3: Synchronizing skill libraries between Claude Code and OpenCode environments using symlinks to ensure a consistent development experience across different tools.
- Case 4: Managing project-level extensions as git submodules to maintain clean version control and environment isolation for complex software projects.
| name | managing-skills |
|---|---|
| description | Install, update, list, and remove Claude Code and OpenCode skills. Supports GitHub repositories (user/repo), GitHub subdirectory URLs, and .skill zip files. Can set up interoperability between Claude Code and OpenCode via symlinks. Use when user wants to install, add, download, update, sync, list, remove, uninstall, delete skills, or share skills between Claude Code and OpenCode. |
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
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)
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
.skillextension
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)
**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
```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
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
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 -lathat the link points correctly
Resolution:
- Verify the URL is correct:
curl -I https://github.com/user/repo - Check if repo is private (requires auth):
gh auth status - For private repos, use SSH:
git clone git@github.com:user/repo
Resolution:
- Ask user: "Skill already exists. Update it or reinstall fresh?"
- Update:
git -C <path> pull - Reinstall:
rm -rf <path>then clone again
Resolution:
- Check URL format matches expected patterns (user/repo or full GitHub URL)
- Normalize shorthand
user/repotohttps://github.com/user/repo - Ask user to verify the URL
Resolution:
- Check if skill uses different structure (look for README or other entry point)
- Warn user: "This doesn't appear to be a valid skill (no SKILL.md found)"
- Ask if they want to keep it anyway
Update is successful when:
-
git pullcompletes 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
.gitmodulesor.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.