Managing Skills

Operation type:

• INSTALL: User wants to add a new skill
• UPDATE: User wants to refresh an existing skill
• LIST: User wants to see installed skills
• REMOVE: User wants to delete a skill
• CHECK: User wants to verify skill source/status

Source type (for INSTALL/UPDATE):

• GITHUB_REPO: user/repo or github.com/user/repo without path after branch
• GITHUB_SUBDIR: URL contains /tree/<branch>/ followed by a path
• SKILL_ZIP: URL ends with .skill

State both classifications before proceeding.

Exit criteria: Operation type, source type, skill name, and location all known.

Phase 2: Validate

• Check if skill already exists (for install)
• Check if skill exists (for update/remove)
• Verify URL is accessible (for install/update)

Exit criteria: Preconditions verified, conflicts identified.

Phase 3: Execute

• Run appropriate commands from reference sections
• Handle errors per <error_handling>

Exit criteria: Commands completed without error.

Phase 4: Verify

• Confirm SKILL.md exists in target location
• Install dependencies if requirements.txt exists
• Report success per <success_criteria>

Exit criteria: Success criteria met, user reminded to restart.

• User skills (~/.claude/skills/<skill-name>/) - available in all projects
• Project skills (<project>/.claude/skills/<skill-name>/) - available only in that project

Suggest project location when:

• Skill is specific to this project's tech stack
• Team needs shared access via version control
• Skill contains project-specific customizations

Always ask the user which location they want before installing.

List installed skills:

ls ~/.claude/skills/
ls .claude/skills/

Remove a skill:

rm -rf ~/.claude/skills/skill-name

After any operation, remind user to restart Claude Code.

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

mkdir -p ~/.claude/skills
git clone https://github.com/user/repo ~/.claude/skills/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 github_repository: has 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

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

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

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

Permission denied:

• Check write permissions on target directory
• Use sudo only if installing to system location (not recommended)

Skill already exists:

• Ask user: overwrite, rename, or cancel
• For updates, overwrite is expected behavior

Invalid skill structure:

• Verify SKILL.md exists in the skill directory
• Check for valid YAML frontmatter

Update is successful when:

• Latest version pulled/downloaded
• No merge conflicts (for git repos)
• User reminded to restart Claude Code

Removal is successful when:

• Skill directory no longer exists
• Submodule fully removed (if applicable)
• User reminded to restart Claude Code

<operation>INSTALL|UPDATE|LIST|REMOVE|CHECK</operation>
<skill_name>name of skill</skill_name>
<location>~/.claude/skills/ or .claude/skills/</location>
<status>SUCCESS|FAILED|BLOCKED</status>
<action_taken>What was done</action_taken>
<next_steps>Restart Claude Code / Additional steps needed</next_steps>

Responses missing any section are incomplete.