Section 01 — Foundations
GitHub 101
Before anything else — the mental model. Understanding what GitHub actually is makes everything else click into place.
Two things, not one
🧱
Git — the engine
A piece of software that runs on your machine. It tracks every change you make to code — who changed what, when, and why. Think of it like "track changes" in Word, but for entire projects and infinitely more powerful.
Git is local. It lives on your computer. It doesn't need the internet.
🌐
GitHub — the platform
A website that hosts git repositories online, making them shareable. It adds collaboration tools: issues, pull requests, discussions, stars, and a web interface for browsing code.
GitHub is the warehouse where people store and share their code publicly — or privately.
Four concepts you'll see everywhere
REPOSITORY
A folder of code + its entire change history. Every GitHub URL points to a repository — github.com/owner/repo-name
CLONE
Copying a repository from GitHub down to your machine. After cloning, you have an exact local copy you can work with offline.
FORK
Creating your own copy of someone else's repo on GitHub. Useful when you want to modify something without affecting the original.
STAR
Clicking the star ★ button bookmarks a repo and adds to its star count. More stars = more popular/trusted. It's GitHub's "like" button.
The key mental model: GitHub is a library. Each repo is a book. Some books are tools you download and use. Some are reference manuals you read. Some are instruction sets you hand to an AI. The type of book determines how you use it — and that's exactly what this guide covers.
Section 02 — Foundations
Anatomy of a Repo
Every GitHub page gives you the same signals. Once you know how to read them, you can understand any repo in 30 seconds.
What a GitHub page tells you
headroomlabs-ai
/
headroom
★ 48.3k
🍴 3.4k
Popular & trusted
Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 60–95% fewer tokens, same answers. Description = what it does
File structure — reveals the type
.claude-plugin/Plugin config
headroom/Source code
sdk/typescript/Library SDK
pyproject.toml→ pip install
package.json→ npm install
DockerfileCan run in container
README.mdRead first — always
README.md — always read this first
## Get started (60 seconds)
pip install "headroom-ai[all]" Install command
headroom wrap claude Use command
pip install "headroom-ai[all]" Install command
headroom wrap claude Use command
The README is the instruction manual. Every well-maintained repo has one. It tells you exactly what the repo is, what it does, and — most importantly — how to install and use it. If the README says pip install, you need Python. If it says npm install, you need Node. If it says /plugin install, you need Claude Code. The README is always your first stop.
Section 03 — Understanding Types
The 5 Types of Repos
Not all repos are the same. The type determines everything — how you get it, what you do with it, and whether it works with VS Code.
A consistent colour system — used throughout this guide
Skills & Plugins
SKILL
Files (mostly Markdown) that get placed in a special folder and teach your AI coding assistant how to behave differently. They don't "run" as programs — the AI reads them at startup and adjusts its responses accordingly.
Examples: Ponytail, UI UX Pro Max, gstack
Install via:
/plugin marketplace add or copy files
CLI Tools
CLI TOOL
Programs you install on your machine that run in the terminal. They can wrap your AI editor, compress API calls, process files, or do anything else that needs to run as a persistent local program. Often they hook into your editor as middleware.
Examples: Headroom, uipro, rtk
Install via:
pip install or npm install -g
Standalone Apps
APP
Full applications that run independently — a web server, a desktop UI, a chatbot interface. They use Claude's API internally but are their own programs. You clone them, install their dependencies, and run them separately from your editor.
Examples: Claude HeadRoom avatar, SalesGym voice agent
Install via:
git clone then npm start or python app.py
Libraries & SDKs
LIBRARY
Code you import into your own projects when building something with Claude. Not for end users — for developers. You call their functions in your code. The Anthropic SDK is an example — it gives you a clean way to call the Claude API from Node or Python.
Examples: anthropic (SDK), headroom-ai (library mode)
Install via:
npm install package or pip install package inside your code
MCP Servers
MCP
Model Context Protocol servers give Claude the ability to interact with external services in real time — your calendar, Notion, Google Drive, GitHub issues, Slack. They run as small local servers that Claude connects to. This is how Claude gets "tools" — the ability to actually do things, not just talk about them.
Examples: Notion MCP, Google Drive MCP, GitHub MCP, Puppeteer MCP
Install via: various — often
npx one-liners or configured in Claude Code settings
Why does the type matter so much? Because you wouldn't try to install a video editing app the same way you'd install a keyboard shortcut. The type tells you: what you need first, what commands to run, where things end up on your machine, and whether the thing works inside your editor or separately from it.
Section 04 — Understanding Types
Reading the Signals
You can identify a repo's type in 30 seconds by looking for specific signals — in the README, in the file list, and in the releases.
What you see → what it means
| Signal you see | Where | Type | What it means |
|---|---|---|---|
| /plugin marketplace add | README | SKILL | Claude Code plugin — two commands install it inside Claude Code |
| SKILL.md in files | File tree | SKILL | Skill file present — the AI reads this file to learn new behaviour |
| pip install "package-name" | README | CLI TOOL | Python package — needs Python 3.x, installs globally |
| npm install -g package | README | CLI TOOL | Node.js package — needs Node.js, installs globally (-g = global) |
| pyproject.toml at root | File tree | CLI / LIB | Python project — install via pip |
| package.json at root | File tree | CLI / APP | Node.js project — install via npm. Check if -g (global/CLI) or not (local app) |
| git clone && npm start | README | APP | Standalone app — clone the code and run it yourself as its own program |
| import { X } from examples | README | LIBRARY | Code library — meant to be imported into your own projects, not used directly |
| MCP server in title/description | Title | MCP | MCP server — gives Claude tools to interact with external services |
| .dmg or .exe in Releases | Releases tab | APP | Downloadable desktop app — download and install like any regular app |
| Dockerfile present | File tree | APP | Can run in a container — more complex, usually server-side software |
| .cursor/rules folder | File tree | SKILL | Has a Cursor rules file — copy it to your project's .cursor/rules/ folder |
Quick shortcut: Open any repo and look at two things — (1) the language bar at the bottom of the sidebar (Python = pip, JavaScript/TypeScript = npm), and (2) the first code block in the README. That first command almost always tells you exactly what type it is and how to use it.
Section 05 — Getting Repos
What You Need First
Three tools unlock almost every repo you'll encounter. Check if you have them — and install any you're missing before trying to use a new repo.
The three prerequisites
Git
Needed for: cloning repos, keeping them updated
$ git --version
Returns: git version 2.x.x if installed
If not installed: brew install git (Mac) or download from git-scm.com (Windows)
Node.js + npm
Needed for: npm packages, JS-based CLI tools
$ node --version
$ npm --version
Returns: v20.x.x if installed
If not installed: download from nodejs.org — npm comes bundled with it
Python 3 + pip
Needed for: Python-based CLI tools like Headroom
$ python3 --version
$ pip --version
Returns: Python 3.x.x if installed
Mac: usually pre-installed. Windows: download from python.org. Needs 3.10+ for most modern tools.
Which prerequisite unlocks which type
| Repo type | Git | Node.js / npm | Python / pip |
|---|---|---|---|
| SKILL via plugin command | ✗ | ✗ | ✗ |
| SKILL via npm CLI (like uipro) | ✗ | ✓ | ✗ |
| CLI TOOL Python-based | ✗ | ✗ | ✓ |
| CLI TOOL Node.js-based | ✗ | ✓ | ✗ |
| APP clone + run | ✓ | Often | Often |
| MCP servers | ✗ | Usually | Sometimes |
Section 06 — Getting Repos
The 6 Installation Methods
Every repo you'll encounter can be acquired through one of these six methods. Each maps directly to the repo type — once you know the type, you know the method.
A
Claude Code Plugin Command
For Skills that support the plugin marketplace
SKILL
Easiest
The simplest method — done entirely inside Claude Code without touching a terminal. You type two commands as messages to Claude Code, and it downloads and installs the skill automatically.
/plugin marketplace add DietrichGebert/ponytail ← send as a message
/plugin install ponytail@ponytail ← send as a second message
Use when: The README says /plugin marketplace add. Works inside Claude Code (VS Code extension). For the Claude desktop app, use the Customize UI instead of the /plugin command.
B
pip install — Python packages
For Python-based CLI Tools and Libraries
CLI TOOL
Easy
pip is Python's package manager. Running pip install downloads the package from PyPI (Python's registry) and installs it on your machine globally. You never need to clone the repo — pip handles fetching everything.
→ ~ pip install "headroom-ai[all]"
Collecting headroom-ai...
Successfully installed headroom-ai-0.27.0
✓ Command headroom is now available → ~ headroom --version 0.27.0 → ~
Successfully installed headroom-ai-0.27.0
✓ Command headroom is now available → ~ headroom --version 0.27.0 → ~
pip install "package-name[all]" # [all] installs optional extras
pip install --upgrade package-name # update later
Use when: README says pip install and the language bar shows Python. Needs Python 3.10+ for most modern tools. If you get a permissions error on Mac/Linux, try pip3 install or add --user.
C
npm install -g — Node.js packages
For Node.js-based CLI Tools
CLI TOOL
Easy
npm is Node.js's package manager. The -g flag means "global" — the tool installs machine-wide and can be run from any folder. This is what you did with uipro for UI UX Pro Max.
→ ~ npm install -g ui-ux-pro-max-cli
added 143 packages in 3.8s
✓ Command uipro now available globally → ~/my-project uipro init --ai cursor ✓ Skill installed to .cursor/skills/ → ~/my-project
✓ Command uipro now available globally → ~/my-project uipro init --ai cursor ✓ Skill installed to .cursor/skills/ → ~/my-project
npm install -g package-name # -g = global, any folder
npm install -g package-name@latest # update later
Use when: README says npm install -g. Needs Node.js installed first. Without -g, it would only install in the current folder — for CLI tools, always include -g.
D
git clone + setup
For Standalone Apps and projects you want to run yourself
APP
Intermediate
Cloning downloads the entire codebase to your machine. You then install the project's dependencies (the packages it relies on) and run it yourself. This gives you the full source code — you can modify it, contribute to it, or just run it as-is.
→ ~ git clone https://github.com/owner/repo-name.git
Cloning into 'repo-name'...
✓ done. Folder 'repo-name' created on your machine. → ~ cd repo-name You're now inside the project folder. → ~/repo-name npm install # or: pip install -r requirements.txt added 892 packages — dependencies installed → ~/repo-name npm start # or: python app.py / node index.js Server running at http://localhost:3000
✓ done. Folder 'repo-name' created on your machine. → ~ cd repo-name You're now inside the project folder. → ~/repo-name npm install # or: pip install -r requirements.txt added 892 packages — dependencies installed → ~/repo-name npm start # or: python app.py / node index.js Server running at http://localhost:3000
# Update later: go to the folder and pull latest changes
git pull
git pull
Use when: README says git clone, or when you want the full source code. Needs Git. Check the README for the exact run command — it varies by project (npm start, npm run dev, python main.py, etc.).
E
Manual file copy
For Rules files used by Cursor, Windsurf, Cline
SKILL
Easiest
Some skill repos can't be installed via a plugin command — instead, they have specific files you copy directly into your project folder. Ponytail for Cursor works this way. You don't need to clone the whole repo — just copy one file.
1
Go to the GitHub page
Navigate to the repo on GitHub in your browser.
2
Find the right file for your editor
Look in the README or file tree for folders named .cursor/rules/, .windsurf/rules/, or .clinerules/. Click the file, then click the copy icon (top right of the file view).
3
Paste into your project
Create the same folder structure in your project root and paste the file. That's it — your editor picks it up automatically.
Use when: You use Cursor, Windsurf, or Cline (not Claude Code), and the repo has a matching rules folder. No terminal needed at all.
F
Download ZIP
The no-code, no-terminal approach — limited but always available
No Git needed
Every GitHub repo lets you download its contents as a ZIP file — no Git, no terminal needed. Click the green "Code" button → "Download ZIP". Useful for reading files, copying skill content manually, or if you just want to inspect what's in a repo before committing to anything.
On any GitHub page:
Click Code ▾ button → Download ZIP → extract → read README and follow manual steps
Limitation: Gives you files but doesn't install anything. For CLI tools and apps, you'd still need to run pip install or npm install inside the extracted folder. Best for skills you're copying manually, or just exploring what a repo contains before using it.
Section 07 — Reference
The Claude Ecosystem
The three repos you've been working with — mapped exactly to their type, their installation method, and what they give you.
Repos you've encountered, decoded
Ponytail
SKILL
Makes Claude write minimal, un-bloated code. Applies YAGNI — "You Aren't Gonna Need It." Cuts ~54% of generated code on real projects. 60k ★ on GitHub.
/plugin marketplace add DietrichGebert/ponytail
/plugin install ponytail@ponytail
/plugin install ponytail@ponytail
Headroom
CLI TOOL
Compresses everything Claude reads — tool outputs, logs, file reads — before it hits the API. 60–95% fewer tokens, same quality answers. Saves real money on Claude Code usage. 48k ★.
pip install "headroom-ai[all]"
headroom wrap claude
headroom wrap claude
UI UX Pro Max
SKILL
Design intelligence skill — gives Claude 67 UI styles, 161 color palettes, 57 font pairings, and industry-specific design reasoning. Installed via a custom CLI tool (uipro). 97k ★.
npm install -g ui-ux-pro-max-cli
uipro init --ai cursor
uipro init --ai cursor
More Claude repos you might encounter
| Repo | Type | What it does | Install method |
|---|---|---|---|
| anthropic-sdk | LIBRARY | Official SDK to call Claude API in your code | npm install @anthropic-ai/sdk |
| gstack | SKILL | Garry Tan's Claude Code skill set for Supabase/Next.js | Copy to .claude/skills/ |
| mcp-server-notion | MCP | Lets Claude read and write to Notion | Config in Claude Code settings |
| rtk | CLI TOOL | Compresses shell command output (used by Headroom) | pip install rtk |
Section 08 — Reference
Compatibility
What actually works where — so you know before you try. "Compatible" means it integrates with or enhances that editor, not just that it runs on the same machine.
Full compatibility matrix
| Repo type | Claude Code (VS Code ext) |
Cursor | Windsurf | Standalone (terminal) |
|---|---|---|---|---|
| SKILL via /plugin | ✓ | copy files | copy files | ✗ |
| SKILL rules file | CLAUDE.md | ✓ | ✓ | ✗ |
| CLI TOOL (pip/npm -g) | ✓ | ✓ | ✓ | ✓ |
| APP (clone + run) | ✗ | ✗ | ✗ | ✓ |
| LIBRARY (in your code) | ✓ | ✓ | ✓ | ✓ |
| MCP servers | ✓ | ✓ | ✓ | Via config |
What makes a repo incompatible
Platform mismatch
A repo that produces a .dmg macOS app won't work on Windows, and vice versa. Always check the Releases tab to see what platforms are supported.
Missing runtime
A Python tool without Python installed, or a Node tool without Node.js. The repo isn't incompatible — your machine just needs the prerequisite first.
Wrong editor
A /plugin marketplace add command only works inside Claude Code. It won't work in Cursor or Windsurf. Those editors need the rules file copied manually instead.
It's a library, not a tool
Libraries are meant to be imported into code, not run directly. Trying to "use" a library without embedding it in a project is like trying to drive an engine without a car around it.
Section 09 — Reference
Decision Tree
Found a repo and not sure what to do with it? Work through this. Start at the top and follow the path.
🔍 I found a GitHub repo I want to use
↓
Step 1 — Open the README. What's the first install command?
↓
/plugin marketplace add
SKILL
→ Method A
→ Method A
pip install
CLI TOOL
→ Method B
→ Method B
npm install -g
CLI TOOL
→ Method C
→ Method C
git clone + npm start
APP
→ Method D
→ Method D
copy this file
SKILL
→ Method E
→ Method E
↓ README isn't clear?
Step 2 — Look at the file tree. What files are at the root?
↓
pyproject.toml
setup.py
setup.py
Python project
pip install .
pip install .
package.json
+ no -g in README
+ no -g in README
Node App
Method D
Method D
SKILL.md
.claude-plugin/
.claude-plugin/
Skill
Method A or E
Method A or E
.dmg / .exe
in Releases
in Releases
Desktop App
Download & install
Download & install
↓ Still not sure?
🤔
Step 3 — Read the Issues tab and Discussions
Search for "install" or "windows" or "how to use". Someone else has almost certainly asked the same question. Or ask an AI with the README pasted in.
Step 3 — Read the Issues tab and Discussions
Search for "install" or "windows" or "how to use". Someone else has almost certainly asked the same question. Or ask an AI with the README pasted in.
Section 10 — Reference
Cheat Sheet
Everything in one place. Screenshot this, print it, bookmark it.
Skills — Type 1
Install (plugin)/plugin marketplace add owner/repo
Then activate/plugin install name@name
Install (manual)copy file to .claude/skills/
For Cursorcopy to .cursor/rules/
For Windsurfcopy to .windsurf/rules/
Update/plugin update name
Remove/plugin remove name
CLI Tools — Type 2
Python installpip install "pkg[all]"
Node installnpm install -g package
Update Pythonpip install --upgrade pkg
Update Nodenpm install -g pkg@latest
Uninstall Pythonpip uninstall package
Uninstall Nodenpm uninstall -g package
Where is Python?which python3
Apps — Type 3 (git clone)
Clonegit clone <url>
Enter foldercd repo-name
Install Node depsnpm install
Install Python depspip install -r requirements.txt
Run (Node)npm start / npm run dev
Run (Python)python app.py / python main.py
Get latest changesgit pull
Git Essentials
Check git installedgit --version
Check Node installednode --version
Check Python installedpython3 --version
See repo statusgit status
See all branchesgit branch
Switch branchgit checkout branch-name
See what changedgit log --oneline
🔍 Signals Quick Reference — What you see → What it means
pyproject.tomlpip install
package.json (no -g)clone + npm install
npm install -gCLI tool
SKILL.mdskill file
.claude-plugin/plugin-capable skill
.cursor/rules/copy for Cursor
.dmg in ReleasesmacOS desktop app
.exe in ReleasesWindows desktop app
MCP serverconfigure in settings
🎓
You're now an SME on GitHub repos
You can identify any repo's type in 30 seconds, know which method to use, which prerequisites you need, and whether it'll work in your editor — without asking anyone.