Guide ID	GS-1
Audience	All users
Prerequisites	Node.js 18+, npm 8+, Git
Time	10 minutes
Difficulty	Beginner

Installation & Setup

GSD Skill Creator is a CLI tool that helps you build a personalized knowledge base for Claude Code. It observes your usage patterns, suggests skills when workflows repeat, and manages skills throughout their lifecycle. This guide walks you through installing the tool, setting up your environment, and verifying everything works.

Prerequisites

Before installing GSD Skill Creator, ensure you have the following software on your system. The tool is built with TypeScript and distributed via npm, so Node.js and npm are required. Git is needed for version tracking and rollback features.

Software	Minimum Version	Check Command
Node.js	18.x or higher	`node --version`
npm	8.x or higher	`npm --version`
Git	Any recent version	`git --version`

Run the following commands to verify your system is ready:

node --version   # Expected: v18.0.0 or higher
npm --version    # Expected: 8.0.0 or higher
git --version    # Expected: git version 2.x.x

Installing Prerequisites

If you need to install the prerequisites, use your platform's package manager:

macOS (Homebrew)

brew install node git

Ubuntu / Debian

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs git

Windows (winget)

winget install OpenJS.NodeJS.LTS
winget install Git.Git

Installation

The recommended installation method is to clone the repository, install dependencies, build the project, and link the CLI globally. This gives you access to all features and the ability to update easily.

Step 1: Clone and Build

# Clone the repository
git clone https://github.com/Tibsfox/gsd-skill-creator.git
cd gsd-skill-creator

# Install dependencies
npm install

# Build the project
npm run build

# Link the CLI globally
npm link

Step 2: Verify Installation

After installation, verify that the CLI is available and the build succeeded:

# Check that the CLI is accessible
skill-creator --version
# Expected: version number (e.g., 1.4.0)

# Run the test suite to verify build integrity
npm test
# Expected: Test Files 15 passed (15), Tests 202 passed (202)

Step 3: Initialize Directory Structure

The tool automatically creates directories on first use, but you can initialize them manually for git tracking. These directories store skills, observations, and generated agents:

# Create skill storage directory
mkdir -p .claude/skills

# Create pattern storage directory
mkdir -p .planning/patterns

# Create agents directory
mkdir -p .claude/agents

# Add placeholder files for git tracking
touch .claude/skills/.gitkeep
touch .planning/patterns/.gitkeep
touch .claude/agents/.gitkeep

# Commit the structure
git add .claude/skills/.gitkeep .planning/patterns/.gitkeep .claude/agents/.gitkeep
git commit -m "Initialize skill creator directories"

Step 4: Configure Git Tracking (Optional)

Customize what gets tracked in version control. For shared repositories, you may want to exclude observation data while keeping skills tracked:

# Add to .gitignore for shared repos
# Exclude large observation files
.planning/patterns/sessions.jsonl

# Keep suggestions and feedback (smaller files)
!.planning/patterns/suggestions.json
!.planning/patterns/feedback.jsonl

Alternative Installation Methods

If the global installation does not suit your workflow, you can install GSD Skill Creator as a local project dependency or run commands directly without linking.

Local Project Dependency

# Install from local path
cd /path/to/your/project
npm install /path/to/gsd-skill-creator

Without Global Link

# Run directly without npm link
node /path/to/gsd-skill-creator/dist/cli.js help

# Or use npx
npx skill-creator help

First-Run Verification

After installation, run a few commands to confirm everything is working. The following commands should all succeed without errors:

# Show available commands
skill-creator help

# List skills (should be empty on first run)
skill-creator list
# Expected: no skills found

# Check token budget status
skill-creator status

# View suggestion statistics
skill-creator suggestions

An empty skill list on first run is expected and correct. You have not created any skills yet, so there is nothing to display.

Shell Aliases (Optional)

For convenience, add short aliases to your shell configuration file (~/.bashrc or ~/.zshrc):

alias sc='skill-creator'
alias sc-suggest='skill-creator suggest'
alias sc-status='skill-creator status'
alias sc-list='skill-creator list'

Troubleshooting

If you encounter issues during installation, here are solutions to the most common problems.

Command Not Found

If skill-creator is not recognized after running npm link, your npm global bin directory may not be in your PATH. Check with npm bin -g and add it to your PATH:

# Check npm global bin directory
npm bin -g

# Add to PATH in ~/.bashrc or ~/.zshrc
export PATH="$PATH:$(npm bin -g)"

Permission Errors

If you encounter permission errors during npm link, configure a user-local npm prefix:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH="$PATH:$HOME/.npm-global/bin"' >> ~/.bashrc
source ~/.bashrc

# Re-link after fixing permissions
cd /path/to/gsd-skill-creator
npm unlink && npm link

Module Not Found Errors

If you see "Cannot find module" errors, the build may be outdated or incomplete. Clean and rebuild:

cd /path/to/gsd-skill-creator
rm -rf node_modules dist
npm install
npm run build

Updating

To update to a newer version, pull the latest changes and rebuild:

cd /path/to/gsd-skill-creator
git stash
git pull origin main
npm install
npm run build
npm test
npm unlink && npm link
git stash pop

What's Next

Core Concepts — Learn about skills, observations, agents, and the token budget system
Creating Your First Skill — Build, validate, and test your first skill in five steps