Installing Skills System

Name: Installing Skills System
Author: obra

obra/clank

9 installs
41 repo stars
Updated October 9, 2025
obra/clank

Claude Code agent workflow helper from OBRA clank repository.

About

Installing Skills System — Clank skill from OBRA repository—agent workflow reference for Claude Code power users in the Superpowers ecosystem.

OBRA clank agent workflow.
Install via skills.sh registry.
Pairs with Superpowers ecosystem.

Installing Skills System by the numbers

9 all-time installs (skills.sh)
+2 installs in the week ending Jul 26, 2026 (Skillselion tracking)
Ranked #12,133 of 16,659 AI & Agent Building skills by installs in the Skillselion catalog
Security screen: HIGH risk (skills.sh audit)
Data as of Jul 26, 2026 (Skillselion catalog sync)

npx skills add https://github.com/obra/clank --skill installing-skills-system

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/obra/clank/installing-skills-system.svg)](https://skillselion.com/skills/obra/clank/installing-skills-system)

Installs	9
repo stars	★ 41
Security audit	0 / 3 scanners passed
Last updated	October 9, 2025
Repository	obra/clank ↗

What it does

Claude Code agent workflow helper from OBRA clank repository.

Files

SKILL.mdMarkdownGitHub ↗

Installing Skills System

Overview

Installs the clank skills repository to ~/.clank/clank and configures Claude to use it.

For Claude agents: Follow the "Installation Steps for Claude" section below.

For humans: Follow the "Quick Install" section.

Installation Steps for Claude

When instructed to install clank, follow these steps exactly:

Step 1: Clone Repository

With GitHub CLI (if available):

mkdir -p ~/.clank
cd ~/.clank
gh repo fork obra/clank --clone --remote-name upstream

Without GitHub CLI:

mkdir -p ~/.clank
cd ~/.clank
git clone https://github.com/obra/clank.git

Step 2: Run Installer

cd ~/.clank/clank
./skills/meta/installing-skills/install.sh

This creates symlinks for skills and commands.

Step 3: Update CLAUDE.md

Use the Edit tool to add this XML section to the very beginning of ~/.claude/CLAUDE.md:

<EXTREMELY_IMPORTANT>
You have a personal skills wiki at ~/.claude/skills/ with proven techniques, patterns, and tools that give you new capabilities.

STOP. Before doing ANYTHING else in this conversation, read this file: skills/getting-started

That file tells you how to find and use your skills.

ONLY after reading getting-started, are you allowed to proceed with the user's request.

CRITICAL: If a skill exists for your task, you MUST use it - even if you think you're already good at that. You're not. The skill prevents mistakes you don't know you make. SKILLS EXIST AND YOU DIDN'T USE THEM = FAILED TASK.

</EXTREMELY_IMPORTANT>

Step 4: Verify Installation

ls -la ~/.claude/skills
ls -la ~/.claude/commands
~/.claude/skills/getting-started/skills-search 'test.*driven'

Step 5: Restart

Tell your human partner: "Installation complete. Please restart your Claude session to pick up the new CLAUDE.md configuration."

Quick Install (for humans)

curl -fsSL https://raw.githubusercontent.com/obra/clank/main/skills/meta/installing-skills/install.sh | bash
# Then manually add CLAUDE.md section from Step 3 above

What install.sh Does

1. Validates you're running from clank repo root (expects ~/.clank/clank) 2. Backs up existing ~/.claude/skills (if exists) to timestamped backup 3. Creates skills symlink: ~/.claude/skills → ~/.clank/clank/skills 4. Symlinks individual commands from ~/.clank/clank/commands/*.md to ~/.claude/commands/ 5. Verifies tools available (skills-search at ~/.claude/skills/getting-started/skills-search) 6. Prints CLAUDE.md XML snippet to add and verification steps

Verification

After installation, verify it worked:

# Should show symlink to ~/.clank/clank/skills
ls -la ~/.claude/skills

# Should show individual command symlinks
ls -la ~/.claude/commands/

# Test skills-search tool
~/.claude/skills/getting-started/skills-search 'test.*driven'

What Gets Installed

Skills (~/.claude/skills/):

Library of proven techniques, patterns, and tools
Referenced with @ syntax in code and documentation
Searchable with skills-search tool

Commands (~/.claude/commands/):

Individual symlinks to clank command files
Slash commands for Claude (/brainstorm, /write-plan, /execute-plan)
Each command references a skill using @ syntax
Makes common workflows one command away

Tools (~/.claude/skills/getting-started/):

skills-search - Find relevant skills using grep patterns
Logs failed searches for gap analysis

Why Fork?

Forking lets you:

Customize skills and commands for your workflow
Contribute improvements back via PR (see skills/contributing-skills)
Stay synced with upstream updates (git pull upstream main)
Track your customizations in version control

Configure CLAUDE.md

After installation, edit your ~/.claude/CLAUDE.md and add this section:

<extremely_important_skills_library>
You have a personal skills wiki at `~/.claude/skills/` with proven techniques, patterns, and tools that give you new capabilities.

STOP. Before doing ANYTHING else in this conversation, read this file: `skills/getting-started`

That file tells you:
- Which phrases trigger brainstorming automatically (like "I've got an idea", "Let's make...")
- How to search for skills before ANY task
- When to announce which skill you're using

After reading getting-started, proceed with the user's request.

CRITICAL: If a skill exists for your task, you MUST use it - even if you think you're already good at that. You're not. The skill prevents mistakes you don't know you make. SKILLS EXIST AND YOU DIDN'T USE THEM = FAILED TASK.
</extremely_important_skills_library>

This enables:

Automatic skill discovery before every task
Mandatory skill usage enforcement
Gap tracking for missing skills (logged searches)

Updating Skills

After initial install, update with:

cd ~/.clank/clank
git pull origin main    # Pull your changes
git pull upstream main  # Pull upstream updates (if configured)

The symlinks stay valid - no need to reinstall.

Troubleshooting

"Error: Not running from clank repository root"

The script expects to be run from ~/.clank/clank/. Clone it first:

mkdir -p ~/.clank
cd ~/.clank
gh repo fork obra/clank --clone
cd clank
./skills/meta/installing-skills/install.sh

"~/.claude/skills already exists"

The installer automatically backs it up with timestamp. Check backups:

ls -la ~/.claude/skills.backup.*

Symlinks broken

Remove and reinstall:

rm ~/.claude/skills
rm ~/.claude/commands/*.md  # Remove individual command symlinks
cd ~/.clank/clank
./skills/meta/installing-skills/install.sh

Uninstalling

# Remove symlinks
rm ~/.claude/skills
rm ~/.claude/commands/brainstorm.md
rm ~/.claude/commands/write-plan.md
rm ~/.claude/commands/execute-plan.md

# Restore backup if desired
mv ~/.claude/skills.backup.YYYY-MM-DD-HHMMSS ~/.claude/skills

# Remove from CLAUDE.md
# Delete the "Skills Library" section from ~/.claude/CLAUDE.md

# Remove cloned repo
rm -rf ~/.clank/clank

Implementation

See @install.sh for the installation script.

#!/usr/bin/env bash
set -euo pipefail

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

# Validate we're running from clank repository root
validate_clank_repo() {
  if [[ ! -d "skills/meta/installing-skills" ]]; then
    echo -e "${RED}Error: Not running from clank repository root${NC}"
    echo ""
    echo "Expected to be run from ~/.clank/clank/"
    echo ""
    echo "To install clank, clone to ~/.clank first:"
    echo "  ${GREEN}mkdir -p ~/.clank && cd ~/.clank${NC}"
    echo "  ${GREEN}gh repo fork obra/clank --clone${NC}"
    echo "  ${GREEN}cd clank${NC}"
    echo "  ${GREEN}./skills/meta/installing-skills/install.sh${NC}"
    exit 1
  fi
}

# Get absolute path to clank repo
get_repo_path() {
  if [[ "$OSTYPE" == "darwin"* ]]; then
    # macOS doesn't have realpath by default, use Python
    python3 -c "import os; print(os.path.realpath('.'))"
  else
    realpath .
  fi
}

# Backup existing skills directory if it exists
backup_existing_skills() {
  local skills_dir="$HOME/.claude/skills"

  if [[ -e "$skills_dir" ]]; then
    local timestamp=$(date +%Y-%m-%d-%H%M%S)
    local backup_path="${skills_dir}.backup.${timestamp}"

    echo -e "${YELLOW}Found existing ~/.claude/skills${NC}"
    echo -e "Backing up to: ${backup_path}"

    mv "$skills_dir" "$backup_path"
    echo -e "${GREEN}✓${NC} Backup created"
    echo ""
  fi
}

# No need to backup commands - we symlink individual files

# Create skills symlink
create_symlink() {
  local repo_path="$1"
  local skills_source="${repo_path}/skills"
  local skills_target="$HOME/.claude/skills"

  # Ensure ~/.claude directory exists
  mkdir -p "$HOME/.claude"

  echo "Creating skills symlink:"
  echo "  ${skills_target} → ${skills_source}"

  ln -s "$skills_source" "$skills_target"
  echo -e "${GREEN}✓${NC} Skills symlink created"
  echo ""
}

# Symlink individual commands
symlink_commands() {
  local repo_path="$1"
  local commands_source="${repo_path}/commands"
  local commands_target="$HOME/.claude/commands"

  # Check if commands directory exists in repo
  if [[ ! -d "$commands_source" ]]; then
    echo -e "${YELLOW}No commands directory in repo, skipping${NC}"
    echo ""
    return
  fi

  # Ensure ~/.claude/commands exists
  mkdir -p "$commands_target"

  echo "Symlinking commands:"

  # Symlink each command file
  for cmd in "$commands_source"/*.md; do
    if [[ -f "$cmd" && "$(basename "$cmd")" != "README.md" ]]; then
      cmd_name=$(basename "$cmd")
      ln -sf "$cmd" "$commands_target/$cmd_name"
      echo "  ${cmd_name}"
    fi
  done

  echo -e "${GREEN}✓${NC} Commands symlinked"
  echo ""
}

# Verify tools exist
verify_tools() {
  local skills_dir="$HOME/.claude/skills"
  local skills_search="${skills_dir}/getting-started/skills-search"

  if [[ -x "$skills_search" ]]; then
    echo -e "${GREEN}✓${NC} skills-search tool available"
    echo ""
  fi
}

# Verify installation
verify_installation() {
  local skills_dir="$HOME/.claude/skills"
  local commands_dir="$HOME/.claude/commands"

  echo "Verifying installation..."

  # Verify skills
  if [[ ! -L "$skills_dir" ]]; then
    echo -e "${RED}✗${NC} ~/.claude/skills is not a symlink"
    exit 1
  fi

  if [[ ! -f "$skills_dir/INDEX.md" ]]; then
    echo -e "${RED}✗${NC} INDEX.md not found in ~/.claude/skills"
    exit 1
  fi

  echo -e "${GREEN}✓${NC} Skills verified"

  # Verify commands were symlinked
  if [[ -d "$commands_dir" ]]; then
    cmd_count=$(find "$commands_dir" -type l -name "*.md" 2>/dev/null | wc -l)
    if [[ $cmd_count -gt 0 ]]; then
      echo -e "${GREEN}✓${NC} Commands verified ($cmd_count symlinked)"
    fi
  fi

  echo ""
}

# Print success message
print_success() {
  local repo_path="$1"

  echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
  echo -e "${GREEN}Installation complete!${NC}"
  echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
  echo ""
  echo -e "${YELLOW}NEXT STEP: Update ~/.claude/CLAUDE.md${NC}"
  echo ""
  echo "Add this to your CLAUDE.md:"
  echo ""
  cat "${repo_path}/skills/meta/installing-skills/CLAUDE_MD_PREAMBLE.md"
  echo ""
  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
  echo ""
  echo "Verify installation:"
  echo "  ${GREEN}ls -la ~/.claude/skills${NC}"
  echo "  ${GREEN}ls ~/.claude/commands/${NC}"
  echo "  ${GREEN}~/.claude/skills/getting-started/skills-search 'test.*driven'${NC}"
  echo ""
  echo "Repository location: ${repo_path}"
  echo ""
}

# Main installation flow
main() {
  echo ""
  echo "Clank Installation"
  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
  echo ""

  validate_clank_repo

  local repo_path=$(get_repo_path)
  echo "Repository path: ${repo_path}"
  echo ""

  backup_existing_skills
  create_symlink "$repo_path"
  symlink_commands "$repo_path"
  verify_tools "$repo_path"
  verify_installation
  print_success "$repo_path"
}

main "$@"